# Subconscious Design System — agent reference **GENERATED — do not edit by hand.** Produced by `scripts/generate-design-md.mjs` from `contract.css`, `derived.css`, and `preview/theme-switcher.js`; regenerate with `npm run generate:design-md`. Those files are the single source of truth. ## Overview The Subconscious design system is a token + doctrine language — it ships no components; consuming apps build their own against `contract.css`. This file is the agent-facing brief: read it before generating or restyling UI. `contract.css` declares the **contract-tier** variables — the colour pair (`--color` / `--backgroundColor`), the full type scale (`--fs-*`, `--font-*`, `--fw-*`, `--lh-*`, `--tracking-*`), spacing (`--sp-*`), and the chart palette (`--chart-*`). Load it (copy into the app, or include its `:root` from https://design.subconscious.ai/contract.css). The system is *generative*: a theme is one pair of hex values (`--darkColor` / `--lightColor`); every grey, foreground, and surface is `color-mix()`-derived from that pair. **Reference the variable or the formula — never paste a hex.** ## Colors Write the reference in the middle column. The only hex literal the system permits is signal red. | token | reference in code | role | |---|---|---| | `primary` | `var(--color)` | ink — text, rules, borders | | `background` | `var(--backgroundColor)` | page background | | `muted` | `color-mix(in srgb, var(--color) 45%, var(--backgroundColor))` | captions, metadata | | `subtle` | `color-mix(in srgb, var(--color) 25%, var(--backgroundColor))` | faint rules, disabled text | | `surface` | `color-mix(in srgb, var(--color) 6%, var(--backgroundColor))` | raised panels | | `grey` | `color-mix(in srgb, var(--color) 50%, var(--backgroundColor))` | neutral mid | | `signal-red` | `#c8102e` | the gap ONLY — errors, deltas, destructive | | `chart-1…chart-5` | `var(--chart-1)…var(--chart-5)` | categorical data-viz | - **contract** — `var(--…)` declared by `contract.css`. - **derived** — not in `contract.css`; write the `color-mix()` expression (it re-derives from the theme pair) or copy `shadcn.css`. - **literal** — `signal-red` is the one permitted hex, only as the gap marker. `--color` / `--backgroundColor` invert with `data-mode`. **Themes.** A theme is one `(--darkColor, --lightColor)` pair set on the root; everything else re-derives. To render a non-default surface, set ``: | theme | `--darkColor` | `--lightColor` | |---|---|---| | `kong` | `#1b165b` | `#ffffff` | | `zyg` | `#813294` | `#c1d88b` | | `bontu` | `#0d0403` | `#00ffff` | | `jones` | `#150800` | `#eda557` | | `peacock` | `#0a2e1f` | `#f97316` | | `figma` | `#1e1e24` | `#0acf83` | | `stripe` | `#0a2540` | `#f6f9fc` | | `floral` | `#2a1854` | `#f8f2dc` | ## Typography Five sizes, all `contract.css` variables — `var(--fs-display)` 64px / `var(--fs-h1)` 40px / `var(--fs-h2)` 28px / `var(--fs-body)` 16px / `var(--fs-meta)` 12px. Doctrine: **one thing violently large, one thing uncomfortably small — kill the middle weight.** Families: `var(--font-display)` and `var(--font-body)` (public Inter Tight stack; internal builds upgrade to Exposure). **Meta / caption / label text uses `var(--font-mono)`.** Weights `--fw-light` 300 / `--fw-regular` 400 / `--fw-display` 800; line-heights `--lh-tight` / `--lh-display` / `--lh-body` / `--lh-loose`; optical tracking `--tracking-display` / `-h1` / `-h2` / `-body` / `-meta`. Those are plain numbers and lengths — write them literally; the no-hex rule covers colors only. ## Layout A 4pt spacing scale, eight steps — all `contract.css` variables: `var(--sp-1)` 4px · `var(--sp-2)` 8px · `var(--sp-3)` 12px · `var(--sp-4)` 16px · `var(--sp-5)` 24px · `var(--sp-6)` 32px · `var(--sp-7)` 48px · `var(--sp-8)` 64px. ## Elevation & Depth **No `box-shadow`.** Depth is expressed with rules and surface tints (`surface`), never shadow. ## Shapes Three radii — write the value literally: `0px` (sharp, the default), `2px` (controls — buttons, inputs), `999px` (dots, true pills). Radius is not a contract variable. **No `border-radius` ≥ 12px** — the doctrine forbids the soft mid-radius. ## Components The system ships **no components** — consuming apps build their own against `contract.css` (do not add component classes to the contract). Golden path: the preview garden at https://design.subconscious.ai/preview/ — `canonical`-status pages are the correct-usage reference. ## Do's and Don'ts Hard rules — an agent generating UI for this system MUST honor every one: - **Do** write `var(--…)` or the `color-mix()` formula; **never** a raw hex literal — only signal red is allowed, and only as the gap marker. - **Don't** ship a banned visual move: `border-radius` ≥ 12px, `box-shadow`, decorative `linear-gradient`, hover `scale()` / `translateY()`. - **Signal red marks the gap only** — errors, deltas, contradictions, destructive states. Never a CTA, accent, or brand color. - **Contrast:** body text meets WCAG AA; red-on-ink is **AA-Large only** (≥18px, or ≥14px bold). Captions stop at `grey`; the faintest tints are hairlines and the disabled state, never type. - **Every animation needs a `prefers-reduced-motion` branch** — see `DOCTRINE.md`§4.2. - **Stated vs Revealed** is the editorial spine: the claim (italic, often struck) on the left, the behavior (upright) on the right, red between. - Positive doctrine: `DOCTRINE.md`§2. Full banned list: `DOCTRINE.md`§3.