Rule 52 - Project: Stories folder alignment
Where a *.stories.js file lives on disk based on the group
segment of its title: string.
Rules
52.1. Every *.stories.js file MUST declare a title: string
whose first segment (before the first /, the "group") maps to
its source folder under src/ according to the table in rule
52.2. The stories file MUST live inside the mapped folder or one
of its descendants.
// Correct - title group "Utilities" maps to src/utilities/// and the file lives at src/utilities/grid/grid.stories.js.export default { title: 'Utilities/Grid' };// Wrong - same title, but the file lives at// src/components/grid/grid.stories.js, which maps to the// "Components" group.
52.2. The canonical group → source folder mapping is:
| Group | Source folder |
|---|---|
Foundation | src/foundation |
Utilities | src/utilities |
Components | src/components |
Form controls | src/components |
Patterns | src/patterns |
Tools | src/tools |
52.3. Form controls/* is an override: form controls are
Components per
Architecture, so their
stories MUST live in src/components/. This is the only override
in the mapping.
52.4. A story whose title: has no / (a root-level page, e.g.
title: 'Welcome') is exempt from the folder mapping and MAY
live anywhere under src/. Root-level pages are an explicit
allow-list - new root-level titles MUST be added to the allow-list
in the linter (see 52.5) and to this rule. The allow-list is empty
today; a root-level page enters it and this rule in the same change.
52.5. The mapping, override, and root-level allow-list are
enforced by packages/cli/src/rules/52.js, which runs as part
of yarn lint. Any change to the mapping, the override, or the
allow-list MUST be made in both the rule text above and the
linter, and packages/cli/tests/src/rules/52.test.js MUST cover
every case.
52.6. When a story's group changes (e.g. promoting a component
from Components to Utilities), the stories file and all its
siblings (CSS, JS, Twig, tests) MUST be moved together so the
component directory remains intact under the new parent.
52.1, 52.2, 52.3, 52.4 by yarn cli 52 (checkStoryFolderFile in packages/cli/src/rules/52.js). 52.5, 52.6 are review only. See enforcement.md.