# Phase 2: Theme System - Context
**Gathered:** 2026-02-26
**Status:** Ready for planning
## Phase Boundary
CSS custom property token architecture with a two-tier system (primitive + semantic), one polished default cyberpunk theme (dark-only, neon-on-void), font pairing with bundled assets, and runtime theme switching via Rust API that re-skins all themed elements with zero JavaScript re-renders. No component implementation (Phase 3), no animations (Phase 4), no additional theme presets (v2).
## Implementation Decisions
### Color palette
- Dual-tone primary palette: cyan `#009BF7` (primary) and magenta `#FE00B3` (secondary)
- Background: dark gradient (near-black with subtle variation, not flat black) — creates spatial depth
- Feedback colors are traditional but neon-ified:
- Error: neon red
- Warning: cyber lime `#FCFE04` (not amber)
- Success: proper cyan (distinct from primary accent which is blue-flavored)
- Neutral text colors: cool grays with blue undertone, cohesive with the cyan-dominant palette
### Font pairing
- Monospace: Fira Code (used for code, data, and technical content)
- Display: Share Tech (used for headings, titles, and prominent UI text)
- Both fonts bundled as embedded assets in the binary (zero external dependencies, works offline)
### Glow & effect tokens
- Default glow intensity: subtle (2-4px blur range) — restrained, premium feel
- Glow color always matches the element's accent color (no independent glow color tokens)
- Surface transparency: token-based opacity levels (e.g., surface-opaque, surface-translucent, surface-glass) — components pick from constrained set
- Glow intensity scales with interaction state, ordered:
1. Default (dimmest)
2. Focus/active (second-dimmest)
3. Hover (second-brightest)
4. Click (brightest, then fades back)
- Button-specific: secondary inner glow layer beneath the surface — lower z-axis, less strength than edge glow but greater throw/range, bleeds inward toward button text. Creates impression of glow beneath glass surface.
### Token architecture
- Two-tier system: primitive tokens (raw values) and semantic tokens (aliases referencing primitives)
- Components reference semantic tokens only; primitives are implementation detail
- Naming convention: flat with `--hh-` namespace prefix (e.g., `--hh-color-primary`, `--hh-glow-blur-sm`, `--hh-font-mono`)
- Theme switching via `data-theme` attribute on root `` element — each theme redefines semantic tokens under `[data-theme="x"]` selector
- Token files split by category: primitives.css, semantic.css, typography.css, effects.css — imported into a single theme entry point
### Claude's Discretion
- Body text font assignment (monospace vs display for paragraph text)
- Exact gradient values for the void background
- Specific neon red hex value for error state
- Exact opacity values for the surface transparency levels
- Size scale and weight hierarchy for typography tokens
- How many primitive color steps per hue (e.g., cyan-100 through cyan-900)
## Specific Ideas
- Buttons should feel like they have a glass surface with glow emanating from beneath — edge glow is crisp and tight, inner glow is softer and bleeds inward
- The "cyber lime" warning color (`#FCFE04`) is a deliberate departure from conventional amber — keeps the neon aesthetic consistent
- Primary cyan is intentionally blue-flavored (`#009BF7`), which frees up "proper cyan" for success states without visual confusion
## Deferred Ideas
None — discussion stayed within phase scope
---
*Phase: 02-theme-system*
*Context gathered: 2026-02-26*