spectrum-web-components / rules

---
description: Enforces consistent file structure, section separators, meta configuration, story tags, and layout parameters for gen2 Storybook stories files. Story prose lives in per-unit MDX; the stories file is definitions-only.
globs: gen2/packages/swc/components/*/stories/**,gen2/packages/swc/patterns/*/*/stories/**,gen2/packages/core/controllers/*/stories/**
alwaysApply: false
---

<!-- GENERATED by .ai/scripts/sync.js from .ai/rules/stories-format.md. Do not edit. Edit the source and run `yarn ai:sync`. -->

# Storybook stories format standards

Enforce consistent formatting and technical structure for Storybook stories files in gen2 components, patterns, and controllers.

**See also**: `.ai/rules/stories-documentation.md` for guidance on WHAT to author in the per-unit MDX (content, patterns, examples).

This rule holds the constraints that apply whenever you edit a gen2 stories file. The full reference (file structure, meta configuration, layout and decorators, story naming and ordering, tags, story types, JSDoc, accessibility requirements, and image assets) lives in the `stories-format` skill at `.ai/skills/stories-format/SKILL.md`. Load it when you write or review a stories file.

## When to apply

- Authoring or reviewing a `.stories.ts` file for a gen2 component, pattern, or controller
- Loads automatically when you work on a file matching the paths below
- Adding a new story (Playground, Options, States, Behaviors, Accessibility, etc.) and needing the right tags, layout parameters, or naming convention

## Scope

Apply to all `.stories.ts` files in:

- `gen2/packages/swc/components/*/stories/` (components)
- `gen2/packages/swc/patterns/*/*/stories/` (patterns)
- `gen2/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/<name>/<name>.mdx`          |
| Internal   | `swc/components/<name>/<name>.internal.mdx` |
| Pattern    | `swc/patterns/<group>/<unit>/<unit>.mdx`    |
| Controller | `core/controllers/<name>/<name>.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 `<Description />` 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 `<Canvas of={Stories.Foo} />` reference.

Stories without a corresponding `<Canvas>` 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.

## Key Principles

### Always Pass Args Through

When using custom `render` functions, **always** spread `...args` into template calls:

```typescript
// ✅ Good - args are passed through
export const MyStory: Story = {
  render: (args) => html`
    ${template({ ...args, size: 's' })}
  `,
};

// ❌ Bad - args are lost
export const MyStory: Story = {
  render: (args) => html`
    ${template({ size: 's' })}
  `,
};
```

This ensures:

- Storybook controls work correctly
- Args from the Playground/global level are respected
- Component defaults can be overridden

### When to Use render vs args

- **Use `args` directly**: When the default render is sufficient (single component, no wrapper)
- **Use `render: (args) =>`**: When you need multiple instances, custom HTML structure, or conditional rendering

```typescript
// ✅ Good - simple case uses args
export const Overview: Story = {
  args: { size: 'm', label: 'Example' },
  tags: ['overview'],
};

// ✅ Good - complex case uses render with args
export const Sizes: Story = {
  render: (args) => html`
    ${template({ ...args, size: 's' })} ${template({ ...args, size: 'm' })}
    ${template({ ...args, size: 'l' })}
  `,
  tags: ['options'],
};
```

### Documentation sections (authored in MDX)

The per-unit MDX file (`<unit>.mdx`) is the source of truth for the docs page layout. Each section is authored as Markdown with an explicit `<Canvas of={Stories.MyStory} />` reference where a story should render:

- **Anatomy** — `## Anatomy` prose + `<Canvas of={Stories.Anatomy} />`
- **Options** — `## Options` heading; for each option story, `### <Story title>` + prose + `<Canvas of={Stories.Sizes} />`
- **States** — same pattern as Options
- **Behaviors** — same pattern as Options
- **Accessibility** — `## Accessibility` prose + `<Canvas of={Stories.Accessibility} />`
- **Upcoming features** — `## Upcoming features` + prose only (no `<Canvas>`); placed before the footer so it reads as forward-looking notes after the current API/behavior
- **API** — handled by `<DocsFooter />` (rendered automatically with `<ApiTable />` for components and patterns; omitted for controllers)

See the `stories-documentation` skill at `.ai/skills/stories-documentation/SKILL.md` for full per-section authoring patterns, and `.ai/rules/stories-documentation.md` for the file template, canonical section order, and genre-specific notes (component vs pattern vs controller vs internal).

**What you need to do**: tag each story by section (`anatomy`, `options`, `states`, `behaviors`, `a11y`), then reference it from the per-unit MDX via `<Canvas of={Stories.StoryName} />`.

## Quick reference

### ❌ Don't

- 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

### ✅ Do

- Tag stories correctly: `anatomy`, `options`, `states`, `behaviors`, `a11y`
- Use `flexLayout: 'row-wrap'` for multi-item stories
- Author all story prose in the per-unit MDX file (`<unit>.mdx`)
- Keep the meta-level JSDoc above `const meta` — it drives the `<Description />` block at the top of the docs page
- Use meaningful, realistic content
- Reference each tagged story from MDX via `<Canvas of={Stories.StoryName} />`

## Checklist

- [ ] Copyright header (current year)
- [ ] Visual separators between sections
- [ ] Meta: title, component, args, argTypes, render, `parameters.docs.subtitle`, `tags: ['migrated']` (or `'controller'`)
- [ ] Internal attributes the component manages via `setAttribute` (not declared `@property`) are declared in `argTypes` with `{ table: { disable: true }, control: false }` so the Storybook helper does not round-trip and clobber them
- [ ] `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: `['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: flat unordered list of parts (no subsections), slot names inline where needed, `['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: `['a11y']` tag (prose lives in MDX)
- [ ] Static colors: single `StaticColors` story (flat or div-wrapped shape) with `staticColorsDemo` (if applicable)
- [ ] 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 `<Canvas of={Stories.StoryName} />` (see `.ai/rules/stories-documentation.md`)

More agent context in adobe/spectrum-web-components

12 other files this repository gives its agents.