docs(swc): retire story-level JSDoc, description-only tag, and section-order parameter

[caseyisonit]

Description

Final cleanup in the JSDoc-to-MDX conversion chain. Now that components, patterns, and controllers all author their docs page in per-unit MDX (PRs #6349 and #6351), retire the workarounds that JSDoc-on-stories required, and rewrite the authoring rules and migration skills so future contributors learn the new pattern.

This branch is based on caseyisonit/docs-mdx-patterns (SWC-2230). Merge that PR first; this PR depends on it.

Scope:

• Runtime simplification: SpectrumStories.tsx drops the description-only branch and the section-order sort. validate-story-tags.js removes description-only from the allowed-tags allowlist.
• Stories-file guidance (.ai/rules/stories-format.md, contributor-docs Phase 4 step, migration-styling skill + template): the stories file is definitions-only. No story-level JSDoc above story exports. Playground uses tags: ['dev'] (no 'autodocs') when a per-unit MDX exists. Genre coverage extended to patterns and controllers.
• Per-unit MDX authoring guide (.ai/rules/stories-documentation.md): reframed from "what to put in JSDoc above stories" to "what to author in the per-unit MDX". New sections cover the per-unit MDX file template, canonical section order, genre-specific table (MDX path, blocks import path, ApiTable branch for DocsFooter, production-build inclusion), per-story title rules (PascalCase → Title Case, storyName override), single-story-section guidance, and untagged-stories-do-not-render warning.
• Code conformance (.ai/rules/code-conformance.md): storybook checks now cover both surfaces. Stories file: no story-level JSDoc, no section-order, no description-only, correct Playground tags. Per-unit MDX: file exists, <Meta of={Stories} /> declared once, <DocsHeader />/<DocsFooter /> placement, canonical section order, every section-tagged story surfaced via <Canvas>, controller-API hand-authoring branch.
• Migration documentation skill (migration-documentation/SKILL.md): Phase 7 now authors the per-component MDX docs page + public-API JSDoc on Component.ts. The Upcoming features pattern moves to MDX prose-only sections.
• Other skill + index updates (documentation/SKILL.md, .ai/README.md): documentation skill and AI README reflect MDX as the primary 2nd-gen docs surface.

Motivation and context

With per-unit MDX as the docs surface, the runtime workarounds — description-only (suppressing Canvas under JSDoc-only stories) and section-order (sorting stories inside a tag-rendered section) — are no longer needed. Removing them simplifies SpectrumStories.tsx and prevents future contributors from reaching for the retired patterns.

The rule and skill rewrites are the more impactful piece: they teach the new pattern to humans and AI agents authoring docs for new units. Without these updates, contributors would continue authoring story-level JSDoc by following the existing rules, which would no longer match how the docs page actually renders.

Related issue(s)

• Tracked internally as SWC-2232 under epic SWC-2229.

Screenshots (if appropriate)

N/A — runtime behavior for converted units is unchanged (the dropped logic was unreachable after SWC-2230). Storybook should render identically.

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

• No remaining description-only or section-order usage in 2nd-gen

  1. From the repo root, run grep -rn "description-only\\|'section-order'" 2nd-gen/packages/ | grep -v node_modules
  2. Expect: no hits (the runtime block and tag allowlist are clean).

• Docs pages still render

  1. Run yarn storybook in 2nd-gen/packages/swc/
  2. Open a converted unit (e.g. /docs/components-badge--docs, /docs/patterns-conversational-ai-system-message--docs, /docs/core-controllers-focus-group-navigation-controller--docs)
  3. Expect: each renders identically to the patterns branch. No Storybook console errors. Sections appear in canonical order.

• Updated rules describe the new pattern

  1. Read .ai/rules/stories-format.md and .ai/rules/stories-documentation.md
  2. Expect: the per-unit MDX model is described clearly; story-level JSDoc is explicitly prohibited; genre table covers components, internal components, patterns, and controllers.

• Migration-documentation skill targets MDX

  1. Read .ai/skills/migration-documentation/SKILL.md
  2. Expect: Phase 7 workflow now authors the per-component MDX file as the primary deliverable; story-level JSDoc is called out as prohibited; public-API JSDoc on Component.ts remains as the second surface.

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. No interactive surface changes in this PR (rules, skills, and a runtime simplification that produces identical output).
  2. Spot-check one converted Docs page with Tab to confirm focus order through anchor links and Canvas content is unchanged versus the patterns branch.

• Screen reader (required — document steps below)

  1. With VoiceOver or NVDA, navigate one converted Docs page by heading.
  2. Expect: section headings and per-story titles read in the canonical order. No new announcements introduced by the runtime simplification.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1a82bc8

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]

I have read through all the proposed changes and agree with them. The updates are the context so nothing to add self review wise.

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

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.