# Foundations — frozen 2026-08-29

The constitution of design system v2. These decisions were made by Rob after a four-direction
exploration scored against objective tests (contrast, density, greyscale survival, token coverage,
"name three products"). **Do not re-litigate them without a new decision from Rob.** The reference
render is the "BrewMDM Synthesis Mock" artifact; its final state encodes every value below.

Scope: every rknightion / m7kni / BroTEK product surface. Web apps consume tokens + components;
marketing/docs sites consume tokens + CSS only; SwiftUI apps consume generated colour/spacing tokens
with native controls (Liquid Glass — never custom cross-platform components).

## The six frozen decisions

1. **Density: compact.** 13.5px body, 12.5px mono table text, 36px table rows, 24px stat figures.
   Operator screens are tables; density is legibility here, not a squeeze.
2. **Spacing: 4px base**, steps 4 / 8 / 12 / 16 / 20 / 24 / 32 / 48 / 64. Matches Tailwind's scale.
   Never add an intermediate step.
3. **Type: Hanken Grotesk** (400 / 500 / 600 / 700) for UI, **JetBrains Mono** (400 / 500 / 600) for
   machine text — hostnames, versions, counts, timestamps, IDs, uppercase micro-labels. Scale:
   10 / 11 / 12.5 / 13.5 / 15 / 18 / 24 px. Micro-labels are mono, uppercase, 0.12–0.14em tracking.
   `tabular-nums` wherever digits align.
4. **Radius: 3px controls, 0px containers, 6px overlays** (menus, dialogs, toasts), full for dots
   only. The radius personality is *precise*. No rounded cards.
5. **Neutral ramp: petrol-tinted** ("Tinted" chrome) — every neutral carries the accent hue (~227°
   OKLCH) at low chroma, light and dark. Light-first; dark is semantic re-pointing of the same
   names, surfaces lift rather than invert.
6. **Accent: Petrol** — `#1d6a8a` light / `#66aecb` dark (dark accent takes dark ink text, not
   white). The only colour that means "interactive". Semantics are quieter than the accent:
   ok green / warn amber / fail red, each with shape + word, never colour alone (■ OK, ◆ WARN,
   ● FAIL).

## Fixed by the exploration, same authority

- **Icons: Phosphor, regular weight**, one set everywhere. No emoji as icons, no mixed sets.
- **Theme: light is the default; dark is required and first-class.** Both AA everywhere.
- **Layout: fixed app shell, scrolling content region only** (the table scrolls, chrome never),
  sticky table headers, bulk-action bar pinned to the bottom edge.
- **Structure: rules and hairlines over cards.** One container level fewer than feels natural.
  Stat strip is divided cells, not card tiles.
- **Motion: 120–200ms, ease-out, no bounce, no parallax.** `prefers-reduced-motion` collapses all.
- **Tables carry the product:** inline meters for magnitudes, contextual notes beside status
  ("FileVault off", "openssl 3.1 EOL"), saved views, dense rows.

## Rules learned the hard way

- **Every surface-on-surface pair must survive every row state.** A meter track that matches the
  hover/selected background disappears. Derive in-cell furniture (tracks, chips, tick-lines) from
  ink via `color-mix(in oklab, var(--ink) 12–15%, var(--surface))`, never from a fixed grey.
  (Found by Rob in the reference mock, light mode, hovered rows.)
- **Zero renders as nothing.** A meter with value 0 shows no track — a dim `0`, not empty furniture.
- **Dark accents take dark ink text.** A light accent fill with white text fails AA on dark.

## Carried over from v1 (the only survivors)

- The **content-voice rules**: calm second person, sentence case, verb-first buttons, "say what is
  safe" before destructive actions, plain-language errors, literal numbers, no exclamation marks,
  no emoji. Source: `~/repos/brewmdm/design/m7kni-design-system/readme.md` §Content fundamentals.
- The **AA discipline**: every fg/bg semantic pair ≥ 4.5:1 (3:1 large text/UI boundaries), both
  themes, enforced by script in CI — never by eye.

## Ban list (goes verbatim into DESIGN.md Do's and Don'ts)

Purple→cyan gradients and neon glows · glassmorphism as default surface · Inter/Geist-as-unchosen-
default · grey-bordered cards as universal container · three-column icon-feature grids · centred
hero + logo row · identical sidebar/topbar/breadcrumb/card-grid shell · emoji as icons · mixed icon
sets · bounce/scale hovers · over-saturated accents · jade green and teal-cyan-on-dark (v1's and the
AI tools' defaults, respectively).