Per-unit MDX authoring procedure
This skill holds the full procedure. The always-apply constraints are in .ai/rules/stories-documentation.md, which loads automatically for matching files.
Documentation structure
Organize MDX into these sections (skip sections that don't apply):
- Overview - rendered automatically by
<DocsHeader />from the meta JSDoc, subtitle, and Overview story - Anatomy - A flat, unordered list of the component's parts, with slot names called out inline where needed (components and patterns)
- Usage - How to instantiate and configure (controllers)
- Options - Configuration, variants, sizes, styles
- States - Different component states
- Behaviors - Methods, events, automatic behaviors
- Accessibility - Features and best practices
- Upcoming features - Roadmap intent (prose only, no Canvas)
- API - Rendered automatically by
<DocsFooter />. Controllers hand-author a## APIsection first. - Feedback - Rendered automatically by
<DocsFooter />.
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
Purpose: Organize shared code, label mappings, and utilities used across multiple stories.
Location: Between export default meta and first story (Playground/Autodocs).
When to use:
- Component has multiple variants, sizes, or options that need consistent labels
- Stories require reusable label mappings or data structures
- Complex rendering logic needs to be shared across stories
Pattern:
// ────────────────────
// HELPERS
// ────────────────────
// Label mappings for sizes
const sizeLabels = {
s: 'Small',
m: 'Medium',
l: 'Large',
xl: 'Extra-large',
} as const satisfies Record<ComponentSize, string>;
// Label mappings for semantic variants
const semanticLabels = {
positive: 'Approved',
negative: 'Rejected',
informative: 'Active',
neutral: 'Archived',
notice: 'Pending',
} as const satisfies Record<SemanticVariant, string>;
// Combined label objects for convenience
const allLabels = { ...semanticLabels, ...colorLabels };
Key principles:
- Use TypeScript
as const satisfiesfor type-safe label mappings - Group related helpers together (size labels, variant labels, etc.)
- Use clear, descriptive constant names (
sizeLabels, notlabels) - Provide realistic, meaningful labels (not "Label 1", "Label 2")
When NOT to use:
- Component has only 1-2 options (no need for label mappings)
- Labels are self-explanatory (e.g., true/false)
- Stories don't share any common code
Section patterns
Where the prose lives. Each pattern below shows a "prose" block. Author that prose as Markdown inside the corresponding
## Section/### Story Titlein the<unit>.mdxfile, immediately above the<Canvas of={Stories.MyStory} />reference. The accompanying story definition has no JSDoc above it.
Overview
Purpose: Quick introduction showing the component in its most common use case.
Documentation: The Overview story content comes from two sources:
JSDoc description above meta: Provides the main description of what the component does and when to use it. This description:
- Is displayed as the primary documentation for the Overview story
- Can include markdown formatting and links to other components
- Should reference other components using Storybook paths:
[Badge](../?path=/docs/components-badge--docs) - Should provide fuller context than the subtitle
parameters.docs.subtitle: Provides a brief summary displayed as the subtitle. This subtitle:- Cannot include links (plain text only)
- Should be concise and to-the-point
- Should not repeat the JSDoc description verbatim
- Complements the JSDoc description
Pattern:
/**
* A badge is a non-interactive visual label that displays a status, category, or attribute.
* Badges can be used to highlight important information or to categorize items. For interactive
* labels, see [Button](../?path=/docs/components-button--docs).
*/
const meta: Meta = {
title: 'Badge',
component: 'swc-badge',
args,
argTypes,
render: (args) => template(args),
parameters: {
docs: { subtitle: `Visual label for status, category, or attribute` },
// ... other parameters
},
tags: ['migrated'],
};
export default meta;
// ... HELPERS section if needed ...
export const Overview: Story = {
tags: ['overview'],
args: {
// Most common/representative configuration
},
};
Note: the Overview story renders into the docs page header via <OverviewStory /> inside <DocsHeader />. The meta-level JSDoc (above const meta) and the parameters.docs.subtitle provide the surrounding prose; the Overview story itself just supplies the canvas.
Anatomy
Purpose: Give the reader a mental model of the component's parts in plain language. Anatomy is not a second copy of the API table: the generated <ApiTable /> (rendered by <DocsFooter />) already lists every slot and property from source with type and description. Anatomy should not duplicate it.
Required content:
- A flat, unordered list of the component's visual parts
- Slot names are called out inline only in places where a reader needs to know a piece of content comes from a slot (so they write it as markup) rather than a property (so they write it as an attribute); not a separate slot inventory
- Visual examples showing structure
Consolidation rule: Combine all slotted content combinations into a single Anatomy story.
MDX prose (## Anatomy section uses hideTitle semantics: no per-story ###, and no ###/#### subsections of any kind):
## Anatomy
A component-name consists of:
- **Primary element**: main visual component
- **Secondary element**, provided via the `icon` slot
- **Optional indicator**: shown conditionally
<Canvas of={Stories.Anatomy} />
Story definition (no JSDoc above it):
export const Anatomy: Story = {
render: (args) => html`
${template({ ...args /* minimal */ })}
${template({ ...args /* with icon */ })}
${template({ ...args /* with additional content */ })}
`,
tags: ['anatomy'],
parameters: {
flexLayout: 'row-wrap',
},
};
Key principles:
- Use a flat, unordered list of parts. Never a numbered list: there is no numbered diagram for the numbers to key off of, and it reads oddly for single-part components. Never
###/####subsections (e.g. no "Content", "Slots", or "Properties" headings). Doing so re-creates the API table by hand and drifts out of sync with it. - Name a slot inline in the parts list only when a reader needs to know content is passed as a slot rather than a property to compose it correctly
- Don't re-list content-rendering properties that are already visible in the rendered example or covered by the API table
- Show all meaningful combinations in one story
Options
Purpose: Document every attribute or property not covered in Anatomy, States, or Behaviors.
Order: Sizes → Semantic variants → Non-semantic variants → Quiet/Subtle/Emphasized → Outline → Static color → Positioning → Other options
Consolidation rules:
- All sizes → single
Sizesstory - All semantic variants → single
SemanticVariantsstory - All non-semantic variants → single
NonSemanticVariantsstory
Layout requirement: Use flexLayout: 'row-wrap' for stories displaying multiple variations.
Pattern for sizes:
### Sizes
Component-names come in [X] sizes to fit various contexts:
- **Small (`s`)**: Used for inline indicators or space-constrained areas
- **Medium (`m`)**: Default size, used for typical use cases
- **Large (`l`)**: Used for prominent displays or primary content areas
- **Extra-large (`xl`)**: Maximum visibility (if applicable)
All sizes shown below for comparison.
<Canvas of={Stories.Sizes} />
export const Sizes: Story = {
render: (args) => html`
${template({ ...args, size: 's', label: 'Small' })}
${template({ ...args, size: 'm', label: 'Medium' })}
${template({ ...args, size: 'l', label: 'Large' })}
`,
tags: ['options'],
parameters: {
flexLayout: 'row-wrap',
},
};
Pattern for semantic variants:
### Semantic variants
Semantic variants provide meaning through color:
- **`accent`**: New, beta, prototype, draft
- **`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
- **`negative`**: Error, alert, rejected, failed
All semantic variants shown below for comparison.
<Canvas of={Stories.SemanticVariants} />
export const SemanticVariants: Story = {
render: (args) => html`
${template({ ...args, variant: 'positive', label: 'Positive' })}
${template({ ...args, variant: 'informative', label: 'Informative' })}
${template({ ...args, variant: 'negative', label: 'Negative' })}
${template({ ...args, variant: 'neutral', label: 'Neutral' })}
${template({ ...args, variant: 'notice', label: 'Notice' })}
`,
tags: ['options'],
parameters: {
flexLayout: 'row-wrap',
},
};
SemanticVariants.storyName = 'Semantic variants';
Pattern for static color: sourced from Spectrum's static color usage guidance (e.g. Button). The component's color pins to the chosen value regardless of the active theme, and the choice of value depends on the background it sits over.
Use `static-color` when the component-name needs to sit on top of a photo or colored background. It pins the component-name's color to the chosen value regardless of the active color theme:
- **`white`**: use on dark color or image backgrounds
- **`black`**: use on light color or image backgrounds
export const StaticColors: Story = {
render: (args) => html`
${['white', 'black'].map(
(color) => html`
${template({ ...args, 'static-color': color })}
`
)}
`,
args: {
label: 'Loading',
},
tags: ['options', '!test'],
parameters: {
flexLayout: false,
staticColorsDemo: true,
},
};
States
Purpose: Document all possible states the component can be in.
Order: Default → Selected → Active → Disabled → Readonly → Error → Loading/Pending/Indeterminate → Other states
Consolidation rule: Combine all states into a single States story when possible (or minimal stories when states are complex).
Pattern (single States story; section heading and story name match — collapse to one heading, no ### States; see "Single-story sections"):
## States
Components can exist in various states:
- **Default**: Normal, interactive state
- **Selected**: Item has been chosen or activated
- **Disabled**: Functionality exists but is not available
- **Error**: Validation failure or error condition
All states shown below for comparison.
<Canvas of={Stories.States} />
export const States: Story = {
render: (args) => html`
${template({ ...args, label: 'Default' })}
${template({ ...args, selected: true, label: 'Selected' })}
${template({ ...args, disabled: true, label: 'Disabled' })}
${template({ ...args, invalid: true, label: 'Error' })}
`,
tags: ['states'],
parameters: {
flexLayout: 'row-wrap',
},
};
For a form field, the Disabled, Read-only, and Error states are values of field-status, not separate boolean attributes. Document them in the field's state sections, and cover the form participation points in forms strategy RFC §3.9, using text-field.mdx as the reference.
Pattern for complex states (when animation or interaction is critical — states no longer combine into one story, so each gets its own per-story ### Title):
### Indeterminate
The indeterminate state shows an animated loading indicator when progress is unknown or cannot be determined.
The animation automatically loops until the state changes.
<Canvas of={Stories.Indeterminate} />
export const Indeterminate: Story = {
tags: ['states'],
args: {
indeterminate: true,
label: 'Loading...',
},
};
Disabled state note (fold into the ## States prose above, or use verbatim if Disabled needs its own ### Disabled story):
A component in a disabled state shows that [functionality] exists, but is not available in that circumstance.
This can be used to maintain layout continuity and communicate that [functionality] may become available later.
**ARIA support**: When disabled, the component automatically sets `aria-disabled="true"`.
Behaviors
Purpose: Document methods, events, and automatic behaviors.
Focus management belongs here only when it's a side effect of a lifecycle or state transition, independent of which input method triggered it: for example, a dialog trapping focus when it opens and restoring it when it closes, or a listbox auto-focusing its first result when it opens. Focus movement that is the keyboard interaction model itself (roving tabindex, arrow keys moving focus between items) belongs in ## Accessibility under keyboard navigation instead: it isn't separable from "how do you operate this with a keyboard," which is already that section's job.
Pattern for automatic behaviors:
### Text wrapping
Long text content automatically wraps to multiple lines to fit the available space.
When space is constrained, text truncates with an ellipsis (...).
<Canvas of={Stories.TextWrapping} />
export const TextWrapping: Story = {
render: (args) => html`
${template({ 'default-slot': 'Short text' })}
${template({
'default-slot':
'This is a much longer text that will wrap to multiple lines when the container becomes too narrow to fit it all on one line',
})}
`,
tags: ['behaviors'],
parameters: {
flexLayout: 'row-wrap',
},
};
TextWrapping.storyName = 'Text wrapping';
Pattern for methods:
### Methods
The component exposes the following public methods:
- **open()**: Opens the component programmatically
- **close()**: Closes the component programmatically
- **toggle()**: Toggles between open and closed states
- **reset()**: Resets the component to its initial state
Example usage:
```javascript
const component = document.querySelector('swc-component-name');
component.open();
```
<Canvas of={Stories.Methods} />
export const Methods: Story = {
tags: ['behaviors'],
// ... implementation
};
Pattern for events:
### Events
The component dispatches the following custom events:
- **change**: Fired when the value changes (bubbles: true, composed: true)
- **input**: Fired during user input (bubbles: true, composed: true)
- **swc-opened**: Fired when the component opens (bubbles: true, composed: true)
- **swc-closed**: Fired when the component closes (bubbles: true, composed: true)
Example event listener:
```javascript
component.addEventListener('change', (event) => {
console.log('Value changed:', event.target.value);
});
```
<Canvas of={Stories.Events} />
export const Events: Story = {
tags: ['behaviors'],
// ... implementation
};
Accessibility
Purpose: Document built-in accessibility features and provide best practices guidance.
Required structure: Two subsections - Features and Best practices.
Pattern:
### Features
The `<swc-component-name>` element implements several accessibility features:
#### Keyboard navigation
- <kbd>Tab</kbd>: Moves focus to/from the component
- <kbd>Space</kbd> or <kbd>Enter</kbd>: Activates the component
- <kbd>Arrow keys</kbd>: Navigate between items
- <kbd>Escape</kbd>: Closes the component (if applicable)
#### ARIA implementation
1. **ARIA role**: Automatically sets `role="progressbar"` (or appropriate role)
2. **Labeling**: Uses the `label` attribute as `aria-label`
3. **States**:
- Sets `aria-valuenow` with current progress value
- Sets `aria-disabled="true"` when disabled
4. **Status communication**: Screen readers announce value changes
#### Visual accessibility
- Progress is shown visually through multiple cues, not relying solely on color
- High contrast mode is supported with appropriate color overrides
- Static color variants ensure sufficient contrast on different backgrounds
### Best practices
- Always provide a descriptive `label` that explains what the component represents
- Use meaningful, specific labels (e.g., "Uploading document" instead of "Loading")
- Ensure sufficient color contrast between the component and its background
- Use semantic variants when status has specific meaning
- Test with screen readers to verify announcements are clear
<Canvas of={Stories.Accessibility} />
export const Accessibility: Story = {
tags: ['a11y'],
args: {
// ... accessible example
},
};
Common accessibility features to document:
- Keyboard navigation: Document all keyboard interactions
- ARIA role: Document automatic role assignment
- ARIA labels: Document labeling mechanism (aria-label, aria-labelledby)
- ARIA states: Document state attributes (aria-disabled, aria-valuenow, etc.)
- Color meaning: For components using color to convey information
- High contrast mode: If supported via forced-colors media query
Accessibility requirements for all stories:
All stories must demonstrate accessible usage:
- Include required labels (
label,aria-label, or slot content) - Use meaningful, realistic content (no placeholder text)
- Show proper ARIA usage when applicable
- Never demonstrate inaccessible patterns
1st-gen to gen2 comparison
When creating gen2 documentation, check 1st-gen (1st-gen/packages/*/README.md) for content to preserve or differences to highlight.
Where to document differences
Document 1st-gen vs gen2 differences as inline notes in the relevant per-unit MDX section, immediately under the section heading and above the <Canvas> reference. Keep notes concise — link to the consumer migration guide for full upgrade instructions.
Pattern for new options or variants:
### Sizes
Component-names come in [X] sizes...
> **Note**: the `xl` size is new in gen2 and not available in 1st-gen.
<Canvas of={Stories.Sizes} />
Pattern for removed features:
### Methods
The component exposes the following public methods...
> **Migration note**: the `validate()` method from 1st-gen has been removed in gen2. Set `field-status="invalid"` instead (for a form field), or use the component's own property. See the [consumer migration guide](?path=/docs/components-<name>-migration-guide--docs) for full upgrade steps.
<Canvas of={Stories.Methods} />
Content to check from 1st-gen
Compare gen2 against 1st-gen for:
- Size options: Verify all sizes (especially
xl) are documented - Variant lists: Ensure all variants are listed (check for
accent, etc.) - States: Check for disabled, loading, or other states
- Behavioral details: Text wrapping, truncation, tooltip integration
- Keyboard interactions: If documented in 1st-gen
- Methods and events: Check for API changes
- Advanced examples: Tooltips, containers, complex layouts
- Specific guidance: Color contrast guidance for static-color variants
Common differences to highlight
New in gen2:
- Additional sizes (e.g.,
xl) - Additional variants (e.g.,
accent) - New properties (e.g.,
subtle,outline) - Improved ARIA implementation
- Better high contrast support
Changed in gen2:
- Property names (e.g.,
emphasized→outline) - Slot names or structure
- Event names or payloads
- Default values
Removed from gen2:
- Deprecated properties
- Removed methods
- Unsupported variants
Using CEM for comparison
Use the Custom Elements Manifest (CEM) to verify differences:
- Check 1st-gen CEM:
1st-gen/packages/component-name/custom-elements.json - Check gen2 types:
gen2/packages/core/components/component-name/*.types.ts - Compare:
- Properties and their types
- Slots and their descriptions
- Methods and their signatures
- Events and their details
Example verification:
# Check 1st-gen properties
grep -A 5 '"name": "size"' 1st-gen/packages/badge/custom-elements.json
# Check gen2 types
grep "VALID_SIZES" gen2/packages/core/components/badge/Badge.types.ts
Common gaps to check
- Missing installation instructions
- Missing size options (xl is common)
- Missing semantic variants (accent is common)
- Undocumented disabled state
- Missing readonly state documentation
- Missing ARIA disabled documentation
- Lack of tooltip integration examples
- Missing icon-only accessibility guidance
- No keyboard navigation documentation
- Missing static-color contrast guidance
- No text truncation/wrapping behavior explanation
- Missing methods documentation
- Missing events documentation
Verification and accuracy
Critical: Always verify documentation against the actual component implementation to prevent hallucinations and inaccuracies.
Verification process
After creating or updating documentation:
Read the component source files:
- Base class implementation (
gen2/packages/core/components/*/Component.base.ts) - Component-specific implementation (
gen2/packages/swc/components/*/Component.ts) - TypeScript type definitions (
gen2/packages/core/components/*/Component.types.ts) - CSS stylesheets (
gen2/packages/swc/components/*/component.css)
- Base class implementation (
Verify slots:
- Check JSDoc comments in component class (
@slotdecorators) - Verify slot names in the render method
- Confirm which slots are required vs. optional
- Check JSDoc comments in component class (
Verify properties:
- Check
@propertydecorators in component and base classes - Verify property types, defaults, and reflect values
- Confirm valid values (enums, arrays defined in types file)
- Check if properties exist in both base and subclass
- Check
Verify ARIA implementation:
- Search for
aria-*attributes in component code - Check for
roleassignments - Verify attribute behavior (when added/removed)
- Don't claim attributes that aren't implemented
- Search for
Verify behavior:
- Check for methods in component class (public methods only)
- Look for event dispatching (
dispatchEvent, custom events) - Verify automatic behaviors in lifecycle methods
Verify constraints:
- Look for validation logic (e.g., outline only with semantic variants)
- Check for console warnings about invalid combinations
- Verify size/variant/option restrictions
Common hallucination patterns to avoid
❌ Claiming attributes that don't exist:
// WRONG: Claiming a `label` attribute when component only has a slot
- Provide label via the `label` attribute
✅ Verify what actually exists:
// CORRECT: Check component source for actual API
- Provide label via the default slot or `aria-label` attribute
❌ Assuming ARIA attributes are set:
// WRONG: Claiming aria-valuemin/aria-valuemax without checking
- Includes `aria-valuemin="0"` and `aria-valuemax="100"`
✅ Verify ARIA implementation in code:
// CORRECT: Only document what the component actually sets
- Sets `aria-valuenow` with the current progress value
❌ Claiming methods that don't exist:
// WRONG: Assuming common methods exist
- **reset()**: Resets the component to initial state
✅ Check component class for public methods:
// CORRECT: Only document methods defined in the class
// (If no public methods exist, state this clearly)
Verification tools
Use these commands to verify claims:
# Search for properties
grep -n "@property" gen2/packages/swc/components/component-name/Component.ts
# Search for slots
grep -n "@slot" gen2/packages/core/components/component-name/Component.base.ts
# Search for ARIA attributes
grep -n "aria-" gen2/packages/swc/components/component-name/Component.ts
# Search for events
grep -n "dispatchEvent\|new CustomEvent" gen2/packages/swc/components/component-name/Component.ts
# Compare with 1st-gen
diff <(grep "@property" 1st-gen/packages/component-name/*.ts) \
<(grep "@property" gen2/packages/swc/components/component-name/*.ts)
Documentation after verification
After verifying accuracy:
- Document what was checked in commit message or PR
- Note any inaccuracies found and fixed
- Include code references for major claims (in the per-unit MDX where helpful)
- Consider creating a verification checklist for complex components
General guidelines
Documentation style
- Use sentence case for all headings and descriptions
- Be specific - Instead of "Loading", use "Uploading document" or "Processing request"
- Show, don't just tell - Include visual examples for every concept
- Consolidate variations - Combine related options into single stories for easier comparison
- Think multi-audience - Balance designer needs (visual) with developer needs (technical)
Component linking
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 docs page using relative paths
- Format:
[ComponentName](../?path=/docs/components-component-name--docs) - Component name format: Use kebab-case in the path (e.g.,
action-button,progress-circle) - Subtitle exception:
parameters.docs.subtitleis plain text and cannot include links.
Examples (meta-level JSDoc):
/**
* A `<swc-badge>` is a non-interactive visual label. For interactive labels,
* see [Action Button](../?path=/docs/components-action-button--docs).
*/
/**
* 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):
For interactive labels, see [Action Button](../?path=/docs/components-action-button--docs).
Code examples
- Use realistic content - Avoid placeholder text, use meaningful labels
- Always be accessible - Include required labels, ARIA attributes
- Show complete patterns - Don't abbreviate important details
- Use consistent formatting - Follow project style guidelines
Story organization
- Use flexLayout for multi-item comparisons
- 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
### Titleheading and prose to the per-unit MDX above the corresponding<Canvas of={Stories.MyStory} />. Do not add JSDoc above story exports.
No filler closing sentences
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 prose when the substantive content ends.
MDX heading levels
All headings inside MDX section prose must start at level 3 (###) or deeper:
- 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 withhideTitle=false(Options, States, Behaviors, Full pattern) - Level 4 (
####): Sub-sections inside per-story prose (e.g., "Slots", "ARIA implementation", "Keyboard navigation")
This preserves the hierarchy expected by the docs page layout (the unit title is h1, section headings are h2, story titles are h3).