Contrast and accessibility

UIX checks every text color against the background it sits on, in every theme, and fixes the pairs that fail before you see them.

What gets checked

Every text pair your system defines: body text on the page and on cards, secondary text, hints, links, error messages, and the labels on brand and danger buttons. Each pair is checked in every theme against WCAG 2.2 AA, which asks for at least 4.5:1 for text.

How fixes work

When a pair fails, UIX moves the token to the nearest shade on the same scale that passes. If no shade works with white or black text, it flips the label instead, so you get dark text on a light fill.

Your brand color stays exact wherever it can. If white or near-black text passes on it, it is the button color itself. If not, the button uses the nearest step that passes.

For example, teal #14B8A6 is too light for white text. UIX keeps the teal button and gives it near-black text. text/on-brand on bg/brand comes out at 7.9:1.

The contrast receipt

You don’t have to take this on trust. When your AI agent calls create_design_system or get_design_system on the MCP server, the answer includes a receipt:

• standard: WCAG 2.2 AA, 4.5:1 for text
• pairsChecked and passing: how many pairs, and how many pass
• lowest: the weakest pair and its ratio
• fixed: the tokens UIX changed, from which shade to which

AGENTS.md has a table of safe pairs, so the agent knows which text goes on which background. From the teal system above, light theme:

AA or AAA

/generate asks “How strict should contrast be?”. AA, the usual standard, means text at least 4.5:1. AAA means at least 7:1, for health, government or older readers. With AAA, some colors get darker.

In Figma

• Color work in the plugin shows WCAG contrast, APCA and a color-blind preview. All free.
• Check my file runs an accessibility check. Free shows the results and gives 3 one-click fixes per scan; Pro has no limit.
• The HTML accessibility report (WCAG 2.2 AA) is Pro.

What contrast doesn’t cover

Color is one part of accessibility. These rules from the AI Pack are worth following by hand too:

• Never remove focus outlines. The focus ring uses border/focus.
• Give every icon-only button an aria-label.
• Make hit targets at least 40px, or 44px on touch screens.
• Don’t use opacity for disabled or secondary text. Use text/disabled and text/secondary.