Using colour

In Syntara you pick colour by role, never by hex. A role names a job, such as text.subtle or action.primary.bg. The theme engine resolves every role for each brand in light and dark. It guarantees contrast only for the pairs listed on this page. Everything else is up to you, and this page shows how to get it right.

Three rules cover most of it:

1. Use a role for its job. Why: the same role gets a different hex in every brand and scheme, and only roles are checked.
2. Put text only on backgrounds it’s checked against. Why: a pair that isn’t listed can pass in one brand and fail in the next.
3. Never say something with colour alone. Why: many people can’t tell some colours apart, and screen readers don’t read colour.

For every hex in every brand, see Colors. For how themes are built, see Theming.

The roles by job

The swatches below are live. They read the CSS variables of the brand you pick, in the site’s current scheme (switch light and dark in the header). The hex beside each one is the engine’s output for that brand, generated when this page was built.

Surfaces

Surfaces stack. The page is surface.canvas. Content sits on surface.default, and cards sit on surface.raised. Don’t skip a step: depth reads from the order. surface.sunken goes the other way, an inset well inside a card or panel.

• Use surface.selected for the one chosen thing in a list, not for decoration. Why: people read it as “this one”.
• surface.inverse flips against the page (a tooltip). Only text.inverse is checked on it.

Text

Most text is text.default or text.subtle. Both are checked on every surface except surface.inverse.

• text.brand is for links and a word of emphasis. It isn’t checked on surface.selected, so don’t use it in a selected row.
• text.disabled is only for disabled controls. WCAG exempts inactive controls from contrast, so the engine doesn’t check it and it sits well below 4.5:1. Never use it for text people need to read, like a hint or a placeholder.

Action

action.primary.* is the brand’s solid button. action.secondary.* is its quiet, tinted sibling. The hover and pressed fills are checked with the same label, so states never lose contrast.

Accent

The accent is a second brand colour. Use it for highlights, not actions. accent.text is checked only on surface.default and accent.subtle.

Borders

• border.subtle is decorative: card edges, dividers, chart grids. It needs no contrast, so never let it be the only thing that shows where something is.
• border.default edges floating layers and secondary controls.
• border.strong marks boundaries people must find, such as input edges. It reaches 3:1 against surface.canvas and surface.default.

Focus ring

focus.ring is the 2px keyboard focus outline, with a soft halo around it. It reaches 3:1 against canvas, default and raised surfaces. Never remove it or recolour it.

Feedback

Each tone (success, warning, danger, info) has the same five roles. The jobs are the same for every tone, so they’re listed once.

Safe pairs

These tables are generated from contrast-pairs.json, the list the engine checks for every brand. If a pair isn’t here, it isn’t checked.

ratio

Guaranteed for every brand the engine generates. The number is the lowest ratio measured on this site: 6 brands in light and dark, 12 themes. Hover it to see where.

—Not guaranteed

Not guaranteed. Don’t use it, even if it looks fine in your brand today.

Labels on fills work differently: each label is checked only on its own fill.

Brand colour, sparingly

• One primary action per view. Why: the primary fill says “do this next”. Two of them cancel out.
• Use text.brand for links and emphasis, not paragraphs. Why: long runs of coloured text are harder to read and dilute the brand.
• Keep surfaces neutral. Don’t flood a card or a page section with the brand fill. Why: brand works as a signal. A brand-filled panel also hides the primary button inside it.
• The glow is for dark mode and one hero element. The feature card and the current page in the sidebar are the only glowing things (ADR-013). Why: on a pale page a coloured halo reads as a smudge, and two glows compete.

Status colours

• Feedback colours are for state only: saved, due, failed, scheduled. Why: if green also means “brand”, success stops meaning anything.
• Always add an icon or a word. Never use colour alone. Why: people who can’t tell red from green, and screen readers, still get the message.
• Use the pair that matches the component:

Inline status text isn’t checked on surface.canvas or surface.raised. On a card, put it in a soft badge or a sunken well instead.

Charts

• Series use --syntara-chart-1 to --syntara-chart-4 in that order. Never reorder them by rank or value. Why: a category keeps its colour across charts and filters, so people don’t have to re-learn the legend.
• Series 1 follows the brand hue when the brand has one. The engine solves the others per brand, so neighbours stay apart for protan, deutan and tritan colour blindness (ADR-016).
• Text never goes in a series colour. Why: series promise 3:1, enough for bars and lines but not for text. The lowest on this site is 3.02:1 (Qamar light, series 1 on surface.raised).
• Grid lines use --syntara-chart-grid (border.subtle, decorative). Axis labels use --syntara-chart-axis (text.subtle, checked for text).

Glass, gradients and tints

• On glass, use only text.default and text.subtle. The engine solves the glass opacity per brand (80–83% on this site) so those two reach 4.5:1 over any backdrop. Any other text colour goes on an opaque role, such as surface.selected for a highlighted row.
• Never put a gradient or overlay behind a label on a solid fill. Why: the solver tunes some fills to exactly 4.5:1 with their label. Any tint can push them below it.
• Hover tints mix text.default at 6% over the surface: color-mix(in oklab, var(--syntara-color-text-default) 6%, transparent). Why: it darkens in light mode and lightens in dark mode, in every brand, without a new colour.
• The feature card’s gradient is capped and proven. It uses 6% of the brand in light and 30% in dark, fading to plain surface.raised by 70% of its radius. A test samples every pixel of it for text contrast in every tenant: pnpm --filter @syntara/react exec vitest run test/card.test.tsx.

Fields and borders

Fields use a soft outline that still meets WCAG (ADR-017). The fill sits between surface.default and surface.sunken, so the edge sits between two close tones and looks quieter. The edge itself still reaches 3:1 against the surface outside the field.

• In light mode the edge is border.strong.
• In dark mode it mixes 80% border.strong into border.default. Dark has more headroom, so it steps back a little.
• On hover the edge gets stronger; on focus the 2px ring and halo take over.

Why not the 1.5:1 hairline many products use? It fails WCAG 1.4.11, and people with low vision can’t find the field.

Do and don’t

Each pair is live, in the brand you pick. The mistakes that would fail contrast are shown as pictures, so this page never ships a failing pair.

Checking your own pairs

If you need a pair that isn’t listed, measure it for every brand you ship, in both schemes:

import { contrastRatio, generateTheme } from '@syntara/theme-engine';

const theme = generateTheme(brand);
for (const scheme of ['light', 'dark'] as const) {
  const { roles } = theme.schemes[scheme];
  const ratio = contrastRatio(roles['text.brand'].hex, roles['surface.selected'].hex);
  console.log(scheme, ratio >= 4.5 ? 'passes' : 'fails', ratio);
}

That covers the brands you have today, not the next one. If the pair should always work, ask for it to be added to packages/theme-engine/src/contrast-pairs.json. Then the solver fixes it for every brand, and the fuzz test covers it:

pnpm test:themes

The fuzz generates random brands in light and dark and fails if any listed pair drops below its minimum. The latest results are on Accessibility.