# Pathrule Pattern: Design Systems with Storybook (1.0.0)
# ::pathrule:package:design-systems-storybook

### [RULE] Stories must be deterministic component contracts  (path: /src/stories)
<!-- scope: folder | priority: high | strict -->

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.

- Cover default, variants, loading, empty, error, disabled, long content, localization, and permission states that consumers must handle.
- Provide stable providers, data, viewport, locale, theme, and time through scoped decorators or parameters.
- Keep stories close enough to the component contract that removed props and states fail during the same change.
- Use semantic queries and user-visible outcomes in play functions rather than implementation selectors.

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.

---

### [MEMORY] The component API owns behavior, not page conventions  (path: /src/components)

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.

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.

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.

---

### [SKILL] review-storybook-component  (path: /)

---
name: review-storybook-component
description: Review a design-system component across states, interaction, accessibility, visuals, responsiveness, and API quality.
---

# Review Storybook Component

Run this procedure whenever the governed surface changes or its operational evidence becomes stale.

1. Inventory the public props, events, slots, ref and focus behavior, supported states, tokens, and known consumer constraints.
2. Inspect deterministic stories for default, variants, edge content, async, error, disabled, locale, direction, theme, and viewport coverage.
3. Run interaction and accessibility checks with keyboard and assistive semantics, then review visual diffs for intended token and layout changes.
4. Classify API and visual changes as compatible, deprecated, or breaking; require migration notes and consumer evidence for non-compatible changes.

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.

---

### [SKILL] release-design-system  (path: /src/components)

---
name: release-design-system
description: Release a design-system change with story evidence, consumer compatibility, migration guidance, and provenance.
---

# Release Design System

Run this procedure whenever the governed surface changes or its operational evidence becomes stale.

1. Freeze the candidate and generate the component, token, icon, and utility changes from the last released version.
2. Run type, unit, story render, interaction, accessibility, visual, theme, locale, and representative consumer tests against the immutable candidate.
3. Assign semantic version impact from the documented public API and visual contract, then write upgrade and deprecation guidance with before and after examples.
4. Publish only after approval, record artifact provenance, verify a clean consumer install, and open tracked work for every announced deprecation removal.

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.