Skip to main content

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.

FilePurposeShippedMandated by
{name}.cssDesign system CSSYes-
{name}.variables.cssComponent token sidecarYesRule 23.6
{name}.jsComponent JS behaviorYes-
{name}.twigTwig templateYes-
{name}.spec.jsMachine-readable contractNoRule 53.1
{name}.spec.jsonProducer output for the docsNoRule 53.15
{name}.mdxComponent documentation pageNoRule 61.29
{name}.stories.jsStorybook stories + testsNoRule 61.1
{name}.stories.cssStory chrome CSSNo-
{name}[.{composition-kebab}].stories.twigStory layout partial(s)NoRule 63.1
{name}.test.jsUnit testsNoRule 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.js
icons.stories.js
build-sprite.util.js ← build-time helper (MAY `export`)
build-sprite.util.test.js

src/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.


Enforced by

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.