# Styling standard (D18) — how it stays consistent

## The problem the operator spotted
The 22 preview pages each carry a hand-rolled <style> block. Fine for
static mocks (self-contained, openable from disk) but they drift — and
mobile rules were re-derived per page (the admin slipped).

## Production answer: tokens + components, gate-enforced
The real SvelteKit build does NOT copy these style blocks. It gets:
1. **One token file** — the suite's `:root` vars (`--teal --terra --ink
   --muted --line --r-* --shadow-* --ease`) become `src/lib/styles/
   tokens.css`. Single source of truth for colour/spacing/radius/motion.
2. **A small shared component layer** — Card, Chip, PillButton, SearchPill,
   Tile, BandSplit, Panel, StatCard, Sparkline (one Svelte component each,
   scoped styles consuming ONLY tokens). The suite is the visual spec.
3. **Mobile-first by contract** — every component ships its own responsive
   behaviour once; pages compose components and inherit it. Grids:
   `repeat(auto-fill,minmax(Npx,1fr))`; charts: SVG `viewBox` + width:100%.
4. **The design-system gate enforces it** — daysout declares
   `design_system:` in repo-type.yaml; the tokens-only lint (warp#7617
   family) blocks raw hex / px font sizes / bespoke one-off classes at
   review time. Standardisation by refusal, not by memory.

## Why not Tailwind?
Considered. Tailwind would work, but: (a) the fleet's design discipline +
review gates are built around token vars (ADR-006 canon) — adding a second
styling paradigm forks that; (b) utility-class HTML makes the persona
review diffs noisier; (c) our component count is small (~10) so Tailwind's
main win (not naming things) barely pays. If we ever adopt it, the config
must map utilities onto the same tokens — the tokens stay canonical either
way.

## Preview suite rule (these mocks)
Stay self-contained (openable from disk, no build step) but: copy the
shared `:root` token block verbatim, fluid SVGs (`viewBox` + 100%), grids
that collapse, no fixed pixel columns without a wrap fallback.

## D18a amendment (2026-06-10) — the admin is different
Operator review kept finding polish bugs in the hand-rolled admin (column
alignment, truncation, grid drift). Root cause: admin dashboards are made
of SOLVED components (tables, tabs, cards, forms, dialogs) and hand-rolling
them re-derives what a library guarantees. Amended split:

- **Consumer + operator surfaces (the brand): unchanged** — tokens + canon
  Svelte components per D18. This is where the design language v3 lives.
- **Admin (`/admin` routes): Tailwind + shadcn-svelte** (bits-ui based,
  Svelte-5 native). Tailwind's config maps colours/radii/spacing onto the
  SAME token vars — tokens stay canonical; utilities are just the delivery.
  The design-system gate gets a per-path carve-out for `/admin`.

**Why this split is principled, not a fudge:** the admin is internal — no
brand stakes, maximum component density, fastest-growing surface, and the
agent fleet knows shadcn idioms cold (less implementation divergence).
The consumer site is the opposite on every axis.

**Preview status:** `admin*.html` mocks are the INFORMATION-ARCHITECTURE
spec (tabs, queues, panels, KPIs, copy) — shadcn-svelte defaults are the
pixel truth at build time. Stop hand-polishing the admin mocks.

**Update:** the admin mocks carry the D18a look (sidebar shell, zinc neutrals, dark-primary buttons) as an inlined style block per page — previews stay fully self-contained (openable from disk), and standalone .css files in docs/ would trip the canon-adoption lint that rightly guards product CSS. The shared-stylesheet discipline arrives with the real build (Tailwind config mapped onto tokens, D18a).