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 files – reset, theme, layout, utils, generics – are the only place shared visual responsibility lives. 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 sixth file, and it is skipped only when there is nothing for it to declare: a project on system fonts, or one that already loads faces outside CSS – a Google Fonts <link> in the document head, or a bundler import in an SPA. A project that self-hosts must keep @font-face out of theme.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 memorizing:

• 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 colors the design system genuinely needs – this site adds --action-contrast. Every interactive extension must ship with a matching -hover pair; a color you can click needs a color that says you clicked it.

Intents are static status colors, 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 from 3xs to 7xl.

Two classes on one element means two owners for display, gap and margin, 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.

Never select by ID. An ID selector is a second identity system with specificity 1,0,0 – no class combination can override it without !important or another ID, and the name cannot be reused. HTML id remains legal for skip links, fragment URLs and JavaScript. Do not style those nodes by ID; give them a class. :target is a condition, not an ID selector, and stays legal.

Width queries are mobile-first. The unqueried rule is the small canvas. Every @media and @container query adds as the canvas grows, which means min-width only. max-width queries – and ceiling ranges like width < 64rem – invert the cascade: you authored the large canvas and then undid it, so the small-screen stylesheet is a pile of exceptions and the 63.999rem off-by-one is waiting for you.

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

Stack inside a stratum with delta math – 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.