Rule 63 - Composition stories use Twig partials
A story whose subject is a composition renders its markup from a Twig partial. Its *.stories.js file owns demo-content selection and arg forwarding; the composed markup itself lives in Twig, one partial per composition, which every story rendering that composition shares.
What is a composition story?
A composition story demonstrates how several elements are arranged together, rather than how one component's props vary. Three kinds qualify:
- Layout components - a component whose primary role is to
arrange other components rather than render its own visual
content (
header,footer, hero with slots). It ships at least one slot prop accepting arbitrary HTML, offers little visual treatment of its own beyond background, spacing, and a positional value, and is demonstrated by composing real components into its slots. - Utilities - a class or behavior whose effect is only visible
on an arrangement of elements (
grid,layout,flex,scrollspy,collapsible,loading). - Patterns - reference assemblies, which are compositions by definition.
Single-instance component stories (button, textfield,
accordion, badge, progress, tabs, …) demonstrate variations
of one component and are OUT OF SCOPE - they continue to express
their stories as JS render functions.
Where a canonical {name}.twig exists it does not change - it stays
the same passthrough container documented by {name}.spec.js. Only
the story compositions move to Twig. Utilities and patterns that
ship no canonical twig express the whole composition in the partial.
Composition partials
63.1. Every named composition story MUST render its markup from a sibling Twig file placed in the same directory, alongside the canonical {name}.twig where one exists. A partial belongs to a composition, not to a story name: stories that render the same composition and differ only in the values they pass MUST share one partial rather than each carry a copy of its body.
Where a file ships several compositions, each partial is named {name}.{composition-kebab}.stories.twig. A partial rendered by one story takes that story's key, kebab-cased (SearchLed → search-led, MobileMenu → mobile-menu). A partial shared by several stories takes the name of the composition they share - CenterWithLeftRail and CenterWithRightRail both render layout.center-with-rail.stories.twig, passing the side they differ in.
A file whose stories all render one composition MAY drop the composition segment and name its single partial {name}.stories.twig - with one partial there is no sibling to tell apart, so the infix carries no information. Every pattern uses this form, because a pattern is one reference assembly demonstrated by one story, and so does a file whose stories only vary the values one demo receives (reveal.stories.twig behind every reveal mode). The moment a second composition appears, every partial MUST take the named form.
src/components/header/header.cssheader.spec.jsheader.stories.jsheader.horizontal.stories.twig ← story partialheader.vertical.stories.twigheader.crowded.stories.twig...
63.2. The story partial owns the composed markup - the
.container, the flex / grid arrangement, the slot positions. Per-slot
content (brand, navigation tree, action buttons, search box, etc.) is
prepared in *.stories.js and passed into the partial as a slot
variable. The partial MUST NOT call demo-content helpers
(sentence(), logos(), …) directly; those belong in the JS layer
so the same partial works under different demo seeds.
{# header.playground.stories.twig #}<div class="container"><div class="flex-wrap items-center justify-between gap-3">{{ brand }}{{ nav }}{{ actions }}</div></div>
63.3. The story's JS render function MUST import the Twig partial
and return its output. JS in *.stories.js is permitted only for:
- demo-content lookup (e.g.
sentence({ index: 1 }),logos({ index })); - per-slot composition of pre-rendered HTML strings the partial consumes via slot variables;
- arg forwarding (
controls.apply(args)).
JS MUST NOT build the composed markup itself. Template literals that
emit <div class="container">…</div> or other arrangement HTML in
*.stories.js are a violation.
// Correct - the Twig partial emits the composition, JS supplies// the demo content for each slot and forwards the args.import HeaderHorizontal from './header.horizontal.stories.twig';export const Horizontal = {render: (args) => HeaderHorizontal({ ...controls.apply(args), brand: brand(), nav: primaryNav(), actions: signIn() + signUp() }),};// Wrong - layout markup built in JS.export const Horizontal = {render: (args) => {const inner = `<div class="container"><div class="d-flex">${brand()}${primaryNav()}</div></div>`;return `<header>${inner}</header>`;},};
63.4. Where a canonical {name}.twig exists and carries a single
content slot, the story partial MUST NOT duplicate its outer element:
the partial emits only the inner layout - the partition the
canonical component wraps - and the JS render passes that output to
the canonical component as the content slot. This keeps every
story exercising the real component shell rather than a copy.
A utility or pattern that ships no canonical twig has no shell to
wrap, so its partial emits the whole composition and the JS render
returns the partial's output directly. The same holds where the
canonical template wraps each entry of an item list in markup of its
own: grid.twig puts every items entry in a column it classes
uniformly, so a composition whose columns differ (offsets, ordering,
per-column spans) has no slot to enter through and its partial emits
the shell as well.
63.5. *.stories.twig partials are story fixtures, not component
implementations. They are excluded from the canonical-Twig lint
passes (passthrough-prop check, header-docblock drift, spec
matching). Any future per-component Twig linter MUST skip
*.stories.twig files when collecting implementation Twigs.
Why
Composition stories are the canonical "here is what a consumer should write" reference. When the composed markup lives in a JS template literal split across helper functions, the Storybook source panel either shows the rendered HTML (with classes, attributes, and demo text inlined) or displays unreadable JS helper soup. Twig partials render exactly the markup a consumer would write, one partial per composition, so the source panel and the on-disk file match.
This split also keeps demo-content variability in the JS layer: the same Twig partial works whether the brand is the Apollo logo, the NASA wordmark, or a future tenant's brand, because the partial takes brand HTML as a slot.
Cross-references
- Rule 31 - Twig component props - the
canonical component still owns its
classes/attributespassthroughs; the story partial does not. - Rule 32 - Twig code formatting - story partials follow the same formatting as production Twig.
- Rule 51 - Project file structure -
story partials sit flat alongside
{name}.twig, no subdirectories. - Rule 61 - Storybook - story file shape, demo content, controls. Composition stories move their markup to Twig partials; the rest of Rule 61 still applies.
63.1, 63.2 by yarn cli 63 (findCopiedPartials, findMisnamedPartials, findNonSiblingPartialImports, findStoriesWithoutPartial, findDemoContentLookups in packages/cli/src/rules/63.js). 63.1 (utility and layout-component stories), 63.3-63.5 are review only. See enforcement.md.