From the screen
into the specimen.

The platform reads on cream paper. Every surface, every line of type, every line of rule derives from three layered ramps. Avoid pure white — its coldness on a 4K panel tires older eyes within hours of clinical use.

Paper ramp — surface layers

Ink ramp — text on paper

Rule ramp — borders, dividers, hairlines

Seven semantic accents replace the 60+ scattered hex values currently spread across nine repos. Every accent is vetted against --paper-base — the primary surface — for WCAG AA contrast or stronger.

Body baseline lifts from 16 px to 18 px — the single most impactful change for our 40+ users. Headings de-escalate proportionally; line-height generous; tap targets ≥ 44 px. All four families are already deployed in at least one sigmacog repo, so no new font dependency.

Type scale

Reading specimen

Nine properties; nine different navies, eight different ambers, eight different greens. Every "brand role" has fragmented into a constellation of near-misses. One unified accent token absorbs them all.

Before — nine palettes (top three hues per repo)

After — one paper, four ink tones, seven accents

The two light-theme prior arts — BrainQ10 (paper/ink/sapphire) and MyndScape (sage/forest) — already work. We collapse the seven dark repos onto BrainQ10's foundation rather than invent a new aesthetic.

Layout, structure, copy, and JavaScript are unchanged. Only color values, font-family, font-size, and line-height shift. Every dark frame on the left is current production; every light frame on the right is the proposed migration target.

Nav bar

Buttons

Form field

Card

Data table

Alerts

Each property keeps a single accent role to preserve its identity within the family — EEG stays cyan-flavored, VisioMynd stays vermilion-flavored, SoraMynd stays jade-flavored. The shared paper-ink-rule foundation makes the family read as one product.

The complete token set, ready to paste into each repo's :root. Per-repo migration touches CSS only — no JavaScript, no HTML structure, no functional logic.

tokens.css — single source of truth

/* sigmacog design tokens v0.1 — light theme */
:root {
  /* paper · ink · rule */
  --paper-deep:    #efe9d8;
  --paper-base:    #f6f1e4;
  --paper-raised:  #fbf8ef;
  --paper-card:    #ffffff;
  --ink-primary:   #0c1620;
  --ink-secondary: #394a5e;
  --ink-muted:     #6a7a8d;
  --ink-faint:     #a2adba;
  --rule-strong:   rgba(12,22,32,.22);
  --rule:          rgba(12,22,32,.12);
  --rule-soft:     rgba(12,22,32,.08);
  --rule-faint:    rgba(12,22,32,.04);

  /* brand · accent · signal */
  --brand:        #1e4a8f;
  --brand-deep:   #14315c;
  --brand-light:  #4a78c2;
  --brand-tint:   rgba(30,74,143,.08);
  --accent-cyan:  #0e7d8e;
  --accent-teal:  #0f8f72;
  --accent-lavender: #6a4bb1;
  --signal-warn:    #8a5e08;
  --signal-warn-bg: #bd8411;
  --signal-danger:    #c8442a;
  --signal-danger-bg: #e0654a;
  --signal-success:   #0f8f72;

  /* typography */
  --font-display: 'Fraunces','Noto Serif TC',Georgia,serif;
  --font-italic:  'Crimson Pro','Noto Serif TC',Georgia,serif;
  --font-body:    'IBM Plex Sans TC','Noto Sans TC',system-ui,sans-serif;
  --font-mono:    'IBM Plex Mono','JetBrains Mono',monospace;

  --text-xs:    0.875rem;
  --text-sm:    1rem;
  --text-base:  1.125rem;  /* ← 40+ baseline */
  --text-lg:    1.25rem;
  --text-xl:    1.5rem;
  --text-2xl:   1.875rem;
  --text-3xl:   2.375rem;
  --text-4xl:   3.125rem;
  --text-display: 4.5rem;

  --lh-tight: 1.2;
  --lh-snug:  1.4;
  --lh-base:  1.75;
  --lh-loose: 1.85;

  --tap-min: 44px;
}

Migration sequence — 1 → 9

1. Place tokens.css in each repo — copy the same file into css/tokens.css (or framework equivalent). No build pipeline required.
2. Map existing variables forward. In each repo's :root, replace declarations with token references — e.g. --navy: var(--brand-deep). Existing component CSS continues to work via the indirection.
3. Flip body background from var(--navy) family to var(--paper-base); flip default text color to var(--ink-primary).
4. Sweep hardcoded hex. Any literal #xxxxxx in component CSS gets mapped to its closest token role. Estimate 30–90 minutes per repo.
5. Set body font-size to var(--text-base) (1.125 rem). Adjust component sizes proportionally — most will already scale via em-based padding.
6. Verify focus halos. Every interactive element receives box-shadow: 0 0 0 3px var(--brand-tint) on :focus-visible.
7. Audit on staging — push to staging branch, walk every operator-facing screen, log any deviation. No prod deploy until the family reads as one.

Non-goals

• No layout restructure. Grid, flex, spacing rhythms untouched.
• No JavaScript edits. No HTML structural changes.
• No iconography swaps. No new dependencies.
• No animations or transitions added beyond what already exists.
• No authentication, session, or security flow changes.

Each sub-app keeps its own primary accent so operators recognise it at a glance. The chassis (paper, ink, rule) is identical across the suite; only the brand-position accent shifts. Do not paint a sub-app with another's identity. When in doubt, default to --brand.

Per-device colors (sgimacog multi-device only)

sgimacog operates 1–4 STEEG devices in parallel. Each gets a Morandi-desaturated accent; these replace the legacy high-saturation RGB palette. Per-channel waveform colors form a separate 8-color set shared across all devices — channels are identified by colour, not by device.

Five recurring failure modes burned ≈ 10 round-trips during the 2026-05-25 migration. Every one is mechanical. Run the four greps below before submitting any theme change.

① --*-tint tokens are background-only

Every --*-tint in the palette is a 12–16% alpha. Using one as a foreground color: gives ≤ 1.5:1 contrast — invisible on paper-cream. Text colour must use --ink-*, --brand-deep, --*-deep, or full-opacity accent.

grep -rnE "color: ['\"]var\(--[a-z-]+-tint\)['\"]" src/

② Dark-theme residue RGBA

Pre-Morandi text colours from the dark theme — pale blue, mint green, salmon — render invisible on paper. Any rgba(1NN, 1NN, 2NN, 0.5–0.9) in a color: property is suspect.

grep -rnE "color: ['\"]rgba\(1[0-9]{2},[12][0-9]{2}" src/

③ paper-card vs paper-raised inversion

The chassis convention: cards sit on white (--paper-card), chrome sits on cream (--paper-raised). VeloMynd's monitor had these inverted across 10 surfaces, making cards visually receded and chrome bright. When porting from dark theme, double-check every background.

④ Legacy palette hex literals

Pre-Morandi: bright teal #48baa6 / rgba(72,186,166, …); lime green #80c854 / rgba(63,185,80, …); GitHub red #f85149 / rgba(248,81,73, …); per-device hi-sat #52b8d8 / #80c854 / #dc7860 / #b060c8.

grep -rnE "#48baa6|#f85149|#52b8d8|#80c854|#dc7860|#b060c8|rgba\(72,186,166" src/

⑤ Numeric-display reflow

Proportional fonts (Crimson Pro, Cormorant Garamond) render "1000" wider than "999". When the value sits in a banner alongside fixed-width siblings, the row bounces with every refresh. Two fixes: set font-variant-numeric: tabular-nums; font-feature-settings: "tnum" on the value, and give the container a fixed width (not just min-width).

⑥ Async gate races

Unlocking a UI option behind cond1 && asyncCond2 is a race trap — if setState(asyncCond2 = true) is batched out or the resolution dispatches before the consumer remounts, the option stays disabled forever. Decouple UI gates from compute gates. Gate the picker by the synchronous condition only; let the compute gate sit deeper.

Two non-obvious build flags decide whether the staged bundle works on the staged Worker. Miss either and the symptom is silent — the page renders, but EEG packets never flow.

① VITE_API_BASE='' when building for *-staging

Every sub-app's wasm.ts defaults API_BASE to 'https://www.sigmacog.xyz' for prod. A local bun run build with no env override bakes that prod URL into the bundle — the staged bundle then fetches the WASM key from prod (different key) and decryption fails. Always prefix with VITE_API_BASE='' so the bundle uses same-origin (= staging.sigmacog.xyz).

VITE_API_BASE='' bun run build
bunx wrangler pages deploy dist \
  --project-name=<app>-staging --branch=staging --commit-dirty=true

# verify: deployed bundle must contain Bt=`` (empty), not Bt=`https://www.sigmacog.xyz`
PROXY=$(grep PROXY_SECRET ~/.staging-secrets | cut -d= -f2-)
curl -s -H "x-proxy-secret: $PROXY" $URL/assets/main-*.js | grep -oE 'Bt=`[^`]*`'

② WASM encryption chain (NFB / Poseidon)

bun run build alone copies the raw .wasm into dist. Runtime expects AES-GCM ciphertext. NFB & Poseidon must run build:full (build:wasm → encrypt:wasm → build) the first time, then incremental edits can use plain build since the encrypted blob is committed. sgimacog auto-chains since 2026-05-02 (commit d0bf7a5).

③ Deploy-then-audit, no exceptions

Every theme push to staging is followed by an inline audit against the deployed bytes — fetch the bundle, grep for the four expected fingerprints (root tokens, identity colours, legacy hex absent, VITE_API_BASE empty). "It compiled" is not evidence the change is live; CF Pages edge cache can serve stale bytes for hours after the deployment URL is announced.

# post-deploy audit — minimum 4 checks
curl -s -H "x-proxy-secret: $PROXY" $URL/assets/main-*.css | grep -oE '--paper-base:[^;}]+'
curl -s -H "x-proxy-secret: $PROXY" $URL/assets/main-*.css | grep -oE '--brand:[^;}]+'
curl -s -H "x-proxy-secret: $PROXY" $URL/assets/main-*.js  | grep -oE 'Bt=`[^`]*`'
curl -s -H "x-proxy-secret: $PROXY" $URL/assets/main-*.js  | grep -cE '#52b8d8|#80c854|#f85149'   # must be 0

Per-app deploy targets