name: system-css description: Author HTML/UI with system.css — an OKLCH + type-driven design engine where components are styled semantic elements themed by inherited custom properties (--hue, --bg, --fg, --lift, --type), not variant classes. Use when building or editing pages, components, forms, tables, dashboards, or app shells on system.css; when the user mentions system.css, the painter/engine model, the .page shell and pg-* regions, the revert-layer gates (.mobile/.tablet/.desktop), the .row/.column/.grid primitives, the .card/.tag/.avatar/.tabs-underline/.search-box components, the semantic hue locks (.suc/.inf/.wrn/.dgr), the number family (.num/.delta/.num-good/.est/.past), or the Laws of authoring. Do NOT use for Tailwind, Bootstrap, or Material work — this engine rejects palette-of-decisions frameworks. scope: general (the engine travels; the EventOS paths inside are examples)

system.css — the engine

system.css is a small design engine, not a component library. You style semantic HTML (button, table, form) and a handful of composition classes, then theme everything by setting a few inherited custom properties. There are no .btn-primary / .btn-lg variant classes. A button is a button; its appearance comes from the --bg/--fg/--hue it inherits.

ONE file, one spine

The engine is a SINGLE file: static/system.css, edited in-repo (the old four-file split and the "canonical source lives elsewhere / read-mostly" doctrine are both retired). Concern boundaries survive as @layer sections inside the file, opened by one spine statement:

@layer reset, core.color, core.type, core.layout, theme, base,
       components, utility, media, skin, view-transitions;

Layers, not source order, decide the cascade — read the whole file before changing it (the layer order IS the cascade; a rule's position in the file tells you nothing about who wins).

THE PAINTER MODEL (how color works)

Color is computed, not picked. You never write a hex value. Instead:

• --hue (0–360) sets the base hue for a subtree. --hue-shift nudges it relative to context; --hue-lock pins it absolutely regardless of what's inherited (used by components and graphs that must stay a fixed color).
• --bg is an ABSOLUTE surface position on a −1…+1 walk through three theme anchors: −1 = neutral floor, 0 = paper, +1 = full chroma. Setting --bg on any element repaints its surface (the universal :where(*) rule re-derives the internal --_bg from each element's own --bg).
• --lift is a RELATIVE surface: this element's surface, N above the host it sits on. Use --lift for "slightly raised card on whatever's behind it"; use --bg for an absolute surface.
• --fg is the INK. Sign selects neutral vs chromatic ink; magnitude sets intensity. --fg: -1 = full neutral ink (near-black on light). --fg: 0.85 = high-chroma ink toward the current hue (this is how colored numbers get their vivid green/red). Small negative values (−0.5…−0.6) = quiet/muted ink.
• --type is a size STEP on the type scale; it also drives weight — and it INHERITS (canon since gf-68): set it on a container and the subtree follows; the scale is absolute, so steps never compound. Type IS spacing (lh/em everywhere), so one step re-rhythms text AND gaps AND control heights (--_control-h is type-derived). COMPONENTS never re-type their own elements — only a USAGE site nudges, only through the knob.

Registered properties (@property — typed/animatable): --bg, --fg, --hue-shift, --lift, --gap, --type, --_sem-ink, --row-width. Everything else is a plain custom property.

• --focus and --border are the derived token PAIR every surface computes: --border is the quiet edge, --focus the vibrant one (focus rings, the .Card voice, active outlines). Read them (border: 1px solid var(--border)); never redefine them.

Publisher contract: a region or .bg element paints via background-color: var(--_bg); --surf: var(--_bg); --surf-bg: var(--bg). You rarely write this — regions and .card do it for you. If you set --bg on a custom element and want it painted, add .bg or let a pg-* region rule do it.

THE CASCADE CONSTITUTION (hard laws)

1. Layers decide the cascade. Within a layer, specificity is ZERO. Every selector is wrapped in :where(...), and :not() guards go INSIDE the :where(). No ID selectors, no !important outside the media and skin layers (config switches that must out-cascade), no specificity battles. A specificity conflict is a SYSTEM FAILURE requiring root-cause review — never patch it with a more-specific selector.
2. Do not touch engine internals when the public API suffices. Internal vars are --_-prefixed (--_bg, --_sem-ink). Author with the public knobs above. If you find yourself reaching for --_sem-ink, stop — you almost certainly want --hue-lock + --fg instead.
3. The right LAYER owns the change. Region surfaces (pg-* --bg) ship in the skin layer; an app recipe that has settled graduates into the engine's own components layer (the project layer RETIRED 2026-09-01, gf-133 — ProjectStyles is gone); a public page's one-off look lives in that page's own @scope block (the landing's idiom). A rule in the wrong layer is silently out-cascaded — that is a layer-placement bug, never a specificity problem to fight.
4. NO NEW CSS CLASSES (gf-185, per Mike, at maximum emphasis). The engine's whole point is explicit declarative HTML composed from the EXISTING composition classes + the style API (--type/--bg/--fg/ --hue-shift/--hue-lock/--lift/--gap) — never a new class per feature. A vertical stepper, a card variant, a layout arrangement: composition (.row/.column + knobs + the ARIA-state idioms + native elements like ), not a class. The EXCEPTION LIST is components that require CLIENT STATE (the google-maps rocket, the date picker) plus Mike's named three — .wash, the landing's @scope, .app-icon — nothing else qualifies without an explicit conversation with Mike. When composition genuinely cannot express something, that is a gap to RAISE (evolve a composition class, or extend the exception list — at the lab bench, with Mike), never a silent new class. Class sprawl "enables a corruption that is mathematically impossible to overcome after a certain point." Corollary: every NEW component or convention is demoed in THE LAB (system-css/site/lab, published at https://deufel.github.io/system-css/lab/) and aligned with Mike BEFORE product use.

Enforcement is Go now (the cowork-era conformance.py is long gone): go test ./... runs view/ratchet_test.go — the INLINE-GEOMETRY ratchet (style= is sanctioned only for --knobs, anchor-name/position-anchor, and commented one-offs; per-.templ counts may only go DOWN), the icon 24px-box ratchet, and the anatomy-reach ratchet (project CSS may not restyle engine anatomy). The cssaudit package charts lines-per-layer complexity on the admin Metrics page. Keep them all green.

LAYOUT — the page shell and primitives

Regions (grid areas on .page, 5-column shell): pg-banner (b), pg-header (h), pg-subheader (s), pg-navigation (n), pg-toolbar (t), pg-main-header (mh), pg-main-subheader (ms — a band under the main header: tabs, crumbs, filter strips that belong to main but must not scroll with it), pg-main (m), pg-main-aside (ma — the main-scoped flank, inboard of pg-aside, starting under the main header), pg-main-footer (mf), pg-aside (a), pg-footer (f). Set --bg on any of them to repaint. pg-aside is recessed by default.

Rails are MIN-WIDTH, TYPE-DERIVED, SERVER-DRIVEN. The published knobs are --pg-navigation-w / --pg-toolbar-w (default 8lh, stamped once on .page); rails can GROW for long content and are exact only when collapsed, where the width is the glyph ANATOMY calc (glyph + item padding + rail padding — centered by construction, never by bespoke rules). Collapse is an explicit server-stamped width (the theme pref (sys_pref, key nav_density) → --pg-navigation-w: var(--rail-w-icon)); labels drop out through the container TIER gates (.medium/.large on the label span). The data-ui-density attribute is RETIRED and stays retired — never infer density from attributes, and never infer rail shape from page width (the @container page restyle is retired too).

Asides are CONTENT-SIZED (no declared width, no containment — the auto track hugs the one-off widget the flank carries). Consequence: aside content cannot gate on the aside itself. ONE topology: there are no alternate grids at narrow widths — a region that cannot fit gates itself (.c-desktop on an aside) and its track collapses; narrow reachability of a gated flank is an app decision (dock, drawer), not a shell re-slot.

Flow primitives: .row / .column (flex), .grid (auto-fit with --grid-min), .spread (space-between row), .lcr (left-center-right 3-zone grid — used for headers), .flank, .oneline (nowrap), .stack (overlap).

Responsive gates (revert-layer trick, in the media layer) — TWO FAMILIES, TWO JOBS:

• Viewport gates: .mobile / .tablet / .desktop show an element only at that viewport width. Container equivalents (LAYOUT band family): .c-mobile / .c-tablet / .c-desktop, same breakpoints (576px / 768px) measured on the nearest query container.
• DENSITY TIERS (component scale): .small (< 8rem) / .medium (8rem–20rem) / .large (≥ 20rem). small = the glyph alone; medium = glyph + label; large = the full block. "And-up" is the multi-class idiom (class="medium large"). The 8rem boundary is rail math: it straddles the rail's two declared widths at every type size, so rail content gates on the tiers instead of inferring density from attributes.
• .fine / .coarse gate on pointer type.
• ORIENTATION and HEIGHT gates (gf-608): .c-portrait / .c-landscape (landscape = wider than 3:2) and .c-short / .c-tall (tall = 10em and up). They answer only inside a SIZE container — a .block — never a width-only .container. THE BLOCK (gf-608, Mike: "each block is able to manage itself"): .block is a size query container with ONE child, its body — a flex column in portrait, a row in landscape (the words first, the big thing beside them). It fills the cell a grid track, a .frame or a .stress hands it and never sizes itself (size containment collapses it under an auto-height parent). A block is pure composition: the engine's tiers and gates inside, no per-block CSS; the lab's Compositions page carries the specimen. .stress resizes both axes. Container rule: gate classes go on a dedicated wrapper div, never on a styled leaf component, and the gated element must also carry a layout primitive (revert-layer restores the primitive's display, not a default).

Focus mode (gf-262): a STORED pref like every other display choice — the server stamps data-ui-state="focus" on .page and the chrome collapses so pg-main* fill the viewport. The Theme shelf of the profile dialog posts /settings/focus/mode; the focus fab retired in gf-307 (its engine classes .focus-fab .i-expand .i-collapse wait, undemoed, for the day it returns) and the old hidden #focus-toggle checkbox before it.

THE EDIT CARD (gf-262, view/settings.templ editCard): the ONE shape for a record's form — h3 + pencil top-right (unlocks), the canon fieldsets bound readonly while locked, Cancel bottom-left as a native type="reset" (the fields fall back to their stored values — no seed strings), Save bottom-right posting the form (contentType 'form'). Stored values are judged by the RENDER (aria-invalid + the message in the field's small — canon (4)); a wizard lights the one control to click next with data-ui-state="guide" (a still ring + a slow glow, motion-gated; the set-up walk that first used it retired in gf-313).

Print: @media print (in the media layer) strips every region except pg-main*, drops surfaces to white while keeping borders, forces black ink. The screen is the themed medium; paper is austere.

COMPONENTS (styled semantics + a few classes)

.card (lifted surface panel), .tag (small pill; pair with a hue helper), .avatar, .crumbs (--type: -3, a crumb is a BARE link — the recipe restates nothing base owns, gf-334), .tree (nested lists of links), .tabs / .tabs-underline (the latter is the GitHub underline treatment; icon-aware, .count pill support), .button-group, .nav-item / .nav-icon, .drawer (+ .left/.right/.top and .glass), .modal, .menu (popover), .search-box (icon+input+kbd as one control), .icon (THE icon-only square — explicit class, aria-label required; never rely on selector inference), section.owns-scroll (a component-scrolled section that stops clipping — how every full-height roster is built; overflow-y:auto clips BOTH axes, which is why corner badges shear without it), .roster (THE SERVER-DRIVEN TABLE: one class on the div holding a roster's head, form and table; truncating cells, the hugging column model with .clip absorbers, tonal head and hover, 1lh head controls that wake on hover, the shadowed .scroll-x — all CSS over server markup, zero client state), .focus-fab, .glass (the surface at --glass-alpha over a --glass-blur of what is behind; 0.65 is a dialog over its dimmed backdrop; an overlay that must read over anything — a toast — wears 0.88; quiet is ink, never opacity on glass: opacity multiplies into it), .hud overlay slots (t/c/b row × l/c/r column; corner slots pad 1lh, the centre none — a scope zeroes it when the top row must be one line, gf-358; a .fab-1/2/3 inside a .hud is frozen to 2.4lh), .wash (gf-359 — a viewport-fixed underlay of two soft pools in the surface's own colour; :has(> .wash) makes the HOST a stacking context so the pools paint above its surface and under its content; the second pool is a real CHILD at --hue-shift: 30, never a pseudo — the engine resolves --_bg per element), .county-map (an engine recipe demoed in the lab only since gf-364's picker paints by --fg groups).

The practice bench is the lab's Forms page (site/lab/forms.html, https://deufel.github.io/system-css/lab/forms.html); the engine rules live in the form/fieldset sections of system.css. If a product form doesn't look like the bench specimens, the product form is wrong.

• Everything lives in <fieldset>s. A fieldset is ONE ROW of fields; <legend> names the group (the legend's own <small> is the GROUP state slot). A form-section heading is <h3>.
• Every field — checkboxes included — is label → small → control: <label><span>Name</span><small></small><input/></label> (checkbox: <label><input/><span>Text</span><small></small></label>). The EMPTY <small></small> is mandatory — it reserves the 1lh state row so the layout never shifts when a message lands.
• <small> is STATE, almost never a caption. Self-descriptor hint text is a smell — if information is truly needed, it belongs in the page's info popover. State lights the slot through the canonical channels only: aria-invalid="true" on the control (danger hue + message in that field's small) or .suc/.inf/.wrn/.dgr on the label or fieldset. Never a separate error div.
• Everything fills the entire width — controls by the canon's own rules; a lone submit button in a .column does NOT stretch on its own, it takes class="fill" (gf-313: the wizard's buttons). Row shares ride --row-width: <number> — a BARE NUMBER (it is a registered <number> property; a flex shorthand like 1 1 100% is INVALID and silently falls back to 1). Since gf-173 labels flex under legended fieldsets too; buttons keep hugging.
• The submit runs through datastar: data-on:submit__prevent={"@post('"+url+"', {contentType: 'form'})"}. A file input additionally requires enctype="multipart/form-data" on the form (gf-52 — without it the bundle silently drops the file). A second endpoint on the same form = a data-on:click @post button (formaction can't fire under __prevent; nested forms are parser-dropped, gf-63).
• The handler stores → publishes → answers 204. Never HTML back, never a redirect on a datastar form; the fat-morph re-lands truth. required generates the asterisk — never hand-write one.
• <div role="form"> is the sanctioned formless spelling for a CQRS group (checkboxes that post individually) — same recipe, no submit.
• State rides the OUTLINE, never the surface (gf-174): a stated field keeps its neutral raised background; the locked hue colors only the border and the small (the engine re-hues the bg back to ambient — don't fight it, don't add tinted backgrounds).
• Fieldsets breathe: the engine gives a fieldset 0.35lh after itself inside a form (gf-174) — never add manual spacers between groups. An <hr> may draw the seam between CONCERNS in one form; a <details><summary> folds a rarely-touched tail (fields inside follow the same canon).
• The segmented groove splits EVENLY (gf-175): chips share the groove equally (flex: 1) and the checked chip wears the ACTIVE state paint (--bg: 1, inverted ink — same as [data-ui-state="active"]). Be prudent: don't wear the groove where the longest option can't fit its equal share.
• The LOCKED form (gf-175): the reading state — NOT disabled. data-ui-state="locked" on the form (field chrome stands down, controls sleep, buttons stay live) + real readonly on text controls for AT (aria-readonly doesn't apply to role=form). The state rides a SIGNAL + data-attr bindings so fat-morphs re-land it intact (the orgEdit precedent); Unlock flips the signal, Save re-locks through the normal 204+publish, Cancel just re-locks and the morph restores stored values. Specimen on the bench.
• THE SINGLE-ROW FORM (gf-183, per Mike): for concise surfaces that must not hog space — a chat composer, a compact search, an inline sign-in. ONE legend-less <fieldset>, BARE controls (aria-label + placeholder carry the name; no label grid, no state small), the submit hugging its own width (buttons hug in every fieldset). Weight fields with --row-width as usual. The moment a field needs a visible name or a state slot it has outgrown the pattern — use the full canon.
• THE ACTION ROW (gf-176, per Mike): submit bottom-RIGHT, cancel bottom-LEFT, SPREAD apart — <div class="spread"> as the form's last row (cancel/destructive first, submit last; a lone submit rides an empty <span></span> on the left). Opposite-effect buttons get maximum visual separation so a user can't fat-finger the wrong one. Never a centered or adjacent pair.
• THE DATABASE FLOWS (gf-176 — wired specimens on the lab's Forms bench): (1) EDIT/SAVE/CANCEL — the draft mechanism: Edit seeds signals from the stored value (the seed expression is server-rendered, so morphs keep it fresh), typing stays client-side, Cancel discards, Save posts signals → 204 → morph re-lands truth. (2) UNLOCK/AUTOSAVE/LOCK — no draft, no Save: the bound field posts on data-on:input__debounce.500ms, the morph carries the receipt ("saved …" in the legend's small), Lock re-sleeps the chrome. (3) SQL PREFLIGHT (gf-177) — the draft debounces into a CHECK op that validates WITHOUT writing (business rules + a uniqueness query, self excluded) and stores draft+verdict in a scratch row; the morph disables Save and speaks a CONCISE per-rule message in the error small (which speaks ONLY on error); Save re-validates and lets the real UNIQUE constraint backstop a race; Cancel clears the scratch — nothing was ever written. (4) DEBOUNCED STORED-STATE VALIDATION — the value stores raw; the RENDER judges it and the morph delivers aria-invalid + the message in the field's small. Validation is stored state re-rendered — never client truth; a second tab goes red at the same instant.
• THE LAYOUT-SHIFT DOCTRINE (gf-178, per Mike): whenever possible, do not cause layout shift. Editing must not reflow the page. For edits with significant validation, use the ANCHORED SMALL DIALOG: .modal.content-1.anchored — the subject wears anchor-name, the dialog wears position-anchor (the sanctioned inline pair). ⚠ Chrome gives DIALOGS no implicit invoker anchor yet (popovertarget does, commandfor on a dialog does NOT — verified live, gf-183): the trigger wears anchor-name, its click stamps el.style.positionAnchor on the dialog BEFORE commandfor opens it (pinned from the first paint), and the server re-stamps it by morph from the stored edit state. One dialog, many triggers. It opens pinned beside the subject in the top layer (zero shift), growing toward inline-START (edit triggers live at row ends), with a min-inline-size in the recipe — without one, auto width silently SHRINKS into a cramped position-area region instead of overflowing it, and position-try-fallbacks never fire (fallbacks trigger on overflow only — verified live, gf-184). The platform gives the focus trap + an inert page (exactly ONE edit open, by construction) and Escape/light-dismiss ARE cancel — wire data-on:close to the cancel op so an abandoned edit can never leak scratch state. One dialog per surface, always in the DOM (the selected-row idiom), content + anchor server-rendered from stored edit state, kept open across morphs by data-preserve-attr="open". Inline editing remains right ONLY for trivial single-value flips (a status select, a checkbox) — anything with preflight rules earns the dialog.
• .stress is the lab's resize handle (resize: horizontal) — for stress-testing specimens only; product surfaces size by composition.
• Radios have two spellings: a PLAIN group rides the checkbox recipe (input → span → small, one label per option, per-option state smalls); a short exclusive choice worn like a control is the SEGMENTED .tabs groove — a div role="group" with a .legend child (NOT a fieldset — its anonymous box breaks tile stretch). Both A label may carry an ICON before its span (gf-362: Manufacturer | Wholesaler | Retailer with factory · truck · store); a disabled option keeps its chip and says why in title. are specimens on the lab's Forms page.