Skip to content

feat: style validation doc examples#6152

Draft
marissahuysentruyt wants to merge 9 commits intoswc-1668/poc-componentsfrom
marissahuysentruyt/feat-style-validation-examples
Draft

feat: style validation doc examples#6152
marissahuysentruyt wants to merge 9 commits intoswc-1668/poc-componentsfrom
marissahuysentruyt/feat-style-validation-examples

Conversation

@marissahuysentruyt
Copy link
Copy Markdown
Collaborator

@marissahuysentruyt marissahuysentruyt commented Apr 8, 2026

Description

During a sync meeting, this work was shared as part of a discussion around how to validate styles for 2nd-gen components. This PR provides the example style validation documents I had Claude create for me.

Steps I took to create these:

  1. spun up claude code
  2. connected to the Figma console mcp
  3. made sure to have the component's S2 desktop page open AND the components token spec page open in separate Figma tabs (you must use the Figma desktop app as opposed to the browser)
  4. asked claude to create a list of tokens with a prompt similar to these:
you will play the role of a senior engineer, gathering design information for their future PR reviewers. we need to document all tokens used in the status light in figma to properly validate that we're using them in the code implementation.
  1. the author validates the style doc against Figma making sure to have all tokens listed, variants covered, any gotchas from the rendering and style migration doc.
  2. once I validated the tokens claude provided to me, i then have claude compare the stylesheet to the list of tokens it created
making sure to follow the css resolution for tokens, validate that our stylesheet correctly includes all tokens and styles you noted in '/Users/marissahuysentruyt/Desktop/projects/spectrum-web-components/CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/statuslight-styling-validation.md'
  1. sometimes claude will catch the discrepancies, for instance, the new vertical padding tokens:
Screenshot 2026-04-08 at 9 22 14 AM 8. my final step is always to do a quick check of making sure i can follow the custom property resolutions back to the tokens in the browser inspector manually. with the style validation doc though, it felt faster than needing to have figma open to cross-check.

Motivation and context

These style validation docs were created to provide a central list of component tokens to the PR reviewer, aimed to make reviewing easier.

Related issue(s)

  • created in part for swc-1670

Screenshots (if appropriate)

Author's checklist

  • I have read the CONTRIBUTING and PULL_REQUESTS documents.
  • I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
  • I have added automated tests to cover my changes.
  • I have included a well-written changeset if my change needs to be published.
  • I have included updated documentation if my change required it.

Reviewer's checklist

  • Includes a Github Issue with appropriate flag or Jira ticket number without a link
  • Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
  • Automated tests cover all use cases and follow best practices for writing
  • Validated on all supported browsers
  • All VRTs are approved before the author can update Golden Hash

Manual review test cases

  • contributor docs navigation is updated
    1. pull down the branch
    2. navigate to the CONTRIBUTOR-DOCS directory cd CONTRIBUTOR-DOCS
    3. run the update nav script node 01_contributor-guides/07_authoring-contributor-docs/update-nav.js
    4. no additional missing contributor doc links should appear (apart from a badge TODO heading that is being addressed in feat(statuslight): ensure visual fidelity for status light #6133)
    5. make sure the docs make sense.
    6. reviewers are free to check the tokens listed are correct by spot checking against the respective component's S2 Desktop page and token specs pages (available upon request 😊)

Device review

  • Did it pass in Desktop?
  • Did it pass in (emulated) Mobile?
  • Did it pass in (emulated) iPad?

Accessibility testing checklist

Required: Complete each applicable item and document your testing steps (replace the placeholders with your component-specific instructions).

documentation updates only

rise-erpelding and others added 9 commits April 8, 2026 09:07
@rise-erpelding @marissahuysentruyt
style(badge): clean up code styles (#6125)
bacc532
@marissahuysentruyt
docs(divider): follows a11y rec for real content in stories (#6123)
d810c9a 
* docs(divider): follows a11y rec for real content in stories

* docs(divider): define default size and add todo for chromatic
- adds a todo comment to capture vrts for WHCM and more sizes in the
static color dividers
- adds medium as the default in the control table

* docs(divider): update content with realistic text
@marissahuysentruyt
feat(badge): ensure visual s2 fidelity (#6114)
51bd14a 
* docs(badge): update rendering-and-styling migration analysis
Clarify that fixed positioning is documented in design system guidance
and note new S2 badge variants (notification, indicator) tracked in SWC-1831.

* feat(badge): add no-label CSS class when label slot is empty
Add `swc-Badge--no-label` class via classMap when the default slot
has no text content, enabling CSS targeting of icon-only badges.

* fix(badge): updates padding block tokens and icon-only gap

* feat(badge): support for swc-icon internal

* feat(badge): icon only accessibility examples

* fix(badge): size types passing into swc-icon

* docs(badge): adds todo for missing variants

* fix(badge): dynamically passes size to slotted icon

* test(badge): anatomy test checks for children elements
previously, we were checking for text content when the badge icon slot
was just accepting strings. Now the anatomy story is using the swc-icon
internal component, so it never has text content (it's got HTML). the
badge test now checks for children.length instead.

* fix(badge): disabled text control for icon-slot

* fix(badge): a11y roles for icon only badges

* fix(badge): inline padding
- adds new --swc-badge-padding-inline-start custom prop to control the
inline padding start of a badge. it changes when there's an icon + label
vs. just the text label
- also fixes the gap property so that we just redefine the custom prop
for the badge gap instead

* docs(badge): add todo for icon only badge size story

* docs(rules): update docs on template vs custom html rendering

* docs: badge examples updated

* fix(badge): correct fallbacks for sized badge padding
Without this fallback, the start padding on a badge without an icon would
always resolve to the 75-scale token regardless of size, because
--swc-badge-padding-inline-start was never set in the size override blocks.

Adding --swc-badge-padding-inline as an intermediate fallback means
size overrides propagate to both sides automatically, while the :has()
rules can still override --swc-badge-padding-inline-start for the icon case.

* revert(badge): medium stays default size; neutral is default variant

* test(badge): update new default assertions

* docs(badge): adds @todo to default sizing discrepancy comment

* fix(badge): reduce selector specificity and refactor private padding tokens

* fix(badge): padding block properties corrected

* docs: correct updated css style guides with badge examples

* docs: fix typo

* docs(badge): use different badge variants per design docs

* docs(badge): adds tickets to todo comments
@rise-erpelding @marissahuysentruyt
style(divider): clean up code styles (#6135)
5038447
@marissahuysentruyt
docs(divider): style validation doc
5118b90
@marissahuysentruyt
docs(progresscircle): style validation doc
da83983
@marissahuysentruyt
docs(statuslight): style validation doc
faabc76
@marissahuysentruyt
docs(badge): style validation doc
1d49a97
@marissahuysentruyt
chore: update contributor nav
d73dbaa
@marissahuysentruyt marissahuysentruyt self-assigned this Apr 8, 2026
@marissahuysentruyt marissahuysentruyt added the 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. label Apr 8, 2026
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Apr 8, 2026

⚠️ No Changeset found

Latest commit: d73dbaa

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

@marissahuysentruyt marissahuysentruyt changed the base branch from main to swc-1668/poc-components April 8, 2026 13:30
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 8, 2026

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-6152

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

@rise-erpelding rise-erpelding force-pushed the swc-1668/poc-components branch from a099390 to 06a2855 Compare April 9, 2026 13:42
@marissahuysentruyt marissahuysentruyt removed their assignment Apr 9, 2026
@marissahuysentruyt marissahuysentruyt added the Status:WIP PR is a work in progress or draft label Apr 9, 2026
@cdransf cdransf force-pushed the swc-1668/poc-components branch from e0d3061 to b446021 Compare April 14, 2026 17:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. Status:WIP PR is a work in progress or draft

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@marissahuysentruyt @rise-erpelding