Theme contrast validation
Browser-free WCAG AA contrast checks for DesignSystemTheme color pairings in CI.
Theme contrast validation
The design system owns which color roles are meant to sit on which (for example primary text on the base surface, inverse text on brand fills). Host sites own their light and dark theme objects. Use validateThemeContrast from the package root to prove a theme's intended pairings meet WCAG AA before merge — no browser, DOM, or CSS APIs required.
This catches inaccessible palette configurations. It does not catch integration bugs where a page uses a color outside the theme.
API
Import only from the public package root:
import {
baseTheme,
contrastPairings,
contrastRatio,
validateThemeContrast,
type ContrastPairing,
type DesignSystemTheme,
type PairingResult,
type ThemeContrastReport,
} from "@kigo-digital/design-system";validateThemeContrast(theme, options?)
| Argument | Type | Notes |
|---|---|---|
theme | DesignSystemTheme | Full theme object (typically a host light/dark theme or a partner override of baseTheme). |
options.pairings | ContrastPairing[] | Optional. Replaces the default intended-pairing manifest. |
options.extraPairings | ContrastPairing[] | Optional. Appended to the default (or replaced) manifest. |
Returns a ThemeContrastReport:
interface ThemeContrastReport {
pass: boolean;
results: PairingResult[];
}
interface PairingResult {
pairing: ContrastPairing;
foregroundColor: string;
backgroundColor: string;
ratio: number | null;
required: number;
pass: boolean;
message?: string;
}passistrueonly when every evaluated pairing passes.- Each result includes the resolved colors, computed ratio, required threshold, and a diagnostic
messagewhen a color is unparseable or the pairing fails. - Unparseable color strings fail that pairing with a diagnostic; remaining pairings still run and nothing throws.
contrastRatio(foreground, background)
Pure WCAG 2.x contrast ratio for two color strings. Useful for ad-hoc checks outside the default manifest.
contrastPairings
The default intended-pairing manifest: an array of ContrastPairing values the design system defines. Role paths resolve within theme.colors (for example text.primary reads theme.colors.text.primary).
type ContrastLevel = "AA-text" | "AA-large" | "AA-ui"; // 4.5:1 | 3.0:1 | 3.0:1
interface ContrastPairing {
id: string;
foreground: string;
background: string;
/** Opaque underlay when `background` is translucent (e.g. surface.chip-dark over surface.base). */
backgroundBase?: string;
level: ContrastLevel;
description?: string;
}Default pairings (v1)
| Foreground | Background | Level |
|---|---|---|
text.primary | surface.base, surface.raised, surface.sunken, surface.partner-tint | AA-text (4.5:1) |
text.secondary | surface.base, surface.raised, surface.sunken | AA-text |
text.muted | surface.base | AA-text |
text.inverse | surface.inverse, brand.DEFAULT, brand.emphasis | AA-text |
text.inverse | surface.chip-dark (composited over surface.base) | AA-text |
partner.on-primary | partner.primary, partner.primary-emphasis | AA-text |
partner.on-accent | partner.accent | AA-text |
partner.primary | surface.partner-tint | AA-ui (3.0:1, non-text icon) |
The shipped baseTheme is expected to pass every pairing in this list. Partner and host themes should re-check after any color override.
Feedback roles excluded (v1)
feedback.* roles are not in the default manifest. They are used for icons and borders over soft tints, not as body text directly on base surfaces, and their intended text pairings are not yet defined. That is a scoping choice, not a blanket contrast failure — on white surface.base, the info color meets AA-text and the danger color meets AA-ui (success and warning do not). When text-on-feedback pairings are formalized, they can be added via options.extraPairings or a future default-manifest revision.
Merge-gate script (host light + dark)
Copy this Node script into a host site (docs site first). Point it at your own theme modules, run it in CI, and exit non-zero when any pairing fails.
// scripts/check-theme-contrast.ts
import {
validateThemeContrast,
type DesignSystemTheme,
} from "@kigo-digital/design-system";
// Replace with the host site's real theme modules. Hosts own light/dark values.
import { lightTheme } from "../src/theme/light";
import { darkTheme } from "../src/theme/dark";
const themes: { name: string; theme: DesignSystemTheme }[] = [
{ name: "light", theme: lightTheme },
{ name: "dark", theme: darkTheme },
];
let failed = false;
for (const { name, theme } of themes) {
const report = validateThemeContrast(theme);
if (report.pass) {
console.log(`✓ ${name}: all pairings pass WCAG AA`);
continue;
}
failed = true;
console.error(`✗ ${name}: contrast failures`);
for (const result of report.results.filter((r) => !r.pass)) {
const { pairing, foregroundColor, backgroundColor, ratio, required, message } =
result;
console.error(
` - ${pairing.id}: ${pairing.foreground} (${foregroundColor}) on ${pairing.background} (${backgroundColor})` +
(ratio == null
? ` — ${message ?? "unparseable color"}`
: ` — ratio ${ratio.toFixed(2)} < required ${required}`),
);
}
}
if (failed) {
process.exit(1);
}package.json
{
"scripts": {
"check:theme-contrast": "bun run scripts/check-theme-contrast.ts"
}
}CI (GitHub Actions sketch)
- name: Theme contrast (WCAG AA)
run: bun run check:theme-contrastFail the job on non-zero exit so inaccessible palettes cannot merge.
Partner / custom pairings
After overriding partner colors, validate the full theme (default pairings cover partner.on-primary / partner.on-accent and Tag surfaces). To add host-only roles:
import {
validateThemeContrast,
type ContrastPairing,
type DesignSystemTheme,
} from "@kigo-digital/design-system";
const hostExtras: ContrastPairing[] = [
{
id: "host.hero-title",
foreground: "text.primary",
background: "surface.raised",
level: "AA-text",
},
];
export function assertThemeContrast(theme: DesignSystemTheme) {
const report = validateThemeContrast(theme, { extraPairings: hostExtras });
if (!report.pass) {
throw new Error(
report.results
.filter((r) => !r.pass)
.map((r) => r.message ?? r.pairing.id)
.join("\n"),
);
}
}Related
- Partner theming — constructing a complete
DesignSystemTheme - Theme reference — every theme key and Augeo default