Expert color palette audit — verify light/dark mode alignment, WCAG contrast compliance, 60-30-10 distribution, and overall color harmony across the 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/(public)/.
Before Starting
- Read
src/app/globals.css — extract ALL color tokens from :root (dark) and .light blocks.
- Read
tailwind.config.ts — verify every CSS var has a corresponding Tailwind color mapping.
- Read
_docs/design/DESIGN_CHAIN.md — confirm the palette spec (Pastoral-Warm: gold primary, warm neutrals).
- Read
_docs/design/DESIGN_CHARTER.md if it exists — confirm the color philosophy.
Audit Dimensions
1. TOKEN COMPLETENESS
Verify every token defined in :root has a matching override in .light:
| Token |
:root (dark) |
.light |
Status |
Check for:
- Tokens defined in
:root but missing from .light (will inherit dark values in light mode)
- Tokens defined in
.light but not in :root (orphaned light-only tokens)
- Tokens in
tailwind.config.ts colors that reference undefined CSS vars
2. CONTRAST COMPLIANCE (WCAG 2.1 AA)
For each semantic token pair, compute the contrast ratio. Use the HSL values from globals.css, convert to hex/RGB, then calculate.
Required ratios:
- Normal text (< 18px / < 14px bold): 4.5:1 minimum
- Large text (≥ 18px / ≥ 14px bold): 3:1 minimum
- UI components and graphical objects: 3:1 minimum
- Focus indicators: 3:1 against adjacent colors
Critical pairs to check:
| Pair |
Background Token |
Foreground Token |
Context |
| Body text |
--background |
--foreground |
Main content |
| Card text |
--card |
--card-foreground |
Cards |
| Primary button |
--primary |
--primary-foreground |
CTAs |
| Secondary button |
--secondary |
--secondary-foreground |
Secondary actions |
| Muted text |
--background |
--muted-foreground |
Subtle labels |
| Muted on card |
--card |
--muted-foreground |
Card subtitles |
| Destructive |
--destructive |
--destructive-foreground |
Error states |
| Success |
--success |
--success-foreground |
Success states |
| Popover text |
--popover |
--popover-foreground |
Dropdowns |
| Input text |
--input |
--foreground |
Form fields |
| Border visibility |
--background |
--border |
Borders |
| Focus ring |
--background |
--ring |
Focus states |
| Light section text |
--bg-light |
--text-dark |
Light bands |
| Light section muted |
--bg-light |
--text-muted-dark |
Light band subtitles |
Check both :root (dark) and .light mode values.
3. COLOR HARMONY & PALETTE COHERENCE
Evaluate the palette as a professional UI designer:
- Hue consistency: All warm neutrals should share a similar hue angle (around 24-36 for this palette). Flag any neutral that drifts into cool territory (blue/green hue).
- Saturation scale: Neutrals should have low, consistent saturation (0-15%). Flag any neutral with saturation > 20%.
- Lightness ramp: Background → card → secondary → muted should form a smooth, monotonic lightness ramp. Flag any inversions or large jumps.
- Primary vs accent distinction:
--primary (gold, for CTAs) must be clearly distinct from --accent (subtle interactive tint). If they're too similar, outline button hovers will look like primary buttons.
- Destructive vs success: These should be clearly distinguishable, including for color-blind users (red-green). Check that they differ in lightness or saturation, not just hue.
4. 60-30-10 COLOR DISTRIBUTION
Audit the actual usage distribution across key pages:
- 60% (dominant):
--background and --foreground — the base canvas. Should dominate.
- 30% (secondary):
--card, --muted, --secondary, --border — structural supporting colors.
- 10% (accent):
--primary (gold) — CTAs, active states, highlights. Should be sparingly used for impact.
Red flags:
- Primary/gold used as a background for large sections (overuse kills impact)
- Too many competing accent colors (primary + destructive + success all visible in one view)
- Muted-foreground used for main body text (too low contrast, should be foreground)
- Border color too prominent (draws attention away from content)
5. DARK/LIGHT MODE PERCEPTUAL BALANCE
Check that both modes feel equally polished:
- Dark mode: Backgrounds should be truly dark (lightness < 12%). Card should be slightly lighter than background. Text should be warm cream, not pure white (pure white on dark = harsh).
- Light mode: Backgrounds should be warm off-white (not pure white). Card can be white. Text should be warm dark, not pure black (pure black on light = harsh).
- Primary in both modes: Gold may need to shift slightly between modes. Too-bright gold on light backgrounds washes out; too-dark gold on dark backgrounds lacks pop.
- Border visibility: Borders should be visible but subtle in both modes. Check that
--border has sufficient contrast against --background in both themes (target 1.5:1+ for decorative borders, 3:1+ for functional borders).
- Shadow behavior: Primary glow shadows should be visible in dark mode and not overwhelming in light mode.
6. ACCESSIBILITY BEYOND CONTRAST
- Color-only information: Search for UI patterns that convey meaning through color alone (e.g., status dots without labels, color-coded categories without text). Flag these.
- Focus visibility: Verify
--ring is visible against both --background and --card in both themes.
- Error states: Verify
--destructive is distinguishable from --primary — users should not confuse error and brand.
- Hover/active states: Check that hover states using
--accent or primary/80 maintain contrast with their text.
- Chart colors: Verify the 5 chart colors are distinguishable from each other AND from the background in both themes.
7. COMPONENT SPOT-CHECK
Scan a sample of component files for color usage violations:
- Components using hardcoded colors instead of tokens (feed into tailwind-cleanup skill)
- Components where bg/text token pairs are mismatched (e.g.,
bg-primary with text-foreground instead of text-primary-foreground)
- Components using opacity modifiers that drop contrast below WCAG thresholds (e.g.,
text-foreground/50 as body text)
- Gradients that make text unreadable at certain scroll positions
Fixing Protocol
- Token fixes (D1): Edit
globals.css :root and/or .light blocks. Both themes must be updated in tandem.
- Mapping fixes: If adding a new token, add the Tailwind mapping in
tailwind.config.ts.
- Never change primary brand color without explicit user approval — gold (#b58c4c / hsl 36 48% 50%) is the brand identity.
- Contrast fixes: Prefer adjusting lightness over changing hue. Bump lightness in 3-5% increments until ratio is met.
- Test after fixing: Verify both dark and light mode in browser after any token change.
Output Format
## Color Palette Audit
### Palette Summary
| Token | Dark Mode (HSL) | Dark Hex | Light Mode (HSL) | Light Hex | Parity |
|-------|----------------|----------|-------------------|-----------|--------|
### Contrast Report
| Pair | Dark Ratio | Light Ratio | WCAG AA | Status |
|------|-----------|-------------|---------|--------|
| bg/fg | 15.2:1 | 12.8:1 | 4.5:1 | PASS |
| bg/muted-fg | 3.8:1 | 4.2:1 | 4.5:1 | FAIL (dark) |
### Issues Found
1. [SEVERITY: CRITICAL/HIGH/MEDIUM/LOW] — description
- Current: value
- Recommended: value
- Affected: list of components/pages
### Color Harmony Assessment
- Hue consistency: [PASS/ADJUST]
- Saturation scale: [PASS/ADJUST]
- Lightness ramp: [PASS/ADJUST]
- 60-30-10 distribution: [PASS/ADJUST]
- Dark/light perceptual balance: [PASS/ADJUST]
### Recommendations
1. [Priority fix with specific token change]
2. ...
Rules
- Always audit BOTH dark and light mode — never just one.
- Present the full audit report before making any changes.
- When computing contrast, use the actual HSL values from globals.css, converted to RGB. Do not estimate.
- Do not change the primary brand hue (gold ~36°) without user approval.
- If contrast fails, prefer adjusting lightness of the weaker token rather than changing the stronger one.
- Flag but do not auto-fix brand-level decisions (e.g., "primary is too close to destructive"). These need user input.
- This audit complements the tailwind-cleanup skill — color-audit checks the palette itself, tailwind-cleanup checks usage in components.
1---
2name: color-audit-2
3description: Expert color palette audit — verify light/dark mode alignment, WCAG contrast compliance, 60-30-10 distribution, and overall color harmony. Checks the palette itself, not just usage.
4user-invocable: true
5allowed-tools: Read, Grep, Glob
6metadata:
7 source: https://skillmd.com/skills/joshuashepherd/color-audit-2
8---
9
10Expert color palette audit — verify light/dark mode alignment, WCAG contrast compliance, 60-30-10 distribution, and overall color harmony across the platform.
11
12Target: $ARGUMENTS
13
14If no target is provided, audit the full palette in `globals.css` and spot-check usage across `src/components/` and `src/app/(public)/`.
15
16## Before Starting
17
181. Read `src/app/globals.css` — extract ALL color tokens from `:root` (dark) and `.light` blocks.
192. Read `tailwind.config.ts` — verify every CSS var has a corresponding Tailwind color mapping.
203. Read `_docs/design/DESIGN_CHAIN.md` — confirm the palette spec (Pastoral-Warm: gold primary, warm neutrals).
214. Read `_docs/design/DESIGN_CHARTER.md` if it exists — confirm the color philosophy.
22
23## Audit Dimensions
24
25### 1. TOKEN COMPLETENESS
26
27Verify every token defined in `:root` has a matching override in `.light`:
28
29| Token | `:root` (dark) | `.light` | Status |
30|-------|----------------|----------|--------|
31
32**Check for:**
33- Tokens defined in `:root` but missing from `.light` (will inherit dark values in light mode)
34- Tokens defined in `.light` but not in `:root` (orphaned light-only tokens)
35- Tokens in `tailwind.config.ts` colors that reference undefined CSS vars
36
37### 2. CONTRAST COMPLIANCE (WCAG 2.1 AA)
38
39For each semantic token pair, compute the contrast ratio. Use the HSL values from globals.css, convert to hex/RGB, then calculate.
40
41**Required ratios:**
42- **Normal text (< 18px / < 14px bold):** 4.5:1 minimum
43- **Large text (≥ 18px / ≥ 14px bold):** 3:1 minimum
44- **UI components and graphical objects:** 3:1 minimum
45- **Focus indicators:** 3:1 against adjacent colors
46
47**Critical pairs to check:**
48
49| Pair | Background Token | Foreground Token | Context |
50|------|-----------------|------------------|---------|
51| Body text | `--background` | `--foreground` | Main content |
52| Card text | `--card` | `--card-foreground` | Cards |
53| Primary button | `--primary` | `--primary-foreground` | CTAs |
54| Secondary button | `--secondary` | `--secondary-foreground` | Secondary actions |
55| Muted text | `--background` | `--muted-foreground` | Subtle labels |
56| Muted on card | `--card` | `--muted-foreground` | Card subtitles |
57| Destructive | `--destructive` | `--destructive-foreground` | Error states |
58| Success | `--success` | `--success-foreground` | Success states |
59| Popover text | `--popover` | `--popover-foreground` | Dropdowns |
60| Input text | `--input` | `--foreground` | Form fields |
61| Border visibility | `--background` | `--border` | Borders |
62| Focus ring | `--background` | `--ring` | Focus states |
63| Light section text | `--bg-light` | `--text-dark` | Light bands |
64| Light section muted | `--bg-light` | `--text-muted-dark` | Light band subtitles |
65
66**Check both `:root` (dark) and `.light` mode values.**
67
68### 3. COLOR HARMONY & PALETTE COHERENCE
69
70Evaluate the palette as a professional UI designer:
71
72- **Hue consistency:** All warm neutrals should share a similar hue angle (around 24-36 for this palette). Flag any neutral that drifts into cool territory (blue/green hue).
73- **Saturation scale:** Neutrals should have low, consistent saturation (0-15%). Flag any neutral with saturation > 20%.
74- **Lightness ramp:** Background → card → secondary → muted should form a smooth, monotonic lightness ramp. Flag any inversions or large jumps.
75- **Primary vs accent distinction:** `--primary` (gold, for CTAs) must be clearly distinct from `--accent` (subtle interactive tint). If they're too similar, outline button hovers will look like primary buttons.
76- **Destructive vs success:** These should be clearly distinguishable, including for color-blind users (red-green). Check that they differ in lightness or saturation, not just hue.
77
78### 4. 60-30-10 COLOR DISTRIBUTION
79
80Audit the actual usage distribution across key pages:
81
82- **60% (dominant):** `--background` and `--foreground` — the base canvas. Should dominate.
83- **30% (secondary):** `--card`, `--muted`, `--secondary`, `--border` — structural supporting colors.
84- **10% (accent):** `--primary` (gold) — CTAs, active states, highlights. Should be sparingly used for impact.
85
86**Red flags:**
87- Primary/gold used as a background for large sections (overuse kills impact)
88- Too many competing accent colors (primary + destructive + success all visible in one view)
89- Muted-foreground used for main body text (too low contrast, should be foreground)
90- Border color too prominent (draws attention away from content)
91
92### 5. DARK/LIGHT MODE PERCEPTUAL BALANCE
93
94Check that both modes feel equally polished:
95
96- **Dark mode:** Backgrounds should be truly dark (lightness < 12%). Card should be slightly lighter than background. Text should be warm cream, not pure white (pure white on dark = harsh).
97- **Light mode:** Backgrounds should be warm off-white (not pure white). Card can be white. Text should be warm dark, not pure black (pure black on light = harsh).
98- **Primary in both modes:** Gold may need to shift slightly between modes. Too-bright gold on light backgrounds washes out; too-dark gold on dark backgrounds lacks pop.
99- **Border visibility:** Borders should be visible but subtle in both modes. Check that `--border` has sufficient contrast against `--background` in both themes (target 1.5:1+ for decorative borders, 3:1+ for functional borders).
100- **Shadow behavior:** Primary glow shadows should be visible in dark mode and not overwhelming in light mode.
101
102### 6. ACCESSIBILITY BEYOND CONTRAST
103
104- **Color-only information:** Search for UI patterns that convey meaning through color alone (e.g., status dots without labels, color-coded categories without text). Flag these.
105- **Focus visibility:** Verify `--ring` is visible against both `--background` and `--card` in both themes.
106- **Error states:** Verify `--destructive` is distinguishable from `--primary` — users should not confuse error and brand.
107- **Hover/active states:** Check that hover states using `--accent` or `primary/80` maintain contrast with their text.
108- **Chart colors:** Verify the 5 chart colors are distinguishable from each other AND from the background in both themes.
109
110### 7. COMPONENT SPOT-CHECK
111
112Scan a sample of component files for color usage violations:
113
114- Components using hardcoded colors instead of tokens (feed into tailwind-cleanup skill)
115- Components where bg/text token pairs are mismatched (e.g., `bg-primary` with `text-foreground` instead of `text-primary-foreground`)
116- Components using opacity modifiers that drop contrast below WCAG thresholds (e.g., `text-foreground/50` as body text)
117- Gradients that make text unreadable at certain scroll positions
118
119## Fixing Protocol
120
1211. **Token fixes (D1):** Edit `globals.css` `:root` and/or `.light` blocks. Both themes must be updated in tandem.
1222. **Mapping fixes:** If adding a new token, add the Tailwind mapping in `tailwind.config.ts`.
1233. **Never change primary brand color** without explicit user approval — gold (#b58c4c / hsl 36 48% 50%) is the brand identity.
1244. **Contrast fixes:** Prefer adjusting lightness over changing hue. Bump lightness in 3-5% increments until ratio is met.
1255. **Test after fixing:** Verify both dark and light mode in browser after any token change.
126
127## Output Format
128
129```
130## Color Palette Audit
131
132### Palette Summary
133| Token | Dark Mode (HSL) | Dark Hex | Light Mode (HSL) | Light Hex | Parity |
134|-------|----------------|----------|-------------------|-----------|--------|
135
136### Contrast Report
137| Pair | Dark Ratio | Light Ratio | WCAG AA | Status |
138|------|-----------|-------------|---------|--------|
139| bg/fg | 15.2:1 | 12.8:1 | 4.5:1 | PASS |
140| bg/muted-fg | 3.8:1 | 4.2:1 | 4.5:1 | FAIL (dark) |
141
142### Issues Found
1431. [SEVERITY: CRITICAL/HIGH/MEDIUM/LOW] — description
144 - Current: value
145 - Recommended: value
146 - Affected: list of components/pages
147
148### Color Harmony Assessment
149- Hue consistency: [PASS/ADJUST]
150- Saturation scale: [PASS/ADJUST]
151- Lightness ramp: [PASS/ADJUST]
152- 60-30-10 distribution: [PASS/ADJUST]
153- Dark/light perceptual balance: [PASS/ADJUST]
154
155### Recommendations
1561. [Priority fix with specific token change]
1572. ...
158```
159
160## Rules
161
162- Always audit BOTH dark and light mode — never just one.
163- Present the full audit report before making any changes.
164- When computing contrast, use the actual HSL values from globals.css, converted to RGB. Do not estimate.
165- Do not change the primary brand hue (gold ~36°) without user approval.
166- If contrast fails, prefer adjusting lightness of the weaker token rather than changing the stronger one.
167- Flag but do not auto-fix brand-level decisions (e.g., "primary is too close to destructive"). These need user input.
168- This audit complements the tailwind-cleanup skill — color-audit checks the palette itself, tailwind-cleanup checks usage in components.