Skip to main content

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.css
header.spec.js
header.stories.js
header.horizontal.stories.twig ← story partial
header.vertical.stories.twig
header.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​


Enforced by

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.