Semetrika - Architecture Rules
Rules describe mechanisms - how to name, compose, wire up, or document something. They do not list specific instances.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in these rules are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.
Code examples are illustrative. They demonstrate the mechanism, not the actual implementation.
Numbering. Rules are grouped by type using a reserved decade
per type - Markup (11-19), CSS (21-29), Twig (31-39), JavaScript
(41-49), Project (51-59), Storybook (61-69). Each type has room
for up to nine rules before the next decade. Sub-rule numbering
stays X.Y (e.g., Rule 21.10).
Read first: Introduction · Glossary · Architecture · Enforcement coverage
Background: References - landscape research, evaluation criteria, and role definitions that inform the rules below.
Every rule file ends with an Enforced by note (a :::note[Enforced by]
directive) that points at the automated check (or marks the rule as
review-only). The full matrix lives in enforcement.md,
which is generated from packages/cli/src/lib/rules-registry.js - run
yarn cli enforcement after changing a rule's enforcer.
Markup
- Rendering modes - classless, class-based, mirror classes
- Data attributes - three uses
- Accessibility - WCAG 2.2 AA
CSS
- Class structure - component-scoped values,
@layer - Capability vocabulary - canonical word list
- Tokens and options - design tokens + runtime flags
- State and color scheme - pseudo/ARIA/namespaced
data-*+ page-leveldata-color-scheme+:root[data-color-scheme='dark']override block - Animations - motion and reduced motion
Twig
- Component props - prop naming
- Code formatting - header layout, defaults, vertical rhythm
JavaScript
- Progressive enhancement - JS as enhancement
- Unit tests and coverage - mandatory
*.test.jssibling, 100% line coverage - Custom event naming -
component-action(hyphen, lowercase) - Spec contract for events and data attributes -
spec.eventsandspec.attributestrack every JS-side API surface - Module and lifecycle shape - IIFE form, lifecycle and handler names, WeakMap registry,
AbortControllerteardown - Collection access - one end-relative read form per receiver type
Project
- File structure - component directory layout
- Stories folder alignment - story title group ↔ source folder mapping
- Component spec -
{name}.spec.jsas source of truth for description, props, values - Prohibited words - words no repository file may contain, each with its own allow-list of files
- Workspace packages - where packages live, what they expose, and the import boundary in both directions
Storybook
- Storybook - stories, chrome, demo content
- Chrome levels - three placement levels for Storybook chrome classes (canvas, in-canvas content, story docs) plus the autodocs surface
- Composition stories - layout components, utilities and patterns ship per-story Twig partials; JS handles demo content and arg forwarding only