Check Text and Background Contrast in Claude Code
Follow a repeatable workflow to pair text with its real background, review interface states, and fix contrast problems without flattening the design.
check text and background contrast inside claude code
Contents
- [Start with a contrast inventory](#start-with-a-contrast-inventory)
- [Check combinations, not isolated colors](#check-combinations-not-isolated-colors)
- [Use a practical decision framework](#use-a-practical-decision-framework)
- [Keep contrast checks tied to design choices](#keep-contrast-checks-tied-to-design-choices)
- [Use this in your AI agent](#use-this-in-your-ai-agent)
To check text and background contrast inside Claude Code, inspect every real foreground and background pairing, then review the result at its actual text size and interface state. A color palette alone is not enough because the same text color can be clear on one surface and weak on another.
Start with a contrast inventory
Ask Claude Code to find text, icons, controls, borders, and focus indicators together with the background behind them. Record the component, foreground color, background color, text size or weight, state, and intended role. Include nested surfaces such as cards, menus, inputs, code blocks, banners, and dialogs.
Use a table like this:
| Element | Foreground | Background | State | Role | Action |
|---|---|---|---|---|---|
| Body copy | hex | canvas | default | primary text | keep or adjust |
| Helper text | hex | input | default | supporting text | verify |
| Link | hex | surface | hover | interactive | verify |
| Focus ring | hex | control | focus | keyboard focus | strengthen |
Do not combine all muted text into one result. A caption, placeholder, disabled label, and secondary paragraph may have different expectations and different backgrounds.
The examples below include a Claude Code page, Notion Developer Platform, and Exa MCP Server. Compare how dark surfaces, light copy, and accent colors are arranged, but treat the cards as references rather than evidence about your own contrast results. The supplied observed colors include green values such as #496c10, #2c7a4a, and #2a966f, alongside darker surfaces such as #15502e and #233f2a.
Captured pages
Colors
#496c10#15502e#14532d#233f2a#254f1a#1e6f30#295631#556659#4a5a4a#2c7a4a#2a966f#799c92
Check combinations, not isolated colors
For each pairing, ask four questions:
- Is the text easy to distinguish from the surface at normal size?
- Does it remain clear on hover, focus, selected, disabled, and error states?
- Is the meaning available through text, shape, icon, or position as well as color?
- Does the same foreground color appear on a different background elsewhere?
Near-black surfaces can make small changes in lightness hard to notice. If several panels use almost the same background, text may technically be visible while the page still feels flat. A bright accent can be readable but too dominant for long passages.
Borders and icons need their own review. A divider that disappears can make a table or form difficult to scan. A low-contrast icon can make an action ambiguous even when its label is readable. Focus indicators deserve special attention because they must stand out against more than one possible background.
Use a practical decision framework
Classify each finding as one of three types:
- Readable but inconsistent: keep the value or create a semantic alias so the role is clear.
- Hard to read: adjust the foreground or background, then recheck every component using that token.
- Technically visible but visually weak: strengthen the hierarchy, spacing, weight, border, or supporting label instead of changing color alone.
Prefer the smallest change that fixes the problem. If secondary text is weak across many surfaces, a semantic token change may be appropriate. If it is weak only inside a tinted banner, create a banner-specific pairing. Do not brighten every muted color until the interface loses hierarchy.
For a quick pass, ask Claude Code:
> Find every meaningful text, icon, border, and focus-indicator color in the interface. For each usage, identify the actual background behind it, component, state, text size or weight when available, and semantic role. Group repeated pairings, flag likely weak combinations and inconsistent reuse, and return a prioritized fix list. Do not change code yet.
Then review the highest-risk items in the browser. Check normal copy, small labels, placeholders, links, controls, focus rings, and status messages. Re-run the inventory after changes so you can catch a fix that improved one pairing but damaged another.
Keep contrast checks tied to design choices
Contrast is one part of a usable interface. Preserve a clear type scale, enough spacing, recognizable control shapes, and visible state changes. A page can pass a numeric check and still be difficult to scan if every surface and label has the same emphasis.
Fudge lets you help inspect observed color roles and contrast from a captured page. Use those observations to compare implemented pairings with a concrete visual reference before editing tokens.
Use this in your AI agent
> Check text and background contrast in this codebase without editing files. Trace each text, icon, border, link, control, and focus-indicator color to the actual background behind it, including nested surfaces and interaction states. Group repeated foreground/background pairings, identify the component and semantic role, flag the highest-risk combinations, and return a prioritized table with the smallest recommended fixes. Preserve hierarchy and do not replace every muted color with the brightest available value. > > Install Fudge for your AI agent to compare the rendered page and its observed color pairings with design references.
Which contrast checks should I prioritize first?
Start with content that carries the most meaning: body text, navigation labels, form labels, buttons, links, error messages, and keyboard focus indicators. Then check helper text, placeholders, table metadata, icons, dividers, and disabled states.
Prioritize pairings that appear often, sit on dark surfaces, use small text, or change during interaction. A weak focus ring can affect every keyboard user even if it appears only briefly. A weak error message can hide the action needed to recover. A faint divider may make dense tables or forms harder to scan.
Review states in this order: default, hover, focus, selected, disabled, error, and success. For each one, confirm that the visual difference is clear and that the meaning is not carried by color alone.
Ask Claude Code to group identical pairings and rank them by how many components use them. Fixing a shared token can help many screens, but inspect exceptions before changing it. A token used on both a neutral card and a tinted status banner may need to split into two semantic roles.
How can I fix weak contrast without making the design harsh?
First decide whether the problem is color or hierarchy. If body text is genuinely difficult to read, adjust its foreground or surface. If a divider is hard to notice, a small increase in border strength or spacing may work better than a bright line. If every label is equally bright, reduce emphasis in low-priority areas while keeping primary actions clear.
Use small, targeted changes. Lighten supporting text slightly, darken a surface behind dense content, or increase the weight of a short label. Avoid changing a shared accent until you know where it appears, because the same value may serve links, buttons, illustrations, and status messages.
After each change, compare the full state set on the affected screens. Ask Claude Code to list all usages of the token and identify any pairing that changed indirectly. Keep a before-and-after note for the role, affected components, and reason. This creates a useful record and prevents future cleanup from undoing a deliberate contrast decision.