From 29f2de78509e5a2ddb50de896db90a8dd8d1a130 Mon Sep 17 00:00:00 2001 From: Michael Czechowski Date: Mon, 30 Mar 2026 18:31:34 +0200 Subject: [PATCH 1/3] docs(spec): implementation plan for re:cinq brand guidelines alignment (#683) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Spec, plan, and task breakdown for aligning the VitePress documentation site with re:cinq brand guidelines v1.0 — color palette, typography, logo, and component style updates across 17 tasks in 4 phases. --- specs/683-brand-guidelines/plan.md | 79 +++++++++++++++++++++++++++ specs/683-brand-guidelines/spec.md | 83 +++++++++++++++++++++++++++++ specs/683-brand-guidelines/tasks.md | 30 +++++++++++ 3 files changed, 192 insertions(+) create mode 100644 specs/683-brand-guidelines/plan.md create mode 100644 specs/683-brand-guidelines/spec.md create mode 100644 specs/683-brand-guidelines/tasks.md diff --git a/specs/683-brand-guidelines/plan.md b/specs/683-brand-guidelines/plan.md new file mode 100644 index 00000000..1911153e --- /dev/null +++ b/specs/683-brand-guidelines/plan.md @@ -0,0 +1,79 @@ +# Implementation Plan: Brand Guidelines Alignment + +## Objective + +Replace the Wave documentation site's generic indigo/purple palette and system fonts with the re:cinq brand guidelines v1.0 color scheme (Midnight Navy, Quantum Blue, Aurora gradients) and Neue Montreal typography. + +## Approach + +This is a CSS-first theming change. The VitePress theme uses CSS custom properties (`--wave-*` and `--vp-c-brand-*`) extensively, making the color swap straightforward. Typography requires adding `@font-face` declarations for Neue Montreal and updating the font stack. Logo/favicon are asset replacements. + +**Strategy:** Work bottom-up from CSS variables (foundation) through component styles, then config/assets, finishing with the hero section. + +## File Mapping + +### Modified Files +| File | Change | +|------|--------| +| `docs/.vitepress/theme/styles/custom.css` | Replace all `--wave-*` color variables with brand palette values; add `@font-face` for Neue Montreal; update `--vp-c-brand-*` mappings; update dark mode overrides to Midnight Navy | +| `docs/.vitepress/theme/styles/components.css` | Update hardcoded hex values in component styles to use brand CSS variables; update gradients to Aurora; adjust border-radius to 8-12px per brand spec | +| `docs/.vitepress/config.ts` | Update font preconnect links if using CDN; update favicon path if format changes | +| `docs/public/logo.svg` | Replace wave motif SVG with re:cinq blue leaf logomark with brackets/slashes | +| `docs/public/favicon.ico` | Replace with simplified leaf icon favicon | +| `docs/index.md` | Update any hardcoded color references in hero section inline styles | + +### No Changes Expected +| File | Reason | +|------|--------| +| `docs/.vitepress/theme/index.ts` | Component registrations unchanged | +| `docs/.vitepress/theme/types.ts` | Type definitions unchanged | +| Vue components | They consume CSS variables; no source changes needed unless they have hardcoded hex values | + +### Possible New Files +| File | Condition | +|------|-----------| +| `docs/public/fonts/NeueMontreal-*.woff2` | If self-hosting the font (preferred for performance) | + +## Architecture Decisions + +1. **Self-hosted fonts over CDN**: Neue Montreal is not on Google Fonts. Self-host WOFF2 files in `docs/public/fonts/` with `@font-face` declarations. This avoids third-party dependencies and GDPR concerns. + +2. **Preserve `--wave-*` variable naming**: Keep the `--wave-` prefix for project-specific variables but update their values to brand colors. This avoids a mass rename across all component files. Add `--brand-*` aliases for direct brand token access. + +3. **Keep functional status colors**: Trust badges use green/amber/red for semantic meaning. These stay but are verified against new brand backgrounds for contrast. + +4. **Logo as SVG**: Create a clean SVG leaf logomark matching the brand description (blue leaf with brackets/slashes). The favicon can be generated from the same SVG source. + +5. **Aurora gradient as reusable variable**: Define `--brand-aurora-gradient` as a CSS custom property so it can be reused across hero, feature cards, and other sections. + +## Risks + +| Risk | Impact | Mitigation | +|------|--------|------------| +| Neue Montreal font licensing | Cannot distribute proprietary font | Check if font files are available in project assets or use a suitable open-source alternative (e.g., PP Neue Montreal if licensed, or Montreal as fallback) | +| Hardcoded hex values in Vue components | Brand colors not applied everywhere | Grep for all hex color literals (`#4f46e5`, `#4338ca`, `#06b6d4`, `#8b5cf6`) across Vue/CSS files | +| Dark mode contrast | Text unreadable against Midnight Navy | Test WCAG AA contrast ratios for all text/background combinations | +| Terminal preview colors | Syntax highlighting may clash with new palette | Terminal uses its own isolated color scheme; verify it works against Midnight Navy | +| Missing asset files | Logo/favicon not attached to issue | Create placeholder SVGs matching the brand description; flag for design review | + +## Testing Strategy + +1. **Visual regression**: Run `npm run docs:dev` and manually verify: + - Home page hero with Aurora gradient + - Light mode: Crystal White/Neutral Fog backgrounds + - Dark mode: Midnight Navy backgrounds + - Feature cards with brand colors + - Trust badges remain readable + - Terminal preview contrast + +2. **Build verification**: Run `npm run docs:build` to confirm no build errors + +3. **Grep validation**: Verify no legacy hex values remain: + - `#4f46e5` (old primary) + - `#4338ca` (old primary-dark) + - `#06b6d4` (old secondary) + - `#8b5cf6` (old accent) + +4. **Font loading**: Verify Neue Montreal renders in headings and body text in browser DevTools + +5. **Cross-browser**: Verify `@font-face` loads in Chrome, Firefox, Safari diff --git a/specs/683-brand-guidelines/spec.md b/specs/683-brand-guidelines/spec.md new file mode 100644 index 00000000..99bb7d2e --- /dev/null +++ b/specs/683-brand-guidelines/spec.md @@ -0,0 +1,83 @@ +# docs: align VitePress documentation site with re:cinq brand guidelines v1.0 + +**Issue:** [#683](https://github.com/re-cinq/wave/issues/683) +**Repository:** re-cinq/wave +**Author:** nextlevelshit +**State:** OPEN +**Labels:** none + +## Context + +The re:cinq brand guidelines v1.0 have been finalised. The Wave documentation site (VitePress) currently uses a generic indigo/purple palette and system fonts that don't match the official brand identity. + +## Brand Specifications + +### Color Palette (Primary) +| Token | Name | Hex | Usage | +|-------|------|-----|-------| +| `--brand-midnight-navy` | Midnight Navy | `#0F1F49` | Main neutral, dark backgrounds, typography | +| `--brand-crystal-white` | Crystal White | `#FFFFFF` | Light backgrounds, text on dark | +| `--brand-quantum-blue` | Quantum Blue | `#0014EB` | Accent: buttons, links, highlights | +| `--brand-aurora-start` | Aurora gradient start | `#E4E6FD` | Gradient backgrounds | +| `--brand-aurora-mid` | Aurora gradient mid | `#5664F4` | Gradient backgrounds | +| `--brand-aurora-end` | Aurora gradient end | `#8F96F6` | Gradient backgrounds | + +### Color Palette (Secondary) +| Token | Name | Hex | Usage | +|-------|------|-----|-------| +| `--brand-pulse-blue` | Pulse Blue | `#5664F4` | Supporting accent | +| `--brand-soft-indigo` | Soft Indigo | `#8F96F6` | Supporting accent | +| `--brand-nebula-light` | Nebula Light | `#E6E8FD` | Light backgrounds, cards | +| `--brand-neutral-fog` | Neutral Fog | `#F2F2F7` | Subtle backgrounds | + +### Typography +- **Font family:** Neue Montreal (sans-serif) -- headlines and body +- **H1:** Bold, 64px/48pt +- **H2:** Medium/Bold, 40px/30pt +- **H3:** Medium/Regular, 24px/18pt +- **Body:** Regular, 16-18px/12-14pt +- **Captions:** Light/Regular, 12-14px/9-10pt +- **Mono (code):** keep JetBrains Mono + +### Visual Elements +- Aurora gradient for hero/banner sections +- Rounded corners: 8-12px (callout/highlight blocks) +- Brand Pattern 1.0: white at 20-30% opacity on Aurora/Pulse Blue backgrounds +- Leaf logomark (blue, brackets/slashes inside) +- Clean, minimal icon style with soft gradients + +## Scope + +### Files to update +- `docs/.vitepress/theme/styles/custom.css` -- replace `--wave-*` colour variables with brand tokens, add Neue Montreal `@font-face` or Google Fonts import +- `docs/.vitepress/theme/styles/components.css` -- update component colours +- `docs/.vitepress/config.ts` -- update font preconnect, og metadata, site title/description if needed +- `docs/public/logo.svg` -- replace with re:cinq logomark (blue leaf) +- `docs/public/favicon.ico` -- replace with re:cinq favicon (simplified leaf icon) +- `docs/index.md` -- update hero section if it uses hardcoded brand elements + +### Changes +1. **Colour tokens** -- map all `--wave-primary`, `--wave-accent`, `--wave-secondary` to brand palette. Dark mode: use Midnight Navy backgrounds. Light mode: use Crystal White/Neutral Fog backgrounds with Quantum Blue accents +2. **VitePress brand vars** -- `--vp-c-brand-1/2/3` should map to Quantum Blue / Pulse Blue / Soft Indigo +3. **Hero gradient** -- replace current `linear-gradient(135deg, ...)` with Aurora gradient +4. **Typography** -- add Neue Montreal as primary sans-serif font; keep JetBrains Mono for code +5. **Logo & favicon** -- replace Wave SVG with re:cinq leaf logomark +6. **Feature cards** -- update hover shadow, border, and background to match brand callout style (Aurora gradient bg, 8-12px radius) +7. **Trust badges / status colours** -- keep functional green/amber/red but ensure they work against new backgrounds + +### Out of scope +- Content rewrites (that's a separate pass) +- `wave serve` web dashboard (separate issue) + +## Acceptance Criteria +- [ ] `docs/.vitepress/theme/styles/custom.css` uses brand hex values exclusively (no legacy `#4f46e5` etc.) +- [ ] Neue Montreal loads correctly and renders in headings + body +- [ ] Logo and favicon match re:cinq logomark +- [ ] Dark mode uses Midnight Navy (`#0F1F49`) backgrounds +- [ ] Light mode uses Crystal White / Neutral Fog backgrounds +- [ ] Aurora gradient visible in hero section +- [ ] `npm run docs:dev` renders without visual regressions + +## Missing Assets +- Neue Montreal font files or CDN URL not provided -- implementer will need to source the font +- Actual logo SVG and favicon files not attached to the issue diff --git a/specs/683-brand-guidelines/tasks.md b/specs/683-brand-guidelines/tasks.md new file mode 100644 index 00000000..60fd9924 --- /dev/null +++ b/specs/683-brand-guidelines/tasks.md @@ -0,0 +1,30 @@ +# Tasks + +## Phase 1: Foundation — CSS Variables & Typography + +- [ ] Task 1.1: Replace `--wave-*` color variables in `custom.css` with brand palette values (Quantum Blue, Pulse Blue, Soft Indigo) for both light and dark mode +- [ ] Task 1.2: Map VitePress `--vp-c-brand-1/2/3` to Quantum Blue / Pulse Blue / Soft Indigo in `custom.css` +- [ ] Task 1.3: Update dark mode overrides to use Midnight Navy (`#0F1F49`) backgrounds +- [ ] Task 1.4: Add Neue Montreal `@font-face` declarations (self-hosted WOFF2 in `docs/public/fonts/`) and update `--vp-font-family-base` to use Neue Montreal +- [ ] Task 1.5: Update `config.ts` font preconnect links — remove Google Fonts preconnect for Inter (no longer needed), keep JetBrains Mono + +## Phase 2: Component Styles + +- [ ] Task 2.1: Update `components.css` — hero gradient to Aurora (`#E4E6FD` → `#5664F4` → `#8F96F6`), feature card border-radius to 8-12px, card backgrounds to Nebula Light [P] +- [ ] Task 2.2: Update `HeroSection.vue` terminal colors — adjust terminal background/text to harmonize with Midnight Navy palette [P] +- [ ] Task 2.3: Update `TerminalOutput.vue` and `TerminalPreview.vue` terminal backgrounds to align with brand dark colors [P] +- [ ] Task 2.4: Verify trust/status color fallbacks in `TrustSignals.vue`, `PermissionMatrix.vue`, `YamlPlayground.vue`, `UseCaseGallery.vue` — keep functional green/amber/red, ensure contrast against new backgrounds [P] +- [ ] Task 2.5: Update `CopyButton.vue` hardcoded success green to use CSS variable [P] +- [ ] Task 2.6: Update `PipelineVisualizer.vue` persona colors to harmonize with brand palette [P] + +## Phase 3: Assets + +- [ ] Task 3.1: Replace `docs/public/logo.svg` with re:cinq leaf logomark (blue, brackets/slashes inside, Quantum Blue background) +- [ ] Task 3.2: Replace `docs/public/favicon.ico` with simplified re:cinq leaf icon +- [ ] Task 3.3: Update `docs/index.md` hero section — remove any hardcoded color references that conflict with brand + +## Phase 4: Validation + +- [ ] Task 4.1: Grep for legacy hex values (`#4f46e5`, `#4338ca`, `#06b6d4`, `#8b5cf6`) — confirm zero matches in CSS/Vue files +- [ ] Task 4.2: Run `npm run docs:build` to confirm no build errors +- [ ] Task 4.3: Visual spot-check — light mode, dark mode, hero gradient, feature cards, terminal preview From c2be691c1e2f5e4ae8865cba3b0960c6583a3305 Mon Sep 17 00:00:00 2001 From: Michael Czechowski Date: Mon, 30 Mar 2026 18:42:24 +0200 Subject: [PATCH 2/3] =?UTF-8?q?feat:=20implement=20#683=20=E2=80=94=20alig?= =?UTF-8?q?n=20VitePress=20docs=20with=20re:cinq=20brand=20guidelines=20v1?= =?UTF-8?q?.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace generic indigo/purple palette with re:cinq brand colors: - Quantum Blue (#0014EB) as primary accent - Midnight Navy (#0F1F49) for dark mode backgrounds - Aurora gradient (E4E6FD → 5664F4 → 8F96F6) for hero sections - Pulse Blue and Soft Indigo as supporting accents - Crystal White / Neutral Fog for light mode backgrounds Add Neue Montreal font-face declarations with fallback stack. Replace logo.svg and favicon.svg with re:cinq leaf logomark. Update all terminal preview colors to harmonize with Midnight Navy. Update PipelineVisualizer persona colors to brand palette. --- docs/.vitepress/config.ts | 4 +- .../theme/components/CopyButton.vue | 4 +- .../theme/components/HeroSection.vue | 26 +++--- .../theme/components/PipelineVisualizer.vue | 20 ++--- .../theme/components/TerminalOutput.vue | 6 +- .../theme/components/TerminalPreview.vue | 38 ++++----- docs/.vitepress/theme/styles/components.css | 47 +++++------ docs/.vitepress/theme/styles/custom.css | 79 ++++++++++++++++--- docs/public/favicon.svg | 7 ++ docs/public/logo.svg | 29 +++---- specs/683-brand-guidelines/tasks.md | 34 ++++---- 11 files changed, 176 insertions(+), 118 deletions(-) create mode 100644 docs/public/favicon.svg diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 08985b18..0af6f58d 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -21,7 +21,9 @@ export default withMermaid( ['link', { rel: 'icon', type: 'image/svg+xml', href: '/wave/favicon.svg' }], ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }], ['link', { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }], - ['link', { href: 'https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&display=swap', rel: 'stylesheet' }] + ['link', { href: 'https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&display=swap', rel: 'stylesheet' }], + ['link', { rel: 'preload', href: '/wave/fonts/NeueMontreal-Regular.woff2', as: 'font', type: 'font/woff2', crossorigin: '' }], + ['link', { rel: 'preload', href: '/wave/fonts/NeueMontreal-Bold.woff2', as: 'font', type: 'font/woff2', crossorigin: '' }] ], themeConfig: { diff --git a/docs/.vitepress/theme/components/CopyButton.vue b/docs/.vitepress/theme/components/CopyButton.vue index 0fbeeef0..f35c1007 100644 --- a/docs/.vitepress/theme/components/CopyButton.vue +++ b/docs/.vitepress/theme/components/CopyButton.vue @@ -92,8 +92,8 @@ async function copyCode() { } .copy-button.copied { - color: #10b981; - border-color: #10b981; + color: var(--wave-trust-green, #10b981); + border-color: var(--wave-trust-green, #10b981); } .copy-button svg { diff --git a/docs/.vitepress/theme/components/HeroSection.vue b/docs/.vitepress/theme/components/HeroSection.vue index 69e9ebdf..9943d8ba 100644 --- a/docs/.vitepress/theme/components/HeroSection.vue +++ b/docs/.vitepress/theme/components/HeroSection.vue @@ -268,7 +268,7 @@ function getLineIcon(icon?: TerminalIcon): string { font-weight: 700; line-height: 1.1; margin-bottom: 16px; - background: linear-gradient(135deg, var(--wave-primary) 0%, var(--wave-accent) 100%); + background: var(--brand-aurora-gradient); -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text; @@ -398,7 +398,7 @@ a.hero-pill { .terminal-window { width: 100%; max-width: 560px; - background: #1a1a2e; + background: #0F1F49; border-radius: 12px; overflow: hidden; box-shadow: 0 20px 40px rgba(0, 0, 0, 0.2); @@ -408,7 +408,7 @@ a.hero-pill { display: flex; align-items: center; padding: 12px 16px; - background: #2d2d44; + background: #162050; gap: 12px; } @@ -431,7 +431,7 @@ a.hero-pill { flex: 1; text-align: center; font-size: 13px; - color: #a9b1d6; + color: #C0C8E8; font-family: var(--wave-font-mono, 'SF Mono', 'Fira Code', monospace); } @@ -442,7 +442,7 @@ a.hero-pill { padding: 4px 8px; background: transparent; border: none; - color: #6b7280; + color: #6B7CA0; cursor: pointer; border-radius: 4px; transition: all 0.15s ease; @@ -450,7 +450,7 @@ a.hero-pill { .terminal-copy-btn:hover { background: rgba(255, 255, 255, 0.1); - color: #a9b1d6; + color: #C0C8E8; } .terminal-copy-btn.copied { @@ -463,7 +463,7 @@ a.hero-pill { font-family: var(--wave-font-mono, 'SF Mono', 'Fira Code', monospace); font-size: 13px; line-height: 1.2; - color: #a9b1d6; + color: #C0C8E8; height: 260px; width: 100%; overflow-x: hidden; @@ -478,7 +478,7 @@ a.hero-pill { left: 0; right: 0; height: 48px; - background: linear-gradient(to bottom, transparent, #1a1a2e); + background: linear-gradient(to bottom, transparent, #0F1F49); pointer-events: none; } @@ -492,7 +492,7 @@ a.hero-pill { } .terminal-line.command { - color: #7dd3fc; + color: #5664F4; } .terminal-line .line-icon { @@ -503,10 +503,10 @@ a.hero-pill { .terminal-line.line-success { color: #27c93f; } .terminal-line.line-error { color: #ff5f56; } .terminal-line.line-warning { color: #ffbd2e; } -.terminal-line.line-info { color: #7dd3fc; } -.terminal-line.line-muted { color: #6b7280; } -.terminal-line.line-highlight { color: #c4b5fd; font-weight: 500; } -.terminal-line.line-logo { color: #7aa2f7; font-weight: 600; } +.terminal-line.line-info { color: #5664F4; } +.terminal-line.line-muted { color: #6B7CA0; } +.terminal-line.line-highlight { color: #8F96F6; font-weight: 500; } +.terminal-line.line-logo { color: #0014EB; font-weight: 600; } .terminal-line.line-meta { display: none; } /* Background pattern */ diff --git a/docs/.vitepress/theme/components/PipelineVisualizer.vue b/docs/.vitepress/theme/components/PipelineVisualizer.vue index 8007b542..11ed3dfa 100644 --- a/docs/.vitepress/theme/components/PipelineVisualizer.vue +++ b/docs/.vitepress/theme/components/PipelineVisualizer.vue @@ -109,11 +109,11 @@ const mermaidCode = computed(() => { // Style nodes by persona const personaColors: Record = { - navigator: '#4a90d9', - auditor: '#d94a4a', - craftsman: '#4ad94a', - philosopher: '#d9a44a', - summarizer: '#9a4ad9' + navigator: '#0014EB', + auditor: '#E04040', + craftsman: '#10b981', + philosopher: '#D9960A', + summarizer: '#8F96F6' } pipeline.steps.forEach((step: PipelineStep) => { @@ -360,9 +360,9 @@ watch(mermaidCode, () => { border-radius: 4px; } -.legend-color.navigator { background: #4a90d9; } -.legend-color.auditor { background: #d94a4a; } -.legend-color.craftsman { background: #4ad94a; } -.legend-color.philosopher { background: #d9a44a; } -.legend-color.summarizer { background: #9a4ad9; } +.legend-color.navigator { background: #0014EB; } +.legend-color.auditor { background: #E04040; } +.legend-color.craftsman { background: #10b981; } +.legend-color.philosopher { background: #D9960A; } +.legend-color.summarizer { background: #8F96F6; } diff --git a/docs/.vitepress/theme/components/TerminalOutput.vue b/docs/.vitepress/theme/components/TerminalOutput.vue index 0ce87cdc..0043c8ec 100644 --- a/docs/.vitepress/theme/components/TerminalOutput.vue +++ b/docs/.vitepress/theme/components/TerminalOutput.vue @@ -22,14 +22,14 @@ defineProps({