Free Claude Code skill

Make your colors look clean and pass contrast

Give this to your AI coding tool and it will choose, check and fix your colors using real numbers. Built from Figma's docs and the official WCAG accessibility standards.

Download SKILL.md

Install it

You don't need GitHub. Pick whichever is easiest.

Claude Code, in one command

Paste this into your terminal on Mac or Linux. It works in all your projects.

mkdir -p ~/.claude/skills/color-contrast && curl -fsSL https://jackprice.ca/skills/color-contrast.md -o ~/.claude/skills/color-contrast/SKILL.md

Any other way

  1. Claude Code by hand: download the file and save it as ~/.claude/skills/color-contrast/SKILL.md. Use .claude/skills/color-contrast/SKILL.md to add it to one project.
  2. Another AI tool: copy the skill and paste it into that tool's rules or custom instructions.
  3. A one-off chat: paste it into your chat, then ask for what you need.

How to use it

Claude Code uses it automatically when you work on colors. To run it yourself, type /color-contrast, or try one of these:

  • "Check my whole site for color contrast problems and fix them."
  • "Build me a clean, modern light and dark color system."
  • "This text on my hero image is hard to read. Fix it."

What's inside

  • Exact WCAG 2.2 ratios, what's exempt and what isn't
  • How to get a clean, modern look without faint text
  • Light and dark color tokens, with every pair calculated
  • Text on images, gradients and transparent layers
  • Buttons, inputs, focus rings, links and charts
  • A step-by-step Figma workflow
  • A contrast checker script and a final review checklist

The full skill

---
name: color-contrast
description: Color contrast and modern, clean color systems for web design. Use when choosing, reviewing or fixing colors, palettes, design tokens, dark mode, text on images or gradients, buttons, borders, focus rings, charts, placeholders, or when text looks washed out, gray or hard to read. Also use for accessibility and WCAG contrast checks, and when building any new UI.
---

# Color Contrast for Modern Web Design

Make interfaces that look clean and modern and that people can actually read. Treat contrast as part of the design from the start, not an audit at the end.

## How to work

Follow this every time you create or change UI colors:

1. **List the pairs.** Find every foreground and background that appear together, in every state and every theme. Include placeholders, hover states, focus rings, icons, input borders, charts and text over images.
2. **Calculate, never estimate.** Run the checker below or use the formula. Do not judge contrast by eye, and do not state a ratio you did not calculate.
3. **Composite first.** Flatten any transparency onto its real background before calculating.
4. **Fix by changing lightness.** Keep the hue, and move the lighter color lighter or the darker color darker until the pair passes.
5. **Fix the token, not the instance.** Change the semantic token so the fix applies everywhere.
6. **Report the numbers.** Show the pair, the ratio, the target and the result.

If a brand color fails, say so plainly and offer the nearest passing shade. Do not lower a threshold to keep a color.

## Required ratios

Based on WCAG 2.2. AA is the default target. Use AAA for long reading and for high-contrast themes.

| What | AA | AAA | Measured between |
|---|---|---|---|
| Normal text | 4.5:1 | 7:1 | Text and its background |
| Large text | 3:1 | 4.5:1 | Text and its background |
| Icons and graphics needed for understanding | 3:1 | | Graphic and adjacent colors |
| UI component boundaries and states | 3:1 | | Component and adjacent colors |
| Focus indicator | 3:1 | 3:1 change between focused and unfocused, with minimum area | Indicator and adjacent colors |

**Never round.** 4.499:1 fails 4.5:1, and 2.999:1 fails 3:1. Always truncate when you report.

**Large text** means at least 24px, or at least 18.66px and bold. WCAG defines it as 18pt, or 14pt bold, and bold varies by font, so use weight 700 or heavier and stay conservative. Thin fonts look fainter than their ratio suggests, so go above the minimum or use a heavier weight.

**Always set both colors.** If you set a text color, also set the background it sits on, and the reverse. Otherwise a user's default colors can break the pair.

### What's exempt, and what isn't

| Exempt | Not exempt |
|---|---|
| Disabled controls that can't be used | Placeholder text |
| Pure decoration | Text shown on hover or focus |
| Text in a logo or brand name | Brand colors in normal text and buttons |
| Text incidental to a photo, like a street sign | Text deliberately placed over an image |
| | Gray logos that only gain contrast on hover |

Disabled is exempt, but keep it recognizable. A control that merely looks disabled while still working must pass.

Characters used as symbols, like an `X` close button or a `>` arrow, count as graphics and need 3:1.

## Calculating contrast

```
Contrast = (L1 + 0.05) / (L2 + 0.05)     L1 = lighter, L2 = darker
L = 0.2126 R + 0.7152 G + 0.0722 B

For each sRGB channel C = value / 255:
  C <= 0.04045  ->  C / 12.92
  otherwise     ->  ((C + 0.055) / 1.055) ^ 2.4
```

The result runs from 1:1 to 21:1. To flatten a translucent color onto its background, do this per channel: `result = alpha * foreground + (1 - alpha) * background`.

Save this as `contrast.mjs`. It needs Node and no packages:

```js
// node contrast.mjs "#52525B" "#FFFFFF"
// node contrast.mjs "#FFFFFF" "#000000" --alpha 0.5 "#FFFFFF"   (text on a 50% black layer over white)
const hex = (h) => {
  let s = h.replace("#", "");
  if (s.length === 3) s = [...s].map((c) => c + c).join("");
  if (!/^[0-9a-fA-F]{6}$/.test(s)) throw new Error(`Bad color: ${h}`);
  return [0, 2, 4].map((i) => parseInt(s.slice(i, i + 2), 16));
};
const lin = (v) => {
  const c = v / 255;
  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
};
const lum = ([r, g, b]) => 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
const ratio = (a, b) => {
  const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
};
const over = (fg, alpha, bg) => fg.map((c, i) => Math.round(alpha * c + (1 - alpha) * bg[i]));

const args = process.argv.slice(2);
const a = args.indexOf("--alpha");
const fg = hex(args[0]);
const bg = a === -1 ? hex(args[1]) : over(hex(args[1]), Number(args[a + 1]), hex(args[a + 2]));
const r = ratio(fg, bg);
const shown = Math.floor(r * 100) / 100;
const mark = (t) => (r >= t ? "pass" : "FAIL");
console.log(`${shown.toFixed(2)}:1`);
console.log(`Normal text  AA 4.5: ${mark(4.5)}   AAA 7: ${mark(7)}`);
console.log(`Large text   AA 3: ${mark(3)}     AAA 4.5: ${mark(4.5)}`);
console.log(`UI, graphics    3: ${mark(3)}`);
```

## What makes it look modern and clean

Good contrast and a clean look work together. Modern interfaces get their calm from restraint, not from faint gray text.

1. **Build hierarchy with a few clear steps.** Use three text levels: primary, secondary and tertiary. Every level must still pass. If you need a fourth, use size or weight.
2. **Use weight and size before color.** A heavier heading in the same color often looks more refined than a colored one.
3. **Use tinted neutrals.** Add a slight hue to your grays, keeping them nearly neutral, so the palette feels designed.
4. **Prefer near-black to pure black for large text areas.** `#18181B` on white is 17.71:1 and feels softer than pure black at 21.00:1. Pure black is allowed, but it's rarely needed.
5. **Keep one accent.** Save saturated color for actions and key states. When everything is colorful, nothing stands out.
6. **Separate surfaces quietly, and controls clearly.** Cards and sections can use subtle fills and hairlines because they're decorative. Anything people must find and operate needs 3:1.
7. **Don't rely on shadows.** A soft shadow doesn't identify a control. If it's the only thing showing the edge of an input, the input needs a real border.
8. **Use real color tokens for text.** Avoid lowering opacity on text. It changes with every background and can silently fail.
9. **Give color room.** Generous spacing and fewer competing colors do more for a premium look than extra effects.
10. **Check squint hierarchy.** Blur or squint at the screen: the headline, then the main action, should still stand out. Then check a grayscale view, which shows whether hierarchy depends on hue alone.

## Reference color tokens

A verified starting point. Adapt the hue, then calculate again. Every pair below has been checked.

```css
:root {
  --bg: #FFFFFF;
  --surface: #F7F7F8;
  --text: #18181B;
  --text-secondary: #52525B;
  --text-tertiary: #65656F;
  --border-subtle: #E4E4E7;     /* decorative only */
  --border-control: #85858F;    /* inputs and controls */
  --accent: #2563EB;
  --accent-hover: #1D4ED8;
  --on-accent: #FFFFFF;
  --success: #15803D;
  --warning: #A16207;
  --danger: #B91C1C;
  --focus: #2563EB;
}

[data-theme="dark"] {
  --bg: #0E0E11;
  --surface: #18181C;
  --text: #F4F4F5;
  --text-secondary: #B4B4BD;
  --text-tertiary: #94949F;
  --border-subtle: #2A2A31;     /* decorative only */
  --border-control: #75757F;    /* inputs and controls */
  --accent: #7DA8FF;
  --accent-hover: #A3C2FF;
  --on-accent: #0B1220;
  --success: #4ADE80;
  --warning: #FACC15;
  --danger: #FCA5A5;
  --focus: #A3C2FF;
}
```

| Pair | Target | Light | Dark |
|---|---|---|---|
| Text on background | 4.5 | 17.71:1 | 17.53:1 |
| Text on surface | 4.5 | 16.54:1 | 16.10:1 |
| Secondary on surface | 4.5 | 7.21:1 | 8.60:1 |
| Tertiary on surface | 4.5 | 5.38:1 | 5.89:1 |
| Accent text on surface | 4.5 | 4.82:1 | 7.51:1 |
| On-accent on accent | 4.5 | 5.16:1 | 7.95:1 |
| On-accent on accent hover | 4.5 | 6.70:1 | 10.44:1 |
| Control border on surface | 3 | 3.41:1 | 3.88:1 |
| Focus on surface | 3 | 4.82:1 | 9.87:1 |
| Success text on surface | 4.5 | 4.68:1 | 10.15:1 |
| Warning text on surface | 4.5 | 4.59:1 | 11.55:1 |
| Danger text on surface | 4.5 | 6.04:1 | 9.32:1 |

Subtle borders score only 1.26:1 in light mode and 1.35:1 in dark mode. That's fine for decoration, and never enough for an input.

Name tokens for their role. `text-secondary` survives a rebrand and `gray-600` doesn't. Components use semantic tokens, and semantic tokens point to raw values.

## Dark mode

- **Design it, don't invert it.** Inverting a palette usually gives harsh text and muddy accents.
- **Avoid pure black backgrounds.** A very dark tinted gray leaves room for elevation, and raised surfaces get lighter.
- **Soften accents.** Colors that work on white are often too dark on a dark background. Use lighter, less saturated versions. In the tokens above, the light accent `#2563EB` scores only 3.72:1 on the dark background.
- **Flip on-accent text when needed.** A light accent usually needs dark text.
- **Go above the minimum for small text.** Mid-gray on dark can pass and still look dim, especially in thin fonts.
- **Test every pair in every theme.** A pair passing in light mode says nothing about dark mode.

Also respect user settings: support `prefers-color-scheme`, consider `prefers-contrast: more`, and keep content working under `forced-colors: active`. A low-contrast theme is only acceptable as an opt-in the user can easily turn off.

## Transparency

Always flatten before calculating, and calculate against the real background.

| Style | Flattened | Ratio on its background |
|---|---|---|
| Black text at 50% on white | `#808080` | 3.94:1 (fails) |
| Black text at 60% on white | `#666666` | 5.74:1 (passes) |
| White text at 50% on `#0E0E11` | `#878788` | 5.37:1 (passes) |
| White text at 50% on `#2563EB` | `#92B1F5` | 2.41:1 (fails) |

The same translucent text can pass on one surface and fail on the next. In glass or blur panels, test against the lightest and darkest content that can scroll behind them.

## Text on images and gradients

Test the **least contrasting area** behind the text. A pass on the average color isn't a pass.

For gradients, check the text against each color along the part it covers, using the worst result.

To make text on photos reliable:

1. Add a dark overlay or gradient scrim.
2. Sample the brightest pixels behind the text, and flatten the scrim over them.
3. Calculate using that result. On a pure white area under a black scrim, white text needs about 54% black to reach 4.5:1: `rgba(0,0,0,.55)` scores 4.74:1, and `rgba(0,0,0,.50)` only 3.94:1.

If the image can change, as with user uploads or carousels, assume the brightest case or place text on a solid panel. Avoid gradient-filled body text. Keep it for short, large headlines, and make every part of the gradient pass.

## Interactive states

- **Default:** Identifiable at rest, without hover. A border, fill or underline must reach 3:1 if it's the only thing identifying the control. A button with clearly readable text inside a tinted fill doesn't automatically need a 3:1 fill, but a primary action should be obvious.
- **Hover:** Can be subtle, as it's a supplement to the pointer. Never reduce contrast. Text on the hover color must still pass.
- **Focus:** Always visible. Never use `outline: none` without a replacement.
- **Selected or checked:** Don't use a color change alone. Add a check, weight, underline or indicator.
- **Disabled:** Exempt, but keep it readable if people need to know what it is.
- **Error:** Use an icon and message as well as red.

### Focus rings

```css
:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}
```

A 2px solid outline around the control is enough area for AAA Focus Appearance if it has a 3:1 change. Measure the ring against what's next to it. On images or changing backgrounds, use two colors so one always shows:

```css
:focus-visible {
  outline: 2px solid #FFFFFF;
  outline-offset: 2px;
  box-shadow: 0 0 0 4px #18181B;
}
```

Ignore shadow and glow when you judge a focus indicator's size. Faint glows often fail.

## Don't rely on color alone

- **Links in text:** Underline them. Without an underline, the link color needs 3:1 against the surrounding text as well as 4.5:1 against the background, which is hard to do. `#2563EB` in `#18181B` text just clears it at 3.42:1, but a color-only link is still easy to miss, so underline it.
- **Forms:** Mark required fields and errors with text or an icon too.
- **Status:** Pair green, amber and red with a label or icon. People need another cue to tell which color they're looking at.
- **Charts:** Keep adjacent colors at 3:1 where possible, or separate them with a gap or border. Add direct labels, patterns or markers so nobody needs a legend matched by color. Check with color blindness simulations.

## Common failures and fixes

Calculated with the formula above. Tailwind names refer to its classic hex values.

| Mistake | Ratio | Fix | Ratio |
|---|---|---|---|
| `#9CA3AF` gray-400 text on white | 2.53:1 | `#6B7280` gray-500 | 4.83:1 |
| `#777777` on white, an easy near miss | 4.47:1 | `#767676` | 4.54:1 |
| White on `#3B82F6` blue-500 button | 3.67:1 | `#2563EB` blue-600 | 5.16:1 |
| White on `#22C55E` green-500 button | 2.27:1 | `#15803D` green-700 | 5.01:1 |
| White on `#F97316` orange-500 button | 2.80:1 | `#C2410C` orange-700 | 5.17:1 |
| Input border `#E5E7EB` on white | 1.23:1 | `#85858F` | 3.65:1 |
| Gray text `#71717A` on `#F4F4F5` card | 4.39:1 | `#65656F` | 5.24:1 |

Also watch for the color passing on the page background but failing on a card or hover row, placeholder text set to a pale gray, and white text on a light brand color.

## Reviewing an existing codebase

Search for the patterns that usually hide failures:

- Text opacity, such as `opacity-50`, `text-black/50`, `text-gray-400`, and `rgba(` in text colors
- `placeholder:` and `::placeholder` styles
- `outline: none`, `outline-none` and `outline: 0`
- `border-gray-100`, `border-gray-200` and similar on inputs
- Text colors set without a background, and the reverse
- `bg-clip-text` and background images behind text
- Hardcoded hex values that skip the tokens

Then check rendered pages too. Static code can't always show which background a component lands on. Where tools are available, run axe or Lighthouse and treat them as a first pass, since they can't reliably judge text over images or gradients.

## Figma workflow

**Check a color**

1. Select the layer and apply a fill or stroke. The selected layer's color is always treated as the foreground.
2. Click its color swatch to open the picker, then click **Check color contrast**.
3. Read the ratio and the AA and AAA results.
4. Use settings to choose **Large text**, **Normal text** or **Graphics** if **Auto** picks the wrong one.
5. An icon next to AA or AAA means it fails. Click it to jump to the nearest passing color, then confirm the result still suits the design.

Figma's help doesn't say how this check handles opacity, gradients or images, so flatten those yourself and calculate them.

**Check for color blindness**

Figma's Color Contrast Checker at figma.com/color-contrast-checker takes two hex codes, shows pass or fail for normal text, large text and UI elements, and previews Protanopia, Deuteranopia, Tritanopia and Achromatopsia.

**Build the token system**

1. In **Variables**, create a **Primitives** collection of raw values, like `gray-900` and `blue-600`.
2. Create a **Semantic** collection whose values point to primitives, like `color/text/primary`, and start with text, background, border and action colors.
3. Add **Light** and **Dark** modes to the semantic collection using **New variable mode**. `color/text/primary` can point to `gray-900` in Light and `gray-100` in Dark.
4. Apply a mode to a frame or page with **Apply variable mode** in the right sidebar, then check contrast in each mode. Multiple modes need a paid Figma plan.
5. Add a **High contrast** mode if you can. Figma suggests modes for high-contrast and color blindness themes.

Point semantic tokens directly at primitives, because long alias chains get hard to maintain. Keep gradients as styles, since variables don't fully support them yet.

## Palette building

- Pick colors by role first: background, surface, text levels, accent, status.
- Figma's color wheel harmonies are a starting point. Monochromatic and analogous schemes feel calm. Complementary, triadic and square schemes feel bolder, so use one dominant color and keep the others as small accents. Harmony doesn't guarantee contrast, so still calculate every pair.
- Build each hue as a lightness scale, then assign semantic tokens to the steps that pass.
- `oklch()` is great for even-looking scales, because lightness behaves predictably. Calculate the final sRGB value anyway, since a color outside the screen's range can shift.
- A wide-gamut color needs an sRGB fallback, and the fallback needs testing too.

## About APCA and WCAG 3

APCA is a newer contrast method being explored for future standards. It can be useful for judging readability, especially on dark backgrounds. It doesn't replace the WCAG 2 ratios for compliance, so meet those first.

## Before you finish

- [ ] Every text, icon, border and focus pair is calculated, in every theme
- [ ] Translucent colors were flattened first
- [ ] Text over images and gradients passes at the worst area
- [ ] Placeholders and hover text pass
- [ ] Inputs and other controls can be identified at rest
- [ ] Keyboard focus is visible everywhere
- [ ] Nothing depends on color alone, including links in text
- [ ] Results are truncated, not rounded up

When reviewing, report results like this:

| Element | Foreground | Background | Ratio | Target | Result | Fix |
|---|---|---|---|---|---|---|
| Card caption | `#9CA3AF` | `#FFFFFF` | 2.53:1 | 4.5 | Fail | Use `#6B7280` (4.83:1) |

## Sources

- WCAG 2.2 Understanding docs for 1.4.1, 1.4.3, 1.4.6, 1.4.11, 2.4.7 and 2.4.13: w3.org/WAI/WCAG22/Understanding
- Figma: color picker help, Color Contrast Checker, design tokens guide, variable modes help and color wheel

Created by Jack Price, jackprice.ca. Free to use and share. This is design guidance, not a legal accessibility audit.

Design guidance, not a legal accessibility audit. Free to use and share.