# Theming & Motion Guide

How color, light/dark mode, section tone, and animation work on this site.

---

## Palette

From the spec, exposed as CSS variables in `src/styles/themes.css` and mapped to
Tailwind utilities in `src/styles/global.css`:

| Token | Value | Meaning |
|---|---|---|
| `--color-slate` | `#1E293B` | Professional confidence (primary) |
| `--color-amber` | `#F59E0B` | Warm accent (the making/creative side) |
| `--color-teal` | `#699a94` | Soft teal (secondary, favorite) |
| `--color-ink` | `#0F172A` | Near-black text on light |
| `--color-cream` | `#FFFBEB` | Cream-white text on dark |

Brand colors are fixed. **Semantic** tokens (`--surface`, `--text`, `--accent`,
`--secondary`, `--border`, ...) resolve differently per theme + section, and are
what components actually use.

---

## Two theming axes

### Axis 1 — Global light/dark

Set on `<html data-theme="light|dark">`:

- A blocking inline script (`src/scripts/theme-init.ts`, inlined in `<head>`)
  reads `localStorage['gk-theme']`, falling back to the OS
  `prefers-color-scheme`. This runs **before first paint**, so there is no flash.
- The nav `ThemeToggle` island flips it and persists the choice.
- If the user has never chosen, the site follows OS changes live.

### Axis 2 — Section tone

Set on `<body data-surface="neutral|professional|interest">` via the `surface`
prop on `<BaseLayout>`:

| Surface | Used on | Tone |
|---|---|---|
| `neutral` | Home, About, Contact | Balanced — clean in light, calm in dark |
| `professional` | Professional page | Dark slate, polished, amber accents |
| `interest` | Interests pages | Warm cream/amber, inviting |

The Professional surface leans dark even in light mode (it is the "polished
wing"). The Interest surface is warm in both modes. This is what gives the two
wings their distinct feel while sharing the same typography and spacing.

Each `(data-theme, data-surface)` combination redefines the semantic tokens in
`themes.css`. Add or adjust a combination there to change any section's palette.

---

## Changing colors

1. **Tweak a brand color:** edit the fixed values in `global.css` under `@theme`
   (e.g. `--color-amber`).
2. **Tweak a section's tone:** edit the relevant `[data-surface="..."]` block in
   `themes.css`. Each block lists `--surface`, `--surface-raised`,
   `--surface-sunken`, `--text`, `--text-muted`, `--text-subtle`, `--border`,
   `--accent`, `--accent-contrast`, `--secondary`.
3. Components use utilities like `bg-surface`, `text-text`, `text-accent`
   (mapped from these variables), so they update automatically.

### Contrast

Verify WCAG AA (4.5:1 for body text) whenever you change a token pair. The
current combinations were chosen for AA compliance. The `--accent` on the neutral
light surface uses a deeper amber (`#b45309`) specifically to meet AA on white.

---

## Motion

Motion is layered and **always** respects `prefers-reduced-motion`:

1. **Hero background** (`AnimatedBackground.tsx`):
   - A CSS mesh-gradient layer (GPU-friendly, animated via the
     `animate-gradient-shift` keyframes in `animations.css`).
   - An optional `<canvas>` particle field (slow drifting dots) on the home hero
     only. It renders at devicePixelRatio (capped at 2), pauses when off-screen,
     and is **skipped entirely** under reduced motion.
2. **Scroll reveals** (`Reveal.astro` + the `.reveal` class):
   - IntersectionObserver toggles `.is-visible`, triggering a CSS fade-up. Zero
     framework cost. The reduced-motion media query in `global.css` forces these
     to their final state instantly.
3. **Page transitions**: Astro `<ClientRouter />` (View Transitions API) morphs
     between pages and persists the nav.
4. **Nav blur on scroll**: a tiny inline script adds `.scrolled` after a few px,
     enabling backdrop-blur + a hairline border + shadow.
5. **Hover micro-interactions**: Tailwind transitions on cards/buttons (lift,
   accent glow, arrow nudge).

### Disabling motion

Everything is gated by the global reduced-motion rule in `global.css`:

```css
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.001ms !important;
    transition-duration: 0.001ms !important;
    ...
  }
}
```

The canvas island additionally checks `matchMedia('(prefers-reduced-motion:
reduce)')` before drawing, so even JS-driven motion is skipped.

---

## Typography

Self-hosted variable fonts via Fontsource (woff2, no external requests):

- **Headings / UI:** Plus Jakarta Sans Variable (geometric sans)
- **Body:** Inter Variable
- **Mono / kickers / quotes:** JetBrains Mono Variable

Font sizes use `clamp()` for fluid scaling (see the `h1`-`h4` rules in
`global.css`).