| name | color-review |
| description | Review color usage in a design for semantic consistency, token adherence, and accessibility. Works from attached images, specs, or Figma files. |
| version | 1 |
| user-invocable | true |
/color-review - Semantic Color Review
Evaluate how color is used in a design. Not just "is it the right shade of blue," but "does every color mean something, and does that meaning hold up everywhere?"
Quick Start
/color-review → Guided questions, then attach or describe the design
/color-review [attach image] → Analyze color usage from a screenshot or export
/color-review [paste spec or describe flow] → Review color decisions in a spec
Output: Review saved to outputs/critique-notes/[feature]-color-review-[date].md
Time: 10–15 minutes
Dependencies: None. Works from images, specs, or descriptions. Figma MCP helps if connected.
Context Routing (Internal)
Before reviewing, check:
| Source | Files/Folders | What to extract |
|---|
| Color tokens | context-library/design-system/principles.md → Color section | Primary, secondary, semantic colors, and any color rules |
| Foundations | context-library/foundations/semantic-color.md | The principle of semantic color and common anti-patterns |
| Component UX | context-library/design-system/component-ux/ | Color rules tied to specific components (e.g., destructive button uses error red) |
| Accessibility | context-library/design-system/principles.md → Accessibility section | Contrast ratios and color independence requirements |
| Storybook | context-library/design-system/storybook.md | Token naming conventions if documented |
Guided Questions
Ask these if the designer hasn't given context:
- "What am I looking at? (Component, page, flow, full screen)"
- "Are you using design tokens, or working from raw hex values?"
- "Is there a dark mode or alternate theme to consider?"
- "Any colors you're unsure about or want a second opinion on?"
What Semantic Color Means
Read context-library/foundations/semantic-color.md for the full reference. The short version:
Semantic color means every color in the UI communicates something specific and does so consistently. Red always means error or danger. Green always means success or confirmation. Blue always means interactive or informational. Colors aren't decorative by default; they carry meaning.
When a color is used without semantic intent (purely for aesthetics, branding flair, or visual variety), it creates noise. Users learn your color language fast, and inconsistency teaches them the wrong things.
Review Framework
1. Color Inventory
List every distinct color visible in the design. For each:
- What role does it play? (Brand, semantic, decorative, interactive, neutral/structural)
- Is it a defined token from
principles.md, or a one-off value?
- Does it appear in more than one place? If so, is the meaning consistent?
Flag any colors that don't map to the team's defined palette or token system.
2. Semantic Consistency
For each semantic color used (success, warning, error, info):
- Is it used only for its semantic purpose?
- Is the same semantic meaning always represented by the same color?
- Are there places where a semantic color is used decoratively? (e.g., green used as a brand accent when it also means "success" elsewhere)
Common violations:
- Red used for both errors and "hot/trending" indicators
- Green used for both success states and brand accent
- Blue used for both links and info banners (sometimes fine, but worth checking)
- Yellow/amber used for both warnings and highlights/emphasis
3. Color Independence
Does the design rely on color alone to communicate state or meaning?
Check for:
- Error states indicated only by red (no icon, no text, no border change)
- Status badges differentiated only by color (no label, no icon)
- Required fields marked only with a colored asterisk
- Active/selected states indicated only by color change
For every instance: what secondary indicator exists? If none, flag it.
4. Contrast and Legibility
- Text on colored backgrounds: does it meet 4.5:1 for normal text, 3:1 for large text?
- UI components (icons, borders, focus rings) on their backgrounds: 3:1 minimum?
- Any text on images or gradients where contrast varies?
- Light text on light backgrounds or dark text on dark backgrounds?
Don't try to calculate exact ratios from screenshots. Flag anything that looks like it might fail, and recommend the designer verify with a contrast checker.
5. Token Adherence
If the team's principles.md defines a color system:
- Are all colors in the design traceable to a defined token?
- Are any raw hex values being used instead of tokens?
- Are any token values being used for the wrong purpose (e.g., using the error token for a decorative border)?
If principles.md color section isn't filled out yet, note this as a gap and suggest the designer define their tokens.
6. Dark Mode and Theme Readiness
If the product supports or will support dark mode:
- Are colors defined as semantic roles (success, error) rather than absolute values (#FF0000)?
- Would the current color choices invert well, or are there hardcoded values that would break?
- Are any colors chosen specifically for a light background that wouldn't work on dark?
If dark mode isn't a consideration, skip this section.
7. Brand vs. Semantic Tension
This is the most common problem. The brand's primary color often collides with a semantic color:
- Brand blue and "interactive/link" blue are the same. Fine in most cases, but flag if the brand blue appears on non-interactive elements.
- Brand green and "success" green are the same. Problematic if green appears decoratively.
- Brand red and "error" red overlap. Rarely a good idea.
Note any collisions and suggest how to resolve them (typically by shifting the brand use slightly or adding a secondary differentiator).
Output Structure
# Color Review: [Screen or Feature Name]
**Date:** [date]
**Source:** [image / spec / Figma link / description]
**Token system defined:** [yes / partial / no — based on principles.md]
---
## Summary
[2–3 sentences: overall color health. Is the color system working semantically, or is it decorative?]
---
## Color Inventory
| Color | Role | Token match | Used consistently | Notes |
|-------|------|-------------|-------------------|-------|
| [hex or description] | [semantic / brand / decorative / interactive / neutral] | [yes / no / N/A] | [yes / no] | |
---
## Findings
| # | Issue | Location | Recommendation | Ties to |
|---|-------|----------|----------------|---------|
| 1 | [what's happening] | [where] | [specific fix] | [principle, token, or WCAG criterion] |
---
## Color Independence Check
[List every place color is the only differentiator. For each, note whether a secondary indicator exists.]
---
## What's Working Well
[Specific color decisions to preserve.]
---
## Gaps
[Missing token definitions, undocumented colors, dark mode considerations.]
---
## Suggested Next Steps
[1–3 actions. e.g., "Define your semantic color tokens in principles.md," "Run /accessibility-review for full contrast audit."]
Quality Check Before Saving
