Expert color palette audit — verify semantic token completeness, WCAG contrast compliance, 60-30-10 distribution, and tonal stacking correctness across the movemental platform.
Target: $ARGUMENTS
If no target is provided, audit the full palette in globals.css and spot-check usage across src/components/ and src/app/(site)/.
Before Starting
- Read
src/app/globals.css — extract ALL color tokens from @theme inline and :root blocks.
- Read
docs/design/DESIGN.md — confirm the palette spec (The Digital Curator: blue primary #0053db, light surface palette, Midnight for inverse sections).
Palette Reference (DESIGN.md)
| Token |
Value |
Role |
--background |
#f7f9fb |
Surface — default canvas |
--foreground |
#2a3439 |
Ink — never pure black |
--section |
#f0f4f7 |
surface_container_low — tonal shift |
--card |
#ffffff |
surface_container_lowest — cards |
--elevated |
#e1e9ee |
surface_container_high — accent band |
--primary |
#0053db |
Actions, CTAs, focus — NOT large backgrounds |
--primary-dim |
#0048c1 |
Gradient endpoint for CTAs |
--inverse-surface |
#101820 |
Midnight hero sections |
--inverse-foreground |
#f7f9fb |
Text on inverse-surface |
--muted-foreground |
#566166 |
on_surface_variant — subtitles |
--border |
rgba(169,180,185,0.15) |
Form fields ONLY |
Audit Dimensions
1. TOKEN COMPLETENESS
Verify all required tokens exist in globals.css:
- Background surface ramp:
--background, --section, --card, --elevated, --surface-highest
- Foreground tokens:
--foreground, --card-foreground, --muted-foreground
- Primary set:
--primary, --primary-dim, --primary-foreground
- Inverse set:
--inverse-surface, --inverse-foreground
- Utility:
--border, --input, --ring, --destructive
- Custom:
--shadow-ambient, --gradient-primary, layout tokens
2. CONTRAST COMPLIANCE (WCAG 2.1 AA)
Required ratios:
- Normal text (< 18px): 4.5:1 minimum
- Large text (≥ 18px / ≥ 14px bold): 3:1 minimum
- UI components: 3:1 minimum
Critical pairs to check:
| Pair |
Background |
Foreground |
Context |
| Body text |
--background (#f7f9fb) |
--foreground (#2a3439) |
Main content |
| Card text |
--card (#fff) |
--foreground (#2a3439) |
Cards |
| Muted text |
--background (#f7f9fb) |
--muted-foreground (#566166) |
Subtitles |
| Primary CTA |
--primary (#0053db) |
--primary-foreground (#fff) |
Buttons |
| Midnight text |
--inverse-surface (#101820) |
--inverse-foreground (#f7f9fb) |
Dark sections |
| Midnight muted |
--inverse-surface (#101820) |
inverse-foreground/55 |
Dark subtitles |
3. TONAL STACKING AUDIT
Verify the surface ramp is monotonic (no lightness inversions):
background (#f7f9fb) → section (#f0f4f7) → elevated (#e1e9ee) → surface-highest (#d7dfe5)
Check that card (#ffffff) is lighter than all — it sits ON these surfaces to create Ghost Lift.
4. 60-30-10 DISTRIBUTION
Audit usage across key pages:
- 60% (dominant):
--background + --foreground — the base canvas
- 30% (secondary):
--card, --section, --elevated, --muted-foreground — structure
- 10% (accent):
--primary (#0053db) — CTAs, highlights, focus rings ONLY
Red flags:
- Primary blue used as background for large sections (kills CTA impact)
text-muted-foreground used for main body text (too low contrast)- Multiple competing accents visible in one view
bg-white or bg-black used instead of semantic tokens
5. COMPONENT SPOT-CHECK
Scan component files for color violations:
- Hardcoded colors:
bg-blue-*, text-gray-*, hex values, rgb()
- Mismatched pairs:
bg-primary without text-primary-foreground
- Opacity dropping below WCAG:
text-foreground/50 as body text
text-white outside of variant="midnight" Section wrappers- Borders used for section separation (should be tonal stacking)
Output Format
## Color Palette Audit
### Token Inventory
| Token | Value | Present | Status |
|-------|-------|---------|--------|
### Contrast Report
| Pair | Ratio | WCAG AA | Status |
|------|-------|---------|--------|
### Issues Found
1. [SEVERITY: CRITICAL/HIGH/MEDIUM/LOW] — description
- Current: value
- Recommended: value
### Tonal Stacking Assessment
- Surface ramp: [PASS/ADJUST]
- 60-30-10 distribution: [PASS/ADJUST]
Rules
- This is a light-primary site. There is NO global dark mode.
- Midnight sections are regional — scoped to
<Section variant="midnight"> or bg-inverse-surface.
- Primary brand color is
#0053db blue — do not change without user approval.
- Never use pure black (
#000) — foreground is #2a3439.
- Never use pure white (
#fff) as a background — surface is #f7f9fb. Card is the only white token.
- Present the full audit before making any changes.
- This audit complements
tailwind-cleanup — color-audit checks the palette, tailwind-cleanup checks usage.
1---2name: color-audit-43description: Expert color palette audit for movemental — verify semantic token completeness, WCAG contrast compliance, 60-30-10 distribution, and tonal stacking correctness. Light-primary site with regional Midnight sections.4---56Expert color palette audit — verify semantic token completeness, WCAG contrast compliance, 60-30-10 distribution, and tonal stacking correctness across the movemental platform.78Target: $ARGUMENTS910If no target is provided, audit the full palette in `globals.css` and spot-check usage across `src/components/` and `src/app/(site)/`.1112## Before Starting13141. Read `src/app/globals.css` — extract ALL color tokens from `@theme inline` and `:root` blocks.152. Read `docs/design/DESIGN.md` — confirm the palette spec (The Digital Curator: blue primary #0053db, light surface palette, Midnight for inverse sections).1617## Palette Reference (DESIGN.md)1819| Token | Value | Role |20|-------|-------|------|21| `--background` | `#f7f9fb` | Surface — default canvas |22| `--foreground` | `#2a3439` | Ink — never pure black |23| `--section` | `#f0f4f7` | surface_container_low — tonal shift |24| `--card` | `#ffffff` | surface_container_lowest — cards |25| `--elevated` | `#e1e9ee` | surface_container_high — accent band |26| `--primary` | `#0053db` | Actions, CTAs, focus — NOT large backgrounds |27| `--primary-dim` | `#0048c1` | Gradient endpoint for CTAs |28| `--inverse-surface` | `#101820` | Midnight hero sections |29| `--inverse-foreground` | `#f7f9fb` | Text on inverse-surface |30| `--muted-foreground` | `#566166` | on_surface_variant — subtitles |31| `--border` | `rgba(169,180,185,0.15)` | Form fields ONLY |3233## Audit Dimensions3435### 1. TOKEN COMPLETENESS3637Verify all required tokens exist in `globals.css`:38- Background surface ramp: `--background`, `--section`, `--card`, `--elevated`, `--surface-highest`39- Foreground tokens: `--foreground`, `--card-foreground`, `--muted-foreground`40- Primary set: `--primary`, `--primary-dim`, `--primary-foreground`41- Inverse set: `--inverse-surface`, `--inverse-foreground`42- Utility: `--border`, `--input`, `--ring`, `--destructive`43- Custom: `--shadow-ambient`, `--gradient-primary`, layout tokens4445### 2. CONTRAST COMPLIANCE (WCAG 2.1 AA)4647**Required ratios:**48- Normal text (< 18px): 4.5:1 minimum49- Large text (≥ 18px / ≥ 14px bold): 3:1 minimum50- UI components: 3:1 minimum5152**Critical pairs to check:**5354| Pair | Background | Foreground | Context |55|------|-----------|------------|---------|56| Body text | `--background` (#f7f9fb) | `--foreground` (#2a3439) | Main content |57| Card text | `--card` (#fff) | `--foreground` (#2a3439) | Cards |58| Muted text | `--background` (#f7f9fb) | `--muted-foreground` (#566166) | Subtitles |59| Primary CTA | `--primary` (#0053db) | `--primary-foreground` (#fff) | Buttons |60| Midnight text | `--inverse-surface` (#101820) | `--inverse-foreground` (#f7f9fb) | Dark sections |61| Midnight muted | `--inverse-surface` (#101820) | inverse-foreground/55 | Dark subtitles |6263### 3. TONAL STACKING AUDIT6465Verify the surface ramp is monotonic (no lightness inversions):66`background (#f7f9fb)` → `section (#f0f4f7)` → `elevated (#e1e9ee)` → `surface-highest (#d7dfe5)`6768Check that `card (#ffffff)` is lighter than all — it sits ON these surfaces to create Ghost Lift.6970### 4. 60-30-10 DISTRIBUTION7172Audit usage across key pages:73- **60% (dominant):** `--background` + `--foreground` — the base canvas74- **30% (secondary):** `--card`, `--section`, `--elevated`, `--muted-foreground` — structure75- **10% (accent):** `--primary` (#0053db) — CTAs, highlights, focus rings ONLY7677**Red flags:**78- Primary blue used as background for large sections (kills CTA impact)79- `text-muted-foreground` used for main body text (too low contrast)80- Multiple competing accents visible in one view81- `bg-white` or `bg-black` used instead of semantic tokens8283### 5. COMPONENT SPOT-CHECK8485Scan component files for color violations:86- Hardcoded colors: `bg-blue-*`, `text-gray-*`, hex values, rgb()87- Mismatched pairs: `bg-primary` without `text-primary-foreground`88- Opacity dropping below WCAG: `text-foreground/50` as body text89- `text-white` outside of `variant="midnight"` Section wrappers90- Borders used for section separation (should be tonal stacking)9192## Output Format9394```95## Color Palette Audit9697### Token Inventory98| Token | Value | Present | Status |99|-------|-------|---------|--------|100101### Contrast Report102| Pair | Ratio | WCAG AA | Status |103|------|-------|---------|--------|104105### Issues Found1061. [SEVERITY: CRITICAL/HIGH/MEDIUM/LOW] — description107 - Current: value108 - Recommended: value109110### Tonal Stacking Assessment111- Surface ramp: [PASS/ADJUST]112- 60-30-10 distribution: [PASS/ADJUST]113```114115## Rules116117- This is a **light-primary** site. There is NO global dark mode.118- Midnight sections are regional — scoped to `<Section variant="midnight">` or `bg-inverse-surface`.119- Primary brand color is `#0053db` blue — do not change without user approval.120- Never use pure black (`#000`) — foreground is `#2a3439`.121- Never use pure white (`#fff`) as a background — surface is `#f7f9fb`. Card is the only white token.122- Present the full audit before making any changes.123- This audit complements `tailwind-cleanup` — color-audit checks the palette, tailwind-cleanup checks usage.
JoshuaShepherd