Skip to main content

Enforcement coverage

Auto-generated by yarn cli enforcement. Do not edit manually.

Every Semetrika rule sits in one of two states:

  • Enforced - an automated check exists. Listed in the first table below, grouped by rule; yarn cli <rule> runs every check of that rule. Violations always emit a [Rule N.N] tag in front of the diagnostic.
  • Review only - no check in this CLI. Listed in the second table. Some are covered by an external linter instead: Stylelint enforces 21.2 (selector-class-pattern), 23.9 (unit-disallowed-list), and the 23.1 / 23.3 / 23.26 naming shapes (custom-property-pattern), and twig-cs-fixer enforces 32.21-32.23. The rest are caught at code-review time and are candidates for future codification.

Bidirectional linking: every rule file in docs/content/handbook/rules/ ends with an Enforced by note that points back at this table.

Enforced rules​

RuleSub-ruleDetectorWhat it checks
1111.3findUnpairedMirrorSelectorsIn a mirrored component, every selector list naming the element form also names the mirror class with the same qualifiers, and the other way round, so both forms share every declaration.
1111.14findRawComponentTagsNo raw <button>, <select>, <textarea>, <blockquote>, <progress>, or <fieldset> in a story render - include the matching component twig instead.
2121.10findInvertedPaletteLayerssrc/layers.css declares emphasis before intent and both before fill, so an explicit status outranks the emphasis default and a fill can still clear the surface either painted.
2121.15findUnlayeredTokenBlocksEvery :root / :root[data-color-scheme] block in a token file (src/variables.css, src/options.css, and every *.variables.css sidecar) is wrapped in @layer tokens.
2121.16findUnlayeredRulesEvery rule in a shipped stylesheet sits inside a @layer block; @font-face, @property, @keyframes and layer statements stay at file scope. An unlayered rule outranks every layer, so an unlayered .flex shows an element .hidden hides.
2222.1vocabdocs/content/capability-vocabulary.md is byte-identical to the auto-generated form (capabilities + custom values + utilities).
2222.2findClassesWithoutSpecEvery CSS class scanned from src/foundation/ + src/utilities/ is declared as an enum-prop value in a utility / foundation spec.js.
2222.16findValuesWithoutCssEvery value a utility / foundation spec.js declares as a class word has a selector carrying that word in that utility's own {id}.css. The reverse of 22.2, and the only check that reaches a utility's standalone classes.
2222.13findForbiddenTierValuesBare .primary / .secondary / .tertiary value classes are forbidden anywhere under src/. Component-prefixed child classes (.mobilenav-primary) remain legal.
2222.15findUnbackedCapabilityValuesEvery value declared on a canonical capability in spec/spec.js is backed by a class selector in shipped CSS under src/. The only check entered from the capability registry rather than from a component spec.
2323.25findTierVocabViolationsFoundational color tokens (--text-color-*, --border-color-*, --background-color-*) use only the subtle / neutral / accent tier vocabulary; legacy --surface-*, --*-muted-color, and bare --text-color / --border-color names are forbidden.
2323.18lintFoundation prefixes (alphabetical) before component prefixes (alphabetical); own-component decls before sub-component groups.
2323.4findLiteralColorViolationsNo token file holds a bare color literal - every value references a primitive or a semantic token. The palette (--color-{family}-{step}) is exempt, having nothing to reference.
2323.7findTierReferenceViolationsA capability rule names its component token in the primary position and a foundation token in the fallback. A foundation token or primitive in the primary position leaves tier 3 with no name to override.
2323.5findTierReferenceViolationsA component sidecar or rules file references tier 2 at the furthest - a primitive there hides the decision from the semantic layer; utility rules files and the foundation are outside the check.
2323.26findUnderscoreCustomPropertiesNo custom property under src/ uses the --_{shortname} underscore-prefix form, in a declaration or a var() read. An underscore name states no target, so nothing records which component owns it.
2323.8findDeviceBreakpointTokensNo custom property under src/ carries a mobile / tablet / desktop segment, in a declaration or a var() read. A device word names a class of hardware while the query it feeds names a width.
2323.28findFocusSlotViolationsA component's focus tokens name one of the canonical concerns - the -focus-ring-* slots the ring reads, plus the box-shadow, background-color and border-color a focused control restyles its own surface with.
2323.27findAxisMismatchedSpacingA declaration that sets a length on one axis reads that axis's spacing scale, and a shorthand covering both axes spells them as a pair. The two scales hold the same value at every step, so a mismatch renders identically and nothing but the name catches it.
2323.29findFoundationTokenWritesA component or utility stylesheet declares a foundation token - one src/variables.css or src/options.css declares - only when it is a color token inside @layer surface, where a component that paints its own surface keeps the typography placed on it legible.
2323.3findPrimitiveVarReferencesNo declaration in the primitive block of src/variables.css reads var(); a token that reads another is a semantic decision and sits in the semantic block.
2323.1findChildTokenNearMissesA sidecar token's child segment is never the singular or plural of a child class the stylesheet ships (--card-action-* beside .card-actions).
2424.11findColorSchemeViolationsBoth :root[data-color-scheme="dark"] and :root[data-color-scheme="light"] set color-scheme: <value>.
2424.12findColorSchemeViolationsThe :root[data-color-scheme="dark"] block carries only genuine differences: no entry identical to its :root value, and no orphan without a :root counterpart.
2424.13findColorSchemeViolationsPure-color values end in -color, -color-subtle, -color-neutral, -color-accent, -color-danger, -color-info, -color-success, -color-warning, -background-color, -border-color, or -shadow-color.
2424.19findIndistinctIntentsWithin one component, no two intents resolve to the same color for the same concern while the other intents differ there. A value shared by every intent is a common default, not a collision.
2424.20findIndistinctEmphasisWithin one component, no two emphasis values resolve to the same color on every concern the pair declares. Compared per pair rather than per concern, because a quieter rung routinely shares its text color and changes only the surface.
2525.2findRedundantReducedMotionBlocksNo @media (prefers-reduced-motion: reduce) block in a shipped stylesheet only clears transitions the --option-animations multiplier already zeroes; a block that swaps an animation for a static state stays, and so does a clear in a sheet with a transition the multiplier does not scale.
3131.3findInvalidBooleanPropNamesBoolean prop names start with is_, has_, or use_.
3131.12findForbiddenTitleLevelThe stale title_level prop is forbidden in *.twig, *.spec.js, and *.stories.js; render the title via title_tag.
3131.13findNonCanonicalPropNamesA Component declares no non-canonical name for a concept the rule names: no aria_* prop or slot, is_labeled, id_prefix, variant, image slot, or enum prop named mode or direction.
3131.14findUnprefixedItemFlagsEvery *.twig under src/ reads a boolean item key through its prefix, in dot or quoted bracket form (item.is_current, never item.current).
3232.1findHeaderDriftDocblock header regenerated byte-idempotently from {name}.spec.js.
3232.20findFunctionFormIncludesEvery {name}.twig includes through the {% include %} tag; the {{ include() }} function form is rejected.
4141.4findInlineStyleWritesComponent JS assigns no style.<property> and calls style.setProperty() only with a custom property; attributes and classes carry state, and a custom property carries a measured value CSS owns.
4141.5findInvalidRegistrationComponent JS file calls _register exactly once, installs no DOMContentLoaded listener, no childList MutationObserver on document.body, passes locally-defined init / destroy function references to _register, and does NOT assign window.Semetrika.<name> directly (the preamble does that).
4242.1checkTestSiblingsEvery covered JS source file has a sibling *.test.js.
4242.13checkTestSiblingsLint blocks CI when a covered file is added without a sibling test.
4343.1findInvalidEventNamesEvent names follow <component>-<action>.
4343.2findInvalidEventNamesEvent names match /^[a-z][a-z0-9]*-[a-z][a-z0-9-]*$/.
4343.10findMissingDebugEventsArgStories calling watchEvents() declare a debug_events arg; utility stories default it to true (a false default needs a justifying comment).
4343.13findMissingDebugEventsArgLint blocks CI when debug_events is missing, or when a utility story defaults it to false without a justifying comment.
4343.11findDynamicEventDispatchesEvents are dispatched directly via new CustomEvent('<literal>', …). Wrapper functions that accept a dynamic event-name parameter (e.g. emit(target, type, detail)) are forbidden.
4343.15findImplicitEventFlagsEvery dispatch passes bubbles and cancelable explicitly.
4343.16findEmptyEventDetaildetail is omitted when the event carries no payload; detail: {} and detail: null are violations.
4343.17findDispatchReturnUsedCancellation is read as event.defaultPrevented; dispatchEvent's boolean return is not consumed.
4343.18findBannedDetailKeysdetail.trigger names the originating element and detail.reason the string discriminator; detail.source is banned.
4343.19findGuardedDispatchA component or utility module carries no typeof CustomEvent environment probe.
4444.1findUnspecifiedEmittedEventsEvery event passed to new CustomEvent(...) matches the derived wire of an emit facet on a behavioral capability.
4444.2findUnimplementedEmittedEventsEvery emit facet's derived wire is dispatched in JS as a literal new CustomEvent(...) call.
4444.3findUnspecifiedListenedEventsEvery Rule 43-shaped event passed to addEventListener(name, …) matches the derived wire of a listen facet.
4444.4findUnimplementedListenedEventsEvery listen facet's derived wire is bound via addEventListener in JS.
4444.5findUnspecifiedAttributesEvery data-… attribute read, written, or selected in JS (excluding -init markers) matches the derived wire of a hook or state facet.
4444.6findUnimplementedAttributesEvery hook / state facet whose derived wire is a data-… attribute is referenced in JS.
4444.9findRedundantWireOverridesNo facet authors a wire equal to the value the Derive conventions already yield; an override names only a borrowed, foundation or markup-contract wire.
4545.1findInvalidModuleWrapperThe file is one arrow IIFE (() => { … })(); whose first statement is 'use strict';, matching src/boot.js.
4545.2findInvalidLifecycleNamesThe two functions passed to _register are named exactly init and destroy.
4545.3findInvalidLifecycleNamesPer-element work runs through named initElement / init{Noun} functions, paired symmetrically with their destroy halves.
4545.4findInvalidHandlerNamesListeners are named handle{Target}{Event}; the on{Action} form is forbidden for declarations and bindings alike.
4545.5findInvalidRegistryShapeA WeakMap named registry / {noun}Registry is the init guard; WeakSet and dataset.*Init markers are forbidden.
4545.6findInvalidRegistryShapeA data-*-init marker appears only where a CSS selector reads it (a _register destroySelector, or an observer attributeFilter).
4545.7findManualListenerTeardownEvery addEventListener passes a signal (or once) option, and removeEventListener is not used.
4545.5findNonRecordRegistryEntriesA registry entry is a record object, or the true a module with nothing to tear down may store; no other value.
4545.12findReimplementedHelpersA behavior window.Semetrika publishes is called, not re-implemented, and an element id never comes from Math.random().
4545.13findAdHocGlobalLifecycleDocument-level listeners run through window.Semetrika._globals, not a hand-rolled install / uninstall pair.
4545.8findDiscardedTimersA setTimeout / setInterval handle is kept, never discarded at statement level, so the matching destroy can clear it; a zero-delay deferral holds no resource and is exempt.
4646.1findEndRelativeIndexReadsNo receiver[receiver.length - n] or receiver.slice(-1)[0] in a JavaScript file the repository owns - an array or string takes .at(-n), an element's last child takes lastElementChild, and a live-collection receiver says so with a // live-collection: marker.
5151.8findJsRuleReferencesInCommentsComments describe the concrete reason, not a rule citation.
5151.9findJsRuleReferencesInCommentsLint catches Rule N / Rule N.M patterns under src/ and .storybook/.
5151.11findDeadGuidancePathsEvery backticked repository path a guidance file cites, outside fenced code and blockquoted examples, exists on disk.
5151.12findDeadRuleReferencesEvery Rule NN.M citation and [NN.M](…) link in a guidance file names a sub-rule its rule document states.
5252.1checkStoryFolderFileTitle first segment maps to its folder under src/.
5252.2checkStoryFolderFileCanonical group <-> folder mapping enforced.
5252.3checkStoryFolderFileForm controls/ override maps to src/components/ per the mapping table.
5252.4checkStoryFolderFileRoot-level titles (no /) are matched against the ROOT_TITLES allow-list (empty today).
5353.1loadComponentSpecSpec file exists and default-exports a CapabilitySpec.
5353.3loadComponentSpecThe CapabilitySpec constructor rejects a spec missing name or description; the load fails and lint reports it.
5353.4loadComponentSpecThe CapabilitySpec constructor rejects an absent or empty description.
5353.7findUnflaggedOutlierEnumsAn enum prop whose values include a word no capability declares sets outlier: true.
5353.8findSpecViolationsEvery declared slot, prop, and visual capability is referenced as a twig variable in the component template.
5353.15produceSpecJsonProducer renders deterministically across two consecutive runs.
5353.16detectWhitespaceBleedExample markup has no run of 2+ spaces and no embedded newlines.
5353.17findUnimplementedSpecValuesEvery spec enum value has a matching .{component}.{value} selector with a non-empty body inside the @layer named after that enum (the capability layer, or {prop.name} for an outlier enum prop).
5353.18findUndeclaredComponentClassesEvery class word compounded with .{component} in the component CSS is declared as an enum value in that component spec.
5353.19runRule53ValuesPer-value sidecar token contract for capabilities with a declared default: canonical --{component}-{variant}-{concern} naming, per-value token existence and usage, no misplaced base read, default mirror, and uniform property-surface coverage. Run via yarn cli 53-19 (part of yarn lint).
5353.19findLiteralRepointsA value rule re-points a base slot to the value's own --{component}-{value}-{concern} token, never to a literal; a slot whose base mirrors another capability's default is exempt. Run via yarn cli 53-19.
5353.20produceSpecJsonA template-less spec authors each example's markup; pairing markup with a {name}.twig, or omitting both, is rejected.
5353.21findRenderingDeclarationDriftThe Styling declaration agrees with the implementation: a CSS element-form/mirror-class pairing requires the mirrored value (and vice versa), element-form styling with no pairing requires bare (and vice versa), the classed default is declared by omitting the capability, a mirrored template never merges its mirror class onto the root, and the badge tags (the value word on the stories meta, <value>:playground on the Playground story) carry exactly the declared value.
5353.21findClassFormOnBareA component declaring the bare styling value carries no .{name} class compound in its CSS; the element form alone styles it.
5353.22findCollidingClassWordsNo class word is declared by two of a component's enum surfaces - two visual capabilities, two enum props, or one of each.
5353.23loadComponentSpecThe spec factories reject a declaration not written as (identifier, options), an option the factory does not read, and a slot, prop, or facet not built by its factory; the load fails and lint reports it.
5353.24loadComponentSpecThe spec factories reject a flag written at its default - required: false, outlier: false, asClass: true, isGlobal: false, or a boolean prop default: false.
5353.25loadComponentSpecCapability.X.use([...]) rejects values listed out of the capability's declared order.
5353.27findUndeclaredCrossReferencesA component or utility stylesheet reads another entry's token, re-points one, or styles another entry's class only when that entry is in its dependency closure, so a selective bundle ships everything the stylesheet references. Run via yarn cli 53-27 (part of yarn lint).
5353.28findEmptyExampleMarkupEvery example except empty renders markup when the component declares any slot, prop or capability value.
5353.29findUndeclaredMarkupClassesEvery class word in rendered example markup is declared by the component, a dependency, a utility or a foundation enum.
5353.30findInlineVisualCapabilitiesEvery visual capability a spec attaches is drawn from the canonical registry in spec/spec.js rather than built in the spec file, and is attached with .use([...]) rather than by bare reference.
5454.1findProhibitedWordsNo file git tracks or would track contains a word from PROHIBITED_WORDS, matched regardless of case and anywhere in a line, unless the word's allowedIn names the file.
5454.2findStaleAllowancesEvery allowedIn entry names a file the scan reads, and that file still contains its word.
5555.3findPathImportsIntoPackagesNo script outside packages/ imports a module inside a package by relative path; it imports the package by name through an entry point its exports map lists.
5555.4findImportsLeavingPackageNo script inside packages/{name}/ imports a file outside that directory by relative path; Node built-ins, dependencies and the package's own entry points are imported by name.
5555.6findSeamBypassesEvery project-module read inside the CLI goes through loadProjectModule() in packages/cli/src/lib/project.js; no other CLI script imports through pathToFileURL() on its own.
6161.4findMissingPlaygroundStoryComponent has an export const Playground.
6161.5findPlaygroundRenderWithoutArgsPlayground render accepts args and forwards them.
6161.7analyzeStoryThemeApplyRenders apply the controls handle from withControls() onto every Twig call.
6161.7findShadowedControlsA Playground render does not overwrite a slot or prop whose generated control still stands; a story-owned slot is declared in the storyFor() demo map.
6161.8findMirrorStoriesNo Classless / Mirror story exports.
6161.9findObjectControlsNo control: object on non-passthrough props.
6161.10findStepLessPlaysA play that drives more than one user action wraps each action in a named step(); only the userEvent calls the play makes directly count.
6161.12findDesignTokenReadsInChromeEvery chrome stylesheet (the shared stories*.css and each *.stories.css) reads only --story-* variables and never a var(--x, fallback); a demo whose subject the token is opts out between /* lint-chrome-tokens: off <reason> */ and /* lint-chrome-tokens: on */.
6161.13findPerComponentChromeViolationsEvery .story-* class a per-component *.stories.css names carries its owner's story-{component} prefix unless the shared chrome declares it.
6161.15runChromeCheckShared chrome classes are listed in src/tools/storybook-chrome/README.md and have a leading purpose comment.
6161.15findPerComponentChromeViolationsPer-component chrome classes sit in the README's per-component table by full name (a trailing * names a family), carry a leading purpose comment, and every listed class exists in its owner.
6161.17findProsePoolsA story-local demoSet() / demoPool() holds structural data; a string of six or more words is prose and comes from sentence(), paragraph() or a demoText entry.
6161.21findPlaylessStoriesEvery component stories file carries at least one play.
6161.23findFormControlStateGapsThe plays of a Form controls/ stories file assert the states its spec declares (is_disabled, is_checked, is_invalid); a bound control also tabs into the control and asserts focus. A comment or rendered markup naming a state is not evidence.
6161.27findUnprefixedChromeVariablesA per-component chrome stylesheet declares only --story-{component}-* variables, or sets a variable the shared chrome declares.
6161.27findUndeclaredChromeReadsEvery var(--story-*) read in a chrome stylesheet names a variable the shared chrome or the sheet itself declares.
6161.25findLegacyConstrainNo legacy constrain parameter or constrain() helper.
6161.26findChromeInRenderNo class="story-..." chrome inside a component or pattern render other than the Level 2 content atoms and story-docs; renders return the component directly (canvas chrome belongs on parameters.canvas).
6161.26findFrameworkWrappersInRenderNo layout-utility class (container, grid, flex, spacing, sizing) on an element a component or pattern render authors; the file-level // lint-story-chrome: off marker opts out.
6161.36findSeparatorJoinsA render placing component instances side by side joins them with ''; a join building a class attribute, an id list or an accessible name keeps its space.
6161.31findRedundantCenteredLayoutNo per-story layout: 'centered' restating the preview-level default; only a centered that overrides an earlier fullscreen / padded is kept.
6161.30findThemeStoriesNo per-story theme arg or theme-named story exports.
6161.32findHardcodedOptionControlsOption controls spread optionsControl(options) so the control type follows the summed label width; hardcoded select / radio / inline-radio is forbidden in either the string or object form.
6161.33findLiteralDemoContentComponent / pattern stories pass no string literal on a content-bearing key; content is referenced as code from the demo-content.js registries or a story-local demoSet() / demoPool() definition, with // demo-literal: <reason> as the reviewed escape.
6161.35findCapabilityLiteralClassesStories route capability values through the capability arg (story.values() on the own component, valuesFor() on a composed one), resolved against the component the call targets; a capability value as a string literal in a classes array, a canonical value the target does not declare, and a class word declared by nothing in the system all fail, with // capability-literal: <reason> as the reviewed escape.
6161.34findHardcodedPlaygroundValuesA Playground play asserts no toHaveClass word or toHaveAttribute value that spells one of the component's own spec values; every such expectation derives from args.
6363.1findCopiedPartialsNo story partial repeats the body of an earlier partial in its directory, compared with Twig comments and whitespace dropped - identically, or with every difference replacing the same word with the same other word. The stories render one partial and pass the value they differ in.
6363.1findMisnamedPartialsA partial is named {name}.{composition-kebab}.stories.twig after its directory, or {name}.stories.twig while it is the directory's only partial.
6363.1findNonSiblingPartialImportsA *.stories.js imports every *.stories.twig partial from its own directory.
6363.1findStoriesWithoutPartialEvery pattern stories file imports a partial from its own directory. A pattern is a composition by definition; which utility and layout-component stories are compositions stays a review call.
6363.2findDemoContentLookupsA partial calls no function and reads no binding that demo-content.js or demo-content.core.js exports; the stories file looks the content up and passes it in as a slot variable.

Review-only rules​

These rules have no automated check today. CI doesn't catch violations; reviewers do. Each row is a candidate for future codification.

RuleSub-rulesDescription
1111.1, 11.2, 11.4-11.13Markup: Rendering modes
1212.1-12.8Markup: Data attributes
1313.1-13.10Markup: Accessibility
2121.1-21.9, 21.11-21.14CSS: Class structure
2222.3-22.12, 22.14CSS: Capability vocabulary (non-enforced sub-rules)
2323.2, 23.6, 23.9-23.17, 23.19-23.24CSS: Tokens and options (non-enforced rules - definitions, units, options)
2424.1-24.10, 24.14-24.17CSS: State and color scheme (non-pairing rules)
2525.1, 25.3-25.7CSS: Animations (non-enforced sub-rules)
3131.1, 31.2, 31.4-31.11, 31.15Twig: Component props (non-prefix rules)
3232.2-32.19, 32.21-32.24Twig: Code formatting (body)
4141.1-41.3, 41.6-41.9JS: Progressive enhancement (non-registration rules)
4242.2-42.12, 42.14, 42.15JS: Unit tests (structure, coverage, public API contract)
4343.3-43.9, 43.12, 43.14, 43.20, 43.21JS: Custom events (emission, notification / intent split, JSDoc, spec listen references)
4444.7, 44.8JS: Spec contract (behavior buckets, factory validation - enforced at CapabilitySpec construction)
4545.9-45.11JS: Module and lifecycle shape (scope collection, prerequisite retry, wrapping keyboard navigation)
5151.1-51.7, 51.10Project: File structure (non-comment rules)
5252.5, 52.6Project: Stories folder alignment (linter implementation, move-together)
5353.2, 53.5, 53.6, 53.9-53.14, 53.26Project: Component spec (non-enforced sub-rules)
5555.1, 55.2, 55.5Project: Workspace packages (location, naming, manifest, test layout)
6161.1-61.3, 61.6, 61.11, 61.14, 61.16, 61.18-61.20, 61.22, 61.24, 61.28, 61.29Storybook (autodocs, interaction tests, demo content, mdx documentation)
6262.1-62.8Storybook: Chrome levels
6363.1 (utility and layout-component stories), 63.3-63.5Storybook: Composition stories (which utility and layout-component stories render from a partial, render functions, canonical shells, lint exclusion)

Snapshot​

  • Enforced: 21 rule(s), 133 sub-rule check(s).
  • Review only: 22 rule(s) / sub-rule groups.