# Principles — the rules of taste > **Read this + `tokens.css` before any UI work.** This is the "rules of taste" doc the rest of the system points at. It was missing from the v0.2 build export, so this file **consolidates the rules that were already documented** across `tokens.css`, the original README, `surface-matrix.md`, and `anti-patterns.md`. Mitch: review and expand — anything only in your head isn't captured yet. The system describes moves we trust — not a regulatory framework. Curated defaults. Override when a brand genuinely calls for it; just be deliberate. --- ## 0. The first decision: name the surface type Before writing any code, **name the surface out loud** — "this is a trust-led marketing surface," "this is admin chrome," "this is a quiet moment." The surface type determines which patterns are *legal*. Most mistakes in this system aren't wrong-color-wrong-size; they're **right-pattern-wrong-surface**. The stadium block isn't bad — it's bad on a payments landing. → The full menu of what's legal where lives in **[`surface-matrix.md`](./surface-matrix.md)**. If a pattern isn't on the row for your surface, it's off-limits — even if you like it, even if the brand color would work. --- ## 1. When in doubt, restraint wins The single most load-bearing rule. Concretely: - **One brand color.** Primary CTAs and active states. Not every button. - **One display font for emphasis** per surface — reach for `--font-display-sans` / `--font-display-serif` maybe 1–2 times per surface, never as chrome. - **Generous whitespace.** Use the spacing scale; let surfaces breathe. - **Hard edges over rounded-full.** Rounded-full + bright fill on small UI = AI-generated SaaS sheen. Keep `--radius-sm` on buttons and pills. - **No shadows by default.** Earn them (`--shadow-pop`, `--shadow-modal`); don't sprinkle them. If you're unsure whether to add a move, **default to off** and add later if the surface earns it. --- ## 2. The two signature "loud" moves (and their only homes) 1. **Editorial lime highlighter** (`--editorial`, the `.h-highlighted` class) — **list-page H1 only.** On a marketing hero or a body word it reads like a Linear marketing site, not a domain product. 2. **Stadium block** (full-bleed color + `--font-display-sans` at huge scale, the Sam Fender move) — **editorial / cultural surfaces only.** On trust-led marketing it makes the brand read like a tour announcement. When in doubt on either → **off.** --- ## 3. The quiet moves (under-used, worth reaching for) - **`--report` blue numerics** — reporting/analytics headline numbers. Not brand color on numbers. - **Italic-serif accent** (`--font-display-serif`) — *one* noun/verb/emphatic-adverb per surface, on a semantically loaded word. Never a preposition, article, or decoration on a clause's last word. Home: quiet moments (confirmations, empty states, thank-you). - **Mono overline / caption** (`--font-mono`, `--track-wide`) — eyebrows, tabular numerals, receipt/terminal register. --- ## 4. Type discipline - Running sans (`--font-sans`) for all chrome — body, labels, headings up to `--text-2xl`. That's the app-chrome ceiling; bigger is editorial. - Display slots are **second-mode type, not chrome.** See §2–§3. - Negative tracking only on display sizes (`--track-tight`). Wide tracking only on mono caps eyebrows. --- ## 5. Color discipline - Structural neutrals (`--bg` … `--rule`) are stable across builds — consistency is doing the work. Override only with a genuine reason. - Status colors come in bg/fg pairs — `--success` on `--success-bg`, etc. Don't invent one-offs. - A **competitor's color is not a brand decision for our product.** When someone shares a reference image, ask *which axis* it points at — composition? color? type? scale? — and lift only that. (See anti-patterns: the fluorescent-lime mistake.) --- ## 6. Don't render chrome you haven't earned Every chrome pattern must earn its place against the actual business shape: - No fake stats / proof strips. If a number isn't real and verifiable, it doesn't go on the page. Show the artifact (a real quote, receipt, named testimonial), not metrics about it. - No call-center top strips, multi-channel chrome, or "Featured On" logo walls unless they're true. - No generic square-letter logo box. For receipt/terminal brands, the wordmark in the right typeface *is* the logo. - Numbered `01 / 02 / 03` eyebrows belong on **sequences**, not on column triplets. If the items aren't ordered, the numbers are SaaS-template decoration. → Full worked examples in **[`anti-patterns.md`](./anti-patterns.md)**. Read those *before* defending a "but the pattern is in the system" decision. --- ## 7. Project brief beats the system A specific project's brand brief (e.g. **[`brand/shopconnect/brand-brief.md`](./brand/shopconnect/brand-brief.md)**) lists narrower ON/OFF patterns and voice. **Project beats system.** The system is the default; the brief is the law for that surface. --- ## How to keep this current When you change your mind about a pattern, **edit the file** — don't work around it and let it go stale. Doc catches up with practice, not the other way around. New pattern? Check `reference-library/reference.html` first; if it's not there, build it consistent with the existing patterns and we'll add it.