@astryxdesign/core 0.2.0 → 0.3.0-canary.1b8b3f2

package/src/theme/expandColorScale.test.ts

@@ -1,9 +1,25 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {expandColorScale} from './expandColorScale';
+import {expandColorScale, ensureContrastTone} from './expandColorScale';
+import {contrastRatio, compositeOver} from './contrast';
+import {hexToHct, tonalPalette} from './hct';
 import {defineTheme} from './defineTheme';
 import {generateThemeRules} from './generateThemeRules';
+import {resolveThemeTokens} from './tokens';
+import {colorDefaults} from './tokens.stylex';
+import {parseColor, formatColor} from '../utils/color';
+
+/** Light-mode half of colorDefaults['--color-accent'] — the hue an accent-less config seeds from. */
+const DEFAULT_ACCENT = '#0064E0';
+const DEFAULT_ACCENT_DARK = '#2694FE';
+
+/** The three tokens that only exist when a seed accent is supplied. */
+const ACCENT_TOKENS = [
+  '--color-accent',
+  '--color-accent-muted',
+  '--color-on-accent',
+] as const;
 
 describe('expandColorScale', () => {
   it('produces all expected token keys', () => {
@@ -84,6 +100,96 @@ describe('expandColorScale', () => {
       standard['--color-text-primary'],
     );
   });
+
+  it('contrast high strengthens both border tokens', () => {
+    const standard = expandColorScale({
+      accent: '#0064E0',
+      contrast: 'standard',
+    });
+    const high = expandColorScale({accent: '#0064E0', contrast: 'high'});
+    // Both the subtle hairline and the emphasized border shift under high
+    // contrast, so structural boundaries stay perceivable.
+    expect(high['--color-border']).not.toBe(standard['--color-border']);
+    expect(high['--color-border-emphasized']).not.toBe(
+      standard['--color-border-emphasized'],
+    );
+  });
+});
+
+describe('expandColorScale — neutral-only themes (#2279)', () => {
+  it('accent is optional — a config without one expands', () => {
+    const tokens = expandColorScale({neutralStyle: 'warm'});
+    expect(tokens['--color-background-surface']).toMatch(/^light-dark\(#/);
+  });
+
+  it('expands an empty config', () => {
+    const tokens = expandColorScale({});
+    expect(tokens['--color-background-surface']).toMatch(/^light-dark\(#/);
+    expect(tokens).not.toHaveProperty('--color-accent');
+  });
+
+  it('omits the accent tokens so they fall through to colorDefaults', () => {
+    const tokens = expandColorScale({neutralStyle: 'warm'});
+    for (const key of ACCENT_TOKENS) {
+      expect(tokens).not.toHaveProperty(key);
+    }
+    // ...and the reference tokens still point at whatever --color-accent resolves to.
+    expect(tokens['--color-text-accent']).toBe('var(--color-accent)');
+    expect(tokens['--color-icon-accent']).toBe('var(--color-accent)');
+  });
+
+  it('seeds the neutral palettes from the light half of the default accent', () => {
+    // Drift guard: the module's DEFAULT_ACCENT_SEED is private, so pin the
+    // colorDefaults value it is copied from. Re-coloring the default accent
+    // without re-seeding would silently change every neutral-only theme.
+    expect(colorDefaults['--color-accent']).toBe(
+      `light-dark(${DEFAULT_ACCENT}, ${DEFAULT_ACCENT_DARK})`,
+    );
+
+    const neutralOnly = expandColorScale({neutralStyle: 'warm'});
+    const seeded = expandColorScale({
+      accent: DEFAULT_ACCENT,
+      neutralStyle: 'warm',
+    });
+    for (const [key, value] of Object.entries(seeded)) {
+      if ((ACCENT_TOKENS as ReadonlyArray<string>).includes(key)) {
+        continue;
+      }
+      expect(neutralOnly[key], key).toBe(value);
+    }
+  });
+
+  it('honours neutralStyle and contrast without an accent', () => {
+    const warm = expandColorScale({neutralStyle: 'warm'});
+    const cool = expandColorScale({neutralStyle: 'cool'});
+    expect(warm['--color-neutral']).not.toBe(cool['--color-neutral']);
+
+    const high = expandColorScale({contrast: 'high'});
+    const standard = expandColorScale({contrast: 'standard'});
+    expect(high['--color-text-primary']).not.toBe(
+      standard['--color-text-primary'],
+    );
+  });
+
+  it('does not re-color themes that do pass an accent', () => {
+    // Seeding from the default hex derives a DIFFERENT accent than the default
+    // token holds, so "just default the seed" is not behavior-preserving —
+    // omitting the tokens is the only way a neutral-only theme keeps the
+    // default accent.
+    const tokens = expandColorScale({accent: DEFAULT_ACCENT});
+    expect(tokens['--color-accent']).toMatch(/^light-dark\(#/);
+    expect(tokens['--color-accent']).not.toBe(colorDefaults['--color-accent']);
+  });
+
+  it('treats an empty accent as supplied, not absent', () => {
+    // '' is falsy but not nullish. Only an absent accent is neutral-only; a
+    // supplied-but-malformed one keeps its pre-#2279 behavior (the hex parser
+    // falls back to black) rather than silently dropping the accent tokens.
+    const tokens = expandColorScale({accent: ''});
+    for (const key of ACCENT_TOKENS) {
+      expect(tokens).toHaveProperty(key);
+    }
+  });
 });
 
 describe('expandColorScale + defineTheme integration', () => {
@@ -110,4 +216,298 @@ describe('expandColorScale + defineTheme integration', () => {
     // The base token itself stays a resolved color pair.
     expect(css).toMatch(/--color-accent: light-dark\(#/);
   });
+
+  it('a neutral-only theme leaves the accent tokens at their defaults (#2279)', () => {
+    const theme = defineTheme({
+      name: 'test-neutral-only',
+      color: {neutralStyle: 'warm'},
+    });
+    for (const key of ACCENT_TOKENS) {
+      expect(theme.tokens).not.toHaveProperty(key);
+    }
+    // Neutrals are still themed.
+    expect(theme.tokens['--color-background-surface']).toMatch(
+      /^light-dark\(#/,
+    );
+
+    const css = generateThemeRules(theme).join('\n');
+    expect(css).not.toContain('--color-accent:');
+    expect(css).not.toContain('--color-on-accent:');
+    expect(css).toContain('--color-background-surface:');
+  });
+
+  it('a neutral-only theme resolves accent tokens to the defaults at runtime (#2279)', () => {
+    // The CSS side falls through by simply not emitting the tokens. The JS side
+    // (useTheme/resolveThemeTokens) has to agree: the omitted tokens come back
+    // from tokenDefaults, and the var() references the theme DOES emit resolve
+    // against them instead of leaking a literal 'var(--color-accent)'.
+    const theme = defineTheme({
+      name: 'test-neutral-only-runtime',
+      color: {neutralStyle: 'warm'},
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    expect(light['--color-accent']).toBe(DEFAULT_ACCENT);
+    expect(light['--color-text-accent']).toBe(DEFAULT_ACCENT);
+    expect(light['--color-icon-accent']).toBe(DEFAULT_ACCENT);
+
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+    expect(dark['--color-accent']).toBe(DEFAULT_ACCENT_DARK);
+    expect(dark['--color-text-accent']).toBe(DEFAULT_ACCENT_DARK);
+  });
+
+  it('an explicit accent token still wins on a neutral-only theme (#2279)', () => {
+    // Neutral scale from HCT + a hand-picked accent: the tokens map is the only
+    // source of --color-accent, so the reference tokens follow it.
+    const theme = defineTheme({
+      name: 'test-neutral-only-explicit-accent',
+      color: {neutralStyle: 'warm'},
+      tokens: {'--color-accent': ['#AA0000', '#FF5555']},
+    });
+    expect(
+      resolveThemeTokens(theme, {mode: 'light'})['--color-text-accent'],
+    ).toBe('#AA0000');
+
+    const css = generateThemeRules(theme).join('\n');
+    expect(css).toContain('--color-text-accent: var(--color-accent);');
+  });
+});
+
+// =============================================================================
+// WCAG contrast guarantees (WCAG 1.4.3 text >= 4.5:1, 1.4.11 non-text >= 3:1)
+// =============================================================================
+
+/** Split a light-dark(a, b) token into its [light, dark] halves. */
+function splitLightDark(value: string): [light: string, dark: string] {
+  const match = value.match(/^light-dark\((.+?),\s*(.+)\)$/);
+  if (!match) {
+    // Single-value tokens apply to both modes.
+    return [value, value];
+  }
+  return [match[1], match[2]];
+}
+
+type Mode = 0 | 1; // 0 = light, 1 = dark
+
+/** Resolve one mode of a token to a concrete color string. */
+function resolveToken(
+  tokens: Record<string, string>,
+  name: string,
+  mode: Mode,
+): string {
+  return splitLightDark(tokens[name])[mode];
+}
+
+/** Resolve one mode of an alpha token, composited over its backdrop. */
+function resolveComposited(
+  tokens: Record<string, string>,
+  name: string,
+  backdrop: string,
+  mode: Mode,
+): string {
+  const fg = parseColor(resolveToken(tokens, name, mode));
+  const bg = parseColor(backdrop);
+  if (fg === null || bg === null) {
+    throw new Error(`could not parse ${name} or its backdrop`);
+  }
+  return formatColor(compositeOver(fg, bg));
+}
+
+describe('expandColorScale WCAG contrast guarantees', () => {
+  // Representative configs: the docs' default accent, both contrast levels,
+  // every neutralStyle, saturated custom brand accents across the hue wheel,
+  // a low-chroma (gray) seed, and degenerate black/white seeds.
+  const configs = [
+    {accent: '#0064E0'},
+    {accent: '#0064E0', contrast: 'high'},
+    {accent: '#DC2626', neutralStyle: 'warm'},
+    {accent: '#B7410E', neutralStyle: 'warm', contrast: 'high'},
+    {accent: '#12B76A', neutralStyle: 'neutral'},
+    {accent: '#D9006E', neutralStyle: 'warm'},
+    {accent: '#657100', neutralStyle: 'cool'},
+    {accent: '#6B7280'},
+    {accent: '#000000'},
+    {accent: '#FFFFFF', neutralStyle: 'neutral', contrast: 'high'},
+  ] as const;
+
+  const modes: [label: string, mode: Mode][] = [
+    ['light', 0],
+    ['dark', 1],
+  ];
+
+  describe.each(configs)('config %o', config => {
+    const tokens = expandColorScale(config);
+
+    it.each(modes)(
+      'text tokens meet 4.5:1 on the surfaces the system pairs them with (%s)',
+      (_label, mode) => {
+        const surface = resolveToken(
+          tokens,
+          '--color-background-surface',
+          mode,
+        );
+        const body = resolveToken(tokens, '--color-background-body', mode);
+        const card = resolveToken(tokens, '--color-background-card', mode);
+        const popover = resolveToken(
+          tokens,
+          '--color-background-popover',
+          mode,
+        );
+        // Alpha tokens paint over the surface — composite before measuring.
+        const muted = resolveComposited(
+          tokens,
+          '--color-background-muted',
+          surface,
+          mode,
+        );
+        const neutral = resolveComposited(
+          tokens,
+          '--color-neutral',
+          surface,
+          mode,
+        );
+
+        const textPrimary = resolveToken(tokens, '--color-text-primary', mode);
+        const textSecondary = resolveToken(
+          tokens,
+          '--color-text-secondary',
+          mode,
+        );
+        const accent = resolveToken(tokens, '--color-accent', mode);
+        const onAccent = resolveToken(tokens, '--color-on-accent', mode);
+
+        // Primary text on every generated background it renders on.
+        for (const bg of [surface, body, card, popover, muted, neutral]) {
+          expect(contrastRatio(textPrimary, bg)).toBeGreaterThanOrEqual(4.5);
+        }
+        // Secondary/muted text on the main content surfaces.
+        for (const bg of [surface, body, card, popover]) {
+          expect(contrastRatio(textSecondary, bg)).toBeGreaterThanOrEqual(4.5);
+        }
+        // Accent-colored text (--color-text-accent references --color-accent).
+        expect(contrastRatio(accent, surface)).toBeGreaterThanOrEqual(4.5);
+        // Label text on accent-filled controls (primary buttons).
+        expect(contrastRatio(onAccent, accent)).toBeGreaterThanOrEqual(4.5);
+      },
+    );
+
+    it.each(modes)(
+      'non-text UI tokens meet 3:1 against the surface (%s)',
+      (_label, mode) => {
+        const surface = resolveToken(
+          tokens,
+          '--color-background-surface',
+          mode,
+        );
+        // Accent-filled controls and focus indicators.
+        expect(
+          contrastRatio(resolveToken(tokens, '--color-accent', mode), surface),
+        ).toBeGreaterThanOrEqual(3);
+        // Meaningful icons alongside text.
+        expect(
+          contrastRatio(
+            resolveToken(tokens, '--color-icon-primary', mode),
+            surface,
+          ),
+        ).toBeGreaterThanOrEqual(3);
+        expect(
+          contrastRatio(
+            resolveToken(tokens, '--color-icon-secondary', mode),
+            surface,
+          ),
+        ).toBeGreaterThanOrEqual(3);
+        // Form-control boundaries (CheckboxInput, Selector borders).
+        expect(
+          contrastRatio(
+            resolveToken(tokens, '--color-border-emphasized', mode),
+            surface,
+          ),
+        ).toBeGreaterThanOrEqual(3);
+      },
+    );
+  });
+
+  it('documents the intentionally decorative tokens excluded from 3:1', () => {
+    // These tokens are decorative or redundant cues, not WCAG 1.4.11
+    // boundaries, and are deliberately NOT held to 3:1:
+    // - --color-border: hairline separator (~1.1:1 by design). Components
+    //   that rely on it as their only boundary are tracked separately.
+    // - --color-skeleton: loading placeholder; conveys no information.
+    // - --color-track: rail behind a >= 3:1 thumb/fill (Slider, Switch,
+    //   ProgressBar) — the indicator, not the rail, carries state.
+    // - --color-text-disabled / --color-icon-disabled: disabled controls
+    //   are explicitly exempt from WCAG 1.4.3/1.4.11.
+    // Lock in the decorative alpha form of --color-border so a future
+    // change that starts relying on it for contrast shows up here.
+    const tokens = expandColorScale({accent: '#0064E0'});
+    const [light, dark] = splitLightDark(tokens['--color-border']);
+    for (const half of [light, dark]) {
+      const parsed = parseColor(half);
+      expect(parsed).not.toBeNull();
+      expect(parsed !== null && parsed.a).toBeLessThanOrEqual(0.2);
+    }
+  });
+});
+
+describe('ensureContrastTone', () => {
+  it('returns the starting tone when it already meets the ratio', () => {
+    // Tone 10 on a near-white background is far past 4.5:1 already.
+    const hex = ensureContrastTone(282, 8, 10, -1, '#FCFDFE', 4.5);
+    expect(hex).toBe(ensureContrastTone(282, 8, 10, 1, '#FCFDFE', 1));
+  });
+
+  it('bumps the tone until the ratio passes', () => {
+    // Tone 70 sits around 2.2:1 on a near-white surface — below 3:1.
+    const before = ensureContrastTone(282, 8, 70, -1, '#FCFDFE', 1);
+    expect(contrastRatio(before, '#FCFDFE')).toBeLessThan(3);
+    const after = ensureContrastTone(282, 8, 70, -1, '#FCFDFE', 3);
+    expect(contrastRatio(after, '#FCFDFE')).toBeGreaterThanOrEqual(3);
+  });
+
+  it('terminates at the tone floor/ceiling for impossible ratios', () => {
+    // 22:1 is unreachable; the loop must stop at pure black.
+    expect(ensureContrastTone(282, 8, 70, -1, '#FFFFFF', 22)).toBe('#000000');
+    expect(ensureContrastTone(282, 8, 30, 1, '#000000', 22)).toBe('#FFFFFF');
+  });
+});
+
+// =============================================================================
+// --color-border-emphasized: concrete before/after delta
+// =============================================================================
+//
+// This is the one generated token whose emitted VALUE changes. Every other
+// token is byte-identical to the pre-change output; they only gained the
+// assertions above. Before this change the token was emitted directly as the
+// neutral-variant palette's tone 70 (light) / 30 (dark) — `ld(NV[70], NV[30])`.
+// Those preferred tones land BELOW the WCAG 1.4.11 3:1 floor against the
+// generated surface, so the generator now tone-bumps them until they clear
+// 3:1. These tests reconstruct the exact old output and lock in the delta so
+// the correction can't silently regress to the sub-3:1 value.
+describe('--color-border-emphasized WCAG 1.4.11 correction (before/after)', () => {
+  const config = {accent: '#0064E0'} as const; // docs default, cool neutrals
+  const NEUTRAL_VARIANT_CHROMA_COOL = 8; // NEUTRAL_VARIANT_CHROMA.cool
+  const {hue} = hexToHct(config.accent);
+  // Exactly what the pre-change generator emitted: NV[70] light / NV[30] dark.
+  const nv = tonalPalette(hue, NEUTRAL_VARIANT_CHROMA_COOL);
+  const tokens = expandColorScale(config);
+
+  it('light: old NV[70] (~2.24:1) is corrected to >= 3:1', () => {
+    const surface = resolveToken(tokens, '--color-background-surface', 0);
+    const oldValue = nv[70];
+    const newValue = resolveToken(tokens, '--color-border-emphasized', 0);
+    expect(contrastRatio(oldValue, surface)).toBeCloseTo(2.24, 1);
+    expect(contrastRatio(oldValue, surface)).toBeLessThan(3);
+    expect(newValue).not.toBe(oldValue);
+    expect(contrastRatio(newValue, surface)).toBeGreaterThanOrEqual(3);
+  });
+
+  it('dark: old NV[30] (~1.84:1) is corrected to >= 3:1', () => {
+    const surface = resolveToken(tokens, '--color-background-surface', 1);
+    const oldValue = nv[30];
+    const newValue = resolveToken(tokens, '--color-border-emphasized', 1);
+    expect(contrastRatio(oldValue, surface)).toBeCloseTo(1.84, 1);
+    expect(contrastRatio(oldValue, surface)).toBeLessThan(3);
+    expect(newValue).not.toBe(oldValue);
+    expect(contrastRatio(newValue, surface)).toBeGreaterThanOrEqual(3);
+  });
 });

package/src/theme/expandColorScale.ts

@@ -2,7 +2,7 @@
 
 /**
  * @file expandColorScale.ts
- * @input Color scale configuration { accent, neutralStyle?, contrast? }
+ * @input Color scale configuration { accent?, neutralStyle?, contrast? }
  * @output Token overrides for derivable color tokens
  * @position Theme utility; consumed by defineTheme.ts
  *
@@ -11,11 +11,27 @@
  * derive from the accent — status colors, categorical hues, and fixed
  * tokens (on-dark/on-light) fall through to colorDefaults.
  *
+ * `accent` is optional: a neutral-only config still gets the full neutral
+ * ramp (seeded from the default accent's hue) while the accent tokens
+ * themselves fall through to colorDefaults, same as the tokens above.
+ *
+ * WCAG contrast guarantees (asserted in expandColorScale.test.ts):
+ * - Text tones are guaranteed >= 4.5:1 against their surfaces by tone
+ *   spacing alone — HCT tone is CIE L*, which fixes relative luminance
+ *   regardless of hue/chroma, so the fixed tone assignments hold for any
+ *   accent/neutralStyle (WCAG 1.4.3).
+ * - --color-border-emphasized (form-control boundaries) is tone-bumped
+ *   until it reaches >= 3:1 against the generated surface (WCAG 1.4.11).
+ * - --color-border, --color-skeleton, and --color-track are intentionally
+ *   decorative/redundant cues and are NOT held to 3:1 — see the test file
+ *   for the rationale.
+ *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/defineTheme.ts
  */
 
-import {hexToHct, tonalPalette, hexWithAlpha} from './hct';
+import {contrastRatio} from './contrast';
+import {hexToHct, hctToHex, tonalPalette, hexWithAlpha} from './hct';
 
 // =============================================================================
 // Types
@@ -31,11 +47,21 @@ import {hexToHct, tonalPalette, hexWithAlpha} from './hct';
  *
  * // With customization
  * { accent: '#B7410E', neutralStyle: 'warm', contrast: 'high' }
+ *
+ * // Neutral-only — keeps the default accent, themes the neutrals
+ * { neutralStyle: 'warm' }
  * ```
  */
 export interface ColorScaleConfig {
-  /** Seed accent color as hex (#RRGGBB). Everything derives from this. */
-  accent: string;
+  /**
+   * Seed accent color as hex (#RRGGBB). Everything derives from this.
+   *
+   * Optional. When omitted, the neutral palettes are seeded from the
+   * default accent's hue and the accent tokens (--color-accent,
+   * --color-accent-muted, --color-on-accent) are not generated — they
+   * fall through to colorDefaults.
+   */
+  accent?: string;
 
   /**
    * Neutral tone warmth. Controls how much of the seed's hue bleeds
@@ -45,7 +71,9 @@ export interface ColorScaleConfig {
   neutralStyle?: 'warm' | 'cool' | 'neutral';
 
   /**
-   * Contrast level. Affects tone assignments for text and UI elements.
+   * Contrast level. `'high'` pulls text, icons, and borders toward stronger
+   * tones (and thickens the subtle border's alpha) so structural and textual
+   * boundaries stay perceivable.
    * @default 'standard'
    */
   contrast?: 'standard' | 'high';
@@ -69,6 +97,14 @@ const NEUTRAL_VARIANT_CHROMA: Record<string, number> = {
   neutral: 6,
 };
 
+/**
+ * Hue source for accent-less configs — the light half of
+ * colorDefaults['--color-accent'] (a test guards the two against drift).
+ * Only its hue reaches the output: the accent tokens stay ungenerated, so
+ * they keep their colorDefaults values rather than this seed's derivation.
+ */
+const DEFAULT_ACCENT_SEED = '#0064E0';
+
 // =============================================================================
 // Computation
 // =============================================================================
@@ -81,6 +117,39 @@ function accentWithAlpha(alpha: number): string {
   return `color-mix(in srgb, var(--color-accent) ${alpha * 100}%, transparent)`;
 }
 
+/** WCAG 1.4.11 minimum contrast for non-text UI boundaries. */
+const NON_TEXT_MIN_CONTRAST = 3;
+
+/**
+ * Walk tone in `step` increments from `startTone` until the color reaches
+ * `minRatio` against `background`, and return the resulting hex.
+ *
+ * Used for tokens whose preferred tone is not guaranteed by tone spacing
+ * alone (e.g. --color-border-emphasized). Because HCT tone is CIE L*,
+ * each step moves luminance monotonically, so the loop always terminates —
+ * at worst at pure black/white (21:1 against anything mid-range).
+ */
+export function ensureContrastTone(
+  hue: number,
+  chroma: number,
+  startTone: number,
+  step: -1 | 1,
+  background: string,
+  minRatio: number,
+): string {
+  let tone = startTone;
+  let hex = hctToHex({hue, chroma, tone});
+  while (
+    contrastRatio(hex, background) < minRatio &&
+    tone + step >= 0 &&
+    tone + step <= 100
+  ) {
+    tone += step;
+    hex = hctToHex({hue, chroma, tone});
+  }
+  return hex;
+}
+
 /**
  * Expand a color scale config into Astryx color token overrides.
  *
@@ -89,18 +158,23 @@ function accentWithAlpha(alpha: number): string {
  * --color-on-dark/on-light) are NOT generated — they fall through
  * to colorDefaults.
  *
+ * Without an `accent`, the accent tokens join that fall-through set: the
+ * neutrals are seeded from the default accent's hue, and --color-accent,
+ * --color-accent-muted and --color-on-accent keep their colorDefaults values.
+ *
  * @example
  * ```
  * const tokens = expandColorScale({ accent: '#0064E0' });
  * // tokens['--color-accent'] === 'light-dark(#..., #...)'
+ *
+ * const neutralOnly = expandColorScale({ neutralStyle: 'warm' });
+ * // neutralOnly['--color-accent'] === undefined
  * ```
  */
-export function expandColorScale(
-  config: ColorScaleConfig,
-): ColorScaleTokens {
+export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
   const {accent, neutralStyle = 'cool', contrast = 'standard'} = config;
 
-  const seed = hexToHct(accent);
+  const seed = hexToHct(accent ?? DEFAULT_ACCENT_SEED);
   const seedHue = seed.hue;
 
   const primaryChroma = Math.max(seed.chroma, 48);
@@ -118,15 +192,59 @@ export function expandColorScale(
   const textSecondaryLightTone = isHigh ? 20 : 30;
   const textSecondaryDarkTone = isHigh ? 80 : 70;
 
+  // Borders track contrast the same way text does: high contrast pulls the
+  // emphasized border tone toward mid-scale (stronger against both the near-
+  // white light surface and the near-black dark surface) and thickens the
+  // otherwise-decorative subtle hairline by doubling its alpha, so structural
+  // boundaries stay perceivable for users who opt into high contrast.
+  const borderSubtleAlpha = isHigh ? 0.2 : 0.1;
+
+  // Emphasized borders outline form controls (CheckboxInput, Selector), so
+  // they are non-text UI boundaries under WCAG 1.4.11 and must reach 3:1
+  // against the surface they sit on. High contrast starts at a more
+  // aggressive tone (50 vs 70/30), guaranteeing a stronger result; standard
+  // contrast starts at 70/30 and walks toward mid-scale only as far as needed.
+  const borderEmphasizedStartLight = isHigh ? 50 : 70;
+  const borderEmphasizedStartDark = isHigh ? 50 : 30;
+  const borderEmphasized = ld(
+    ensureContrastTone(
+      seedHue,
+      neutralVariantChroma,
+      borderEmphasizedStartLight,
+      -1,
+      N[99],
+      NON_TEXT_MIN_CONTRAST,
+    ),
+    ensureContrastTone(
+      seedHue,
+      neutralVariantChroma,
+      borderEmphasizedStartDark,
+      1,
+      N[10],
+      NON_TEXT_MIN_CONTRAST,
+    ),
+  );
+
   return {
-    // Core semantic
-    '--color-accent': ld(P[40], P[80]),
-    // Derived accent tokens reference --color-accent instead of baking its
-    // resolved hex, so a scoped override of the base token re-accents the
-    // whole subtree at runtime. --color-on-accent stays baked: it is a
-    // contrast computation against the accent, which CSS cannot express.
-    '--color-accent-muted': ld(accentWithAlpha(0.2), accentWithAlpha(0.25)),
-    '--color-on-accent': ld(P[100], P[20]),
+    // Core semantic — only with a seed accent. Without one these fall through
+    // to colorDefaults, whose --color-accent is NOT what the default seed
+    // derives: defaulting the seed instead of omitting the tokens would
+    // recolor every neutral-only theme. Nullish and not truthy, matching the
+    // seed above, so a supplied-but-malformed accent keeps its old behavior.
+    ...(accent != null
+      ? {
+          '--color-accent': ld(P[40], P[80]),
+          // Derived accent tokens reference --color-accent instead of baking its
+          // resolved hex, so a scoped override of the base token re-accents the
+          // whole subtree at runtime. --color-on-accent stays baked: it is a
+          // contrast computation against the accent, which CSS cannot express.
+          '--color-accent-muted': ld(
+            accentWithAlpha(0.2),
+            accentWithAlpha(0.25),
+          ),
+          '--color-on-accent': ld(P[100], P[20]),
+        }
+      : null),
     '--color-neutral': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[90], 0.2)),
     '--color-background-surface': ld(N[99], N[10]),
     '--color-background-body': ld(N[95], N[5]),
@@ -168,8 +286,14 @@ export function expandColorScale(
     '--color-background-inverted': ld(N[10], N[99]),
 
     // Border
-    '--color-border': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[95], 0.1)),
-    '--color-border-emphasized': ld(NV[70], NV[30]),
+    // Border
+    // Decorative hairline — not a WCAG 1.4.11 boundary. High contrast
+    // doubles the alpha so structural boundaries stay perceivable.
+    '--color-border': ld(
+      hexWithAlpha(N[10], borderSubtleAlpha),
+      hexWithAlpha(N[95], borderSubtleAlpha),
+    ),
+    '--color-border-emphasized': borderEmphasized,
 
     // Effects
     '--color-skeleton': ld(NV[70], NV[30]),