re-cinq · nextlevelshit · Mar 30, 2026
diff --git a/specs/684-webui-brand-guidelines/plan.md b/specs/684-webui-brand-guidelines/plan.md
@@ -0,0 +1,65 @@
+# Implementation Plan — #684 webui brand guidelines
+
+## Objective
+
+Replace the generic indigo/purple palette, system fonts, and custom Wave SVG logo in the `wave serve` web dashboard with the re:cinq brand guidelines v1.0 color system, Neue Montreal typography, and leaf logomark.
+
+## Approach
+
+This is a CSS-heavy theming change with minimal structural HTML changes. The strategy:
+
+1. **Define brand tokens as CSS custom properties** — add `--brand-*` tokens at `:root` level, then map existing `--wave-*` and `--color-*` variables to brand values
+2. **Update three color blocks** — `:root` (dark default), `[data-theme="light"]`, and `@media (prefers-color-scheme: light)` all need parallel updates
+3. **Replace logo SVG** — swap the inline `<svg viewBox="0 0 200 200">` in layout.html with a re:cinq leaf logomark SVG
+4. **Add Neue Montreal font** — add `@font-face` declarations or CDN import; update `--font-sans`
+5. **Audit hardcoded colors** — a few CSS rules use hardcoded hex values (e.g. `.btn-fork`, ANSI colors, status-hook badges); semantic/functional colors stay, but shadow/glow rgba values referencing old brand hex need updating
+6. **Add aurora gradient** — create a utility class or update `.nav-brand` gradient to use the Aurora gradient stops
+
+## File Mapping
+
+### Modified files
+| File | Changes |
+|------|---------|
+| `internal/webui/static/style.css` | Replace `:root`, `[data-theme="light"]`, and `@media (prefers-color-scheme: light)` color blocks with brand palette; add `@font-face` for Neue Montreal; update `--font-sans`; update navbar gradient; update button shadow rgba values; update `.progress-bar` gradient |
+| `internal/webui/templates/layout.html` | Replace inline SVG logo with re:cinq leaf logomark; optionally update `<title>` from "Wave" to "re:cinq Wave"; add font preload `<link>` if using self-hosted fonts |
+
+### No changes needed
+| File | Reason |
+|------|--------|
+| `internal/webui/templates/*.html` (non-layout) | Audit confirmed: no hardcoded hex colors in templates — all use CSS variables |
+| `internal/webui/static/app.js` | No color references |
+
+## Architecture Decisions
+
+1. **Keep existing variable names** — map `--wave-primary`, `--color-bg`, etc. to new brand values rather than renaming. This avoids touching every CSS rule that references them.
+
+2. **Add `--brand-*` token layer** — define brand tokens once at `:root`, then use them in both dark/light theme blocks. This makes future brand updates a single-location change.
+
+3. **Dark mode secondary/tertiary derivation** — Midnight Navy `#0F1F49` is the base. Derive secondary (`#162254`) and tertiary (`#1D2B60`) by lightening slightly rather than picking arbitrary values.
+
+4. **Neue Montreal font loading** — use `@font-face` with self-hosted WOFF2 files for reliability. If font files aren't available, use a CDN import. Fallback chain: `"Neue Montreal", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`.
+
+5. **Functional/semantic colors preserved** — green (completed), red (failed), amber (pending), and ANSI terminal colors are NOT brand colors. They stay as-is. Only adjust if contrast ratio against new backgrounds drops below WCAG AA (4.5:1).
+
+6. **Logo approach** — the re:cinq leaf logomark SVG is not provided in the issue. Options:
+   - Check repo for existing brand assets
+   - Use a minimal placeholder leaf SVG matching brand style
+   - The implementer will need to source or create the SVG
+
+## Risks
+
+| Risk | Mitigation |
+|------|-----------|
+| Neue Montreal font files not available | Provide sensible fallback stack; font renders system sans-serif if unavailable |
+| re:cinq leaf logomark SVG not in repo | Create a clean minimal leaf SVG matching brand guidelines aesthetic |
+| Contrast issues with new dark background | Verify status colors and text remain legible against Midnight Navy; adjust if needed |
+| `@media (prefers-color-scheme: light)` block falls out of sync | Structure CSS so light theme values are defined once and reused in both `[data-theme="light"]` and the media query |
+| Button/card shadow rgba values still reference old brand hex | Audit all `rgba(79, 70, 229, ...)` and update to new brand blue |
+
+## Testing Strategy
+
+1. **Visual inspection** — `wave serve` in browser, toggle dark/light mode, verify all pages
+2. **No Go tests affected** — this is a pure CSS/HTML change; webui handler tests don't validate colors
+3. **Acceptance criteria checklist** — verify each criterion from the issue
+4. **Contrast check** — spot-check text/background contrast ratios on key elements
+5. **Build verification** — `go build ./cmd/wave` to confirm embedded assets still compile
diff --git a/specs/684-webui-brand-guidelines/spec.md b/specs/684-webui-brand-guidelines/spec.md
@@ -0,0 +1,86 @@
+# feat(webui): align wave serve dashboard with re:cinq brand guidelines v1.0
+
+**Issue**: [#684](https://github.com/re-cinq/wave/issues/684)
+**Author**: nextlevelshit
+**State**: OPEN
+
+## Context
+
+The re:cinq brand guidelines v1.0 have been finalised. The `wave serve` web dashboard currently uses a generic indigo/purple palette (`#4f46e5`), system fonts, and a custom Wave SVG logo that don't match the official brand identity.
+
+## Brand Specifications
+
+### Color Palette (Primary)
+| Token | Name | Hex | Usage |
+|-------|------|-----|-------|
+| `--brand-midnight-navy` | Midnight Navy | `#0F1F49` | Dark backgrounds, navbar, sidebar |
+| `--brand-crystal-white` | Crystal White | `#FFFFFF` | Light mode backgrounds, text on dark |
+| `--brand-quantum-blue` | Quantum Blue | `#0014EB` | Buttons, links, active states |
+| `--brand-aurora-gradient` | Aurora | `#E4E6FD -> #5664F4 -> #8F96F6` | Hero, header accents |
+
+### Color Palette (Secondary)
+| Token | Name | Hex | Usage |
+|-------|------|-----|-------|
+| `--brand-pulse-blue` | Pulse Blue | `#5664F4` | Running status, active nav |
+| `--brand-soft-indigo` | Soft Indigo | `#8F96F6` | Hover states, secondary actions |
+| `--brand-nebula-light` | Nebula Light | `#E6E8FD` | Card backgrounds (light mode) |
+| `--brand-neutral-fog` | Neutral Fog | `#F2F2F7` | Page background (light mode) |
+
+### Typography
+- **Font family:** Neue Montreal (sans-serif) — all UI text
+- **Mono (code/logs):** keep existing monospace stack
+- **Body:** Regular 16-18px
+- **Captions/labels:** Light/Regular 12-14px
+
+### Visual Elements
+- Navbar background: Midnight Navy (dark) / Crystal White (light)
+- Callout/highlight blocks: Aurora gradient background, 8-12px rounded corners
+- Table headers: brand primary type style, lightweight body
+- Icons: clean, minimal, geometric (matching brand icon style)
+
+## Current State vs Target
+
+| Element | Current | Target |
+|---------|---------|--------|
+| `--wave-primary` | `#818cf8` (dark) / `#4f46e5` (light) | Quantum Blue `#0014EB` or Pulse Blue `#5664F4` |
+| `--wave-accent` | `#8b5cf6` | Soft Indigo `#8F96F6` |
+| `--color-bg` (dark) | `#0d1117` (GitHub-like) | Midnight Navy `#0F1F49` |
+| `--color-bg` (light) | `#ffffff` | Crystal White `#FFFFFF` (same) |
+| `--color-bg-secondary` (light) | `#f8fafc` | Neutral Fog `#F2F2F7` |
+| `--color-btn-primary` | `#4f46e5` | Quantum Blue `#0014EB` |
+| Font | System sans-serif | Neue Montreal |
+| Logo | Custom Wave SVG (`<svg viewBox="0 0 200 200">`) | re:cinq leaf logomark |
+| Title | "Wave" text in navbar | "re:cinq Wave" or "Wave" with re:cinq logomark |
+
+## Scope
+
+### Files to update
+- `internal/webui/static/style.css` — replace all colour variables with brand tokens, add Neue Montreal `@font-face`/import, update table/callout styles
+- `internal/webui/templates/layout.html` — replace inline SVG logo with re:cinq leaf logomark, update `<title>` if needed, add font link
+- `internal/webui/templates/*.html` — audit for any hardcoded colour values or inline styles
+
+### Changes
+1. **CSS custom properties** — replace `:root` and `[data-theme="light"]` colour blocks with brand palette values
+2. **Dark mode** — backgrounds shift from GitHub-dark (`#0d1117`) to Midnight Navy (`#0F1F49`), secondary surfaces use slightly lighter navy tones
+3. **Light mode** — backgrounds use Crystal White/Neutral Fog, accents use Quantum Blue
+4. **Navbar** — replace inline SVG wave logo with re:cinq leaf logomark SVG; keep "Wave" text or change to "re:cinq Wave"
+5. **Buttons** — primary buttons use Quantum Blue; hover uses Pulse Blue
+6. **Status colours** — keep functional green/amber/red semantic colours, but adjust tonal balance against new backgrounds
+7. **Typography** — load Neue Montreal; update `--font-sans` to prioritise it
+8. **Tables** — headers use brand primary type style per guidelines; body text lightweight
+9. **Cards/callouts** — aurora gradient accent on status cards, 8-12px radius (already close at `--radius-md: 8px`)
+
+### Out of scope
+- VitePress documentation site (tracked in #683)
+- TUI/terminal display colours (`internal/display/`)
+- Functional behaviour changes
+
+## Acceptance Criteria
+- [ ] `internal/webui/static/style.css` uses brand hex values exclusively (no legacy `#4f46e5`, `#0d1117` etc.)
+- [ ] Neue Montreal renders in dashboard UI (with sensible fallback)
+- [ ] Navbar shows re:cinq leaf logomark instead of wave SVG
+- [ ] Dark mode backgrounds are Midnight Navy (`#0F1F49`)
+- [ ] Light mode backgrounds are Crystal White / Neutral Fog
+- [ ] Buttons and links use Quantum Blue (`#0014EB`)
+- [ ] `wave serve` loads cleanly in browser with no visual regressions
+- [ ] Status colours (completed/running/failed) remain distinguishable against new backgrounds
diff --git a/specs/684-webui-brand-guidelines/tasks.md b/specs/684-webui-brand-guidelines/tasks.md
@@ -0,0 +1,33 @@
+# Tasks
+
+## Phase 1: Brand Token Foundation
+- [ ] Task 1.1: Add brand color tokens to `:root` in style.css — define `--brand-midnight-navy`, `--brand-crystal-white`, `--brand-quantum-blue`, `--brand-aurora-gradient`, `--brand-pulse-blue`, `--brand-soft-indigo`, `--brand-nebula-light`, `--brand-neutral-fog` as CSS custom properties
+- [ ] Task 1.2: Add Neue Montreal font loading — add `@font-face` declarations or CDN `@import` at top of style.css; update `--font-sans` to prioritize "Neue Montreal"
+
+## Phase 2: Dark Mode Color Migration
+- [ ] Task 2.1: Update `:root` (dark mode default) color block — replace `--wave-primary` (#818cf8 -> #5664F4), `--wave-primary-dark` (#6366f1 -> #0014EB), `--wave-accent` (#8b5cf6 -> #8F96F6), `--color-bg` (#0d1117 -> #0F1F49), `--color-bg-secondary`, `--color-bg-tertiary`, `--color-border`, `--color-border-light`, `--color-btn-primary` (#4f46e5 -> #0014EB), `--color-btn-primary-hover`, `--color-link-hover` with brand-derived values
+- [ ] Task 2.2: Verify/adjust dark mode text colors and semantic status colors against Midnight Navy background for WCAG AA contrast
+
+## Phase 3: Light Mode Color Migration [P]
+- [ ] Task 3.1: Update `[data-theme="light"]` color block — `--wave-primary` (#4f46e5 -> #0014EB), `--color-bg-secondary` (#f8fafc -> #F2F2F7), `--color-bg-tertiary` (#f1f5f9 -> #E6E8FD), `--color-btn-primary` (#4f46e5 -> #0014EB), `--color-running` (#4f46e5 -> #5664F4) with brand values
+- [ ] Task 3.2: Update `@media (prefers-color-scheme: light)` block — mirror the same values as `[data-theme="light"]` to keep system-preference and explicit-toggle in sync
+
+## Phase 4: Hardcoded Color Cleanup [P]
+- [ ] Task 4.1: Update button shadow rgba values — replace `rgba(79, 70, 229, 0.25)` and `rgba(79, 70, 229, 0.35)` in `.btn-primary` with brand-appropriate rgba values based on Quantum Blue
+- [ ] Task 4.2: Update `.log-search input:focus` box-shadow — replace `rgba(79, 70, 229, 0.15)` with brand blue rgba
+- [ ] Task 4.3: Update `.nav-brand a` gradient — replace `var(--wave-primary) -> var(--wave-accent)` gradient with Aurora gradient (`#E4E6FD -> #5664F4 -> #8F96F6`)
+
+## Phase 5: Logo and Layout
+- [ ] Task 5.1: Replace inline SVG logo in `layout.html` — swap the `<svg class="nav-logo" viewBox="0 0 200 200" ...>` with re:cinq leaf logomark SVG
+- [ ] Task 5.2: Update navbar brand text — change "Wave" to include re:cinq branding if appropriate
+- [ ] Task 5.3: Add font preload link to layout.html `<head>` if using self-hosted Neue Montreal
+
+## Phase 6: Polish and Gradient Accents
+- [ ] Task 6.1: Update `.progress-bar` fill gradient — replace `var(--wave-primary) -> var(--wave-accent)` with Aurora gradient
+- [ ] Task 6.2: Update `.btn-primary` gradient — replace `var(--color-btn-primary) -> var(--wave-accent)` with brand gradient
+- [ ] Task 6.3: Audit remaining hardcoded hex colors in CSS — verify functional colors (fork green, rewind amber, ANSI terminal, status-hook badges) still have sufficient contrast against new backgrounds
+
+## Phase 7: Validation
+- [ ] Task 7.1: Build verification — run `go build ./cmd/wave` to confirm embedded static assets compile
+- [ ] Task 7.2: Visual verification — confirm `wave serve` renders correctly in browser with dark/light mode toggle
+- [ ] Task 7.3: Acceptance criteria checklist — verify all 8 acceptance criteria from the issue