docs(adr): add Percy automation ADR

[HenriqueLimas]

Description

Created ADR following changes from #414

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6651a0b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Copilot]

Pull request overview

Adds an ADR documenting the decision to automate Percy visual regression testing with partial builds in GitHub Actions.

Changes:

• Introduces ADR 0002 describing Percy automation approach (partial PR builds + full main builds).
• Documents dependency tracking via component-metadata.json and expected tradeoffs.

[Copilot]

For clarity/consistency in an ADR, consider formatting field names as code (e.g., component and submodules) and using “Reuse” instead of “Re-use” (common spelling in most style guides).

Suggested change

	- Using the existing `component-metadata.json` mappings (component and submodules fields) to determine snapshot dependencies
	- Triggering full builds only when global files change (tokens, variables, mixins)
	2. **Full builds for main commits**: Execute and auto-approve the complete snapshot suite on the main branch
	3. **Simplified dependency tracking**: Re-use existing component metadata instead of automated code analysis (e.g., mixin dependency detection), as the additional complexity provides minimal benefit
	- Using the existing `component-metadata.json` mappings (`component` and `submodules` fields) to determine snapshot dependencies
	- Triggering full builds only when global files change (tokens, variables, mixins)
	2. **Full builds for main commits**: Execute and auto-approve the complete snapshot suite on the main branch
	3. **Simplified dependency tracking**: Reuse existing component metadata instead of automated code analysis (e.g., mixin dependency detection), as the additional complexity provides minimal benefit

[agliga]

I would call the file 002-visual-regression-testing
If it ever gets superceeded its hard to see what superceeded it.

I also would add the problem not being about the snapshots but rather we need to test visual regression on our css code.
I think being generic is key with these adrs

I like the steps part and such.
I would add also other frameworks we looked at if we did any why we didn't pick those.

[ianmcburnie]

So we already have a 0002: #509. Even if that one gets rejected, it will stay as 0002

[HenriqueLimas]

I also would add the problem not being about the snapshots but rather we need to test visual regression on our css code.
I think being generic is key with these adrs

My understanding was that this ADR was about automating Percy visual regression, not about visual regression itself as we decided on that already.

I would call the file 002-visual-regression-testing
If it ever gets superceeded its hard to see what superceeded it.

Agree that it should be generic, but as mentioned above I think it should be about the automation so 003-visual-regression-automation

[ianmcburnie]

My understanding was that this ADR was about automating Percy visual regression, not about visual regression itself as we decided on that already.

That was my understanding too.

[agliga]

My understanding was that this ADR was about automating Percy visual regression, not about visual regression itself as we decided on that already.

That was my understanding too.

Hmm I think there's a disconnect here. What prompted in writing this ADR is that we wanted to show that we chose Percy visual regression testing over Vitest snapshot or whatever other testing framework.

If we keep it as is, Im wondering then what is the point of this ADR.
My understanding for ADR is to catch decisions and why we made it.

• Saying we chose Percy over X other visual regression tools is a good decision record.
• Saying we chose to automate Percy over not automate Percy seems to get into the area of having too many ADRs for each thing we do.

Our goal is always to automate as many things as we can. The assumption is that we try to automate everything.
IMO, an ADR would make sense if we had tried to automate Percy and decided not to. That goes against our ways of working and we should document that.

It would be like adding changesets instead of just publishing manually. We don't need an ADR for that, we just do it because our goal is to automate everything we can...
But if we were to choose changesets over another tool, that to me makes sense to have an ADR.

[HenriqueLimas]

@agliga make sense, and I agree. I have updated the ADR with the information regarding the visual-html that we discussed in the past. Can you check if I missed any item to be added?

[agliga]

To me this looks great! I think its almost there.

I think there's a couple of minor edits, but Im fine approving after this.

I would also remove any mention of eBay as a whole.
We should talk about this from an open source perspective.

[ianmcburnie]

Thanks for this.

[ArtBlue]

Looks great. Just a couple of minor things.

[ArtBlue]

There are a couple of other factors IMO.

1. Percy has responsive testing out of the box, which also has specific mobile browser testing
2. Percy is actively being maintained and improved, so we should have more abilities to scale and automate in the future.

[agliga]

Agree with this

[ArtBlue]

Nice