docs(adr): restore Percy automation context and tradeoffs

Reintroduce the original operational context and implementation details for Percy automation, including partial PR builds, full main builds, and metadata-based dependency tracking. Capture the key cost, speed, and maintenance tradeoffs without duplicating rationale across sections.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HenriqueLimas

docs/adr/0003-visual-regression-testing-tool.md

@@ -8,7 +8,7 @@ Accepted
 
 ## Context
 
-We need visual regression testing to catch unintended UI changes across our component library. With approximately 990 visual snapshots across our components, we needed to evaluate different visual regression testing tools to determine the best fit for our needs.
+We need visual regression testing to catch unintended UI changes across our component library. We have approximately 990 snapshots, and Percy snapshots were previously executed manually. That process was paused because full runs were costly and slow, and running the full suite for every PR was not sustainable.
 
 The primary options considered were:
 
@@ -18,26 +18,32 @@ The primary options considered were:
 
 ## Decision
 
-We will use Percy for visual regression testing.
+We will use Percy for visual regression testing and run it through automated GitHub Actions with partial builds for PRs and full builds on `main`.
 
-Key factors in this decision:
+Implementation approach:
 
-1. **Existing infrastructure**: We already have an existing Percy account, eliminating procurement and setup overhead
-2. **Cross-browser testing**: Percy provides testing across multiple browsers (Chrome, Firefox, Safari, Edge), which visual-html does not natively support
-3. **Accurate**: Percy has been found to be accurate in finding differences between snapshots. Some other tools tend to show a lot of false positive
-4. **Cloud infrastructure**: Percy's cloud-based service provides a good UI to quickly see the visual differences and approve the build.
+1. **Partial builds for PRs**: Run snapshots only for components affected by changed files, and run full builds only when global files change (tokens, variables, mixins).
+2. **Full builds on `main`**: Run and auto-approve the complete snapshot suite for baseline coverage.
+3. **Metadata-based dependency tracking**: Reuse `component-metadata.json` mappings (including component/submodule relationships) instead of adding higher-complexity automated dependency analysis.
 
 ## Consequences
 
 **Positive:**
 
-- Cross-browser visual regression coverage without additional infrastructure
+- Existing Percy account avoids procurement and setup overhead
+- Cross-browser and responsive coverage out of the box, including mobile browser testing
+- Accurate visual diffing with fewer false positives than alternatives
+- Partial PR builds reduce build time and cost by running only snapshots impacted by changed files
+- Full builds on `main` preserve complete baseline coverage
+- Automation reduces manual effort and human error
+- Cloud UI and PR integration improve collaboration and review speed
+- Active product maintenance should improve long-term scalability and automation
 - No need to maintain custom visual regression infrastructure
-- Better collaboration through Percy's PR integration and review UI
 
 **Negative:**
 
-- Ongoing costs based on snapshot count (~990 snapshots)
-- Requires careful cost management through partial builds (only running snapshots for changed components)
+- Ongoing costs based on snapshot count (~990 snapshots), even with partial build optimization
+- Dependency mapping in `component-metadata.json` must be kept accurate and maintained
+- Risk of missing visual regressions when component dependencies are incomplete or stale
 - Dependency on external service rather than an internal eBay tool
 - Must trigger full builds when global files change (tokens, variables, mixins)