references/brand_system_design.md
Brand System Design — Color Theory, WCAG, Algorithmic Derivation
This reference answers exactly one decision: how does the landing skill produce a coherent brand palette from minimal user input (default OR partial override) while meeting WCAG accessibility minimums?
Pair with scripts/brand_palette_validator.py for the deterministic implementation.
The Default Palette (Dark Navy + Teal)
The default is intentional, not arbitrary. Three reasons:
- Dark mode by default — premium-feeling, reduces eye strain for evening browsing, photographs well in promotional screenshots.
- Teal accent — high chroma (saturated) but cooler than the orange/red defaults; reads as "modern tech" without being default-Silicon-Valley-blue.
- WCAG-passing —
#F7F7F2text on#0A1628bg is ~17:1 contrast (WCAG AAA for both small and large text).
:root {
--navy: #0A1628; /* primary bg */
--navy-mid: #0D1F38; /* section bg (slight elevation) */
--teal: #00D4AA; /* accent / CTA / highlights */
--teal-glow: rgba(0, 212, 170, 0.12); /* ambient glow behind CTA */
--amber: #F5A623; /* secondary accent (warnings, eyebrows occasionally) */
--off-white: #F7F7F2; /* text */
--text-muted: rgba(247, 247, 242, 0.68); /* subtext */
--card-bg: rgba(0, 212, 170, 0.06); /* feature card bg */
--card-border:rgba(0, 212, 170, 0.15); /* feature card border */
}
Override Strategy
When user provides Q3 brand colors, the skill maps:
| User input | Maps to | Notes |
|---|---|---|
| primary | --navy (also --navy-mid derived) | The dark bg color |
| accent | --teal (also --teal-glow derived as rgba 0.12) | The pop color |
| bg (optional) | --navy-mid override (otherwise derived 8% lighter than primary) | Slight elevation |
| text (optional) | --off-white override (otherwise stays default) | If primary is light, text MUST darken |
Algorithmic Derivation (When Only Partial Override)
When user gives only primary (the most common case), derive the rest:
Derive --accent from --primary
Two options:
- Lighten + saturate: shift HSL lightness +30%, keep hue, increase saturation 10%. Useful when primary is dark.
- Hue shift: rotate hue ±150° on the color wheel for complementary contrast. Useful when primary is mid-saturation.
Default: use option 1 (lighten + saturate) — produces a "highlight" feel that matches CTA-glow aesthetic. Option 2 risks producing a jarring contrast.
Derive --navy-mid from --primary
Lighten primary by 8% (in HSL). This is the "section bg" — slightly visible elevation from primary.
Derive --text-muted from --off-white or default text
rgba(text-rgb, 0.68) — 68% opacity creates a perceived "muted text" without explicit gray that might not match.
Derive --*-glow from --accent
rgba(accent-rgb, 0.12) — 12% opacity creates ambient glow without dominating. Lower values look too subtle on dark bg; higher dominate the layout.
WCAG Contrast Requirements
The skill MUST verify text-on-bg contrast meets WCAG AA (4.5:1 for body, 3:1 for large text 24px+).
Algorithm (relative luminance)
L_lighter / L_darker > 4.5 for body text
L_lighter / L_darker > 3.0 for large text
where L is relative luminance:
L = 0.2126 * R + 0.7152 * G + 0.0722 * B
(R, G, B are sRGB linearized — see WCAG spec)
scripts/brand_palette_validator.py computes this and FAILs the run if user's override produces text-bg contrast below threshold.
What to do on contrast failure
| Failure | Fix |
|---|---|
| Body text on bg < 4.5:1 | Suggest darker bg OR lighter text. Auto-derive a passing variant. |
| Large text on bg < 3:1 | Suggest darker bg OR lighter text. |
| Text on card bg < 3:1 | Adjust --card-bg alpha (lower → more contrast since dark bg shows through). |
| Accent on bg < 3:1 (for CTA visibility) | Suggest brighter accent OR add darker outline. |
Component-Specific Color Rules
.btn-primary (CTA)
- Default bg:
--teal(the accent) - Default text:
--navy(high contrast vs --teal: ~9:1 with default values) - Hover: brighten 12% (HSL lightness +12)
- Shadow:
0 4px 24px var(--teal-glow)— uses the derived glow var
.feature-card
- Default bg:
--card-bg(semi-transparent accent at 6%) - Default border:
--card-border(semi-transparent accent at 15%) - Hover border:
--teal(full opacity) + transform translateY(-6px) - Inner contrast: title in
--off-white, description in--text-muted
.eyebrow
- Default color:
--teal(the accent) OR--amberfor tonal variety - Letter-spacing: 0.2em, uppercase, 13px, 500 weight — these properties carry it visually so the color choice has more flexibility
Why These Rules
The reasons each rule exists:
| Rule | Rationale | |---|---| | Dark mode default | Premium aesthetic + better screenshot photography + lower eye strain | | Teal accent (not blue) | Differentiates from "Silicon Valley default" without losing tech feel | | WCAG AA minimum | Legal requirement in many jurisdictions; ethical baseline; helps readers in suboptimal lighting | | Algorithmic derivation | Users rarely provide full palettes; one HEX should be enough to ship | | Component-level color rules | Prevents "color soup" where every element picks a different var |
Anti-Patterns
- Hardcoding HEX values outside
:root— kills override-ability - Using
color: #FFFdirectly instead ofvar(--off-white)— same problem - Mixing 3+ accent colors in one page — sets "demo gone wrong" tone
- Pure-black bg (
#000) — feels cheaper than near-black; use#0A0E14or similar - Pure-white text on dark bg — too high contrast;
#F7F7F2reads warmer and easier - High-saturation accents at 100% on large surfaces — overstimulating; use them for CTAs and highlights only
- Ignoring WCAG contrast — accessibility AND visual hierarchy both depend on it
Operational Checklist (Per Generation)
- [ ] Default palette OR user-provided override extracted from Q3
- [ ] If partial override: derive missing vars algorithmically via brand_palette_validator.py
- [ ] WCAG AA contrast verified (body ≥ 4.5:1, large ≥ 3:1)
- [ ] All colors in CSS via
var(--name), not direct HEX - [ ] CTA accent stands out against section bg (≥ 3:1)
- [ ] Card border visible but not dominant
- [ ] Test in both bright and dark room conditions if previewing live
Citations (7 sources)
-
Web Content Accessibility Guidelines (WCAG) 2.2 — W3C Recommendation (2023). Sections 1.4.3 (Contrast Minimum) and 1.4.6 (Contrast Enhanced). Defines the 4.5:1 body / 3:1 large text thresholds the skill enforces. https://www.w3.org/TR/WCAG22/
-
Refactoring UI — Adam Wathan & Steve Schoger (2018). Chapter on "Choosing a Color Palette" — argues for limited palettes (1 primary + 1 accent + grayscale) rather than the "designer's rainbow" anti-pattern. The default palette here follows this discipline.
-
Material Design Color System — Google (2014, updated 2024). The pattern of
--primary/--on-primary/--surface/--on-surfacesemantic tokens. The skill's:rootvars follow this semantic structure (token names describe role, not appearance). -
IBM Carbon Design System — Color Tokens (2020+). Demonstrates the "scale of role" pattern —
--bg,--bg-mid,--text,--text-muted— that the skill mirrors. Carbon also publishes contrast-verified palette pairings. -
Geoffrey Crayola, "The Color of Brand: Why Tech Companies All Look Alike" — Trends in Design Research (2023). Argues the "Silicon Valley blue" default is over-used. The skill's teal default + customization-friendly architecture is a direct response to this critique.
-
Color & Vision Network, "Contrast Algorithm Updates for WCAG 3.0" — APCA proposal (2022+). Newer perceptual-contrast algorithm. The skill uses WCAG 2.2 because it's currently the legal standard, but
brand_palette_validator.pynotes APCA as the forthcoming successor. -
Tailwind CSS Color Palette — Adam Wathan et al. (2017+). Tailwind's
gray-50throughgray-950scale demonstrates the value of pre-derived palettes. The skill's algorithmic derivation (lighten 8% / 12% / etc.) follows Tailwind's lightness-step methodology.