Design Systems with Storybook
Pathrule1 Rule • 1 Memory • 2 Skills
Design systems with Storybook need more than a gallery of ideal component states. This bundle defines component contracts, deterministic stories, interaction and accessibility tests, visual review, deprecation, and consumer-safe release procedures. Unlike shadcn/ui, it governs a team's evolving component system and evidence rather than the adoption and customization of one component collection.
Suggested path map
Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.
/ workspace root
review-storybook-component
src/
stories/
Stories must be deterministic component contracts
components/
The component API owns behavior, not page conventions
release-design-system
Rules
1Stories must be deterministic component contracts/src/storieshighstrictEvery supported component state renders from explicit args and controlled decorators without hidden application or network state.
| 1 | Every supported component state renders from explicit args and controlled decorators without hidden application or network state. A story that relies on current time, random data, live services, global order, or an app singleton cannot serve as reliable documentation or test evidence. Enforce this boundary in /src/stories so invalid work stops before it reaches another subsystem or creates an externally visible side effect. |
| 2 | |
| 3 | - Cover default, variants, loading, empty, error, disabled, long content, localization, and permission states that consumers must handle. |
| 4 | - Provide stable providers, data, viewport, locale, theme, and time through scoped decorators or parameters. |
| 5 | - Keep stories close enough to the component contract that removed props and states fail during the same change. |
| 6 | - Use semantic queries and user-visible outcomes in play functions rather than implementation selectors. |
| 7 | |
| 8 | Verification: Run stories in isolation, shuffled order, CI, both themes, and representative viewports; confirm network is mocked and repeated runs produce the same DOM and assertions. |
Memories
1The component API owns behavior, not page conventions/src/componentsA shared component should encode reusable interaction, semantics, states, and tokens while leaving product-specific data fetching and workflow policy to its consumer.
| 1 | A shared component should encode reusable interaction, semantics, states, and tokens while leaving product-specific data fetching and workflow policy to its consumer. Define controlled and uncontrolled behavior, events, focus, disabled and loading semantics, composition slots, and accessibility expectations in the public contract. |
| 2 | |
| 3 | Keep page-specific copy, permissions, analytics names, routing, and server calls outside the primitive. Use design tokens and documented variants rather than exposing arbitrary styling escape hatches by default. Deprecate APIs with warnings and migration examples before removal when consumers ship independently. Keep the decision explicit at /src/components; moving it into an incidental caller makes behavior depend on which route happened to execute first. |
| 4 | |
| 5 | See /src/stories for executable states and the component release skill for compatibility. That related boundary consumes this decision and carries the evidence that proves it still holds. |
Skills
2review-storybook-component/rootReview a design-system component across states, interaction, accessibility, visuals, responsiveness, and API quality.
| 1 | --- |
| 2 | name: review-storybook-component |
| 3 | description: Review a design-system component across states, interaction, accessibility, visuals, responsiveness, and API quality. |
| 4 | --- |
| 5 | |
| 6 | # Review Storybook Component |
| 7 | |
| 8 | Run this procedure whenever the governed surface changes or its operational evidence becomes stale. |
| 9 | |
| 10 | 1. Inventory the public props, events, slots, ref and focus behavior, supported states, tokens, and known consumer constraints. |
| 11 | 2. Inspect deterministic stories for default, variants, edge content, async, error, disabled, locale, direction, theme, and viewport coverage. |
| 12 | 3. Run interaction and accessibility checks with keyboard and assistive semantics, then review visual diffs for intended token and layout changes. |
| 13 | 4. Classify API and visual changes as compatible, deprecated, or breaking; require migration notes and consumer evidence for non-compatible changes. |
| 14 | |
| 15 | Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory. |
release-design-system/src/componentsRelease a design-system change with story evidence, consumer compatibility, migration guidance, and provenance.
| 1 | --- |
| 2 | name: release-design-system |
| 3 | description: Release a design-system change with story evidence, consumer compatibility, migration guidance, and provenance. |
| 4 | --- |
| 5 | |
| 6 | # Release Design System |
| 7 | |
| 8 | Run this procedure whenever the governed surface changes or its operational evidence becomes stale. |
| 9 | |
| 10 | 1. Freeze the candidate and generate the component, token, icon, and utility changes from the last released version. |
| 11 | 2. Run type, unit, story render, interaction, accessibility, visual, theme, locale, and representative consumer tests against the immutable candidate. |
| 12 | 3. Assign semantic version impact from the documented public API and visual contract, then write upgrade and deprecation guidance with before and after examples. |
| 13 | 4. Publish only after approval, record artifact provenance, verify a clean consumer install, and open tracked work for every announced deprecation removal. |
| 14 | |
| 15 | Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory. |
Why this pattern
Agents add one happy-path story, depend on application context implicitly, or change component behavior without testing interaction, accessibility, visual states, and consumers.
Built for Teams building shared frontend components and documenting them with Storybook.
Keeps your assistant from:
- Stories that only render inside the full application
- Interactive states documented but never asserted
- Breaking component changes released without deprecation or migration guidance
- License
- Apache-2.0
- Version
- 1.0.0
- Updated
- 2026-08-25