Skip to main content

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:

GroupSource folder
Foundationsrc/foundation
Utilitiessrc/utilities
Componentssrc/components
Form controlssrc/components
Patternssrc/patterns
Toolssrc/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.


Enforced by

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.