Rule 51 - Project: File structure
Where component files live and how they are named.
Rules
51.1. Each component MUST live in its own directory under
src/components/ using kebab-case. The directory name MUST be the
component's canonical name.
51.2. A component directory holds the files below. Each is either mandated by the rule named in the last column or optional; no other top-level file kind belongs in a component directory.
Two subdirectories are expected alongside them: fixtures/ per
Rule 42.10, and __screenshots__/ holding the
visual-regression baselines the capture spec writes.
| File | Purpose | Shipped | Mandated by |
|---|---|---|---|
{name}.css | Design system CSS | Yes | - |
{name}.variables.css | Component token sidecar | Yes | Rule 23.6 |
{name}.js | Component JS behavior | Yes | - |
{name}.twig | Twig template | Yes | - |
{name}.spec.js | Machine-readable contract | No | Rule 53.1 |
{name}.spec.json | Producer output for the docs | No | Rule 53.15 |
{name}.mdx | Component documentation page | No | Rule 61.29 |
{name}.stories.js | Storybook stories + tests | No | Rule 61.1 |
{name}.stories.css | Story chrome CSS | No | - |
{name}[.{composition-kebab}].stories.twig | Story layout partial(s) | No | Rule 63.1 |
{name}.test.js | Unit tests | No | Rule 42.1 |
Utility scripts that follow the .util.js suffix convention (Rule
51.10) and their .util.test.js siblings sit outside this table -
they are build-time helpers, not part of the runtime component
contract.
Adding a file kind to a component means adding a row here in the same change, so the rule that mandates it and this inventory cannot drift apart.
One directory under src/components/ is a showcase rather than a component: content/ demonstrates the foundation typography on prose and ships only content.mdx and content.stories.js, so no spec, stylesheet or template applies to it.
51.3. The directory name MUST match the component class name from Rule 21.
51.4. Story chrome CSS MUST use --story-* variables. Design
tokens MUST NOT be used in story chrome, except in the two demos
whose subject the token is - see
Rule 61.12.
51.5. All files MUST end with a final newline.
51.6. For the four framework types (Foundation, Utility, Component, Pattern) see Architecture.
51.7. Directories under src/tools/ are Storybook-only. Their
contents MUST NOT be exported by the distributed package and MUST
NOT be imported by Foundation, Utility, Component, or Pattern
source files. Tools provide infrastructure consumed by stories
(chrome CSS / JS, demo content, palette generators) and by other
tools. The build excludes src/tools/** from any published
artifact.
51.8. Source file comments MUST NOT reference rule numbers. A comment
should describe the concrete reason for the code (the invariant, the
workaround, the intent) - not defer that reason to a rule citation.
Rule numbers change; the reason does not. References like per Rule 11
or Rule 13.10 (sibling association) are forbidden in src/** and
.storybook/**. The rule documents themselves
(docs/content/handbook/rules/), the lint scripts that enforce rules
(packages/cli/**/*.js), and their test fixtures
(packages/cli/tests/fixtures/) are the only places rule numbers
belong.
/* Wrong - defers the reason to a rule citation. *//* Button styles moved to src/components/button/button.css per Rule 11. *//* Correct - states the reason directly. *//* Button styles moved to src/components/button/button.css. */
51.9. The check findJsRuleReferencesInComments in packages/cli/src/rules/51.js scans the comments of every JavaScript file (.js, .mjs, .cjs) under src/, .storybook/, packages/ outside packages/cli/, and scripts/, skipping *.test.js and fixtures, for Rule \d+(\.\d+)? patterns and fails the lint step when it finds one. CSS, Twig and MDX comments are review-caught.
51.10. JavaScript utility scripts that reside under src/ but
are NOT shipped as part of the design system bundle MUST use a
.util.js suffix (with a sibling .util.test.js test file). The
.util.js suffix exempts the file from Rule 41.5's no-export
constraint and signals to the bundle build that the file is a
build-time or development helper, not a runtime component. The
bundle build in packages/cli/src/commands/build.js excludes every
*.util.js from the published bundle automatically; the test
sibling requirement from Rule 42.1 still applies.
src/foundation/icons/icons.spec.jsicons.stories.jsbuild-sprite.util.js ← build-time helper (MAY `export`)build-sprite.util.test.jssrc/components/carousel/carousel.js ← runtime component (no `export`)carousel.test.js
51.11. Every repository path a guidance file cites in backticks (CLAUDE.md, the skill files under .claude/skills/, docs/content/, the tool READMEs under src/tools/, the package READMEs) MUST exist on disk. A path runs under one of the repository's top-level directories, or names a root-level file - package.json, CLAUDE.md, a *.config.js, a dotfile with an extension such as .stylelintrc.json; a bare file name that could sit in any directory is not a path. A path inside a fenced code block or a blockquoted example, or one carrying a placeholder ({name}, NN, <file>, an ellipsis) or a glob, is a shape rather than a file and is not checked.
51.12. Every Rule NN.M citation and every [NN.M](…) link in those files MUST name a sub-rule the rule NN document states. A lettered clause (Rule 24.16b) resolves to its parent sub-rule.
51.8, 51.9, 51.11, 51.12 by yarn cli 51 (findJsRuleReferencesInComments, findDeadGuidancePaths, findDeadRuleReferences in packages/cli/src/rules/51.js). 51.1-51.7, 51.10 are review only. See enforcement.md.