diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ac5f5014..b408cf78 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -72,6 +72,8 @@ jobs:
       - run: npm run security:scan
       - name: No string-built SQL (parameterized-query guard)
         run: npm run sql:scan
+      - name: CSS contract (contrast and theming guards)
+        run: npm run css:scan
 
   test-core:
     name: test-core
diff --git a/package.json b/package.json
index b10f4e81..ad059b32 100644
--- a/package.json
+++ b/package.json
@@ -15,6 +15,7 @@
     "lint": "turbo lint",
     "typecheck": "turbo typecheck",
     "security:scan": "node --import tsx scripts/security-surface-scan.ts",
+    "css:scan": "node --import tsx scripts/css-contract-scan.ts",
     "sql:scan": "bash scripts/check-no-string-sql.sh",
     "check": "bash scripts/check.sh",
     "db:migrate": "npm run db:migrate --workspace=@rayhealth/core",
diff --git a/packages/web/src/design-system.test.ts b/packages/web/src/design-system.test.ts
index 613143e0..db5ce359 100644
--- a/packages/web/src/design-system.test.ts
+++ b/packages/web/src/design-system.test.ts
@@ -1,27 +1,68 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
+import {
+  AA_NON_TEXT,
+  AA_TEXT,
+  AGENCY_THEME_VARIABLES,
+  composite,
+  contrastRatio,
+  parseCssColor,
+  type Rgb,
+} from '@rayhealth/core/domain/theme-resolver.js';
 
 const srcDirectory = resolve(process.cwd(), 'src');
 const colorLiteralPattern = /#[\da-f]{3,4}\b|#[\da-f]{6}(?:[\da-f]{2})?\b/gi;
+const css = readFileSync(join(srcDirectory, 'index.css'), 'utf8');
 
-function tokenHex(css: string, token: string): string {
-  const value = css.match(new RegExp(`${token}:\\s*(#[\\da-f]{6})`, 'i'))?.[1];
-  if (!value) throw new Error(`Missing hex value for ${token}`);
-  return value;
-}
+/**
+ * The `:root` declarations, as a raw name -> value map.
+ *
+ * Comments are stripped first: token names appear inside the explanatory
+ * comments in index.css, and a naive scan reads those as declarations and
+ * silently overwrites the real values with prose.
+ */
+const cssWithoutComments = css.replace(/\/\*[\s\S]*?\*\//g, '');
+const tokens: Record<string, string> = Object.fromEntries(
+  [...(/:root\s*\{[\s\S]*?\n\}/.exec(cssWithoutComments)?.[0] ?? '').matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)]
+    .map((match) => [match[1], match[2].trim()])
+);
 
-function relativeLuminance(hex: string): number {
-  const channels = hex.match(/[\da-f]{2}/gi)?.map((channel) => parseInt(channel, 16) / 255) ?? [];
-  const linear = channels.map((channel) =>
-    channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4
-  );
-  return (0.2126 * linear[0]) + (0.7152 * linear[1]) + (0.0722 * linear[2]);
-}
+const WHITE: Rgb = { r: 255, g: 255, b: 255 };
+
+/**
+ * Resolve a token to a concrete color, following `var()` indirection and
+ * flattening any alpha over `backdrop`.
+ *
+ * Compositing is the point: several tokens are 8-25% tints, and their real
+ * contrast is the contrast of the composited result. Scoring the tint color
+ * itself , which is what a naive check does , reports a number the user never
+ * actually sees.
+ */
+function colorOf(token: string, backdrop: Rgb = WHITE, depth = 0): Rgb {
+  const raw = tokens[token];
+  if (!raw) throw new Error(`token ${token} is not defined in :root`);
+  if (depth > 5) throw new Error(`token ${token} has a circular definition`);
+
+  const indirect = /^var\(\s*(--[\w-]+)\s*\)$/.exec(raw);
+  if (indirect) return colorOf(indirect[1], backdrop, depth + 1);
+
+  // Translucent values MUST be matched before parseCssColor, which drops the
+  // alpha channel. Scoring rgba(16, 116, 128, 0.08) as if it were solid teal
+  // reports the contrast of a color nobody ever sees.
+  const rgba = /^rgba\(\s*(\d+),\s*(\d+),\s*(\d+),\s*([\d.]+)\s*\)$/.exec(raw);
+  if (rgba) {
+    return composite(
+      { r: Number(rgba[1]), g: Number(rgba[2]), b: Number(rgba[3]) },
+      Number(rgba[4]),
+      backdrop
+    );
+  }
 
-function contrastRatio(first: string, second: string): number {
-  const [lighter, darker] = [relativeLuminance(first), relativeLuminance(second)].sort((a, b) => b - a);
-  return (lighter + 0.05) / (darker + 0.05);
+  const direct = parseCssColor(raw);
+  if (direct) return direct;
+
+  throw new Error(`token ${token} has an unparseable value: ${raw}`);
 }
 
 function sourceFiles(directory: string): string[] {
@@ -42,8 +83,6 @@ function sourceFiles(directory: string): string[] {
 
 describe('RayHealth visual system', () => {
   it('defines one bold, accessible brand contract for every surface', () => {
-    const css = readFileSync(join(srcDirectory, 'index.css'), 'utf8');
-
     expect(css).toContain('--color-on-brand:');
     expect(css).toContain('--color-text-on-dark:');
     expect(css).toContain('--color-surface-elevated:');
@@ -64,21 +103,83 @@ describe('RayHealth visual system', () => {
     expect(violations).toEqual([]);
   });
 
-  it('keeps white labels WCAG AA-safe on every bold action color', () => {
-    const css = readFileSync(join(srcDirectory, 'index.css'), 'utf8');
-    const onBrand = tokenHex(css, '--color-on-brand');
-    const actionTokens = [
-      '--color-primary',
-      '--color-primary-dark',
-      '--color-accent',
-      '--color-accent-dark',
-      '--color-success',
-      '--color-danger',
-      '--color-warning',
-    ];
-
-    for (const token of actionTokens) {
-      expect(contrastRatio(onBrand, tokenHex(css, token)), token).toBeGreaterThanOrEqual(4.5);
+  it('gives every resolver-managed variable a static default', () => {
+    // Without a default, an agency with no theme configured would get nothing
+    // at all for that variable. scripts/css-contract-scan.ts enforces the
+    // reverse direction too.
+    for (const name of AGENCY_THEME_VARIABLES) {
+      expect(tokens[name], `${name} missing from :root`).toBeTruthy();
     }
   });
+
+  /**
+   * Every pair below is a real pairing somewhere in index.css or a feature
+   * page. The old version of this suite only checked white-against-token, which
+   * is why `.btn-ghost` , brand-colored text on a brand-colored surface , went
+   * undetected: nothing here knew which foreground met which background.
+   */
+  describe.each([
+    // Labels on a brand-filled surface (.btn-primary, badges, avatars, and
+    // every stop of --gradient-brand).
+    ['--color-on-brand', '--color-primary', WHITE, AA_TEXT],
+    ['--color-on-brand', '--color-primary-dark', WHITE, AA_TEXT],
+    ['--color-on-brand', '--color-accent', WHITE, AA_TEXT],
+    ['--color-on-brand', '--color-success', WHITE, AA_TEXT],
+    ['--color-on-brand', '--color-danger', WHITE, AA_TEXT],
+    ['--color-on-brand', '--color-warning', WHITE, AA_TEXT],
+    ['--color-on-accent', '--color-accent', WHITE, AA_TEXT],
+
+    // Brand color used AS TEXT on a light surface: .btn-ghost labels, every
+    // link, and ~229 inline call sites. This is the pair whose absence produced
+    // the invisible Refresh button.
+    ['--color-primary', '--color-surface', WHITE, AA_TEXT],
+    ['--color-primary-dark', '--color-surface', WHITE, AA_TEXT],
+    ['--color-accent', '--color-surface', WHITE, AA_TEXT],
+    ['--color-primary-dark', '--color-primary-bg', WHITE, AA_TEXT],
+
+    // The text ramp on light surfaces.
+    ['--color-text', '--color-surface', WHITE, AA_TEXT],
+    ['--color-text-secondary', '--color-surface', WHITE, AA_TEXT],
+    ['--color-text-muted', '--color-surface', WHITE, AA_TEXT],
+    ['--color-text-subtle', '--color-surface', WHITE, AA_TEXT],
+    ['--color-slate-700', '--color-surface', WHITE, AA_TEXT],
+    ['--color-text', '--color-surface-soft', WHITE, AA_TEXT],
+    ['--color-text-secondary', '--color-surface-soft', WHITE, AA_TEXT],
+
+    // Semantic banners and badges: colored text on its own tint.
+    ['--color-success-text', '--color-success-bg', WHITE, AA_TEXT],
+    ['--color-danger-text', '--color-danger-bg', WHITE, AA_TEXT],
+    ['--color-warning-text', '--color-warning-bg', WHITE, AA_TEXT],
+    ['--color-info-text', '--color-info-bg', WHITE, AA_TEXT],
+
+    // The dark sidebar rail. Contrast runs the other way here, which is why
+    // --color-text-muted-on-dark exists as a separate token.
+    ['--color-sidebar-text', '--color-sidebar', WHITE, AA_TEXT],
+    ['--color-sidebar-text-active', '--color-sidebar', WHITE, AA_TEXT],
+    ['--color-text-on-dark', '--color-sidebar', WHITE, AA_TEXT],
+    ['--color-text-muted-on-dark', '--color-sidebar', WHITE, AA_TEXT],
+
+    // Note on borders: --color-border and friends are deliberately NOT asserted
+    // at 3:1. WCAG 1.4.11 covers non-text content required to IDENTIFY a
+    // control, and these are decorative separators , a control here is
+    // identified by its label and its fill, and its state by the focus ring,
+    // which the theme resolver does guarantee at 3:1 against the surface.
+  ] as const)('%s on %s', (foreground, background, backdrop, required) => {
+    it(`meets ${required}:1`, () => {
+      // A translucent background composites over the surface it sits on; the
+      // dark rail composites over itself.
+      const isDark = background.includes('sidebar');
+      const base = isDark ? colorOf('--color-sidebar') : backdrop;
+      const ratio = contrastRatio(colorOf(foreground, base), colorOf(background, base));
+      expect(Number(ratio.toFixed(2))).toBeGreaterThanOrEqual(required);
+    });
+  });
+
+  it('keeps the active sidebar item and role badge legible on the rail', () => {
+    const rail = colorOf('--color-sidebar');
+    expect(contrastRatio(colorOf('--color-sidebar-text-active'), colorOf('--color-sidebar-active', rail)))
+      .toBeGreaterThanOrEqual(AA_TEXT);
+    expect(contrastRatio(colorOf('--color-brand-badge-text'), colorOf('--color-brand-badge-bg', rail)))
+      .toBeGreaterThanOrEqual(AA_NON_TEXT);
+  });
 });
diff --git a/packages/web/src/lib/contrast-audit.ts b/packages/web/src/lib/contrast-audit.ts
new file mode 100644
index 00000000..24f115de
--- /dev/null
+++ b/packages/web/src/lib/contrast-audit.ts
@@ -0,0 +1,220 @@
+/**
+ * Dev-only runtime contrast auditor.
+ *
+ * Static analysis cannot see composed color. The bug that motivated this file
+ * was a `<button class="btn-ghost">` whose own rule said
+ * `background-color: transparent; color: var(--color-primary)` , which reads as
+ * perfectly fine , while a lower-specificity `button` rule painted a brand
+ * gradient underneath that the longhand could not clear. The element rendered
+ * brand-on-brand and was invisible, and no linter, type checker, or unit test
+ * could tell.
+ *
+ * This walks the live DOM instead. It resolves each text node's EFFECTIVE
+ * background by climbing ancestors through transparent fills, and , the part
+ * that matters , when it meets a `background-image` it parses the gradient's
+ * color stops and scores against every one of them, reporting the worst. That
+ * is precisely the case `getComputedStyle` cannot answer on its own.
+ *
+ * Usage (dev server only):
+ *   window.__contrastAudit()            // -> Offender[], also console.table'd
+ *   http://localhost:5173/admin?contrast=1   // outlines offenders in the page
+ */
+import { contrastRatio, parseCssColor, type Rgb } from '@rayhealth/core/domain/theme-resolver.js';
+
+export interface Offender {
+  ratio: number;
+  required: number;
+  text: string;
+  color: string;
+  background: string;
+  /** Set when the background is a gradient/image, naming the worst stop. */
+  via?: string;
+  selector: string;
+  element: Element;
+}
+
+const OPAQUE_WHITE: Rgb = { r: 255, g: 255, b: 255 };
+
+/** `rgba(r, g, b, a)` -> alpha, or 1 when the value is opaque. */
+function alphaOf(color: string): number {
+  const match = /rgba?\([^)]*[,/]\s*([\d.]+)\s*\)/.exec(color);
+  return match ? Number(match[1]) : 1;
+}
+
+function blend(fg: Rgb, alpha: number, bg: Rgb): Rgb {
+  return {
+    r: Math.round((fg.r * alpha) + (bg.r * (1 - alpha))),
+    g: Math.round((fg.g * alpha) + (bg.g * (1 - alpha))),
+    b: Math.round((fg.b * alpha) + (bg.b * (1 - alpha))),
+  };
+}
+
+/** Every color stop in a gradient string, in source order. */
+function gradientStops(image: string): Rgb[] {
+  const stops: Rgb[] = [];
+  for (const match of image.matchAll(/rgba?\([^)]*\)|#[0-9a-fA-F]{3,8}\b/g)) {
+    const parsed = parseCssColor(match[0]);
+    if (parsed && alphaOf(match[0]) > 0.15) stops.push(parsed);
+  }
+  return stops;
+}
+
+interface Backdrop {
+  colors: Rgb[];
+  description: string;
+}
+
+/**
+ * The colors actually painted behind `element`, climbing through transparent
+ * ancestors. Returns every candidate: a gradient contributes one entry per
+ * stop, so the caller can score the worst case rather than an average.
+ */
+function effectiveBackdrop(element: Element): Backdrop {
+  let node: Element | null = element;
+  let accumulated: { color: Rgb; alpha: number }[] = [];
+
+  while (node) {
+    const style = getComputedStyle(node);
+    const image = style.backgroundImage;
+
+    if (image && image !== 'none') {
+      const stops = gradientStops(image);
+      if (stops.length > 0) {
+        return {
+          colors: stops.map((stop) => accumulated.reduceRight((bg, layer) => blend(layer.color, layer.alpha, bg), stop)),
+          description: `${image.slice(0, 60)}${image.length > 60 ? '...' : ''}`,
+        };
+      }
+      // A bitmap or data-URI background: colors are unknowable from here.
+      return { colors: [], description: `image: ${image.slice(0, 40)}` };
+    }
+
+    const parsed = parseCssColor(style.backgroundColor);
+    const alpha = alphaOf(style.backgroundColor);
+    if (parsed && alpha > 0) {
+      if (alpha >= 0.999) {
+        return {
+          colors: [accumulated.reduceRight((bg, layer) => blend(layer.color, layer.alpha, bg), parsed)],
+          description: style.backgroundColor,
+        };
+      }
+      accumulated = [...accumulated, { color: parsed, alpha }];
+    }
+
+    node = node.parentElement;
+  }
+
+  // Ran off the top of the tree: the canvas is white.
+  return {
+    colors: [accumulated.reduceRight((bg, layer) => blend(layer.color, layer.alpha, bg), OPAQUE_WHITE)],
+    description: 'page canvas',
+  };
+}
+
+/** WCAG: 3:1 for large text (>=18.66px, or >=14px bold), 4.5:1 otherwise. */
+function requiredRatio(style: CSSStyleDeclaration): number {
+  const size = parseFloat(style.fontSize);
+  const weight = Number(style.fontWeight) || (style.fontWeight === 'bold' ? 700 : 400);
+  const isLarge = size >= 24 || (size >= 18.66 && weight >= 700);
+  return isLarge ? 3 : 4.5;
+}
+
+function describe(element: Element): string {
+  const tag = element.tagName.toLowerCase();
+  const id = element.id ? `#${element.id}` : '';
+  const classes = typeof element.className === 'string' && element.className
+    ? `.${element.className.trim().split(/\s+/).join('.')}`
+    : '';
+  return `${tag}${id}${classes}`;
+}
+
+/** Text this element renders itself, ignoring text owned by its children. */
+function ownText(element: Element): string {
+  return [...element.childNodes]
+    .filter((node) => node.nodeType === Node.TEXT_NODE)
+    .map((node) => node.textContent ?? '')
+    .join('')
+    .trim();
+}
+
+export function auditContrast(root: ParentNode = document.body): Offender[] {
+  const offenders: Offender[] = [];
+
+  for (const element of root.querySelectorAll('*')) {
+    const text = ownText(element);
+    if (text.length === 0) continue;
+
+    const style = getComputedStyle(element);
+    if (style.visibility === 'hidden' || style.display === 'none' || Number(style.opacity) === 0) continue;
+
+    const rect = element.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) continue;
+
+    const foreground = parseCssColor(style.color);
+    if (!foreground) continue;
+
+    const backdrop = effectiveBackdrop(element);
+    if (backdrop.colors.length === 0) continue; // unknowable background, needs a human
+
+    const required = requiredRatio(style);
+    let worst = Number.POSITIVE_INFINITY;
+    let worstColor: Rgb | null = null;
+    for (const candidate of backdrop.colors) {
+      const ratio = contrastRatio(foreground, candidate);
+      if (ratio < worst) {
+        worst = ratio;
+        worstColor = candidate;
+      }
+    }
+
+    if (worst < required) {
+      offenders.push({
+        ratio: Number(worst.toFixed(2)),
+        required,
+        text: text.length > 48 ? `${text.slice(0, 48)}...` : text,
+        color: style.color,
+        background: worstColor
+          ? `rgb(${worstColor.r}, ${worstColor.g}, ${worstColor.b})`
+          : backdrop.description,
+        via: backdrop.colors.length > 1 ? backdrop.description : undefined,
+        selector: describe(element),
+        element,
+      });
+    }
+  }
+
+  return offenders.sort((a, b) => a.ratio - b.ratio);
+}
+
+/** Draw an outline on every offender so they can be found on the page. */
+export function highlightOffenders(offenders: Offender[]): void {
+  for (const offender of offenders) {
+    (offender.element as HTMLElement).style.outline = '2px dashed #FF00FF';
+    (offender.element as HTMLElement).style.outlineOffset = '2px';
+  }
+}
+
+/**
+ * Wire the auditor onto `window` for the dev server. Never called in a
+ * production build , main.tsx guards on import.meta.env.DEV, so this module is
+ * tree-shaken out entirely.
+ */
+export function installContrastAudit(): void {
+  const run = (): Offender[] => {
+    const offenders = auditContrast();
+    if (offenders.length === 0) {
+      console.info('[contrast] no failures on this route');
+    } else {
+      console.warn(`[contrast] ${offenders.length} failing element(s) on ${window.location.pathname}`);
+      console.table(offenders.map(({ element, ...row }) => row));
+    }
+    return offenders;
+  };
+
+  (window as unknown as { __contrastAudit: typeof run }).__contrastAudit = run;
+
+  if (new URLSearchParams(window.location.search).has('contrast')) {
+    // Let the route settle (data fetches, transitions) before measuring.
+    window.setTimeout(() => highlightOffenders(run()), 1200);
+  }
+}
diff --git a/packages/web/src/main.tsx b/packages/web/src/main.tsx
index 707b7fe6..f339817c 100644
--- a/packages/web/src/main.tsx
+++ b/packages/web/src/main.tsx
@@ -9,6 +9,15 @@ import './index.css';
 
 document.documentElement.dataset.appVersion = '2026.05.19';
 
+// Dev-only contrast auditor. Static rules cannot see composed color , a
+// gradient painted by a lower-specificity rule under a transparent element is
+// invisible to them , so this walks the live DOM instead. Call
+// window.__contrastAudit() in the console, or append ?contrast=1 to a route to
+// outline every failing element. Tree-shaken out of production builds.
+if ((import.meta as unknown as { env?: { DEV?: boolean } }).env?.DEV) {
+  void import('./lib/contrast-audit.js').then(({ installContrastAudit }) => installContrastAudit());
+}
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <AuthProvider>
diff --git a/scripts/check.sh b/scripts/check.sh
index 33453bad..a1a65523 100755
--- a/scripts/check.sh
+++ b/scripts/check.sh
@@ -6,4 +6,5 @@ npm run typecheck
 npm run test
 npm run build
 npm run security:scan
+npm run css:scan
 npm run sql:scan
diff --git a/scripts/css-contract-scan.ts b/scripts/css-contract-scan.ts
new file mode 100644
index 00000000..0d7c9c27
--- /dev/null
+++ b/scripts/css-contract-scan.ts
@@ -0,0 +1,279 @@
+/**
+ * Guards the invariants that keep the web app readable under any agency's
+ * color scheme.
+ *
+ * Every rule here exists because the corresponding bug actually shipped. The
+ * headline one: `button { background: var(--gradient-brand) }` sets a
+ * background-IMAGE, and `.btn-ghost { background-color: transparent }` , a
+ * longhand , cannot clear an image. So every ghost button in the admin app
+ * rendered brand-colored text on the brand gradient, i.e. invisible. Nothing in
+ * lint, typecheck, or the unit tests could see it.
+ *
+ * Run: npm run css:scan
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const ROOT = process.cwd();
+const STYLESHEET = 'packages/web/src/index.css';
+const RESOLVER = 'packages/core/src/domain/theme-resolver.ts';
+const TSX_DIRS = ['packages/web/src'];
+
+const failures: string[] = [];
+
+function repoPath(path: string): string {
+  return relative(ROOT, path).replace(/\\/g, '/');
+}
+
+function fail(file: string, line: number, message: string): void {
+  failures.push(`${file}:${line}: ${message}`);
+}
+
+function lineOf(source: string, index: number): number {
+  return source.slice(0, index).split('\n').length;
+}
+
+/**
+ * Blank out comments while preserving every byte offset, so the rules below
+ * never fire on prose. A rule that bans an idiom has to describe it, and a
+ * scanner that flags its own documentation is a scanner people switch off.
+ */
+function withoutComments(source: string): string {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, (block) => block.replace(/[^\n]/g, ' '))
+    .replace(/(^|[^:'"`\\])\/\/[^\n]*/g, (match, prefix: string) => prefix + ' '.repeat(match.length - prefix.length));
+}
+
+function sourceFiles(relativeDir: string): string[] {
+  const absoluteDir = join(ROOT, relativeDir);
+  return readdirSync(absoluteDir).flatMap((name) => {
+    const path = join(absoluteDir, name);
+    if (statSync(path).isDirectory()) return sourceFiles(path.slice(ROOT.length + 1));
+    if (!/\.tsx?$/.test(path)) return [];
+    if (/\.(test|spec)\.tsx?$/.test(path)) return [];
+    return [path];
+  });
+}
+
+const css = withoutComments(readFileSync(join(ROOT, STYLESHEET), 'utf8'));
+const rootBlock = /:root\s*\{[\s\S]*?\n\}/.exec(css)?.[0] ?? '';
+if (!rootBlock) {
+  fail(STYLESHEET, 1, 'no :root token block found; the rest of this scan cannot run');
+}
+
+interface Rule {
+  selector: string;
+  body: string;
+  line: number;
+}
+
+const rules: Rule[] = [];
+for (const match of css.matchAll(/([^{}]*)\{([^{}]*)\}/g)) {
+  rules.push({
+    selector: match[1].trim(),
+    body: match[2],
+    line: lineOf(css, match.index ?? 0),
+  });
+}
+
+const declaresImage = (body: string): boolean =>
+  /background-image:/.test(body) || /background:\s*(linear-|radial-|conic-|url\()/.test(body);
+
+// ---------------------------------------------------------------------------
+// Rule 1: the shorthand/longhand trap.
+// ---------------------------------------------------------------------------
+// `background-color` only replaces the color layer. If ANY lower-specificity
+// rule paints an image on the same element, that image keeps rendering on top
+// of the fill you asked for. A rule that declares its own image is stating its
+// full intent and is fine; a rule that does not must use the `background`
+// shorthand, which resets the image layer.
+for (const rule of rules) {
+  if (rule.selector.includes(':root')) continue;
+  if (!/background-color:/.test(rule.body)) continue;
+  if (declaresImage(rule.body)) continue;
+  fail(
+    STYLESHEET,
+    rule.line,
+    `\`${rule.selector.replace(/\s+/g, ' ')}\` sets the background-color longhand without declaring its own ` +
+      'background-image. A longhand cannot clear an inherited image, so the fill you asked for may never ' +
+      'render. Use the `background` shorthand.'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Rule 2: no raw color literals outside the token block.
+// ---------------------------------------------------------------------------
+// design-system.test.ts already bans hex in .tsx. The stylesheet itself was
+// exempt, which is how ~27 stray values and one orphaned lavender accumulated
+// in colors no agency theme could ever reach.
+for (const rule of rules) {
+  if (rule.selector.includes(':root')) continue;
+  for (const hex of rule.body.matchAll(/#[0-9a-fA-F]{3,8}\b/g)) {
+    fail(
+      STYLESHEET,
+      rule.line + lineOf(rule.body, hex.index ?? 0) - 1,
+      `raw color literal ${hex[0]} outside :root. Define a token so it can follow an agency theme.`
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rule 3: white and black are tokens too.
+// ---------------------------------------------------------------------------
+// `color: white` on a brand-filled surface is an assumption that the brand is
+// dark. --color-on-brand is chosen by measured contrast instead.
+for (const rule of rules) {
+  if (rule.selector.includes(':root')) continue;
+  const match = /(?:^|[;{\s])color:\s*(white|black)\s*[;}]/.exec(rule.body);
+  if (match) {
+    fail(
+      STYLESHEET,
+      rule.line,
+      `\`${rule.selector.replace(/\s+/g, ' ')}\` hardcodes \`color: ${match[1]}\`. Use --color-on-brand ` +
+        '(brand surfaces), --color-text-on-dark (dark panels), or --color-text.'
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rule 4: every token referenced anywhere is defined in :root.
+// ---------------------------------------------------------------------------
+const definedTokens = new Set(
+  [...rootBlock.matchAll(/(--[\w-]+)\s*:/g)].map((match) => match[1])
+);
+
+const tsxFiles = TSX_DIRS.flatMap(sourceFiles);
+const scopedPrefixes = ['--rh-', '--mk-', '--pub-'];
+// Page-scoped design systems (LandingPage, SiteLayout, public-brand) define
+// their own variables inside <style> blocks; only global tokens are checked.
+const isGlobalToken = (token: string): boolean =>
+  token.startsWith('--color-') || token.startsWith('--gradient-') ||
+  token.startsWith('--shadow-') || token.startsWith('--font-') ||
+  token.startsWith('--space-') || token.startsWith('--radius-') ||
+  token.startsWith('--focus-');
+
+for (const [file, source] of [
+  [STYLESHEET, css] as const,
+  ...tsxFiles.map((path) => [repoPath(path), withoutComments(readFileSync(path, 'utf8'))] as const),
+]) {
+  for (const use of source.matchAll(/var\(\s*(--[\w-]+)/g)) {
+    const token = use[1];
+    if (scopedPrefixes.some((prefix) => token.startsWith(prefix))) continue;
+    if (!isGlobalToken(token)) continue;
+    if (definedTokens.has(token)) continue;
+    if (new RegExp(`${token}\\s*:`).test(source)) continue; // defined locally in the same file
+    fail(file, lineOf(source, use.index ?? 0), `var(${token}) is not defined in the :root token block.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rule 5: the resolver and the stylesheet cannot drift apart.
+// ---------------------------------------------------------------------------
+// This is the rule that permanently closes the original hole. --color-on-brand
+// existed in :root but was not in the override list, so it stayed white forever
+// no matter what an agency picked. Any token whose default is derived from the
+// brand MUST be resolver-managed, and vice versa.
+const resolverSource = withoutComments(readFileSync(join(ROOT, RESOLVER), 'utf8'));
+const listBlock = /AGENCY_THEME_VARIABLES[^=]*=\s*\[([\s\S]*?)\]/.exec(resolverSource)?.[1] ?? '';
+const managed = new Set([...listBlock.matchAll(/'(--[\w-]+)'/g)].map((match) => match[1]));
+
+if (managed.size === 0) {
+  fail(RESOLVER, 1, 'could not read AGENCY_THEME_VARIABLES; rule 5 cannot run');
+}
+
+for (const token of managed) {
+  if (!definedTokens.has(token)) {
+    fail(
+      STYLESHEET,
+      1,
+      `${token} is managed by the theme resolver but has no static default in :root. ` +
+        'Agencies with no theme would get nothing.'
+    );
+  }
+}
+
+// Any :root token whose VALUE mentions a brand color is brand-derived, so it
+// has to be overridable.
+for (const declaration of rootBlock.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) {
+  const [, token, value] = declaration;
+  const derivesFromBrand = /var\(\s*--color-(primary|accent|brand-raw)/.test(value);
+  if (derivesFromBrand && !managed.has(token)) {
+    fail(
+      STYLESHEET,
+      lineOf(css, declaration.index ?? 0),
+      `${token} is derived from the brand color but is not in AGENCY_THEME_VARIABLES, so it would keep ` +
+        'the RayHealth default when an agency theme is applied.'
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rule 6: --color-brand-raw is never allowed to carry text.
+// ---------------------------------------------------------------------------
+// It deliberately holds the agency's UNADJUSTED color, which may fail AA. It is
+// for logo marks and decorative washes only.
+for (const [file, source] of [
+  [STYLESHEET, css] as const,
+  ...tsxFiles.map((path) => [repoPath(path), withoutComments(readFileSync(path, 'utf8'))] as const),
+]) {
+  for (const use of source.matchAll(/(^|[^-\w])color\s*:\s*['"`]?\s*var\(\s*--color-brand-raw/gm)) {
+    fail(
+      file,
+      lineOf(source, use.index ?? 0),
+      '--color-brand-raw is the agency color BEFORE contrast adjustment and may be unreadable. ' +
+        'Use --color-primary for anything that carries text.'
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rule 7: no alpha byte appended to a token.
+// ---------------------------------------------------------------------------
+// `` `${RISK_COLOR[level]}14` `` yields the literal string "var(--color-accent)14",
+// an invalid declaration the browser silently drops. The element loses its
+// background and its colored text lands on whatever is underneath.
+for (const path of tsxFiles) {
+  const source = withoutComments(readFileSync(path, 'utf8'));
+  for (const use of source.matchAll(/\$\{[^}]+\}[0-9a-fA-F]{2}`/g)) {
+    fail(
+      repoPath(path),
+      lineOf(source, use.index ?? 0),
+      'hex alpha appended to an interpolated color. That only works on a hex literal, and every color ' +
+        'here is a var() token, so the declaration is invalid and dropped. Use tint() from lib/color.ts.'
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rule 8: no dead var() fallbacks.
+// ---------------------------------------------------------------------------
+// If the first token is defined in :root, the fallback can never apply, so it
+// is dead code that hides which color is really in effect. That mattered: a
+// batch of error banners read `var(--color-accent, var(--color-danger-bg))`,
+// which looks like a danger state but actually renders the BRAND accent , so
+// on an orange-branded agency an error banner was indistinguishable from
+// ordinary brand chrome.
+for (const path of tsxFiles) {
+  const source = withoutComments(readFileSync(path, 'utf8'));
+  for (const use of source.matchAll(/var\(\s*(--[\w-]+)\s*,\s*var\(\s*(--[\w-]+)\s*\)\s*\)/g)) {
+    const [, primary, fallback] = use;
+    if (!definedTokens.has(primary)) continue; // a real fallback for a scoped token
+    fail(
+      repoPath(path),
+      lineOf(source, use.index ?? 0),
+      `var(${primary}, var(${fallback})) , ${primary} is always defined, so the fallback is dead code. ` +
+        'Keep whichever token you actually mean.'
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+if (failures.length > 0) {
+  console.error(`CSS contract scan found ${failures.length} issue(s):\n`);
+  for (const failure of failures) console.error(`  ${failure}`);
+  console.error('\nSee scripts/css-contract-scan.ts for why each rule exists.');
+  process.exit(1);
+}
+
+console.log('CSS contract scan passed.');