docs: MVP-5 extend CEM + scaffold composable block library

[caseyisonit]

Description

Extends the CEM pipeline with custom JSDoc tags and scaffolds a composable block library so component docs can render directly from CEM rather than per-component metadata files. This is the documentation-pipeline groundwork that MVP-7 (Badge pilot) and the broader entity-readme rollout (Phase 2) depend on.

Two changes, one PR:

1. CEM extension — cem.config.js swaps statusPlugin for swcJsdocTagsPlugin, which parses additional JSDoc tags into the manifest:

   • @summary — one-line subtitle (consumed by the new <Subtitle /> block)
   • @genre / @category — taxonomy fields used by future doc routing
   • @related — comma-split list of sibling entity tag names
   • @RSPparity — React Spectrum 2 parity status (full | partial | none | <note>)
   • @a11yPattern — short pattern reference (e.g. aria-describedby-owner)
   • structured @deprecated — JSON { reason, since, replacedBy }, key-value, or free-form prose; emitted as a structured object on the declaration

   Existing @status / @since behaviour is preserved (Badge still emits status: "preview", since: "0.0.1").

2. Block library scaffold — six new React blocks under .storybook/blocks/, each reading from CEM via a shared cem-helpers.ts module:

   • EventsTable — renders events[] (from @fires)
   • CssPartsTable — renders cssParts[] (from @csspart)
   • CssPropsTable — renders cssProperties[] (from @cssprop); the --swc-* contract is documented in the block's JSDoc
   • EmbedStory — thin wrapper around <Canvas of={…} /> + optional <Source of={…} />, for embedding executable examples in narrative MDX
   • RelatedEntities — renders cross-links from @related
   • Subtitle — reads @summary from CEM, falls back to Storybook's built-in subtitle block for transitional compatibility

   DocumentTemplate.mdx is updated to import the new local Subtitle block; the existing scaffolding is otherwise unchanged.

Motivation and context

Per the docs-overhaul v2 plan (CONTRIBUTOR-DOCS RFC), the per-entity authoring shape is class JSDoc + README.mdx + optional executable-only stories. For the MDX layer to render API surface (events, parts, props) without hand-maintained tables, every block needs to read from CEM — and CEM needs to carry the full surface.

This PR builds the CEM-side parsing and the block-side rendering. It changes no public API surface and adds no new authoring requirements; existing components keep working unchanged.

Related issue(s)

Stacks on #6205 (MVP-3 persona sidebar). Unblocks MVP-7 (Badge pilot), which exercises every new block end-to-end.

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed the Accessibility Practices for this feature.
• I have added automated tests to cover my changes. (N/A — pure tooling/scaffolding; first end-to-end exercise lands in MVP-7 Badge pilot)
• I have included a well-written changeset if my change needs to be published. (N/A — no public package surface change)
• I have included updated documentation if my change required it.

Manual review test cases

• CEM regenerates with new tags.

  1. Check out the branch
  2. From 2nd-gen/packages/swc, run yarn analyze
  3. Open 2nd-gen/packages/swc/.storybook/custom-elements.json
  4. Verify Badge's class entry still has status: "preview" and since: "0.0.1" (backward-compat preserved)
  5. Verify no new errors or warnings in the analyzer output

• Storybook still renders.

  1. From 2nd-gen/packages/swc, run yarn storybook
  2. Verify the sidebar loads with all sections (Get started, Components, Reference, etc.)
  3. Open the Badge docs page
  4. Verify the subtitle area still renders (currently from parameters.docs.subtitle until MVP-7 sets @summary)
  5. Verify the API table, examples, and existing scaffolding all render unchanged

• Type-check passes.

  1. From repo root, run npx tsc --noEmit -p 2nd-gen/packages/swc/tsconfig.json
  2. Confirm no new type errors from the new block files (a pre-existing @vitest/browser/providers/playwright error is unrelated)

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)

  No new interactive surface — all six new blocks render static HTML (tables, links). The only links are in <RelatedEntities />, which uses native <a href> elements with no custom focus handling. Confirm no regressions in surrounding examples.

  1. Open the Badge docs page in Storybook
  2. Tab through the page
  3. Expect: focus order is unchanged from the pre-PR baseline; no new focus traps; native link focus indicators are visible

• Screen reader (required — document steps below)

  Tables and links use semantic HTML (<table>, <thead>, <tbody>, <a>); no custom ARIA. The <Subtitle /> block emits a <p class="sbdocs-subtitle"> matching Storybook's built-in subtitle markup.

  1. Open the Badge docs page in Storybook with VoiceOver active
  2. Navigate through the page
  3. Expect: subtitle is announced as a paragraph; tables (when populated by MVP-7) are announced with row/column structure; cross-links (when populated) are announced as links with their slug-derived label

[changeset-bot]

⚠️ No Changeset found

Latest commit: ae76c6e

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

[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-6211

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.