From 1b52231cc9956655944459b7c75b81777795f1e2 Mon Sep 17 00:00:00 2001 From: Michael Czechowski Date: Mon, 30 Mar 2026 18:34:42 +0200 Subject: [PATCH] docs(webui): add spec, plan, and tasks for #684 brand guidelines alignment --- specs/684-webui-brand-guidelines/plan.md | 65 +++++++++++++++++ specs/684-webui-brand-guidelines/spec.md | 86 +++++++++++++++++++++++ specs/684-webui-brand-guidelines/tasks.md | 33 +++++++++ 3 files changed, 184 insertions(+) create mode 100644 specs/684-webui-brand-guidelines/plan.md create mode 100644 specs/684-webui-brand-guidelines/spec.md create mode 100644 specs/684-webui-brand-guidelines/tasks.md diff --git a/specs/684-webui-brand-guidelines/plan.md b/specs/684-webui-brand-guidelines/plan.md new file mode 100644 index 00000000..868bc48d --- /dev/null +++ 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 `` 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 `` from "Wave" to "re:cinq Wave"; add font preload `` 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 new file mode 100644 index 00000000..597137a6 --- /dev/null +++ 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 (``) | 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 `` 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 new file mode 100644 index 00000000..92de6653 --- /dev/null +++ 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 `` 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