writing-css

name

writing-css

description

How CSS is written in this repo — every value comes from a design token, one component gets one name across both surfaces, and the five theme lints decide what ships. Covers the token layer and the half-finished spacing migration, modern syntax that is actually safe here (cascade layers and container queries are Baseline widely; anchor positioning is not), keeping specificity flat with :where() instead of !important, component structure and shared partials, DRY across report.css and panel.css, dark mode and print, and the anti-patterns that have already shipped invisible bars and an unthemeable printed page. Use when planning, writing, reading, reviewing or refactoring report.css, panel.css or _ui_theme.py, when adding a component or a colour, or when the same rule is about to exist twice.

Writing CSS here

Two stylesheets, ~2,000 lines, concatenated by Python after a generated token layer into one inline <style>. Neither is valid alone — both reference custom properties they do not declare, and panel.css on its own fails the color-scheme check. Assembly, splitting and the byte pins belong to refactoring-the-assembled-ui; this is how you write a rule.

Tokens are the language

_ui_theme.py declares 78 custom properties on :root (58 of them user-themable) and prepends them to both sheets. The discipline is already strong — panel.css uses var(--…) 605 times against 13 raw hex literals, report.css 429 against 8 — and it is the thing to protect.

• Never write a raw colour. If a role does not exist, add the token; do not inline a hex.
• The spacing migration is half done, so finish it rather than widening it. --sp-0 … --sp-7 exist and are used throughout the usage sections, yet .5rem, .25rem, .75rem, 1rem and 1.5rem are still written raw 204 times elsewhere — and each of those five has an exact token. Use the token.
• Type has a four-step scale and the sheets contain about 23 distinct font-size literals. Pick a step; add one if the design genuinely needs it.
• A metric both surfaces use is a token, or it will drift. It already has: .shell is max-width:92rem in the panel and 96rem in the report, .bud's grid disagrees in four places, the nav breakpoint is 70rem against 72rem, .tri is .9em against 1em.
• Adding a token has obligations. compile_theme(DEFAULT_THEME) == TOKEN_CSS is pinned byte-for-byte, so no comment inside TOKEN_CSS may contain a brace, and a new token must be placed in a theme group or the neutral list or the round-trip case fails.

Modern syntax that is safe here

Check the feature before using it — grep '^| container-queries ' in refactoring-the-assembled-ui/references/baseline-snapshot.md. As of the 2026-07-08 snapshot:

• Widely available, use freely: cascade layers (@layer), container queries (@container), :has(), nesting, :where()/:is().
• Newly available, needs @supports plus a fallback: light-dark(), view transitions.
• Limited, do not use: anchor positioning.

None of @layer, :where(), :is() or @container appears in either sheet today. That is the gap worth closing first: with no specificity management, source order carries the whole cascade, which is why report.css needs 18 !important declarations and a documented ordering dependency between two blocks 290 lines apart.

• :where() for anything shared. It contributes zero specificity, so a base rule written :where(a,button,input,summary):focus-visible{…} lets both surfaces override it without escalation. The focus ring is currently written four times in each file with no base.
• @container over @media for component-level responsiveness — a report is read at widths nobody chose.
• Media queries cannot read var(). A shared breakpoint is either one agreed literal in the shared part or a Python-side substitution; it cannot be a token like --nav-w is.

One component, one name

31 class names exist in both sheets. 35 pairs are the same component under different names — .utip and .rtip are 11 of 11 declarations identical, .uhmperiod and .hmperiod 5 of 5, .mut and .muted the same idea. Worse, ten names collide with incompatible meanings: .bar is an 8px track in the panel and a bordered 13rem block in the report; .chip is a neutral tag versus a status pill; .advice is the styled block versus the list containing it.

• Name the component once, and use that name on both surfaces.
• Rename before extracting. Merging two rules that share a name and disagree silently breaks one surface. The rename touches the emitters (panel.js, report.js, _report_html.py) in the same commit.
• Pick one modifier grammar. The tree has both .btn.primary and .btn-primary.
• A repeated selector prefix is a missing component class. The sticky-table-header recipe is written six times in panel.css and the table root nine times, differing only in font-size.

Dark mode, print

• Light is the base; dark is an override, and it is written twice on purpose — once under prefers-color-scheme and once under [data-theme="dark"] — because a media query and an attribute selector cannot share a block. Keep both in step.
• Never define a colour only inside a media query. A token declared only in a dark block vanishes in light mode; theme_asymmetric_vars() checks both directions because that shipped once as invisible bars.
• color-scheme must be restated wherever a theme is chosen — it is the one thing custom properties cannot reach, and it paints scrollbars, <select> menus and date pickers.
• @media print is outside the theme compiler's reach. A palette hard-coded there cannot be themed — which is the current state: the print block uses greys that exist in no token, so a themed report prints in someone else's colours.

Anti-patterns and pitfalls

• A raw value where a token exists — the single most common one here.
• !important outside @media print and prefers-reduced-motion. Every one of the 18 in the tree is inside those and carries a comment justifying it. Reach for :where() or a better selector instead.
• ID selectors for styling. There are about eleven; do not add the twelfth.
• Deep descendant chains (table.x tbody tr:last-child td) — eight of these in panel.css are one missing .tbl component class.
• A missing ; — it annexes the next declaration silently. unterminated_css_decls() exists because one such miss swallowed a five-line comment and a token declaration.
• A var(--x) with no declaration paints transparent and logs nothing. undeclared_css_vars() exists because that is how --bar-neutral shipped as invisible bars.
• A CSS escape mangled by Python string handling — mangled_css_escapes() exists because a filter chip shipped showing ¹30 instead of a tick, in every report for several versions.
• Reflowing a rule casually. Around 70 exact substring assertions pin the assembled stylesheet, two of them across line boundaries. Reflow deliberately and update the pin.

What must stay green

All five theme lints run against the assembled string — undeclared_css_vars, unterminated_css_decls, theme_asymmetric_vars, mangled_css_escapes, themes_missing_color_scheme. A sheet that is valid alone proves nothing.

Then the browser: node tools/capture-screenshots.mjs --check and node tools/check-report-interactive.mjs on a rendered report. These assert computed values and are the only thing that can catch a cascade-order regression a substring pin cannot see — a Python case can assert the CSS says display:block; only a browser proves the bar paints.