docs(components): standardize component reference docs, stories, and API JSDoc by rise-erpelding · Pull Request #6526 · adobe/spectrum-web-components

rise-erpelding · 2026-07-17T17:06:38Z

Description

Standardizes the 2nd-gen component reference docs, stories, and API JSDoc. This includes everything under components/ except the migration guides (48 files: 19 reference .mdx, 18 stories/*.ts, 6 component source .ts JSDoc, 5 tests):

Consistent anatomy / options / states / behaviors sections across components
Sentence-case headings and meta names; removed duplicated content
Standardized static-color patterns
Documented previously-undocumented API in component source JSDoc (Badge, Button, IllustratedMessage, StatusLight, Tab, Tabs)
Sentence-cased story/test names to match

Changes to .ts files are JSDoc/comment and story/test-name only; no runtime or behavior changes.

Motivation and context

This is 1 of 5 PRs splitting the oversized rise-erpelding/docs-site-small-updates branch (112 files) into reviewable pieces, divided by documentation surface. The original single PR was too large for GitHub and human reviewers to handle. Splitting by surface keeps each review scoped; the cross-surface consistency observations that a directory-based split would otherwise hide are preserved in the "Consistency notes" section below.

The five PRs together reproduce the original change set exactly (18 + 48 + 20 + 22 + 4 = 112 files, disjoint).

Merge order

Merge this before #6529. That PR adds a .husky/pre-commit rule enforcing sentence-case headings for component + internal genres; it will trip the hook against these docs until they are on main. No ordering constraint relative to the other content PRs.

Consistency notes

This PR establishes the sentence-case heading convention and the anatomy / options / states / behaviors section model for component + internal genres.
Patterns and controllers (docs: normalize patterns, core/controller docs, and contributor/tool docs #6528) are not yet audited to the same standard — tracked as a follow-up.

Related issue(s)

SWC-2379
Part of the branch split. Sibling PRs: docs(migration-guides): standardize and normalize component migration guides #6525, docs(storybook): normalize site guides and Storybook navigation #6527, docs: normalize patterns, core/controller docs, and contributor/tool docs #6528, docs(ai): update authoring rules and add sentence-case heading validation #6529

Screenshots (if appropriate)

N/A (documentation only)

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have included updated documentation (this PR is documentation).
Accessibility Practices — N/A (no component behavior change).
Automated tests — N/A (documentation / JSDoc / test-name changes only, no runtime change).
Changeset — N/A (no published-package behavior change).

Manual review test cases

Documentation-only; no runtime or behavior changes to verify. Review is mixed:

Prose/structure review of the .mdx reference docs and stories.
Code review of the 6 component .ts JSDoc additions.

Device review / Accessibility testing

N/A (no rendered component behavior changes)

changeset-bot · 2026-07-17T17:06:43Z

⚠️ No Changeset found

Latest commit: d6ecc13

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

rise-erpelding · 2026-07-17T17:49:41Z

📦 1 of 5 PRs splitting the oversized docs-site-small-updates branch (112 files) by doc surface. Siblings: #6525 (migration guides), #6527 (site guides), #6528 (patterns/core), #6529 (standards + validation).

⚠️ Merge order: please merge this before #6529. That PR adds a .husky/pre-commit rule enforcing sentence-case headings for component + internal genres; it will trip the hook against these docs until they're on main.

🔀 Cross-surface note: this PR establishes the sentence-case heading convention and the anatomy/options/states/behaviors section model for component + internal genres. Patterns and controllers (#6528) are not yet audited to the same standard.

…API JSDoc Normalizes the per-component reference documentation for 2nd-gen components: - Consistent anatomy / options / states / behaviors sections across components - Sentence-case headings and meta names; removed duplicated content - Standardized static-color patterns - Documented previously-undocumented API in component source JSDoc (Badge, Button, IllustratedMessage, StatusLight, Tab, Tabs) - Sentence-cased story/test names to match Part of splitting the large docs-site-updates branch (SWC-2379). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

rise-erpelding · 2026-07-17T21:22:51Z

 This style reduces visual weight while maintaining semantic meaning.

-> **Important**: The outline style is only valid for semantic variants (`accent`, `informative`, `neutral`, `positive`, `notice`, `negative`).
+> ⚠️ **Important:** The `outline` style is only valid for semantic variants (`accent`, `informative`, `neutral`, `positive`, `notice`, `negative`).


We'll probably want a follow-up ticket to look into changing these into the inline-style alerts/callouts that you see in the migration guides (under Styling).

See also #6525 (comment), I'll keep this thread open until there's a ticket for this.

SWC-2385 is the ticket!

rise-erpelding · 2026-07-17T21:25:12Z

This one needs an mdx file (which is why a few things are off here), noted and ticket made: SWC-2382

…ctions These two sections (plus the AdaptiveContrast story) were removed from color-loupe in the "make anatomy sections consistent" pass, but they document real, shipping behavior (the white-first adaptive inner-border contrast for WCAG 1.4.11, implemented in ColorLoupe.base.ts) and were not duplicated elsewhere — color-handle keeps its equivalent sections. Restoring them to match color-handle and origin/main; the removal was out of scope for that pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

rise-erpelding · 2026-07-17T21:52:37Z

+The inner-border opacity is computed from the current `color`: it holds a floor of 12% whenever the white outer border already carries 3:1, and climbs only where white cannot. The surrounding color is approximated by the loupe's own `color`, which is accurate on smooth gradients and approximate at steep or saturated edges.
+
+<Canvas of={ColorLoupeStories.AdaptiveContrast} />
+


I wasn't sure why these were removed in the previous commit, but if someone else has an idea about why, I'm happy to hear it! 😅

Looks like this along with several other things were carried over when Claude was rebasing and creating the new PRs, it didn't properly account for changes from #6513 and #6439, these should all be addressed now, at least in this PR

github-actions · 2026-07-20T12:51:37Z

📚 Branch Preview Links

🔍 Gen1 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-6526

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 · 2026-07-20T18:20:36Z

  },
 };

+export const Orientation: Story = {


Adding this story so it should show up as new in Chromatic, and you'll see that the story is used in the mdx docs.

I did this because a lot of content under the old ### Vertical heading and ### Layout Orientation heading before was duplicative. So they were combined into an ### Orientation heading with an orientation story to match that shows both vertical and horizontal orientations.

rise-erpelding · 2026-07-20T18:21:21Z

  `,
  parameters: {
    flexLayout: 'column-center',
+    chromatic: { disableSnapshot: true },


This story is used for testing only now, if you look in the mdx file, ### Orientation with corresponding story has replaced ### Vertical and its story.

rise-erpelding · 2026-07-20T19:21:24Z

There's a ticket to add an accessibility section to typography.mdx: SWC-2380

aramos-adobe · 2026-07-20T20:04:46Z

 ### Quiet

-The `quiet` variant removes the item divider borders and rounds the header corners on hover and focus.
+The `quiet` variant removes the item divider borders and rounds the header corners on hover.


In the css, it says:

/* Quiet: removes dividers and rounds header corners (visible on hover and focus) */ :host([quiet]) ::slotted(swc-accordion-item) { --swc-accordion-item-divider-color: transparent; --swc-accordion-item-header-corner-radius: var(--_swc-accordion-corner-radius); }

We should bring back the and focus here (?)

Yes, they are rounded as well, but I think this one I opted to take out because focus visible corners are always rounded (for every variant, but also for almost all components), so I didn't want it to sound like the rounded corners for focus were quiet-specific.

aramos-adobe · 2026-07-20T20:08:02Z

Most component stories don't have this parameter of section-order. Button group and link have this. Do we still need this parameter?

Ooh good catch, we do not need it.

I wonder if we should take it out of our rules? It kind of feels like rules could use a bigger audit than just removing rules around section-order though.

I agree - I'm not sure if section-order needs a rule set for now

rise-erpelding · 2026-07-20T20:11:21Z


 Non-semantic variants use color-coded categories, ideal for data visualization and labeling. Best used when there are **8 or fewer** categories being color coded.

 > **Note**: The `pink`, `turquoise`, `brown`, `cinnamon`, and `silver` variants are new in 2nd-gen and not available in 1st-gen.


Claude had originally made an item for a follow-up ticket so that we remove 1st-gen references/comparisons from our Docs (.mdx) pages and anything in .ts file comments and only leave them in the migration guides, I think in some ways that separation makes sense (so that when the time comes where Spectrum 1 is gone, we don't need to make corrections to our code other than removing migration guides), but I can also see how notes like this are helpful on the main docs page.

I didn't end up making the ticket, but am open to opinions if we think it would be valuable to do so.

…est titles Follow-up from PR #6526 review: writes down the conventions the PR established but didn't document, and removes the meta.title/test-title duplication that made the Storybook sentence-case rename fragile. - stories-documentation.md: replace the two-tier visual/technical Anatomy pattern with the flattened bullet-list pattern actually used in this PR - text-formatting.md: document the warning-emoji convention for consequential Important callouts - stories-format.md: add a states-vs-behaviors test for story tagging - derive `${meta.title}/Tests` instead of re-literaling the title in the five .test.ts files this PR touched Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…ng literals Storybook's story indexer statically parses `title` via AST without executing the module ("CSF: unexpected dynamic title"), so `` `${meta.title}/Tests` `` broke the Storybook build (and everything downstream of it: the browser test suites and Chromatic) in the five files touched by the previous commit. Revert to literal title strings in these files; the meta.title/test-title duplication stands as a known fragility, not one fixable with a template literal. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Rajdeepc · 2026-07-21T07:51:03Z

Correction to my earlier review comment: the suggestion to derive title: \${meta.title}/Tests`instead of re-literaling it doesn't hold. Storybook's CSF indexer parsestitlestatically via AST without executing the file, so a computed title fails withCSF: unexpected dynamic titleand breaks the Storybook build (which is why the 5 CI checks went red after my last push). Reverted ind56bfec— the string-literal duplication betweenmeta.titleand each.test.ts` file's title stands as a known, but not template-literal-fixable, fragility.

coveralls · 2026-07-21T07:52:26Z

Coverage Report for CI Build 29815384104

Coverage increased (+0.002%) to 96.243%

Details

Coverage increased (+0.002%) from the base build.
Patch coverage: No coverable lines changed in this PR.
No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

Coverage Stats


Relevant Lines:	39208
Covered Lines:	37935
Line Coverage:	96.75%
Relevant Branches:	6469
Covered Branches:	6026
Branch Coverage:	93.15%
Branches in Coverage %:	Yes
Coverage Strength:	460.67 hits per line

💛 - Coveralls

Merging main brought in button-custom-properties.vrt.ts (added by PR #6463 after this branch diverged), which enforces that every @cssprop documented on Button.ts has a matching visual test row. This docs PR documented --swc-button-down-state-transform (and --swc-button-max-inline-size, already covered) in Button.ts's JSDoc without a corresponding row, which failed the coverage check on the PR/main merge build ("Button VRT: Custom Properties"). Add the missing row, forcing the active state and overriding to a visually obvious rotate() so the reference/override pair shows a real difference. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

rise-erpelding · 2026-07-21T12:34:35Z

There are actually changes to all of these rules (stories-documentation, stories-format, and text-formatting) in #6529, which is meant to capture rule changes we found we needed to make across the whole series of PRs (not just components) and establishes a lint rule, could we add any of these changes if they're necessary to that PR instead?

Anatomy/callout/tag convention updates to stories-documentation.md, stories-format.md, and text-formatting.md belong with the other .ai/rules standardization work landing in #6529, not this docs-content PR. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

This was referenced Jul 17, 2026

docs(ai): update authoring rules and add sentence-case heading validation #6529

Merged

Tracking: split of docs-site-small-updates into reviewable PRs #6530

Closed

docs(migration-guides): standardize and normalize component migration guides #6525

Merged

This was referenced Jul 17, 2026

docs(storybook): normalize site guides and Storybook navigation #6527

Merged

docs: normalize patterns, core/controller docs, and contributor/tool docs #6528

Merged

rise-erpelding force-pushed the rise-erpelding/docs-split-component-reference branch from b849b95 to 33892c4 Compare July 17, 2026 18:13

rise-erpelding commented Jul 17, 2026

View reviewed changes

rise-erpelding marked this pull request as ready for review July 17, 2026 21:53

rise-erpelding requested a review from a team as a code owner July 17, 2026 21:53

Rajdeepc requested changes Jul 20, 2026

View reviewed changes

Comment thread 2nd-gen/packages/swc/components/button/Button.ts Outdated

Comment thread 2nd-gen/packages/swc/components/button/Button.ts Outdated

fix: improper rebase of button

99e6be1

Rajdeepc requested changes Jul 20, 2026

View reviewed changes

Comment thread 2nd-gen/packages/swc/components/color-loupe/test/color-loupe.test.ts

fix: accidental revert from #6513

0ae46f5

pfulton assigned Rajdeepc Jul 20, 2026

pfulton requested a review from aramos-adobe July 20, 2026 14:18

pfulton assigned aramos-adobe Jul 20, 2026

rise-erpelding requested a review from Rajdeepc July 20, 2026 17:22

rise-erpelding added the run_vrt Triggers the Chromatic VRT run for 2nd-gen label Jul 20, 2026

fix: disabled Vertical snapshot

20de280

rise-erpelding commented Jul 20, 2026

View reviewed changes

aramos-adobe reviewed Jul 20, 2026

View reviewed changes

rise-erpelding commented Jul 20, 2026

View reviewed changes

fix: remove lingering section-orders

2d64548

rise-erpelding requested a review from aramos-adobe July 21, 2026 00:33

Rajdeep Chandra and others added 2 commits July 21, 2026 13:11

Rajdeep Chandra and others added 2 commits July 21, 2026 14:11

Merge branch 'main' into rise-erpelding/docs-split-component-reference

38ced7a

rise-erpelding commented Jul 21, 2026

View reviewed changes

Rajdeepc approved these changes Jul 21, 2026

View reviewed changes

rise-erpelding pushed a commit that referenced this pull request Jul 21, 2026

docs: add states vs. behaviors section from #6526

abbd812

aramos-adobe approved these changes Jul 21, 2026

View reviewed changes

Merge branch 'main' into rise-erpelding/docs-split-component-reference

d6ecc13

rise-erpelding merged commit 7520279 into main Jul 21, 2026
33 checks passed

rise-erpelding deleted the rise-erpelding/docs-split-component-reference branch July 21, 2026 14:36

		The inner-border opacity is computed from the current `color`: it holds a floor of 12% whenever the white outer border already carries 3:1, and climbs only where white cannot. The surrounding color is approximated by the loupe's own `color`, which is accurate on smooth gradients and approximate at steep or saturated edges.

		<Canvas of={ColorLoupeStories.AdaptiveContrast} />


		Non-semantic variants use color-coded categories, ideal for data visualization and labeling. Best used when there are 8 or fewer categories being color coded.

		> Note: The `pink`, `turquoise`, `brown`, `cinnamon`, and `silver` variants are new in 2nd-gen and not available in 1st-gen.

Uh oh!

Conversation

rise-erpelding commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Merge order

Consistency notes

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Manual review test cases

Device review / Accessibility testing

Uh oh!

changeset-bot Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

rise-erpelding commented Jul 17, 2026

Uh oh!

rise-erpelding Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 20, 2026

📚 Branch Preview Links

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rise-erpelding Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rajdeepc commented Jul 21, 2026

Uh oh!

coveralls commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for CI Build 29815384104

Coverage increased (+0.002%) to 96.243%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

rise-erpelding Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

rise-erpelding commented Jul 17, 2026 •

edited

Loading

changeset-bot Bot commented Jul 17, 2026 •

edited

Loading

rise-erpelding Jul 17, 2026 •

edited

Loading

rise-erpelding Jul 21, 2026 •

edited

Loading

coveralls commented Jul 21, 2026 •

edited

Loading

rise-erpelding Jul 21, 2026 •

edited

Loading