Skip to main content

Rule 62 - Storybook chrome: three levels

Every shared Storybook chrome class belongs to exactly one of three levels. The level dictates where the class is applied, what it does, and how it composes. A separate fourth surface (.story-autodocs) covers the Storybook autodocs page.

This rule is the placement contract. The catalog of every shipped chrome class is in src/tools/storybook-chrome/README.md; class names there are organized by these levels.

Levels​

62.1. Level 1 - Canvas​

The surface the story renders into. Applied to #storybook-root by the canvas decorator via parameters.canvas. Defines geometry - width, padding, scrollability, viewport-frame simulation - and any canvas-level layout primitives the story uses to arrange siblings on the root.

  • Surface family - .story-canvas-*. The default surface (.story-canvas) is auto-applied by the decorator if the story does not request another surface. It sets a width cap, never a width, so the surface shrinks to the story and the centered layout can center it (see Rule 61.26).
  • Width sizers - .story-w-*. The way a story states a working width, since the surface no longer imposes one.
  • Layout primitives - .story-row, .story-stack, .story-form-grid, .story-compass. Applied via parameters.canvas.

A story MUST NOT wrap render output in a <div> to apply canvas-level layout. Canvas chrome is set on the canvas root; the render returns the component (or sibling components for multi-instance composition) directly.

62.2. Level 2 - In-canvas content​

Chrome rendered as content inside the canvas by the story's render function. Sits alongside or instead of the styled component output. Not documentation. Used to label, sample, annotate, or demonstrate.

  • Generic content atoms - .story-label, .story-group-label, .story-badge, .story-panel, .story-region.
  • Arrangement atoms - .story-cluster (horizontal wrap) and .story-column (vertical stack), with -gap-* modifiers, for specimens inside a render where the Level 1 row and stack cannot reach.
  • Floating overlay - .story-event-toast-* (fixed-positioned event log, gated by data-debug-events).
  • Utility-story shared chrome - .story-util-track (+ -vertical). Used by the margins (auto-margin demo) and sizing utility stories to provide a dashed 100% reference container for percentile demos.

Level 2 chrome is not a child of .story-docs. It is canvas content, not documentation prose. Use Level 3 for anything that documents the story.

62.3. Level 3 - Story docs (.story-docs)​

.story-docs is the single wrapper for all in-story documentation rendered inside the canvas. Acts as the typography-revert target so design-system classless rules (typography on <h1> / <p> / <ol> / <a> …) do not bleed into the doc-style prose of the help block.

A story doc block introduces, explains, or supports the demo - heading + description, hint paragraphs, table of contents, legends, demo control buttons.

  • The wrapper - .story-docs.
  • The TOC nav - .story-toc (and -heading, -list, -section, -indent) - MUST be nested inside a .story-docs parent (or compose .story-docs onto the same <nav> element).
  • The legend - .story-legend (and -item, -swatch) - MUST be nested inside .story-docs.
  • Demo control buttons - there is no .story-button class. A <button> placed inside .story-docs is styled via .story-docs button { … } so any control button automatically picks up the demo affordance.

Free-form prose inside .story-docs (h1-h6, p, code, kbd, pre, small, mark, var, ul, ol, blockquote, a) reverts to a controlled chrome rhythm via the typography-revert rule in src/tools/storybook-chrome/stories.css.

62.4. Autodocs surface (.story-autodocs)​

.story-autodocs wraps the Storybook autodocs page - a separate surface from a story canvas. Applied by .storybook/docs/docs-page.js to the autodocs container. Carries no layout styling; serves only as the typography-revert target so design-system element rules do not bleed into autodocs chrome.

Mechanics​

62.5. Typography revert​

The framework-isolation rule in src/tools/storybook-chrome/stories.css MUST list only .story-docs and .story-autodocs in its :where(...) selectors. No other surface reverts design-system element rules. The auto-applied .story-canvas MUST NOT revert design-system typography - components placed on the canvas need their <ol> / <ul> / <a> / <p> styling intact.

62.6. Naming and prefixes​

  • Level 1 surfaces use the .story-canvas-* prefix.
  • Level 1 width sizers use the .story-w-* prefix.
  • Level 1 layout primitives use flat names (.story-row, .story-stack, etc.) and are recognized as canvas-level by appearing only in parameters.canvas.
  • Level 2 atoms use flat .story-{atom} names.
  • Level 3 wrapper is exactly .story-docs. Children inside it retain their specific names (.story-toc, .story-legend).
  • Autodocs surface is .story-autodocs.

62.7. Adding new chrome​

When introducing a new chrome class:

  1. Identify which level it belongs to using the contracts above.
  2. Name it with the level's prefix (or flat name where the level convention permits).
  3. If single-consumer, add it to that consumer's *.stories.css (per-component chrome). If multi-consumer, add to shared chrome (src/tools/storybook-chrome/).
  4. Document the new class in src/tools/storybook-chrome/README.md: shared chrome under the matching level section, single-consumer chrome as a row in the per-component table.

A new class MUST NOT mix levels. A class that styles canvas geometry AND also serves as a typography-revert target is two classes masquerading as one - split it.

62.8. Per-component chrome​

Single-consumer chrome lives next to its consuming story (e.g. .story-sidenav-viewport-scroll in src/components/sidenav/sidenav.stories.css) and is listed in the README's per-component table rather than in the shared level sections. The level rules above still apply to per-component chrome - it just lives in a component's *.stories.css instead of src/tools/storybook-chrome/.

Cross-references​


Enforced by

62.1-62.8 are review only. See enforcement.md.