Skip to main content

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​

  1. Rendering modes - classless, class-based, mirror classes
  2. Data attributes - three uses
  3. Accessibility - WCAG 2.2 AA

CSS​

  1. Class structure - component-scoped values, @layer
  2. Capability vocabulary - canonical word list
  3. Tokens and options - design tokens + runtime flags
  4. State and color scheme - pseudo/ARIA/namespaced data-* + page-level data-color-scheme + :root[data-color-scheme='dark'] override block
  5. Animations - motion and reduced motion

Twig​

  1. Component props - prop naming
  2. Code formatting - header layout, defaults, vertical rhythm

JavaScript​

  1. Progressive enhancement - JS as enhancement
  2. Unit tests and coverage - mandatory *.test.js sibling, 100% line coverage
  3. Custom event naming - component-action (hyphen, lowercase)
  4. Spec contract for events and data attributes - spec.events and spec.attributes track every JS-side API surface
  5. Module and lifecycle shape - IIFE form, lifecycle and handler names, WeakMap registry, AbortController teardown
  6. Collection access - one end-relative read form per receiver type

Project​

  1. File structure - component directory layout
  2. Stories folder alignment - story title group ↔ source folder mapping
  3. Component spec - {name}.spec.js as source of truth for description, props, values
  4. Prohibited words - words no repository file may contain, each with its own allow-list of files
  5. Workspace packages - where packages live, what they expose, and the import boundary in both directions

Storybook​

  1. Storybook - stories, chrome, demo content
  2. Chrome levels - three placement levels for Storybook chrome classes (canvas, in-canvas content, story docs) plus the autodocs surface
  3. Composition stories - layout components, utilities and patterns ship per-story Twig partials; JS handles demo content and arg forwarding only