teaching-site-design-system

Teaching Site Design System

Token starter (copy this, don't re-derive): templates/tokens.css — full :root block + dark theme + signature components (day-hero, glass-card, prompt-card, task-list, learning-goal, concept, unit, material, table). Paste into the <style> block of index.html (vanilla SPA pattern) or use as external style.css.

Schema authority: this skill defines visual tokens; data field names live in _shared/domain-primitives.md. When styling a component, read that file to know the data shape you're rendering.

Reference implementation: d:/GitHub/ai-workshop/index.html:11-1700 — the full production CSS this skill's tokens were extracted from.

This skill defines the visual layer of a teaching site: color tokens, typography, geometry, components, dark mode strategy, and — critically — the reasoning behind each decision. The rationale matters more than the literal values; future sites can re-tune the values, but the why survives across projects.

When to Invoke

• Setting up a new teaching site (read tokens before writing first CSS).
• Adding a new visual element (badge, card, hero) — check whether an existing pattern covers it before inventing.
• Tuning dark mode (which token to override, which not to).
• Producing a corporate edition or ebook (same tokens flow to print CSS).
• Reviewing visual consistency complaints ("it looks inconsistent here").

The Foundational Decision: OKLCH, Not HEX/RGB

:root {
  --bg:      oklch(99% 0.002 240);
  --surface: oklch(100% 0 0);
  --fg:      oklch(18% 0.012 250);
  --accent:  oklch(58% 0.18 255);
  --accent-2: oklch(66% 0.14 65);
}

Why OKLCH (not #1a73e8 or hsl(...)):

1. Perceptually uniform — oklch(60% ...) and oklch(70% ...) look like an equal step apart; HSL doesn't (its 60→70 yellow jumps visually huge but blue barely changes).
2. Predictable dark mode — for each light token at L=N%, the dark equivalent is roughly L=(100-N)% with the same chroma+hue. Mechanical.
3. color-mix(in oklab, ...) works natively — e.g. soft accent tints (color-mix(in oklab, var(--accent) 18%, transparent)) compose cleanly, no manual rgba math.
4. Modern browser support is fine (Chrome 111+, Safari 15.4+, Firefox 113+). For a static teaching site this is acceptable.