Storybook design system documentation: define authority, cover states, and verify changes

Storybook describes itself as a workshop for building components and pages in isolation. Stories preserve states that may be difficult to reach in the full application, and those stories can feed documentation and tests. Both are useful capabilities. The governance problem starts when that convenience becomes an unstated rule that whatever appears in Storybook must be the design system.

A rendered story is evidence produced by component code, a fixture, Storybook configuration, loaded assets, and the current environment. If a button has the wrong focus treatment, editing the story until it looks right may hide the real fault. The semantic token could be wrong. The export could be stale, the component could contain a local override, or the story could apply an artificial background. Correct the layer that owns the decision.

A component in the Storybook sidebar is still only an inventory entry. The documentation becomes useful when another developer or coding agent can tell what the component is for, which cases it supports, which source governs its appearance, and how its current claims were checked.

Write the contract before expanding the story set. Keep required behavior separate from illustrative examples. A marketing card may need short and long content fixtures, while an internal status badge may have no responsive behavior of its own. Project requirements determine the coverage. A universal checklist would add noise and imply support for states the component cannot reach.

component: ""
purpose: ""
owner: ""
source_authority:
  location: ""
  version_or_date: ""
semantic_roles:
  - role: ""
    source_reference: ""
    implementation_mapping: ""
variants:
  required: []
  unsupported: []
states:
  required: []
  project_defined: []
content_fixtures:
  - name: "typical"
    reason: ""
color_modes: []
responsive_conditions:
  - condition: ""
    expected_result: ""
accessibility_requirements: []
exceptions:
  - decision: ""
    owner: ""
    reason: ""
documentation_surfaces:
  rendered_stories: []
  generated_docs: []
  mdx_guidance: []
  external_sources: []
evidence:
  status: unresolved | observed | tested | accepted
  records: []
unresolved_items: []
last_reviewed: ""

Evidence status matters because the fields do different jobs. An upstream value can be verified while its component mapping remains unresolved. A story may be observed while keyboard behavior remains untested. A visual check can pass even though the documentation still makes an obsolete claim. Don't collapse these into a single complete flag.

• Unresolved: no authoritative answer or observation has been recorded yet.
• Observed: a person or tool inspected a named surface under recorded conditions.
• Tested: a repeatable check exercised a specific assertion and produced a result.
• Accepted: the authorized reviewer judged the available evidence sufficient for the stated scope.

Storybook offers stories, generated documentation, MDX, testing surfaces, viewports, and sharing workflows. There isn't one best surface. The useful question is which one can carry a particular fact without overstating what that fact proves.

Start with representative components that expose different failure classes. A button reveals interaction states and focus treatment. An input adds validation and content behavior. Cards expose composition and pressure from long content, while tables add density, overflow, sorting, empty data, and numeric alignment. Choose only components your project actually supports.

For each component, cross the required cases with realistic fixtures. Light and dark modes need separate observations because semantic roles may resolve to different values. Base responsive checks on supported containers or viewports, not an arbitrary collection of device widths. Include expected unchanged behavior in the matrix too, since unrelated movement is often the first sign of an overly broad token or CSS change.

Don't create a story for every conceivable state. Coverage should trace to a component API, product requirement, design rule, accessibility requirement, supported environment, or observed failure. If none of those supports the case, record it as outside the current contract instead of implying that the component handles it.

Ambient Sage works here because its public page exposes real upstream artifacts. It documents Plus Jakarta Sans for heading and body roles, JetBrains Mono for technical strings, semantic light and dark roles, DESIGN.md, and exports including DTCG tokens, CSS variables, Tailwind configurations, and a shadcn registry item. Those facts can populate the source side of a documentation record.

Everything else must remain explicitly unresolved until a real project supplies evidence. Identity Forge does not automatically import a kit into Storybook, create stories, synchronize documentation, define product behavior, or prove visual parity. The intake record below preserves that boundary.

artifact: "Ambient Sage public design kit"
source_status: "verified from frozen public page"
source_authority:
  design_guidance: "published DESIGN.md"
  semantic_tokens: "published light and dark roles"
verified_typography:
  heading: "Plus Jakarta Sans, weights 400 500 600 700"
  body: "Plus Jakarta Sans, weights 400 500 600 700"
  mono: "JetBrains Mono, weights 400 500 700"
available_delivery_formats:
  - "DESIGN.md"
  - "DTCG tokens JSON"
  - "CSS variables"
  - "Tailwind v3 config"
  - "Tailwind v4 theme"
  - "shadcn registry JSON"
storybook_mapping:
  status: "unresolved"
  token_import_path: "unresolved"
  global_mode_control: "unresolved"
  component_role_mapping: "unresolved"
implementation_observations:
  component_behavior: "not observed"
  light_mode_parity: "not observed"
  dark_mode_parity: "not observed"
  responsive_behavior: "not observed"
  accessibility_evidence: "not tested"
acceptance: "blocked until project-specific mapping and evidence exist"

A static review can confirm that documentation looks plausible. A controlled change checks whether the documented chain actually propagates. Choose one bounded semantic-role change in a development or review context where the change is authorized. The goal is to observe named consumers and detect unrelated movement, not to restyle the whole library.

Suppose the approved upstream source changes the value assigned to a focus-ring role. Before applying it, list the components and stories expected to consume that role. Name the surfaces that should remain unchanged too, such as card backgrounds, destructive text, and chart series. Now the change is a falsifiable check.

1. 1

   Freeze the source decision

   Record the authoritative artifact, version, semantic role, old value, approved new value, owner, and reason. If the change is only hypothetical, stop before editing and use the record as a planning exercise.

2. 2

   Name expected consumers

   List the components, stories, modes, and states expected to change. Include at least one representative focus state in light and dark mode when both modes are supported.

3. 3

   Name expected unchanged surfaces

   List nearby roles and components that must not move. This catches broad selectors, alias mistakes, and local overrides that a target-only review misses.

4. 4

   Update the delivery artifact

   Record the generated output or mapping change. A changed source with an unchanged export is a stale-delivery failure, not a Storybook documentation problem.

5. 5

   Observe stories and collect tests

   Inspect the named stories under recorded modes, states, viewports, and fixtures. Attach each test result to the assertion it supports. Keep missing checks marked unresolved.

6. 6

   Assign a disposition

   Accept only when expected consumers changed, expected unchanged surfaces held, documentation claims remain accurate, and no blocking evidence gap remains. Use revise for bounded defects and block when authority or required evidence is missing.

change_id: "focus-ring-role-example"
change_status: "planned, not executed"
authoritative_source:
  artifact: ""
  version: ""
  owner: ""
semantic_role: "focus ring"
approved_change:
  from: ""
  to: ""
expected_consumers:
  - component: "Button"
    stories: ["Focus"]
    modes: ["light", "dark"]
expected_unchanged:
  - "Card background"
  - "Destructive text"
  - "Chart series"
delivery_evidence:
  generated_output: "unresolved"
  mapping_diff: "unresolved"
story_observations:
  light: "unresolved"
  dark: "unresolved"
test_evidence: []
local_overrides: []
exceptions: []
unresolved_items:
  - "Project mapping not supplied"
  - "No implementation was executed in the frozen evidence"
disposition: "block"
disposition_reason: "Required project evidence is absent"

When a story differs from the intended system, start at the highest authoritative layer and move toward the rendered surface. This keeps you from fixing a symptom in a fixture while every real consumer remains wrong.

1. Upstream source: Is the intended semantic role or rule explicit, current, approved, and owned?
2. Export mapping: Did the correct source version produce the artifact used by the project, with the expected identifier and mode values?
3. Component implementation: Does the component consume the mapped semantic role, or does a local value, selector, or variant override it?
4. Story fixture: Does the story reproduce a supported state with realistic args, content, context, globals, and viewport?
5. Documentation claim: Does generated documentation or MDX describe the current component API, limitations, exceptions, and authority accurately?
6. Test environment: Does the check load the same tokens, fonts, decorators, mode settings, and component version as the documented story?
7. Release observation: Does the published Storybook or product build contain the reviewed artifacts, and does it show the accepted result?

Stop at the first layer that fails and route the correction there. Source ambiguity needs an authorized design decision. A stale export needs regeneration or mapping work. A component override needs an implementation fix, while a misleading fixture needs story maintenance. If a released build contains old artifacts, it needs release correction. The visual symptom may be identical, but the responsible owner isn't.

Documentation is current only within a declared scope. A button contract can be accepted while a table remains unresolved. State the component versions, modes, viewports, fixtures, environments, and evidence included in the decision so readers don't mistake partial coverage for a library-wide guarantee.

This workflow does not replace Storybook's official installation, framework, API, addon, migration, or configuration references. Nor does it prove accessibility conformance or release readiness. It provides a narrower record those references do not: which decisions Storybook is showing, which states are covered, who owns exceptions, and what evidence supports a current claim.

Start with one representative component. Write its contract and capture its required stories in light and dark mode. Then plan or run one authorized semantic-role change against named consumers and unchanged surfaces. Record the result as accept, revise, or block before treating that part of Storybook as current.

• Storybook: Frontend workshop for UI development: Storybook supports isolated component development, hard-to-reach states captured as stories, testing, generated documentation, publishing, and sharing.
• Get started with Storybook | Storybook docs: Storybook provides distinct surfaces for stories, testing, Autodocs, MDX, viewports, documentation builds, publishing, embedding, and composition.
• GitHub - storybookjs/storybook: The official Storybook project provides the implementation, framework support, addons, APIs, installation paths, and contributor resources.
• Introduction to Storybook: A Guide for UI Development: The observed beginner tutorial covers setup, folder structure, a first story, addons, CSF, categories, and MDX.
• Ambient Sage Design Kit: The public Ambient Sage kit documents Plus Jakarta Sans for heading and body roles, JetBrains Mono for technical strings, semantic light and dark tokens, DESIGN.md, and several developer export formats.
• Brand kit for web developers: what an implementation-ready handoff needs: An implementation-ready handoff separates authoritative decisions, delivery artifacts, implemented consumers, unresolved requirements, owners, and acceptance evidence.
• AI UI review checklist: test generated interfaces before you ship: A release review needs separate evidence for task behavior, design-system conformance, required states, accessibility, controlled changes, and unresolved limitations.