Unifies — Design System (RawBlock v2)Legacy format

• Structure over decoration. Hierarchy comes from border weight, scale, hard

shadow offset, and inversion — never from soft shadows, gradients, or imagery.

• Honest materials. Borders are 2–3px. Backgrounds are flat. Text is high contrast.

Hard offset shadows are structural (they read as physical depth, not glow).

• Intentional tension. Spacing is deliberately irregular. Asymmetry is encouraged.

If it looks "too designed," strip it back — but keep the hard shadow.

• Two themes, one system. Light (ink-on-paper) and Dark (paper-on-ink) are total

inversions driven by the same token set. No third theme, no per-component exceptions.

---

All color is expressed as space-separated RGB channels so Tailwind opacity modifiers

(/60, /40) and rgb(var(--token) / ) both work. Light is the default

(:root); Dark overrides under html.dark.

| Token | Light (default) | Dark (inverted) | Role |

| ----------------- | ---------------------- | ----------------------- | -------------------------------------- |

| --bg | 246 247 249 #f6f7f9 | 10 10 12 #0a0a0c | Page canvas |

| --surface | 255 255 255 #ffffff | 22 23 27 #16171b | Cards, panels, inputs |

| --elevated | 255 255 255 | 30 31 37 #1e1f25 | Popovers, sticky bars |

| --fg | 10 10 12 #0a0a0c | 244 244 245 #f4f5f7| Primary text, primary fills, borders |

| --muted | 84 86 92 #54565c | 162 165 173 #a2a5ad | Secondary / helper text |

| --faint | 138 141 148 #8a8d94| 108 111 119 #6c6f77 | Tertiary / meta text |

| --line | 216 219 224 #d8dbe0| 43 45 51 #2b2d33 | All borders & dividers |

| --accent | 17 17 17 #111111 | 244 244 245 #f4f5f7| Monochrome brand ink (no hue) |

| --accent-fg | 255 255 255 | 10 10 12 #0a0a0c | Text/icon on --accent |

| --success | 17 163 107 #11a36b | 47 191 126 #2fbf7e | Completed / XP / "done" |

| --danger | 224 36 36 #e02424 | 255 90 90 #ff5a5a | Errors / destructive / delete |

| --warn | 194 130 10 #c2820a | 224 169 58 #e0a93a | Cautions / skips / celebrate |

Shadow tokens (hard offset — not soft):

```

--shadow-hard-x: 4px; --shadow-hard-y: 4px;

--shadow-hard-color: rgb(var(--fg) / 0.9);

--shadow-hard: var(--shadow-hard-x) var(--shadow-hard-y) 0 0 var(--shadow-hard-color);

```

In dark mode the offset color flips to rgb(var(--fg) / 0.5) so the shadow stays

visible on a near-black canvas. :hover nudges the element -1px,-1px and grows the

shadow; :active collapses it to 0 0 (physical press).

Rules

1. The accent is monochrome (ink ↔ paper). There is no brand hue. Do not introduce

blue/cyan/fuchsia as "brand" color.

2. --success / --danger / --warn are semantic only — never decorative.

3. Dark mode is a full inversion of the token set. There is no third theme.

4. The legacy Tailwind palette (slate, cyan, fuchsia, emerald, red, amber,

black, white) is remapped to these tokens in CSS (see §11) so historical JSX

conforms automatically. Prefer the token utilities (bg-surface, text-fg,

border-line, bg-accent, text-success…) in new code.

---

Motion is structural and snappy. All animations respect prefers-reduced-motion

(fully disabled, not merely slowed).

| Token | Keyframes | Use |

| --------------- | -------------------- | ------------------------------------------- |

| animate-fade-in | fade-in (0→1 opacity) | Panel/section entrance |

| animate-pop | pop (scale 0.96→1.02→1) | Toasts, modals, created rows |

| animate-pop-in | pop-in (scale 0.9→1) | Tooltips, small surfaces |

| animate-slide-up| slide-up (y12→0) | Staggered list rows, highlights |

| flash (heatmap) | flash (brightness 1→1.6→1) | Recently-touched heatmap cells |

• Buttons: transition-[transform,box-shadow]; hover lifts -1px,-1px + grows shadow;

active collapses shadow to 0 0 (physical press).

• Respect prefers-reduced-motion: a global media query zeroes all durations.

---

• Activity heatmap: 7×N grid of square cells; intensity maps to commit-count

buckets via --surface → --line → --accent ramp. Recently touched cells

animate-flash. Monochrome (no rainbow). Tooltip shows exact count + date.

• XP / level gauntlet: horizontal progress bars built from --line track +

--accent fill + font-mono percentage. Milestone ticks at level boundaries.

• Stats: font-display huge numbers (text-h1) with font-mono unit labels.

• All charts are CSS/SVG only — no chart library, keeping the brutalist honesty.

---

• Mobile-first. Base layout single-column; grids expand at sm: (≥640px).

• Header wraps: brand left, [theme-toggle] [account] right; title scales to

text-lg and row wraps with gap-3 on narrow screens.

• Phase grid: grid sm:grid-cols-2 — one column on phones, two on larger.

• Mobile FAB (§7.9) guarantees a primary action is always thumb-reachable.

• Touch targets: buttons ≥ 44px tall; checkbox/radio hit areas ≥ 20px.

• No horizontal scroll: overflow-x guarded; long curriculum text wraps. The

deployment "gauntlet" view scrolls horizontally only when a phase genuinely

overflows, with scrollbar-stable to avoid layout shift.

• Safe areas: index.html ships viewport-fit=cover; .safe-t / .safe-b and the

FAB offset use env(safe-area-inset-*).

• Reduced motion: honors prefers-reduced-motion — celebratory animations are

disabled, not merely slowed.

• PWA: installable, offline-cached (Workbox precache), themed theme-color that

follows light/dark.

---

• Contrast: all token pairings meet WCAG AA; --muted/--faint used only for

secondary text, never primary.

• Focus: every interactive element has a visible 2px outline (on --accent) at

outline-offset:2px; never removed.

• Skip link: "Skip to content" is the first focusable element, visually hidden until

focused, jumps to #main.

• Labels: form fields have associated `; icon-only buttons carry aria-label`.

• Motion: prefers-reduced-motion fully disables non-essential animation.

• Semantics: landmarks (header/main/footer/nav), role/aria-* on

dialogs and live regions for XP/toast announcements.

---

• Tokens + component classes live in src/index.css (@layer base tokens,

@layer components for .raw-*/legacy aliases, @layer utilities for helpers).

• Theme-alias layer: components still using Tailwind's default palette are remapped

onto the tokens via CSS !important aliases so they render flawlessly in BOTH themes

without per-file rewrites:

• bg-white/text-black/bg-black/text-white/border-black → ink↔paper

inversion (--bg/--fg/--accent-fg).

• slate-* → --surface / --line / --fg / --muted / --faint (per role).

• cyan/fuchsia/sky/indigo → --accent (monochrome brand).

• emerald/green → --success, red → --danger, amber/yellow → --warn.

• fill-white → fill-accent-fg (theme-aware SVG checkmarks).

• Keyframes (fade-in, pop, pop-in, slide-up, flash) are defined globally;

prefers-reduced-motion zeroes them.

• New code: use the raw-* classes and token utilities (bg-surface, text-fg,

border-line, bg-accent, text-success…). Do not hand-roll colors.

• Fonts: Inter / Space Grotesk / JetBrains Mono via Google Fonts in index.html.

• No build-time theming — theme is a runtime class toggle, instant and total.

---