The specification

1. Blocks derive from the component filename.UserCard.tsx becomes .user_card. RootLayout.astro becomes.root_layout. For framework route files with generic names — index.astro,page.tsx — use the route's semantic identity instead:.home_page,.settings_page.

2. One hyphen joins a block to its element. Underscores separate words inside either half. The hyphen therefore means exactly one thing in the entire codebase: belongs to.

3. Element names are flat. They never encode DOM depth, and selectors never nest to reach them. Depth changes; names should not.

Those five required files are the only place global responsibilities live. A component stylesheet must never redefine a reset, a token, a layout primitive or a generic — if you find yourself wanting to, the thing you want belongs in the global layer, or it is not as global as you think.

fonts.css is the one optional member, and it is optional for a reason: a project on system fonts does not need it, and a project that has fonts should keep @font-face out oftheme.css. Loading an asset and naming a typeface are different jobs —fonts.css declares the files, --typeface-* in theme.css decides what they mean. Import it first, so the faces are known before anything asks for them.

The firewall has three rules and they are worth memorising:

• Components read Layer 3 only. Reaching into Layers 1 or 2 is always a bug.
• Semantics point down at the theme switchboard, never sideways at another semantic.--button-bg: var(--bg-surface) creates a token with no theme of its own.
• Anything reusable enters through theme.css and gets all three layers. Anything genuinely one-off stays local as --c-*.

Extensions are bespoke interactive colours the design system genuinely needs — this site adds --action-contrast. Every interactive extension must ship with a matching-hover pair; a colour you can click needs a colour that says you clicked it.

Intents are static status colours, limited to three weights:base, subtle, strong. Enough for a badge, a banner and a chart. Not enough to reinvent the palette.

The spacing scale runs on a 4px grid where --space-4 equals 1rem. The number in the token is the grid step, not an arbitrary index, which is why the scale can be extended without renumbering anything.

.l_switcher is container-query driven, not viewport driven, so a component moved into a sidebar rearranges itself without anyone editing a media query. Thresholds follow the standard container scale from3xs to 7xl.

Two classes on one element means two owners for display, gap andmargin, which is a specificity argument waiting to happen. Worse, the component now knows how it is arranged, so it cannot be moved without editing it.

One exception. A block may set position: relative on a direct child.l_container to establish a stacking anchor, provided it does not touch the container's display model.

Verify it in CI. If a raw fluid( reaches your output, the plugin never ran:

Stack inside a stratum with delta maths — calc(var(--z-overlay) + 1) — so the relationship is visible in the value rather than implied by two numbers being near each other.

Transitions must use --duration-* and--ease-*, because they respond to user input and must obey prefers-reduced-motion centrally.Named animations may use bespoke timings, because choreography is authored, not systematic. Composable chunks like --transition-pressable exist so utilities can share physics safely.

Utilities (u_*) are single-purpose and state-free. Zero-state contracts — the ones that strip user-agent styling — are wrapped in :where() so their specificity is zero and a component class always wins without anyone reaching for!important.

Generics (g_*) are real visual objects that are too ubiquitous to deserve a component file: .g_divider, .g_spinner, .g_tag,.g_kbd. They follow every BEAM rule and may hold state.

.g_prose is the one sanctioned exception to the no-descendant-selectors rule. It is an encapsulation zone for HTML you did not write — Markdown output, CMS bodies — where there are no classes to target by design.