Standing note — No hardcoded CSS; the token set is the tunable surface (toward a theme editor)

Version. v0.1 Date. 2026-06-26 Type. Standing note (development principle). Operator-facing; governs every frontend change request from here forward. Repository home. loomworks-record/standing-notes/

Plain-language summary

This records a settled principle for the Loomworks frontend: no hardcoded CSS values. Every visual value a component uses — a color, a font, a spacing, a corner radius — comes from a named token, never written directly into the component. The tokens live in one place (tokens.css); components refer to them by name.

Why this matters beyond tidiness. The goal is a product line of many custom Companions, each with its own look — and eventually a theme editor: a surface where someone tunes a Companion's appearance on a big screen and watches the interface re-skin live. That feature is only possible if every visual value is a token. A single hardcoded value is a pixel the editor can't reach — it would stay fixed while everything around it changes. So "no hardcoded CSS" is not hygiene for its own sake; it is the precondition that makes a live theme editor buildable at all.

What is decided now, and what is deferred. Color is tokenized repo-wide, now — it is small, regular, and the customization that matters most (brands care about color first). Typography and spacing are known debt, deferred: the app today has 16 arbitrary font sizes with no scale, and fixing that is a design exercise (collapse to a clean scale), not a mechanical sweep — it waits for a later, deliberate pass.

The principle (settled)

1. No hardcoded CSS values in component files. No raw hex or rgba(), no literal sizes in inline styles, no brand color or font written directly. Components consume tokens (via the framework's token classes); the values live in tokens.css.

1. The token set is the tunable surface. Tokens are not just an internal convenience — they are the API a future theme editor edits. So they are named and organized to be read and tuned by a human: semantic where it helps, grouped sensibly, not a mechanical dump of extracted values.

1. Distinct colors are preserved as distinct, tunable tokens — not consolidated. When two shades are nearly identical, they still each become their own token. Consolidating near-duplicates destroys tunability before the tuner exists. A future editor may offer to merge them; the tokenization does not pre-decide it. (This is the opposite of the typography rule below — colors multiply into knobs; type sizes collapse into a scale.)

1. **Typography and spacing conform to a designed scale, not a 1:1 tokenization.** The right number of font sizes is a handful, not sixteen. The type/spacing work is a consolidation — design the scale, snap the app to it, discard the noise — which means some sizes will shift slightly as they snap. This is deferred design work, not a find-replace.

1. A theme editor tunes a few meaningful knobs, never per-element values. The editor's controls are scale-level — a handful of colors, a type choice, a density setting — not a knob per value. Per-element customization is explicitly out of scope and a non-goal. The whole point of a scale is that one control moves everything that shares the token.

1. Build for Loomworks first; tunability is the consequence. The token set is designed for the appearance Loomworks actually needs — not speculatively for hypothetical future Companions whose needs cannot be known yet. The same ready-not-active discipline that governs the rest of the build: build the real thing clean, and it is swappable as a consequence.

Legitimate homes for literal CSS values

• src/styles/tokens.css — the sole legitimate home for raw color (and font/spacing) values. This is where colors are defined; here a literal hex is correct.
• src/app/globals.css — the token-wiring home (binds tokens into the framework). No raw color of its own.
• Both are excluded from any "no hardcoded CSS" guard. The guard scans component files (.tsx), where literal CSS is forbidden.

What's done, deferred, and named-future

• Done / in progress: Color tokenization. CR-2026-125 (Companion-surface Phase 1) tokenizes TopBar and adds the two off-palette tokens the repo needs (--color-vellum-soft, a gold token). CR-2026-126 (repo-wide color sweep) tokenizes every remaining color in src/, including white and shadow as swappable tokens, leaving zero raw color outside tokens.css.
• Deferred (named debt): The typographic + spacing scale. 16 arbitrary font sizes today, no scale to convert to. A later design CR collapses them to a designed, editor-tunable scale. Not scheduled; recorded so it is not forgotten and not re-litigated as "should we."
• Named future arc: The theme editor — a big-screen surface for tuning a Companion's appearance with live preview. The reason the tokenization is built the way it is. Built when the token foundation is ready; not now.

Guard (how the principle is enforced in code)

A static-scan test (the established vocabulary-wall pattern) over component files fails the build on raw hex / rgba() and on hardcoded brand literals outside the string registry. It reliably catches what a line-scan can catch (literal color, brand strings); finer rules (every user-facing string registered; no hardcoded spacing once the scale exists) remain review-enforced where a scan would be over-broad. The guard's scope grows with the work: scoped to new files in CR-2026-125, repo-wide for color in CR-2026-126.

DUNIN7 — Done In Seven LLC — Miami, Florida Standing note — No hardcoded CSS; the token set is the tunable surface — v0.1 — 2026-06-26