DESIGN.md

Design

Linear × Stanford lectures. Paper-tinted neutrals, deliberate typography, single restrained accent. 1px hairlines instead of borders + shadows. Reads as a research artifact, not a demo.

Theme

Light, paper-tinted. The surface is a slightly warm off-white — like a printed paper under a desk lamp. No dark mode in v1; the academic register is paper-native.

Color (OKLCH)

--paper      oklch(0.987 0.004 85)   page bg
--paper-2    oklch(0.972 0.005 85)   panel bg
--paper-3    oklch(0.955 0.006 85)   inset / well
--rule       oklch(0.91  0.006 85)   hairlines
--rule-2     oklch(0.84  0.008 85)   stronger borders
--ink-mute   oklch(0.62  0.010 85)   captions, secondary
--ink-soft   oklch(0.45  0.012 85)   tertiary text
--ink        oklch(0.22  0.014 85)   body
--ink-deep   oklch(0.12  0.014 85)   primary headings, emphasis

--accent          oklch(0.50 0.18 25)    Stanford cardinal — used sparingly
--accent-strong   oklch(0.42 0.20 25)    hover / pressed
--accent-faint    oklch(0.96 0.02 25)    selection bg tint

# Module kind palette — restrained, all chroma ≤ 0.10
--k-emb     oklch(0.55 0.020 85)
--k-norm    oklch(0.55 0.060 75)
--k-attn    oklch(0.55 0.080 60)
--k-mlp     oklch(0.50 0.080 250)
--k-block   oklch(0.55 0.060 320)
--k-head    oklch(0.50 0.090 145)
--k-loop    oklch(0.62 0.010 85)
--k-moe     oklch(0.55 0.090 290)
--k-input   oklch(0.30 0.012 85)
--k-output  oklch(0.30 0.020 145)

Strategy: restrained. Neutrals carry the surface; the cardinal accent appears only on the actively-playing node, the user-selected node, and the play scrubber thumb. Module kind colors are quiet earthy hues used at low chroma — they distinguish kinds without competing with the cardinal.

Typography

serif   "Source Serif 4", "Source Serif Pro", Charter, Georgia, serif
sans    "Inter", -apple-system, system-ui, sans-serif
mono    "JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace

Loaded via Google Fonts @import in styles.css. Inter has tabular-nums (font-variant-numeric: tabular-nums) — used everywhere numbers compare.

Scale (1.25 ratio):

• 11px — small caps labels
• 12px — UI default, captions
• 14px — primary body
• 16px — subhead
• 20px — section
• 28px — page title (serif)

Conventions:

• Page / panel titles: serif, italic for project name only.
• Section labels: 11px sans, letter-spacing: 0.08em, uppercase, ink-mute.
• Code, paths, model ids, shapes: mono.
• Inline numbers in prose: tabular-nums.
• Greek/math glyphs (μ, σ, ×): use real glyphs, not letters.

Elevation & borders

No shadows. All separation by 1px hairlines (--rule). Stronger 1px (--rule-2) for top-level surface boundaries. Cards are out — use rules and spacing.

Active states

• Selected module node: 1.5px border in --accent, faint --accent-faint tint, no glow.
• Currently playing module node: 1.5px solid --accent, plus a 1px outline offset (CSS outline) — no pulse animation, no glow.
• Hover on interactive elements: bg shifts to --paper-3, no transform.

Layout

Three regions:

• Left rail: 360px, panels separated by hairlines, no card chrome.
• Main: graph canvas, paper bg, hairline grid background.
• Bottom: 56px play bar, hairline top.

Section spacing within the rail: 24px between sections, 8–12px within. No nested boxes. Labels sit above content with small caps.

Anti-patterns banned in this project

• Side-stripe colored borders.
• Gradient text or buttons.
• Glow on active state.
• Emoji in chrome (titles, labels, buttons).
• box-shadow for separation.
• Pulse animations.
• Bright accent on every panel header.

Components

• Module node: paper bg, 1px kind-colored border, kind name in 12px caps top-left, class name in 11px mono below, shape annotation (matmul) in 12px mono. Param/FLOPs corner badges removed; surface in side panel instead.
• Loop / MoE container: dashed 1px hairline, kind label in tiny caps top-left flush with rule, repeat count as × N in mono right-edge.
• Terminals (Input / Output): solid --ink-deep bg, paper text, 1px outline. Single per graph.
• Buttons: 1px hairline, paper-2 bg, ink text. No filled primary. Active button: ink-deep bg, paper text.
• Inputs: paper-2 bg, 1px hairline, mono content, focus ring 1.5px in cardinal.
• Pills/tags: paper-3 bg, ink-mute text, 1px hairline. Used for kind labels, "leaf", param counts in NodeCard.

Motion

Only the play timeline animates. Scrubber moves linearly. Hover/active transitions: 120ms ease-out on color/border only (no transform).

Things I'm explicitly not doing

• Dark theme variant. Out of scope for v1.
• Custom-drawn icons. Use plain typography and unicode symbols (§, ·, →, ×).
• A logo. The serif title is the identity.