diff --git a/.ai/README.md b/.ai/README.md index f5127b29fdd..af757154568 100644 --- a/.ai/README.md +++ b/.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 (`.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 (`.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 diff --git a/.ai/rules/code-conformance.md b/.ai/rules/code-conformance.md index 555d57e117f..2bf923ccbc4 100644 --- a/.ai/rules/code-conformance.md +++ b/.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 (`.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 (`.mdx`):** + +- Per-unit MDX file exists at the unit root with the correct relative import path for `DocsHeader` / `DocsFooter` +- `` declared exactly once +- `` at the top, `` 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 `` +- Per-story `### Title` headings match Storybook's rendered story names +- No `` references to untagged stories +- Controllers: hand-authored `## API` section is present and `meta.tags` includes `'controller'` so `` is omitted by `` +- 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: diff --git a/.ai/rules/stories-documentation.md b/.ai/rules/stories-documentation.md index 30aca13146a..c50c8725f78 100644 --- a/.ai/rules/stories-documentation.md +++ b/.ai/rules/stories-documentation.md @@ -1,33 +1,153 @@ --- -description: Comprehensive guide for what to document in 2nd-gen Storybook stories — overview, anatomy, options, states, behaviors, and accessibility sections — with patterns for JSDoc, args, accessible examples, and 1st-gen comparison notes. -globs: 2nd-gen/packages/swc/components/*/stories/** +description: Authoring guide for the per-unit MDX docs page for 2nd-gen components, internal components, patterns, and controllers. Covers section content, accessible examples, and 1st-gen comparison notes. Story prose lives in MDX, not in JSDoc above story exports. +globs: 2nd-gen/packages/swc/components/*/*.mdx, 2nd-gen/packages/swc/patterns/*/*/*.mdx, 2nd-gen/packages/core/controllers/*/*.mdx alwaysApply: false --- -# Component stories documentation standards +# Per-unit MDX authoring standards -Comprehensive guide for creating consistent, accurate, and accessible component documentation in Storybook stories. +Authoring guide for the per-unit MDX file that powers each Storybook Docs page. Applies to all four 2nd-gen genres: components, internal components, patterns, and controllers. -This guide integrates Shoelace's documentation patterns with Spectrum Web Components' structure, providing both visual and technical breakdowns while using TOC anchor linking. +**See also**: `.ai/rules/stories-format.md` for the stories file (`.stories.ts`) structure and conventions. ## Scope -Apply to all component stories in: +Apply to per-unit MDX files in: -- `2nd-gen/packages/swc/components/*/stories/*.stories.ts` +- `2nd-gen/packages/swc/components//.mdx` (components) +- `2nd-gen/packages/swc/components//.internal.mdx` (internal components — production builds exclude these) +- `2nd-gen/packages/swc/patterns///.mdx` (patterns) +- `2nd-gen/packages/core/controllers//.mdx` (controllers) + +## Authoring surface: per-unit MDX + +Long-form documentation lives in the per-unit MDX file at the unit's root, not in JSDoc above story exports. The MDX file is the source of truth for the Docs page layout and prose. + +### File template + +```mdx +import { Canvas, Meta } from '@storybook/addon-docs/blocks'; +import { DocsFooter, DocsHeader } from '../../.storybook/blocks'; // components +// or '../../../.storybook/blocks' for patterns +// or '../../../swc/.storybook/blocks' for controllers + +import * as Stories from './stories/.stories'; + + + + + +## Anatomy + +...prose... + + + +## Options + +### Sizes + +...prose... + + + +## States + +### States + +...prose... + + + +## Behaviors + +### Text wrapping + +...prose... + + + +## Upcoming features + +...prose only, no Canvas... + +## Accessibility + +...prose with `### Features` and `### Best practices` subheadings... + + + + +``` + +### Canonical section order + +Matches `DocumentTemplate.mdx` so production and per-unit MDX render identically: + +1. **Anatomy** — `hideTitle` semantics: no per-story `###` heading +2. **Upcoming features** — `hideTitle` semantics; prose-only sections allowed (no ``) +3. **Usage** — `hideTitle` semantics (controllers; describes how to instantiate) +4. **Options** — per-story `### Title` headings appear +5. **States** — per-story `### Title` headings appear +6. **Behaviors** — per-story `### Title` headings appear +7. **Accessibility** — `hideTitle` semantics +8. **Full pattern** — per-story `### Title` headings appear (patterns only) +9. **API** — rendered by ``. Controllers ship a hand-authored `## API` ahead of `` with a Methods/Events/Options table; `` omits `` when `meta.tags` contains `'controller'`. +10. **Appendix** — `hideTitle` semantics; prose-only. +11. **Feedback** — rendered by ``. + +### Genre-specific notes + +| Topic | Component | Internal | Pattern | Controller | +| ------------------------------------ | --------------------------- | --------------------------------- | ------------------------------ | ---------------------------------------------------- | +| MDX path | `components//.mdx` | `components//.internal.mdx` | `patterns///.mdx` | `controllers//.mdx` | +| Blocks import path | `'../../.storybook/blocks'` | `'../../.storybook/blocks'` | `'../../../.storybook/blocks'` | `'../../../swc/.storybook/blocks'` | +| Meta tag for `DocsFooter` API branch | `'migrated'` | n/a | n/a | `'controller'` (omits ``) | +| Anatomy section | required (DOM-bearing) | required if applicable | required (DOM-bearing) | omitted (controllers have no DOM) | +| Production build inclusion | yes | no (`.internal.mdx` excluded) | yes | yes (dev) — core docs excluded from production build | + +### Per-story title rules + +Per-story `### Title` headings (in sections with `hideTitle=false`: Options, States, Behaviors, Full pattern) must match the story's rendered name exactly: + +- If the story has an explicit `.storyName = '...'` override, use that exact string. +- Otherwise, use Storybook's PascalCase → Title Case conversion of the export name (each word capitalized). + +Examples: + +| Export name | Rendered title | +| ----------------------------------------------------------------- | ----------------------- | +| `Sizes` | `Sizes` | +| `TextWrapping` | `Text Wrapping` | +| `InActionButton` | `In Action Button` | +| `ActivationModes` | `Activation Modes` | +| `SemanticVariants` with `.storyName = 'Semantic variants'` | `Semantic variants` | +| `NonSemanticVariants` with `.storyName = 'Non-semantic variants'` | `Non-semantic variants` | + +### Single-story sections + +Even when a section has only one story (e.g. a single `States` story called `States`), the `### Title` subheading appears under the `## Section` heading. This matches the `SpectrumStories` block's behavior when `hideTitle=false`. + +### Untagged stories do not appear + +Stories without any section tag (`anatomy`, `options`, `states`, `behaviors`, `a11y`, `upcoming`, `usage`, `appendix`, `full-pattern`, `api`) are not surfaced on the Docs page (subject to the global `'!autodocs'` / `'!dev'` exclusion in `preview.ts`). Do not author a `` for an untagged story in MDX; that would surface content production does not render. ## Documentation structure -Organize documentation into these sections (skip sections that don't apply): +Organize MDX into these sections (skip sections that don't apply): -1. **Overview** - Introduction and primary use case -2. **Anatomy** - Both visual and technical structure -3. **Options** - Configuration, variants, sizes, styles -4. **States** - Different component states -5. **Behaviors** - Methods, events, automatic behaviors -6. **Accessibility** - Features and best practices +1. **Overview** - rendered automatically by `` from the meta JSDoc, subtitle, and Overview story +2. **Anatomy** - Both visual and technical structure (components and patterns) +3. **Usage** - How to instantiate and configure (controllers) +4. **Options** - Configuration, variants, sizes, styles +5. **States** - Different component states +6. **Behaviors** - Methods, events, automatic behaviors +7. **Accessibility** - Features and best practices +8. **Upcoming features** - Roadmap intent (prose only, no Canvas) +9. **API** - Rendered automatically by ``. Controllers hand-author a `## API` section first. +10. **Feedback** - Rendered automatically by ``. -**Note**: Installation instructions and standard documentation sections (Anatomy, Options, States, Behaviors, Accessibility) are programmatically generated by `DocumentTemplate.mdx` and should not be manually added. +The remaining sections of this rule describe the **prose content** for each section. Author that prose inside the per-unit MDX, not as JSDoc above stories. ## Helpers section @@ -84,6 +204,8 @@ const allLabels = { ...semanticLabels, ...colorLabels }; ## Section patterns +> **Where the prose lives.** Each pattern below shows a "prose" block that previously sat in a JSDoc above a story. In the per-unit MDX model, that prose is authored as Markdown inside the corresponding `## Section` / `### Story Title` in the `.mdx` file, immediately above the `` reference. The accompanying story definition has no JSDoc above it. + ### Overview **Purpose**: Quick introduction showing the component in its most common use case. @@ -149,37 +271,40 @@ export const Overview: Story = { **Consolidation rule**: Combine all slotted content combinations into a **single Anatomy story**. -**Pattern**: +**MDX prose** (`## Anatomy` section uses `hideTitle` semantics — no per-story `###`): + +```mdx +## Anatomy + +A component-name consists of: + +1. **Primary element** — main visual component +2. **Secondary element** — additional visual content +3. **Optional indicator** — shown conditionally + +### Content + +#### Slots + +- **Default slot**: primary content (text or HTML) +- **icon slot**: optional icon element +- **description slot**: additional descriptive content + +#### Properties + +Properties that render visual content: + +- **label**: text label displayed by the component +- **icon**: icon identifier to display +- **src**: image source URL +- **value**: displayed value content + + +``` + +**Story definition** (no JSDoc above it): ```typescript -/** - * ### Visual structure - * - * A component-name consists of: - * - * 1. **Primary element** - Main visual component - * 2. **Secondary element** - Additional visual content - * 3. **Optional indicator** - Shown conditionally - * - * ### Technical structure - * - * #### Slots - * - * - **Default slot**: Primary content (text or HTML) - * - **icon slot**: Optional icon element - * - **description slot**: Additional descriptive content - * - * #### Properties - * - * Properties that render visual content: - * - * - **label**: Text label displayed by the component - * - **icon**: Icon identifier to display - * - **src**: Image source URL - * - **value**: Displayed value content - * - * All variations shown below for comparison. - */ export const Anatomy: Story = { render: (args) => html` ${template({ ...args /* minimal */ })} @@ -237,7 +362,6 @@ export const Sizes: Story = { tags: ['options'], parameters: { flexLayout: 'row-wrap', - 'section-order': 1, }, }; ``` @@ -268,7 +392,6 @@ export const SemanticVariants: Story = { tags: ['options'], parameters: { flexLayout: 'row-wrap', - 'section-order': 2, }, }; ``` @@ -299,7 +422,6 @@ export const StaticColors: Story = { parameters: { flexLayout: false, staticColorsDemo: true, - 'section-order': 5, }, }; ``` @@ -748,7 +870,7 @@ After verifying accuracy: 1. Document what was checked in commit message or PR 2. Note any inaccuracies found and fixed -3. Include code references for major claims (in JSDoc comments if helpful) +3. Include code references for major claims (in the per-unit MDX where helpful) 4. Consider creating a verification checklist for complex components ## General guidelines @@ -763,27 +885,33 @@ After verifying accuracy: ### Component linking -When referencing other components in the JSDoc description above meta: +When referencing other components — whether in the meta-level JSDoc, the meta `parameters.docs.subtitle`, or anywhere in the per-unit MDX: -- **Use Storybook paths**: Link to the component's overview story using relative paths -- **Format**: `[ComponentName](../?path=/docs/component-name--readme)` +- **Use Storybook paths**: Link to the component's docs page using relative paths +- **Format**: `[ComponentName](../?path=/docs/components-component-name--docs)` (or `--readme` if that's the convention in your area) - **Component name format**: Use kebab-case in the path (e.g., `action-button`, `progress-circle`) -- **Always link to readme**: Use `--readme` as the story anchor +- **Subtitle exception**: `parameters.docs.subtitle` is plain text and cannot include links. -**Examples**: +**Examples (meta-level JSDoc)**: ```typescript /** * A `` is a non-interactive visual label. For interactive labels, - * see [Action Button](../?path=/docs/action-button--readme). + * see [Action Button](../?path=/docs/components-action-button--docs). */ /** - * Progress circles are commonly used with [Button](../?path=/docs/button--readme) - * and [Card](../?path=/docs/card--readme) components to show loading states. + * Progress circles are commonly used with [Button](../?path=/docs/components-button--docs) + * and [Card](../?path=/docs/components-card--docs) components to show loading states. */ ``` +**Examples (in MDX prose)**: + +```mdx +For interactive labels, see [Action Button](../?path=/docs/components-action-button--docs). +``` + ### Code examples - **Use realistic content** - Avoid placeholder text, use meaningful labels @@ -794,38 +922,56 @@ When referencing other components in the JSDoc description above meta: ### Story organization - **Use flexLayout** for multi-item comparisons -- **Set section-order** to control display order within sections -- **Tag appropriately** - Use correct tags for each section -- **Add JSDoc comments** - Explain what each story demonstrates (except Playground and Overview) +- **Tag appropriately** — use correct tags for each section +- **Order sections in MDX** — section ordering is hand-authored in the per-unit MDX, not via a story parameter +- **Author prose in MDX** — for each tagged story, add a `### Title` heading and prose to the per-unit MDX above the corresponding ``. Do not add JSDoc above story exports. ### No filler closing sentences -Do not end JSDoc comments with sentences that restate what the reader can already see rendered in Storybook, such as: +Do not end MDX prose blocks with sentences that restate what the reader can already see rendered in the Canvas below, such as: - "All sizes shown below for comparison." - "Both variants shown below for comparison." - "Label-only and icon-with-label wrapping shown below for comparison." -These add no information. End the comment when the substantive content ends. +These add no information. End the prose when the substantive content ends. -### JSDoc heading levels +### MDX heading levels -All headings in JSDoc comments must start at level 3 (`###`) or deeper: +All headings inside MDX section prose must start at level 3 (`###`) or deeper: -- **Level 3 (`###`)**: Top-level sections within a story (e.g., "Visual structure", "Features", "Methods") -- **Level 4 (`####`)**: Sub-sections within those sections (e.g., "Slots", "ARIA implementation", "Keyboard navigation") +- **Level 2 (`##`)**: Reserved for top-level sections (`## Anatomy`, `## Options`, etc.) — author these as the section roots in MDX +- **Level 3 (`###`)**: Per-story title in sections with `hideTitle=false` (Options, States, Behaviors, Full pattern) +- **Level 4 (`####`)**: Sub-sections inside per-story prose (e.g., "Slots", "ARIA implementation", "Keyboard navigation") -This ensures proper hierarchy since JSDoc content is rendered within the story context, subordinate to the main section headings in the DocumentTemplate (which use `##`). +This preserves the hierarchy expected by the docs page layout (the unit title is `h1`, section headings are `h2`, story titles are `h3`). ## Checklist When creating or updating documentation: -- [ ] Overview story with common use case -- [ ] JSDoc description above meta (explains component purpose, links to related components) +### Stories file (`.stories.ts`) + +- [ ] Overview story with common use case (tag: `'overview'`) +- [ ] Meta-level JSDoc above `const meta` (explains unit purpose, links to related units) - [ ] `parameters.docs.subtitle` is concise and non-repetitive (plain text, no links) - [ ] Helpers section for shared label mappings and utilities (if applicable) -- [ ] Anatomy with both visual and technical structure +- [ ] Proper story tags for all sections (`anatomy`, `options`, `states`, `behaviors`, `a11y`, `upcoming` as applicable; `controller` on meta for controllers) +- [ ] Playground uses `tags: ['dev']` (not `['autodocs', 'dev']`) when a per-unit MDX exists +- [ ] No story-level JSDoc comments above any `export const` +- [ ] No `section-order` parameter; no `description-only` tag + +### Per-unit MDX (`.mdx`) + +- [ ] File exists at the unit root with the correct relative import path for `DocsHeader` / `DocsFooter` +- [ ] `` declared exactly once +- [ ] `` at the top, `` at the bottom +- [ ] Sections appear in the canonical order (Anatomy → Upcoming features → Usage → Options → States → Behaviors → Accessibility → Full pattern → API → Appendix → Feedback) — skip sections that do not apply +- [ ] Every section-tagged story is referenced via `` +- [ ] Per-story `### Title` headings match Storybook's rendered story names (PascalCase → Title Case, or explicit `storyName`) +- [ ] No `` references to untagged stories +- [ ] Controllers: hand-authored `## API` section ahead of ``; `meta.tags` contains `'controller'` so `` is omitted +- [ ] Anatomy: visual and technical structure documented (components and patterns) - [ ] All slots documented with descriptions - [ ] All content-rendering properties listed - [ ] All configuration options documented @@ -835,10 +981,9 @@ When creating or updating documentation: - [ ] Automatic behaviors explained - [ ] Comprehensive accessibility section with features and best practices - [ ] All examples use accessible, meaningful content -- [ ] Consistent flexLayout usage for comparisons -- [ ] Proper story tags for all sections -- [ ] JSDoc comments for all stories (except Playground and Overview) -- [ ] JSDoc headings start at level 3 (`###`) or deeper + +### Cross-checks + - [ ] **Checked 1st-gen README.md for missing content or differences** - [ ] **Documented 1st-gen differences where apparent (new/changed/removed features)** - [ ] **Verified against component implementation** (no hallucinations) @@ -846,3 +991,4 @@ When creating or updating documentation: - [ ] All properties verified with `@property` decorators - [ ] ARIA attributes verified in component code - [ ] Methods and events verified in implementation +- [ ] Visual parity confirmed against production rendering for converted units diff --git a/.ai/rules/stories-format.md b/.ai/rules/stories-format.md index e1f5fe18137..620aebdc935 100644 --- a/.ai/rules/stories-format.md +++ b/.ai/rules/stories-format.md @@ -1,20 +1,42 @@ --- -description: Enforces consistent file structure, section separators, meta configuration, story tags, layout parameters, and JSDoc conventions for 2nd-gen Storybook stories files. -globs: 2nd-gen/packages/swc/components/*/stories/** +description: Enforces consistent file structure, section separators, meta configuration, story tags, and layout parameters for 2nd-gen Storybook stories files. Story prose lives in per-unit MDX; the stories file is definitions-only. +globs: 2nd-gen/packages/swc/components/*/stories/**, 2nd-gen/packages/swc/patterns/*/*/stories/**, 2nd-gen/packages/core/controllers/*/stories/** alwaysApply: false --- # Storybook stories format standards -Enforce consistent formatting and technical structure for Storybook stories files in 2nd-gen components. +Enforce consistent formatting and technical structure for Storybook stories files in 2nd-gen components, patterns, and controllers. -**See also**: `.ai/rules/stories-documentation.md` for comprehensive guidance on WHAT to document (content, patterns, examples). +**See also**: `.ai/rules/stories-documentation.md` for guidance on WHAT to author in the per-unit MDX (content, patterns, examples). ## Scope -Apply to all `.stories.ts` files in `2nd-gen/packages/swc/components/*/stories/`. +Apply to all `.stories.ts` files in: -**Note**: Component-specific `.usage.mdx` files are no longer needed. The `DocumentTemplate.mdx` automatically renders all documentation sections based on story tags. +- `2nd-gen/packages/swc/components/*/stories/` (components) +- `2nd-gen/packages/swc/patterns/*/*/stories/` (patterns) +- `2nd-gen/packages/core/controllers/*/stories/` (controllers) + +## Source of truth: per-unit MDX, not JSDoc + +Long-form documentation lives in a **per-unit MDX file** at the unit's root, not in JSDoc comments above story exports. + +| Genre | MDX location | +| ---------- | ------------------------------------------- | +| Component | `swc/components//.mdx` | +| Internal | `swc/components//.internal.mdx` | +| Pattern | `swc/patterns///.mdx` | +| Controller | `core/controllers//.mdx` | + +The stories file contains story **definitions** (render, args, tags, parameters). It does **not** carry prose: + +- **Meta-level JSDoc** (above `const meta: Meta = { ... }`) is the only retained JSDoc — it is rendered by the `` block at the top of the docs page. +- **Story-level JSDoc** (above each `export const Foo: Story = ...`) is **not** authored. Prose for each section and story lives in the per-unit MDX alongside an explicit `` reference. + +Stories without a corresponding `` reference in the MDX do not appear on the docs page (subject to the `'!autodocs'` / `'!dev'` global tag exclusion in `preview.ts`). + +Component-specific `.usage.mdx` files are no longer used. Units without a per-unit MDX fall back to `DocumentTemplate.mdx`, which renders sections from story tags via the `SpectrumStories` block. ## File structure @@ -26,7 +48,7 @@ Required structure with visual separators between sections: 2. **Imports** 3. **METADATA** - Meta object with component configuration 4. **HELPERS** - Shared label mappings and utilities (if needed) -5. **AUTODOCS STORY** - Playground story +5. **PLAYGROUND STORY** - Playground story 6. **OVERVIEW STORY** - Emblematic default use case shown on the docs page 7. **ANATOMY STORIES** - Component structure (if applicable) 8. **OPTIONS STORIES** - Variants, sizes, styles @@ -46,7 +68,7 @@ Required structure with visual separators between sections: // ──────────────────── // ──────────────────── -// AUTODOCS STORY +// PLAYGROUND STORY // ──────────────────── // ────────────────────────── @@ -124,23 +146,21 @@ export const Sizes: Story = { }; ``` -### Documentation sections (auto-generated) - -**Component-specific `.usage.mdx` files are no longer needed.** The `DocumentTemplate.mdx` automatically renders all standard documentation sections based on story tags: +### Documentation sections (authored in MDX) -- **Anatomy** (tag: `anatomy`) - Rendered with `hideTitle` -- **Options** (tag: `options`) -- **States** (tag: `states`) -- **Behaviors** (tag: `behaviors`) -- **Accessibility** (tag: `a11y`) - Rendered with `hideTitle` +The per-unit MDX file (`.mdx`) is the source of truth for the docs page layout. Each section is authored as Markdown with an explicit `` reference where a story should render: -Each section only renders if stories with the corresponding tag exist. The template handles: +- **Anatomy** — `## Anatomy` prose + `` +- **Options** — `## Options` heading; for each option story, `### ` + prose + `` +- **States** — same pattern as Options +- **Behaviors** — same pattern as Options +- **Accessibility** — `## Accessibility` prose + `` +- **Upcoming features** — `## Upcoming features` + prose only (no ``) +- **API** — handled by `` (rendered automatically with `` for components and patterns; omitted for controllers) -- Installation instructions (auto-generated) -- Section headers and ordering -- Conditional rendering based on story availability +See `.ai/rules/stories-documentation.md` for full per-section authoring patterns including genre-specific notes (component vs pattern vs controller vs internal). -**What you need to do**: Just tag your stories appropriately. The documentation structure is handled automatically. +**What you need to do**: tag each story by section (`anatomy`, `options`, `states`, `behaviors`, `a11y`), then reference it from the per-unit MDX via ``. ## Meta configuration @@ -259,40 +279,32 @@ The decorator displays two background zones—dark gradient for `static-color="w ## Story ordering -Control display order within sections using `section-order`. Stories sort by lowest value first, then alphabetically for ties or missing values. +Section ordering is hand-authored in each component's per-component MDX file (`.mdx` at the component root). Inside an MDX page, sections appear in the order they are written; story-level parameters do not control rendering order. -```typescript -export const Sizes: Story = { - tags: ['options'], - parameters: { 'section-order': 1 }, -}; - -export const StaticColors: Story = { - tags: ['options'], - parameters: { 'section-order': 10 }, -}; -``` +Do not use a `section-order` parameter on stories. The previous `section-order` workaround is retired now that MDX is the source of truth for documentation layout. ## Tags ### Required tags -| Tag | Usage | -| --------------------- | --------------------------------------------- | -| `'autodocs'`, `'dev'` | Playground story only | -| `'overview'` | Overview story | -| `'anatomy'` | Anatomy stories | -| `'options'` | Variant, size, and style stories | -| `'states'` | State demonstration stories | -| `'behaviors'` | Method, event, and automatic behavior stories | -| `'a11y'` | Accessibility story | -| `'migrated'` | On meta object | +| Tag | Usage | +| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `'dev'` | Playground story only. Drop `'autodocs'` when the unit has a per-unit MDX file (`.mdx`); the MDX is the docs page and `'autodocs'` would create a duplicate Docs entry. | +| `'overview'` | Overview story | +| `'anatomy'` | Anatomy stories | +| `'options'` | Variant, size, and style stories | +| `'states'` | State demonstration stories | +| `'behaviors'` | Method, event, and automatic behavior stories | +| `'a11y'` | Accessibility story | +| `'migrated'` | On meta object (components and patterns) | +| `'controller'` | On meta object (controllers; `DocsFooter` reads this to omit ``) | ### Optional tags -- `'description-only'` - Story contains only descriptive content (no interactive component rendered) - `'upcoming'` - Story demonstrates a feature or variant that is not yet available +> The previous `'description-only'` tag is retired. Prose-only sections live in the per-component MDX (`.mdx`) as Markdown without a `` reference, not as story exports. + ### Exclusion tags - `'!dev'` - Exclude from the development Storybook sidebar without affecting tests @@ -300,52 +312,30 @@ export const StaticColors: Story = { ## Story types +> Story-level JSDoc comments are **not** authored above story exports. Long-form prose lives in the per-unit MDX file. The only JSDoc that remains is the **meta-level JSDoc** above the `const meta: Meta = { ... }` declaration — that prose is read by the `` block at the top of the docs page (rendered via ``). + ### Playground -First story after meta. No JSDoc comment. Set args to the most common use case—this appears as the docs page preview. +First story after meta. No story-level JSDoc. Set args to the most common use case — this appears as the Playground/Controls preview. ```typescript export const Playground: Story = { args: { /* most common use case */ }, - tags: ['autodocs', 'dev'], + tags: ['dev'], }; ``` -**Note**: Use `args` directly (not `render`) when the default render is sufficient. Only use `render: (args) => html` when you need custom rendering. - -Include comprehensive JSDoc comment above the meta object explaining what the component does. - -Every story export must have a JSDoc comment explaining: - -- What it demonstrates -- Any important context or usage notes -- Best practices if relevant - -**Exceptions**: Do NOT add JSDoc comments above the Playground or Overview stories. - -Use markdown formatting within JSDoc: +**Notes:** -- `**Bold**` for emphasis -- Bullet lists for multiple points -- Code formatting with backticks - -```typescript -/** - * A `` is a UI element that displays a **status** or **message**. - */ -export const Playground: Story = { - args: { - /* most common use case */ - }, - tags: ['autodocs', 'dev'], -}; -``` +- Use `args` directly (not `render`) when the default render is sufficient. Only use `render: (args) => html` when you need custom rendering. +- Use `tags: ['dev']` (without `'autodocs'`) when the unit has a per-unit MDX file. The MDX is the Docs page; `'autodocs'` would error with "duplicate docs entry". +- For units without an MDX (still rendering through `DocumentTemplate.mdx`), keep `tags: ['autodocs', 'dev']`. ### Overview -Quick introduction showing the component in its most common use case. No JSDoc comment needed. +Quick introduction showing the component in its most common use case. No story-level JSDoc. Rendered into the docs page header by `` inside ``. ```typescript export const Overview: Story = { @@ -385,7 +375,7 @@ export const Anatomy: Story = { ### Options -Document every attribute/property not covered in Anatomy, States, or Behaviors. Consolidate related options into single stories. Use this order for story section-order: +Document every attribute/property not covered in Anatomy, States, or Behaviors. Consolidate related options into single stories. The recommended canonical order, mirrored in the per-component MDX, is: | Story | Content | | ------------------------- | ------------------------------------------------- | @@ -398,9 +388,6 @@ Document every attribute/property not covered in Anatomy, States, or Behaviors. | `Positioning` | Positioning modifiers (fixed, absolute, relative) | ```typescript -/** - * Components come in multiple sizes to fit various contexts. - */ export const Sizes: Story = { render: (args) => html` ${template({ ...args, size: 's', label: 'Small' })} @@ -411,18 +398,6 @@ export const Sizes: Story = { parameters: { flexLayout: 'row-wrap' }, }; -/** - * Semantic variants provide meaning through color. - * - * Use these variants for the following statuses: - * - * - **Informative**: active, in use, live, published - * - **Neutral**: archived, deleted, paused, draft, not started, ended - * - **Positive**: approved, complete, success, new, purchased, licensed - * - **Notice**: needs approval, pending, scheduled, syncing, indexing, processing - * - **Negative**: error, alert, rejected, failed - * - */ export const SemanticVariants: Story = { render: (args) => html` ${template({ ...args, variant: 'positive' })} @@ -434,9 +409,6 @@ export const SemanticVariants: Story = { tags: ['options'], }; -/** - * Non-semantic variants use color-coded categories. - */ export const NonSemanticVariants: Story = { render: (args) => html` ${template({ ...args, variant: 'seafoam' })} @@ -446,6 +418,8 @@ export const NonSemanticVariants: Story = { }; ``` +Prose for each story (e.g. the description of size choices, semantic variant meanings) lives in the per-unit MDX under `### Sizes`, `### Semantic variants`, etc. + #### Static color pattern For components with a `static-color` attribute, use whichever of these two patterns best fits the component's visual surface: @@ -457,9 +431,6 @@ For components with a `static-color` attribute, use whichever of these two patte 3. **`StaticColors`** - Both variants side-by-side ```typescript -/** - * Use `static-color` for display over images or colored backgrounds. - */ export const StaticBlack: Story = { args: { 'static-color': 'black' }, parameters: { styles: { color: 'black' } }, @@ -488,10 +459,6 @@ export const StaticColors: Story = { **Combined-story pattern** — use when the component has additional dimensions (e.g., fill styles) that are most clearly shown together in a single story. Use structural `
` wrappers instead of `flexLayout` here: the `staticColorsDemo` decorator targets `:first-child` and `:last-child` to apply the dark/light background zones, so the two color groups must be direct children of the render output. ```typescript -/** - * Use `static-color` for display over images or colored backgrounds. - * Both fill styles are shown for each color. - */ export const StaticColors: Story = { render: (args) => html`
html` ${template({ ...args })} ${template({ ...args, selected: true })} @@ -537,9 +501,6 @@ export const States: Story = { Complex states (e.g., animated indeterminate) may warrant separate stories. ```typescript -/** - * Indeterminate state shows unknown progress. - */ export const Indeterminate: Story = { tags: ['states'], args: { @@ -553,9 +514,6 @@ export const Indeterminate: Story = { Document automatic (built-in) behaviors, like text-wrapping, as well as, all methods, and all events. ```typescript -/** - * Long text automatically wraps to multiple lines. - */ export const TextWrapping: Story = { render: (args) => html` ${template({ 'default-slot': 'Long text that wraps to multiple lines' })} @@ -566,44 +524,32 @@ export const TextWrapping: Story = { ### Accessibility -Required for every component. Document features and best practices. +Required for every component. Document features and best practices in the per-unit MDX (`## Accessibility` section). ```typescript -/** - * ### Features - * The `` element implements several accessibility features: - * - * 1. **Feature name**: Description (e.g., keyboard navigation, ARIA states, roles, properties) - * 2. **Feature name**: Description - * - * ### Best practices - * - * - Best practice, such as, "Always provide a descriptive label" - * - Best practice, such as, "Ensure sufficient color contrast" - */ export const Accessibility: Story = { tags: ['a11y'], }; ``` -## JSDoc requirements +The Accessibility features list and best practices for the unit live in `## Accessibility` in the per-unit MDX, not above this story export. -Every story export requires a JSDoc comment explaining what it demonstrates, **except Playground**. +## JSDoc requirements -Use markdown formatting: +Only the **meta-level JSDoc** above the `const meta: Meta = { ... }` declaration is authored. It is rendered by the `` block at the top of the docs page (inside ``). It should describe the component's purpose, primary use case, and link to related components. -- `**Bold**` for emphasis -- Bullet lists for multiple points -- Backticks for code +Do **not** add JSDoc comments above any individual `export const Foo: Story = ...` declaration. Story prose lives in the per-unit MDX file alongside the corresponding `` reference. ```typescript /** - * Semantic variants provide meaning through color: - * - **Positive**: approved, complete, success - * - **Negative**: error, alert, rejected + * A `` is a non-interactive visual label that displays a status, + * category, or attribute. For interactive labels, see + * [Button](../?path=/docs/button--docs). */ -export const SemanticVariants: Story = { - /* ... */ +const meta: Meta = { + title: 'Badge', + component: 'swc-badge', + // ... }; ``` @@ -699,8 +645,11 @@ See `asset.stories.ts` for complete examples. ### ❌ Don't -- Add JSDoc to Playground or Overview story -- Use 'usage' tag (deprecated) +- Add JSDoc above any individual story export (Playground, Overview, or any other) +- Use the `'usage'` tag for new units (deprecated) +- Use the `'description-only'` tag (retired — prose-only sections live in MDX) +- Use the `'section-order'` parameter (retired — section order is hand-authored in MDX) +- Use `tags: ['autodocs', 'dev']` on a unit that has a per-unit MDX file (creates a duplicate Docs entry — use `['dev']`) - Omit `subtitle` in meta parameters - Use placeholder text - Demonstrate inaccessible patterns @@ -709,26 +658,30 @@ See `asset.stories.ts` for complete examples. - Tag stories correctly: `anatomy`, `options`, `states`, `behaviors`, `a11y` - Use `flexLayout: 'row-wrap'` for multi-item stories -- Include comprehensive JSDoc (except Playground and Overview) +- Author all story prose in the per-unit MDX file (`.mdx`) +- Keep the meta-level JSDoc above `const meta` — it drives the `` block at the top of the docs page - Use meaningful, realistic content -- Let the DocumentTemplate handle section rendering automatically +- Reference each tagged story from MDX via `` ## Checklist -- [ ] Copyright header (2025) +- [ ] Copyright header (current year) - [ ] Visual separators between sections -- [ ] Meta: title, component, args, argTypes, render, `parameters.docs.subtitle`, `tags: ['migrated']` +- [ ] Meta: title, component, args, argTypes, render, `parameters.docs.subtitle`, `tags: ['migrated']` (or `'controller'`) - [ ] `title` uses sentence case, no filename labels, group is not a single-component wrapper - [ ] Meta JSDoc description above meta object (with component links if applicable) - [ ] Subtitle is concise and non-repetitive (plain text only, no links) -- [ ] Playground: `['autodocs', 'dev']` tags, no JSDoc, common use case args +- [ ] Playground: `['dev']` tag when an MDX exists (or `['autodocs', 'dev']` for template-only fallback), no JSDoc, common use case args - [ ] Overview: `['overview']` tag, common use case args, no JSDoc on story itself - [ ] Anatomy: all slots + content properties, `['anatomy']` tag, `flexLayout: 'row-wrap'` - [ ] Options: all uncovered attributes, `['options']` tag, `flexLayout: 'row-wrap'` - [ ] States: consolidated states, `['states']` tag, `flexLayout: 'row-wrap'` (if applicable) - [ ] Behaviors: `['behaviors']` tag (if applicable) -- [ ] Accessibility: features + best practices, `['a11y']` tag +- [ ] Accessibility: `['a11y']` tag (prose lives in MDX) - [ ] Static colors: three-story or combined-story pattern with `staticColorsDemo` (if applicable) -- [ ] Story order: `section-order` parameter where needed +- [ ] No story-level JSDoc comments above any `export const` +- [ ] No `section-order` parameter on any story +- [ ] No `description-only` tag on any story - [ ] All stories accessible with meaningful content - [ ] Image assets: use `picsum.photos` with static IDs (if applicable) +- [ ] Per-unit MDX file exists at the unit root and references each section-tagged story via `` (see `.ai/rules/stories-documentation.md`) diff --git a/.ai/scripts/validate-story-tags.js b/.ai/scripts/validate-story-tags.js index a7f76f9c74b..9952d6e53a5 100644 --- a/.ai/scripts/validate-story-tags.js +++ b/.ai/scripts/validate-story-tags.js @@ -43,7 +43,6 @@ const ALLOWED_TAGS = new Set([ 'dev', 'utility', 'upcoming', - 'description-only', '!test', '!dev', '!autodocs', diff --git a/.ai/skills/documentation/SKILL.md b/.ai/skills/documentation/SKILL.md index 8a375617a2e..ddc4d3d1a2a 100644 --- a/.ai/skills/documentation/SKILL.md +++ b/.ai/skills/documentation/SKILL.md @@ -13,8 +13,9 @@ You are a technical writer. Documentation is a product, not an afterthought. Wri ## When to Use This Skill -- Designing and writing story documentation (i.e. JSDoc comments) for Storybook -- Updating documentation for 1st-gen documentation site +- Authoring 2nd-gen Storybook docs pages (per-unit MDX in `.mdx`) +- Writing JSDoc on public APIs (`Component.ts`, the meta-level JSDoc above `const meta`) +- Updating documentation for the 1st-gen documentation site - Writing any documentation that is shipped to external consumers - Creating documentation that is internal - Developing a changeset for a pull request @@ -37,7 +38,14 @@ The `` element contains a list of items that can be expanded or co ## Key patterns -Most often, documentation is written in Markdown or JSDoc formats. +Most often, documentation is written in Markdown (including MDX for Storybook docs pages) or JSDoc (for public APIs). + +For 2nd-gen Storybook documentation specifically: + +- **Per-unit docs page**: authored as a Markdown / MDX file (`.mdx`) at the unit's root. This is the docs surface for components, internal components, patterns, and controllers. See [`.ai/rules/stories-documentation.md`](../../rules/stories-documentation.md) for the per-unit MDX authoring template and conventions. +- **Public-API JSDoc**: authored on `@property`, `@slot`, public methods, dispatched events, etc. in `Component.ts`. This is read by the Custom Elements Manifest and rendered into Storybook's API table. +- **Meta-level JSDoc**: a single JSDoc above `const meta: Meta = { ... }` in the stories file. Rendered by `` at the top of the docs page. +- Story-level JSDoc (above individual `export const Foo: Story = ...`) is **not** used in 2nd-gen. Prose for each story lives in the per-unit MDX next to the corresponding `` reference. ### Markdown syntax reference diff --git a/.ai/skills/migration-documentation/SKILL.md b/.ai/skills/migration-documentation/SKILL.md index 7fe41e16d44..c2e633ece3a 100644 --- a/.ai/skills/migration-documentation/SKILL.md +++ b/.ai/skills/migration-documentation/SKILL.md @@ -1,20 +1,26 @@ --- name: migration-documentation description: - Phase 7 of 1st-gen to 2nd-gen component migration. Use to write JSDoc, - Storybook stories, and usage docs so the component is usable and - understandable by others. + Phase 7 of 1st-gen to 2nd-gen component migration. Use to author the + per-component MDX docs page and finalize Storybook stories so the + component is usable and understandable by others. --- # Migration documentation ([Phase 7](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) -[Phase 7](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is JSDoc on the public API and Storybook stories covering the main use cases. +[Phase 7](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is the per-component MDX docs page (`.mdx`) authored to render every Storybook section with prose and `` references, plus JSDoc on the public API exposed by `Component.ts` (the source class). -See also: [`documentation`](../documentation/SKILL.md) for Adobe content writing standards to follow when writing usage docs. +See also: + +- [`documentation`](../documentation/SKILL.md) — Adobe content writing standards +- [`.ai/rules/stories-format.md`](../../rules/stories-format.md) — stories file structure +- [`.ai/rules/stories-documentation.md`](../../rules/stories-documentation.md) — per-unit MDX authoring patterns ## Mindset -You are writing for the next contributor, not for yourself. Every story and JSDoc line should answer the question a new engineer would ask six months from now. Avoid restating the implementation. Explain the intent and the constraints. Be sure to follow the `documentation` skill for writing style and content expectations. +You are writing for the next contributor, not for yourself. Every MDX section and JSDoc line on a public API member should answer the question a new engineer would ask six months from now. Avoid restating the implementation. Explain the intent and the constraints. Follow the `documentation` skill for writing style and content expectations. + +**Where prose lives**: long-form documentation for Storybook is authored in the **per-component MDX file** (`2nd-gen/packages/swc/components/[component]/[component].mdx`), not in JSDoc comments above story exports. JSDoc above story exports is not used in 2nd-gen. The only JSDoc retained in the stories file is the meta-level JSDoc above `const meta: Meta = { ... }`, which is rendered by the `` block at the top of the docs page. Read the migration plan at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component]/migration-plan.md` when available before documenting the component. Use it to understand constraints, behavioral decisions, and deferred work. If it is missing, stale, or intentionally incomplete, derive the needed context from the implemented component and source material and call out the missing plan as a risk. See also [`migration-plan-contract`](../migration-prep/references/migration-plan-contract.md). @@ -22,8 +28,7 @@ Read the migration plan at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[ - Phase 6 (migration-testing) is complete - The user asks to "document [component]" or "add stories for [component]" -- The user asks to write JSDoc, add Storybook stories, or document migration - notes +- The user asks to author the per-component MDX file, add Storybook stories, or document migration notes - The user refers to "Phase 7" of the 2nd-gen component migration workstream ## When NOT to use @@ -43,7 +48,7 @@ Read the migration plan at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[ ### Step 0: Check the migration plan documentation checklist -Before writing anything, read the `### Documentation` section of the migration plan at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component]/migration-plan.md`. Make a note of every unchecked item. These are the documentation gaps Phase 7 must close. Return to this checklist at the end and confirm which items are now covered by stories JSDoc and which remain outstanding. +Before writing anything, read the `### Documentation` section of the migration plan at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component]/migration-plan.md`. Make a note of every unchecked item. These are the documentation gaps Phase 7 must close. Return to this checklist at the end and confirm which items are now covered by the per-component MDX (or by JSDoc on the public API in `Component.ts`) and which remain outstanding. ### Step 1: Ask for guidance resources @@ -54,27 +59,21 @@ Before writing any "when to use" or "why to use" descriptions for sizes, variant - The 1st-gen component README (`1st-gen/packages/[component]/README.md`) - An explicit statement in the migration plan -If no source is available at authoring time, limit JSDoc to technically verifiable facts only (see [What NOT to include](#what-not-to-include-in-stories-jsdoc) below). Do not invent guidance. Implementors cannot easily distinguish AI-invented guidance from documented design decisions, which erodes trust in the documentation. +If no source is available at authoring time, limit the prose to technically verifiable facts only (see [What NOT to include](#what-not-to-include-in-mdx-or-jsdoc) below). Do not invent guidance. Implementors cannot easily distinguish AI-invented guidance from documented design decisions, which erodes trust in the documentation. ### Step 2: Check for a Phase 5 stories scaffold -If Phase 5 (migration-styling) was completed, `2nd-gen/packages/swc/components/[component]/stories/[component].stories.ts` likely already exists with Playground, Overview, Anatomy, Options, States, and Behaviors stories — all structurally correct but without JSDoc prose. Phase 7's job is to: +If Phase 5 (migration-styling) was completed, `2nd-gen/packages/swc/components/[component]/stories/[component].stories.ts` likely already exists with Playground, Overview, Anatomy, Options, States, and Behaviors stories — all structurally correct, no story-level JSDoc, and the Accessibility story body left as a `// TODO` comment. Phase 7's job is to: -1. Add JSDoc comments to every story (except Playground and Overview, which have none by convention). -2. Complete the Accessibility story body — it was left as a `// TODO` comment in Phase 5. -3. Add any stories that were deferred or were not CSS-visible enough to include in Phase 5. -4. For each item in the migration plan's Additive table: - - If the feature is implemented and has no story yet, add it as a normal - story in the relevant section (Options, Behaviors, etc.). - - If the feature is not yet implemented, add it to an `UpcomingFeatures` - story (tag: `['upcoming', 'description-only']`). Keep it brief and - bullet-point style — the goal is to signal roadmap intent, not explain - scope decisions. Write from a consumer's perspective (what it does for - them) and omit internal framing like "not part of the initial scope" or - "deferred pending a decision". Do not include ticket numbers or TODO - language. +1. Create (or augment) `2nd-gen/packages/swc/components/[component]/[component].mdx` as the per-component docs page — see [`stories-documentation`](../../rules/stories-documentation.md) for the full template, including the canonical section order, required imports, `` / `` placement, and per-section authoring patterns. +2. Author the prose for each section (`## Anatomy`, `## Options`, `## States`, `## Behaviors`, `## Accessibility`) in the per-component MDX, with a `` reference under each `### Story Title` heading (for `hideTitle=false` sections) or directly under the `## Section` heading (for `hideTitle=true` sections like Anatomy and Accessibility). +3. Complete the Accessibility story body in the stories file — it was left as a `// TODO` in Phase 5. Add the Features / Best practices prose into `## Accessibility` in the MDX. +4. Add any stories that were deferred or were not CSS-visible enough to include in Phase 5. For each new story, add a `` reference and accompanying prose to the MDX. +5. For each item in the migration plan's Additive table: + - If the feature is implemented and has no story yet, add a story in the relevant section (Options, Behaviors, etc.) and reference it from the MDX with a ``. + - If the feature is not yet implemented, add an `## Upcoming features` section to the per-component MDX with bullet-point prose describing the roadmap intent. Do **not** create a story export to hang the prose on — MDX renders prose-only sections directly without a story. Keep it brief and consumer-focused (what it does for them); omit internal framing like "not part of the initial scope" or "deferred pending a decision". Do not include ticket numbers or TODO language. -If the stories document already exists, do **not** recreate the file from scratch. Augment what is already there. +If the stories file or the per-component MDX already exists, do **not** recreate them from scratch. Augment what is already there. Follow **[Phase 7: Documentation](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-7-documentation)** @@ -83,27 +82,35 @@ common problems, and the quality gate for this phase. If the docs need to describe behavior that differs from the approved migration plan, follow [`migration-plan-contract`](../migration-prep/references/migration-plan-contract.md). -### Step 3: Write story JSDoc +### Step 3: Write the per-component MDX prose and finalize JSDoc on `Component.ts` + +Author the prose for each section in the per-component MDX following the patterns in [`stories-documentation`](../../rules/stories-documentation.md). Drop the `'autodocs'` tag from the Playground story (keep `'dev'`) so the MDX is the unit's Docs page rather than a duplicate. -Follow the rules in [What NOT to include](#what-not-to-include-in-stories-jsdoc) strictly. Write JSDoc that is technically accurate and sourced. Where no source is available for usage guidance, describe what the attribute does (its effect) rather than when to use it. +Then add or update JSDoc on the public API surface in `2nd-gen/packages/swc/components/[component]/Component.ts` — `@property` decorators, public methods, dispatched events, slots. This is the developer-facing API doc that the `` block renders from the Custom Elements Manifest. It is **not** the same as story-level JSDoc (which is not used). + +Follow the rules in [What NOT to include](#what-not-to-include-in-mdx-or-jsdoc) strictly. Write prose and JSDoc that is technically accurate and sourced. Where no source is available for usage guidance, describe what the attribute does (its effect) rather than when to use it. ### Step 4: Cross-check against the documentation checklist Return to the list from Step 0. For each unchecked documentation item in the migration plan: -- If it is now covered by a story or JSDoc comment, note it as done. -- If it belongs in the consumer migration guide (breaking changes, migration paths from 1st-gen), note it as deferred to the `consumer-migration-guide` skill — do **not** add it to the stories file. -- If it is genuinely missing from both stories and the consumer guide, flag it to the user. +- If it is now covered by an MDX section, a Canvas reference, or a JSDoc comment on the public API in `Component.ts`, note it as done. +- If it belongs in the consumer migration guide (breaking changes, migration paths from 1st-gen), note it as deferred to the `consumer-migration-guide` skill — do **not** add it to the per-component MDX or the stories file. +- If it is genuinely missing from both the docs and the consumer guide, flag it to the user. --- -## What NOT to include in stories JSDoc +## What NOT to include in MDX or JSDoc + +The following must never appear in the per-component MDX, in the meta-level JSDoc, or in JSDoc on the public API in `Component.ts`: + +### Story-level JSDoc -The following must never appear in `.stories.ts` files: +Do not author JSDoc comments above any `export const Foo: Story = ...` declaration in `.stories.ts` files. Story prose lives in the per-component MDX. The only JSDoc retained in the stories file is the meta-level JSDoc above `const meta: Meta = { ... }` (rendered by `` at the top of the docs page). ### Migration notes -Do not include "Migration note:", "replaces legacy X", or "1st-gen vs 2nd-gen" content in story JSDoc. Migration guidance is for developers upgrading from 1st-gen and belongs in the dedicated consumer migration guide produced by the `consumer-migration-guide` skill. Stories are consumed by all users of the component, not only by people migrating. +Do not include "Migration note:", "replaces legacy X", or "1st-gen vs 2nd-gen" content in the per-component MDX or in stories-file JSDoc. Migration guidance is for developers upgrading from 1st-gen and belongs in the dedicated consumer migration guide produced by the `consumer-migration-guide` skill. The Storybook docs page is consumed by all users of the component, not only by people migrating. ### Invented usage guidance diff --git a/.ai/skills/migration-styling/SKILL.md b/.ai/skills/migration-styling/SKILL.md index 8d2f1ea906d..790da163d8d 100644 --- a/.ai/skills/migration-styling/SKILL.md +++ b/.ai/skills/migration-styling/SKILL.md @@ -55,7 +55,7 @@ Then use the `rendering-and-styling-migration-analysis.md` file for the componen - **If it exists**, confirm it renders the component in Storybook with no console errors before touching CSS. - **If it does not exist**, create it now using [`assets/stories-template.md`](assets/stories-template.md) before starting CSS work. Follow the template's "Decisions to make" section and its checklist. -**Phase 5 stories scope** — the stories file at this phase should contain: Playground, Overview, Anatomy, Options (one story per constant array in the types file), States, and any Behaviors that exercise CSS-visible properties. Do **not** add JSDoc prose to stories and do **not** write the Accessibility story body — these are deferred to Phase 7. Leave a `// TODO` comment referencing that phase. +**Phase 5 stories scope** — the stories file at this phase should contain: Playground, Overview, Anatomy, Options (one story per constant array in the types file), States, and any Behaviors that exercise CSS-visible properties. Do **not** add story-level JSDoc and do **not** write the Accessibility story body — these are deferred to Phase 7, which authors the per-component MDX file (`.mdx`) as the docs surface. Leave a `// TODO` comment referencing Phase 7. **Step 3 — Align render template class names with CSS selectors.** Before writing CSS, read the component's `render()` method and note every class name emitted. The CSS you write must use those exact names. Mismatches cause styles to silently not apply — there is no error. diff --git a/.ai/skills/migration-styling/assets/stories-template.md b/.ai/skills/migration-styling/assets/stories-template.md index 20f28156641..234f969ad86 100644 --- a/.ai/skills/migration-styling/assets/stories-template.md +++ b/.ai/skills/migration-styling/assets/stories-template.md @@ -1,6 +1,6 @@ # Phase 5 stories template -A minimal `[component].stories.ts` file for visual verification of 2nd-gen CSS during Phase 5. Full JSDoc and the Accessibility story are deferred — JSDoc belongs to Phase 7 (Documentation); the Accessibility story belongs to the accessibility phase. +A minimal `[component].stories.ts` file for visual verification of 2nd-gen CSS during Phase 5. The per-component MDX file (`[component].mdx`) and the Accessibility story body are deferred to Phase 7 (Documentation). No story-level JSDoc is authored in 2nd-gen — prose lives in the per-component MDX. ## What to replace @@ -183,7 +183,8 @@ export const Anatomy: Story = { // ────────────────────────── // One story per distinct constant array in the types file (sizes, variants, -// fill styles, static colors, etc.). Add section-order to control display order. +// fill styles, static colors, etc.). Section ordering is hand-authored in the +// per-component MDX file, not via story parameters. export const Sizes: Story = { render: (args) => html` @@ -191,7 +192,6 @@ export const Sizes: Story = { template({ ...args, size, 'default-slot': sizeLabels[size] }) )} `, - parameters: { 'section-order': 1 }, tags: ['options'], }; @@ -201,7 +201,6 @@ export const Variants: Story = { template({ ...args, variant, 'default-slot': variantLabels[variant] }) )} `, - parameters: { 'section-order': 2 }, tags: ['options'], }; Variants.storyName = 'Variants'; // rename if PascalCase doesn't read as sentence case (e.g. 'Semantic variants', 'Non-semantic variants') diff --git a/2nd-gen/packages/swc/.storybook/blocks/SpectrumStories.tsx b/2nd-gen/packages/swc/.storybook/blocks/SpectrumStories.tsx index bccff395122..5d228859f84 100644 --- a/2nd-gen/packages/swc/.storybook/blocks/SpectrumStories.tsx +++ b/2nd-gen/packages/swc/.storybook/blocks/SpectrumStories.tsx @@ -8,7 +8,7 @@ import React, { Fragment } from 'react'; /** * A block that renders all stories tagged with a specified tag from the component's stories file. - * Stories are rendered in definition order (using story id which includes definition index). + * Stories are rendered in definition order. * * @param of - The Storybook meta or story to resolve the component from * @param tag - The story tag to filter by (e.g., "usage", "a11y", "examples") @@ -25,36 +25,19 @@ export const SpectrumStories = ({ }) => { const resolvedOf = useOf(of || 'meta', ['meta']); - // Get stories and filter by tag - let taggedStories = Object.values(resolvedOf.csfFile.stories).filter( + const taggedStories = Object.values(resolvedOf.csfFile.stories).filter( (story: any) => story.tags?.includes(tag) ); - const descriptionOnlyStories = taggedStories.filter((story: any) => - story.tags?.includes('description-only') - ); - - // Sort by explicit order if provided, otherwise preserve current order - taggedStories = taggedStories.sort((a: any, b: any) => { - const aIndex = a.parameters['section-order'] ?? taggedStories.length; - const bIndex = b.parameters['section-order'] ?? taggedStories.length; - // Stories not in order array go to the end - return aIndex - bIndex; - }); - if (taggedStories.length === 0) { return null; } - const spectrumStories = taggedStories.map((story: any) => ( + return taggedStories.map((story: any) => ( {!hideTitle && {`### ${story.name}`}} - {!descriptionOnlyStories.includes(story) && ( - - )} + )); - - return spectrumStories; }; diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/07_add-stories-for-2nd-gen-component.md b/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/07_add-stories-for-2nd-gen-component.md index 93ba13df29f..6ef1d7da059 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/07_add-stories-for-2nd-gen-component.md +++ b/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/07_add-stories-for-2nd-gen-component.md @@ -36,10 +36,10 @@ Use the `migration-styling` skill's [`assets/stories-template.md`](../../../../. **Phase 4 scope:** -- Playground (`tags: ['autodocs', 'dev']`) +- Playground (`tags: ['dev']`; omit `'autodocs'` when the component has a per-component MDX file) - Overview (`tags: ['overview']`) - Anatomy — shows all meaningful slot combinations (`tags: ['anatomy']`) -- Options — one story per constant array in the types file (`tags: ['options']`), with `section-order`, `storyName` where needed, and `staticColorsDemo: true` + `'!test'` for static colors +- Options — one story per constant array in the types file (`tags: ['options']`), with `storyName` where needed, and `staticColorsDemo: true` + `'!test'` for static colors. Section ordering is hand-authored in the per-component MDX, not via story parameters. - States — all interactive states (`tags: ['states']`) - Behaviors — properties that produce CSS-visible differences (`tags: ['behaviors']`) - Accessibility section — `// TODO` comment only diff --git a/CONTRIBUTOR-DOCS/03_project-planning/README.md b/CONTRIBUTOR-DOCS/03_project-planning/README.md index c9d9fc827a7..4bbf025e26c 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/README.md +++ b/CONTRIBUTOR-DOCS/03_project-planning/README.md @@ -77,8 +77,6 @@ - [Milestones](04_milestones/README.md) - Strategies - [Focus Management Strategy: 2nd-Gen Proposal](05_strategies/focus-management-strategy-rfc.md) -- Initiatives - - Decisions diff --git a/CONTRIBUTOR-DOCS/README.md b/CONTRIBUTOR-DOCS/README.md index 11f57d94f86..ab34fd58c88 100644 --- a/CONTRIBUTOR-DOCS/README.md +++ b/CONTRIBUTOR-DOCS/README.md @@ -43,7 +43,6 @@ - [Components](03_project-planning/03_components/README.md) - [Milestones](03_project-planning/04_milestones/README.md) - Strategies - - Initiatives