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

.ai/README.md

@@ -84,7 +84,7 @@ These two rules share the same glob (`2nd-gen/**/stories/**`) and work as a pair
   - Verification process to prevent hallucinated attributes, slots, or ARIA claims
 - **stories-format**: File structure and technical conventions
   - Visual separators, meta configuration, required tags, layout parameters
-  - `render` vs `args` patterns, `flexLayout` usage, `section-order` parameter
+  - `render` vs `args` patterns, `flexLayout` usage
   - Static color three-story pattern, image asset conventions
 
 #### Component README
@@ -295,10 +295,10 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re
 
 #### Migration — phase 7: documentation (`migration-documentation`)
 
-- **purpose**: Write JSDoc, Storybook stories, and usage docs so the component is usable and understandable by others
+- **purpose**: Author the per-component MDX docs page and finalize Storybook stories + public-API JSDoc so the component is usable and understandable by others
 - **How to invoke**: Say "write docs for [component] migration", "document [component] for 2nd-gen", or "phase 7 migration for [component]"
 - Use when: Tests pass and the approved `migration-plan.md` can be used as the source of truth for migration notes and rationale
-- Provides: JSDoc guidelines, stories scaffolding, README/usage doc structure, documentation checklist, and plan-aligned migration-note guidance
+- Provides: per-component MDX authoring (`<component>.mdx`), public-API JSDoc guidelines on `Component.ts`, stories file finalization (drop `'autodocs'` from Playground, complete Accessibility story), documentation checklist, and plan-aligned migration-note guidance
 
 #### Migration — phase 8: review (`migration-review`)
 
@@ -324,8 +324,8 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re
 #### Documentation
 
 - **purpose**: Follow Adobe content writing standards when writing documentation
-- **How to invoke**: Use when writing or editing docs — e.g. story JSDoc (`.stories.ts`), README/changeset/Jira/PR (`.md`, `.mdx`), or when you say “write the PR description”, “draft the Jira ticket”, “add JSDoc to this story”.
-- Use when: Writing story JSDoc, 1st-gen docs, changesets, Jira tickets, or PR descriptions
+- **How to invoke**: Use when writing or editing docs — e.g. per-unit MDX docs pages (`<unit>.mdx`), public-API JSDoc in `Component.ts`, the meta-level JSDoc in `.stories.ts`, README/changeset/Jira/PR (`.md`, `.mdx`), or when you say “write the PR description”, “draft the Jira ticket”, “write the docs for this component”.
+- Use when: Authoring 2nd-gen docs pages, writing 1st-gen docs, changesets, Jira tickets, or PR descriptions
 - Provides: Voice and tone, grammar and mechanics, markdown/JSDoc reference, links to Spectrum design system content guidelines
 
 #### Explain code

.ai/rules/code-conformance.md

@@ -95,19 +95,32 @@ Reference: [Linting tools](../../CONTRIBUTOR-DOCS/02_style-guide/03_linting-tool
 **Authoring guidelines:**
 
 - Stories format: `.ai/rules/stories-format.md` — file structure, meta, tags, layout, visual separators
-- Stories documentation: `.ai/rules/stories-documentation.md` — section content, anatomy, options, states, behaviors, accessibility
+- Stories documentation: `.ai/rules/stories-documentation.md` — per-unit MDX authoring (section content, anatomy, options, states, behaviors, accessibility)
 
-**What to check:**
+**What to check (`<unit>.stories.ts`):**
 
 - File has the correct section order and visual separators
-- Meta has all required fields: `title`, `component`, `args`, `argTypes`, `render`, `parameters.docs.subtitle`, `tags: ['migrated']`
-- All stories have correct tags: `anatomy`, `options`, `states`, `behaviors`, `a11y`, etc.
-- JSDoc comments are present on all stories except Playground and Overview
-- JSDoc headings start at level 3 (`###`) or deeper
+- Meta has all required fields: `title`, `component`, `args`, `argTypes`, `render`, `parameters.docs.subtitle`, `tags: ['migrated']` (or `'controller'`)
+- All stories have correct section tags: `anatomy`, `options`, `states`, `behaviors`, `a11y`, etc.
+- Playground uses `tags: ['dev']` when the unit has a per-unit MDX file (no `'autodocs'` to avoid a duplicate Docs entry)
+- No story-level JSDoc comments above any `export const` — only the meta-level JSDoc remains
+- No `section-order` parameter; no `description-only` tag
 - `flexLayout: 'row-wrap'` is used for multi-item stories
 - All examples use accessible, meaningful content: no placeholder text, no missing labels
 - Image assets use `picsum.photos` with static IDs
 
+**What to check (`<unit>.mdx`):**
+
+- Per-unit MDX file exists at the unit root with the correct relative import path for `DocsHeader` / `DocsFooter`
+- `<Meta of={Stories} />` declared exactly once
+- `<DocsHeader />` at the top, `<DocsFooter />` at the bottom
+- Sections appear in canonical order (Anatomy → Upcoming features → Usage → Options → States → Behaviors → Accessibility → Full pattern → API → Appendix → Feedback)
+- Every section-tagged story is referenced via `<Canvas of={Stories.StoryName} />`
+- Per-story `### Title` headings match Storybook's rendered story names
+- No `<Canvas>` references to untagged stories
+- Controllers: hand-authored `## API` section is present and `meta.tags` includes `'controller'` so `<ApiTable />` is omitted by `<DocsFooter />`
+- MDX heading levels start at `###` inside section prose (top-level sections use `##`)
+
 ## Guideline gaps
 
 If the code is already correct and appropriate but the relevant style guide does not cover the pattern, do not change the guideline and do not block the review on it. Instead, surface it to the user with: