Use semantic colour tokens

Name the purpose

A palette token describes a pigment; a semantic token describes its job. Keep blue-500 in the palette layer, then map action-background to it. Components should reference the semantic layer. This makes a theme change a deliberate mapping rather than a hunt through individual buttons.

Define states together

For each interactive control, specify default, hover, focus, disabled and error states. Avoid making disabled controls look like editable fields. Pair error color with a short explanation and an icon or label so color is never the only signal.

:root {
  --surface: #0b1020; --text: #f4f7ff;
  --text-muted: #b5bfd5; --action: #a4f4fd;
}
button:focus-visible { outline: 2px solid var(--action); outline-offset: 4px; }

Check the rendered pairing

Measure foreground against its actual background, including overlays and images. For normal text, target WCAG AA contrast of at least 4.5:1; large text uses 3:1 under WCAG’s size definition. A transparent panel can pass over one video frame and fail over another, so use a stable backing for essential copy.

Keep a small specimen

Create a single review view with links, buttons, inputs, alerts and selected tabs. Test light and dark themes there. Include keyboard focus and error states rather than checking only the initial appearance. Update the semantic token mapping when the same issue appears across several components.