docs(swc): convert 2nd-gen component story JSDoc to per-component MDX

[caseyisonit]

Description

Move long-form documentation that previously lived as JSDoc comments above story exports in .stories.ts files into per-component MDX files at the component root. Each MDX file uses Storybook doc blocks (<Meta of={...} />, <Canvas of={Story} />) to render stories explicitly, and becomes the authoritative Docs page for that component, replacing the template-driven page generated by DocumentTemplate.mdx on a per-component basis.

Scope (this PR): 9 components + 2 internal stories + shared infrastructure.

• Components: badge, avatar, color-loupe, divider, progress-circle, status-light, typography, illustrated-message, button, tabs
• Internal components: asset (.internal.mdx), icon (.internal.mdx)
• Shared blocks: DocsHeader and DocsFooter (in 2nd-gen/packages/swc/.storybook/blocks/) own all the standard chrome at the top and bottom of every docs page, so the template-driven page and per-component MDX share the exact same surface with no duplicate boilerplate.
• Template rewrite: DocumentTemplate.mdx now composes itself from the new blocks; components without a per-component MDX continue to render through it unchanged.
• Sidebar refresh: Auto-generated preview.ts registrations for several new migration-analysis contributor docs (action-button, button-group, close-button, grid, infield-button, link, popover, changelog strategy) — picked up from update-nav.js.

Patterns and controllers are deferred to a follow-up PR (saved on caseyisonit/docs-mdx-patterns). This PR is scoped to components only.

Motivation and context

Story-level JSDoc was the only mechanism for long-form prose attached to each story, which forced documentation-only stories (tags: ['description-only']) and section-order parameters to influence rendering order. Moving to MDX:

• Eliminates the description-only anti-pattern: prose-only sections live in MDX without needing a fake story to hang JSDoc on.
• Removes section-order workarounds: ordering is explicit in MDX.
• Enables a single, hand-authored source of truth per component, with explicit <Canvas of={Story} /> references that survive lint and refactors.
• Sets up patterns and controllers to use the same DocsHeader / DocsFooter shell (out of scope for this PR but enabled by it).

The new MDX structure mirrors the section order of DocumentTemplate.mdx so local builds match production rendering: Anatomy → Upcoming features → Usage → Options → States → Behaviors → Accessibility → API → Feedback.

Related issue(s)

• Tracked internally; no external ticket.

Screenshots (if appropriate)

Visual parity verified by spot-checking badge, status-light, and tabs Docs pages against the template-driven rendering.

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

• Per-component Docs pages render via MDX

  1. Run yarn storybook in 2nd-gen/packages/swc/
  2. Open each of: /docs/components-badge--docs, components-avatar--docs, components-color-loupe--docs, components-divider--docs, components-progress-circle--docs, components-status-light--docs, components-typography--docs, components-illustrated-message--docs, components-button--docs, components-tabs--docs
  3. Expect: each page renders header (title, status badge, subtitle, description, overview, getting started), all section headings in canonical order (Anatomy, Upcoming features where applicable, Options, States, Behaviors, Accessibility), API table, controls, and feedback link.

• Unconverted components still render through DocumentTemplate

  1. Open /docs/components-accordion--docs (no MDX file exists)
  2. Expect: page still renders end-to-end via the rewritten DocumentTemplate.mdx, indistinguishable from the previous template output.

• Internal Docs pages render

  1. In dev mode, open /docs/components-asset--docs and /docs/components-icon--docs
  2. Expect: each renders from its .internal.mdx. Confirm they are excluded from production builds (rerun with NODE_ENV=production).

• Story title and section order match production

  1. Compare badge, status-light, and tabs Docs pages against the production deploy.
  2. Expect: per-story ### Title headings (Title Case for PascalCase exports without storyName, exact string for those with storyName) appear in the same order and with the same casing as production.

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.

• Keyboard (required — document steps below)

  1. From the Docs page of any converted component (e.g. /docs/components-button--docs), press Tab through the page.
  2. Expect: focus order moves through the in-page anchor links (Anatomy, Options, States, Behaviors, Accessibility, API, Feedback), then into each rendered Canvas (where interactive components like buttons are focusable), then to the "Open an issue" feedback link.
  3. Confirm focus is visible at every stop and no focus traps exist inside <Canvas> regions.

• Screen reader (required — document steps below)

  1. With VoiceOver (macOS) or NVDA (Windows), navigate the Docs page by heading.
  2. Expect: heading levels read in order — h1 (component title), h2 (section: Anatomy / Options / etc.), h3 (per-story title where hideTitle=false), h4/h5 (subsections within JSDoc-derived prose).
  3. Confirm each rendered story Canvas exposes its component(s) with role, name, and state as defined in the component's accessibility behavior. No new announcements are introduced by the MDX wrapper itself.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2f74c9e

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

[caseyisonit]

This and the DocsHeader blocks will be refined in a future PR but this reflects the current patterns that are consistent across all docs so far. Heavily based on DocumentTemplate.

[caseyisonit]

Auto generated from merges to main that werent picked up before

[caseyisonit]

You will notice the order some sections (behaviors) varies from production, this is because its honoring the authoring order whereas production was following alpha order when rendering because we didnt use the section-order parameter. this is an acceptable difference as long as the content for each story is still accurate.

[github-actions]

📚 Branch Preview Links

• Documentation Site (first-gen)
• Storybook (first-gen)
• Storybook (second-gen)

🔍 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:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6349

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.