Shared design rules for the stylesheets: tokens, a short contract and a drift check

[JDProfresh]

More and more of us are adding UI to Codeman, and many of us work with an agent that reads CLAUDE.md before it touches anything. For the stylesheets there's nothing for it to read yet, so every PR picks its own sizes, spacing and colours, and the files keep growing new one-off values. I'd like to propose a small set of shared rules for that, and I'm raising it here first because it touches the files everyone edits and because the visual decisions are yours.

What it looks like today

Measured on master at 1.47.0 (f1f7eec4), across styles.css (23,337 lines) and mobile.css (4,208 lines):

Property	Distinct values
font-size	83 (for example 0.62rem, 0.63rem, 0.64rem, 0.645rem and 0.65rem all appear)
padding	286
border-radius	37
z-index	38
width breakpoints	14
!important	234 declarations

Since September 1, 203 commits from 11 people have changed those two files. None of that is anyone doing something wrong; there's just no shared scale to reach for, so a new rule copies whatever its neighbour uses or picks a new value.

What I'm proposing

One additive PR that changes no pixels and adds no dependency:

1. Tokens in a new css/tokens.css: --cm-* names for type sizes, spacing, radii, control heights, motion, and semantic colours that point at the existing skin variables (no new hues; colour stays with the skins). The z-index stack already documented in src/web/CLAUDE.md gets names, with its values unchanged. The file sits in a cascade layer, so it can only add names and can never override an existing rule.
2. A short contract, docs/design-system.md, with a pointer from CLAUDE.md and src/web/CLAUDE.md: new rules read tokens instead of raw values, colour belongs to the skins, overlays take a layer from the named stack, and where a new rule goes.
3. A drift check, npm run check:css: a small script that counts the distinct values in the table above and fails when a count goes up over a committed baseline. Reading a token never counts, so following the contract is always free. To be clear about what it is: it caps how many different values exist, it doesn't prove a new rule uses tokens.

What it deliberately doesn't do: no restructuring of styles.css or mobile.css, no visual changes, and no renaming of existing classes.

What could come after, only if you want it

• A small component kit (.cm-btn, menus, dialogs, switches, banners), each family arriving in its own PR together with the existing markup moved onto it and the old rules deleted, so nothing ships unused and nothing is styled from two places.
• I've been running a much larger version of this on my dev instance, including some UX ideas (a header overflow menu, panels that dock beside the terminal instead of covering it, a regrouped phone toolbar). Those are product changes, not rules, so if any of them interest you I'd bring each as its own thread with screenshots, the way you ran Tab strip redesign: seven directions, which ones would you use? #426.

Questions

1. Do you want shared design rules for the stylesheets at all, or would you rather keep reviewing them by eye?
2. If yes, are --cm-* names in a cascade layer the shape you'd want, or would you prefer plain :root variables?
3. The drift check: a hard gate in CI and the pre-push hook, warn-only to start, or not at all? As a gate, it would fail a PR that adds, say, a new 0.66rem font size until it uses a token or an existing value, which is the point but is also new friction for everyone sending CSS.
4. Should the contract live in docs/design-system.md with pointers, or directly in src/web/CLAUDE.md next to the other frontend rules?
5. Since the visual direction is yours: if I bring any of the UX ideas, is one thread each with screenshots the way you'd like to see them?

If it's a yes in some shape, I'll send the first part as one PR referencing this thread.