Augeo AI Docs
Augeo Design SystemTheming

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?)

ArgumentTypeNotes
themeDesignSystemThemeFull theme object (typically a host light/dark theme or a partner override of baseTheme).
options.pairingsContrastPairing[]Optional. Replaces the default intended-pairing manifest.
options.extraPairingsContrastPairing[]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;
}
  • pass is true only when every evaluated pairing passes.
  • Each result includes the resolved colors, computed ratio, required threshold, and a diagnostic message when 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)

ForegroundBackgroundLevel
text.primarysurface.base, surface.raised, surface.sunken, surface.partner-tintAA-text (4.5:1)
text.secondarysurface.base, surface.raised, surface.sunkenAA-text
text.mutedsurface.baseAA-text
text.inversesurface.inverse, brand.DEFAULT, brand.emphasisAA-text
text.inversesurface.chip-dark (composited over surface.base)AA-text
partner.on-primarypartner.primary, partner.primary-emphasisAA-text
partner.on-accentpartner.accentAA-text
partner.primarysurface.partner-tintAA-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-contrast

Fail 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"),
    );
  }
}