UI Contrast Review

Review UI surfaces for theme-driven readability and visibility failures.

Primary Goal

Catch light-mode and dark-mode contrast regressions before they ship.

Prefer system fixes:

• shared tokens
• semantic color variables
• reusable component classes

Avoid one-off per-page color patches unless the issue is intentionally local.

Review Workflow

1. Identify the target surfaces.

• page routes
• reusable components
• empty states
• tables
• dialogs
• badges
• charts
• forms

2. Check both themes.

• light theme
• dark theme
• hover / active / disabled / selected states
• focus rings and keyboard focus visibility

3. Inspect the highest-risk UI pairs.

• body text vs background
• muted text vs card background
• button label vs button fill
• border vs surrounding surface
• placeholder text vs input background
• badge text vs badge fill
• link text vs surrounding paragraph
• chart lines/bars vs canvas background
• toast/alert text vs status fill

4. Look for token drift.

• hard-coded Tailwind colors mixed with semantic theme tokens
• text-muted-foreground on surfaces that are already muted
• border-white/10 or border-black/10 used in the wrong theme
• color combinations that only work in one theme

5. Recommend the smallest durable fix.

• first choice: theme variable / semantic token
• second choice: shared component class
• last choice: local page override

Minimum Contrast Standard

Use WCAG AA as the baseline heuristic:

• normal text: aim for 4.5:1 or better
• large text: aim for 3:1 or better
• UI boundaries and focus indicators: visibly distinct without requiring hover

When exact ratios are not available, make a practical engineering judgment:

• if text is even slightly hard to read in either theme, treat it as a bug
• if borders disappear into the background, treat it as a bug
• if disabled and secondary states become illegible, treat it as a bug

Output Format

For each issue, provide:

• surface
• theme
• failing element
• why it fails
• preferred fix
• file/component reference when available

Use this structure:

Findings
1. [severity] Surface — issue
File: path/to/file.tsx
Theme: light|dark|both
Fix: semantic token or component-level change

If no issues are found, state that explicitly and mention what was checked.

Good Fix Patterns

• replace hard-coded color with semantic token
• raise muted foreground contrast one step
• strengthen border token for light theme separately from dark theme
• give focus rings a dedicated accessible token
• ensure disabled text is still readable, not just low-opacity

Avoid

• only checking dark mode
• only checking screenshots without interaction states
• fixing with arbitrary hex values when a shared token should exist
• shipping “looks okay on my screen” judgments without checking both themes

Notes

When browser tooling is available, review the real rendered UI.

When browser tooling is not available, inspect:

• route components
• shared UI primitives
• Tailwind utility usage
• CSS variables / theme tokens

Start with the shared primitives if the same contrast problem appears in multiple pages.

About this skill

Part of the Synter free skills collection — open-source agent skills for advertising, PPC, and marketing automation.

Want this skill (and 40+ more) running on autopilot against your live ad accounts? Try Synter — AI Agent Media Buyers that connect to Google, Meta, LinkedIn, TikTok, Reddit, Amazon, and 7+ more platforms.

• 🌐 syntermedia.ai
• 📚 All free skills
• 💬 Built by @syntermedia — questions? Open an issue.