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 viaparameters.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 bydata-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-docsparent (or compose.story-docsonto the same<nav>element). - The legend -
.story-legend(and-item,-swatch) - MUST be nested inside.story-docs. - Demo control buttons - there is no
.story-buttonclass. A<button>placed inside.story-docsis 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 inparameters.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:
- Identify which level it belongs to using the contracts above.
- Name it with the level's prefix (or flat name where the level convention permits).
- 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/). - 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
- Rule 61 - Storybook - story file layout, demo content, test policy, canvas chrome usage from a story author's perspective.
src/tools/storybook-chrome/README.md- the canonical inventory of every shipped chrome class, organized by the levels defined here.
62.1-62.8 are review only. See enforcement.md.