fix(web): text on a tint of its own hue uses the house -fg tokens (#3150)

A hue painted as text on a color-mix tint of itself sits close to the
surface under it. On Minstrel's surfaces the raw accent on its 15% tint
measures 1.97:1 at worst (dark mode, hover surface), against AA's 4.5.

- tokens.json gains colors.fg: the five FabledSword -fg formulas (accent
  45%, success 45%, warning, error and info 50%), each mixed toward
  parchment so one declaration serves both modes. Success is Minstrel's
  moss. tokens-to-css emits them in :root.
- Tailwind exposes them as text-accent-fg, text-warning-fg, text-error-fg
  and text-info-fg.
- 23 sites swapped: 14 Tailwind class strings (PlayerBar and the admin
  count pills) and 9 CSS rules (StatusPill's four tones and five accent
  chips). Worst case after: accent-fg 5.03, error-fg 4.75, warning-fg
  4.92, success-fg 4.85.
- scripts/check-tint-contrast.js finds the pair in either spelling. Its
  test scans src in the web Vitest lane and fails on any new site, with
  fixture cases showing it can fail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

web/scripts/check-tint-contrast.js

@@ -0,0 +1,89 @@
+// Finds a hue painted as TEXT on a tint of itself (#3150). The tint sits close
+// to the surface under it, so the raw hue on it measures 1.6–2.4:1 against
+// AA's 4.5. The fix is the hue's -fg partner (tokens.json colors.fg), mixed
+// toward parchment: accent-fg on an accent tint measures 5.03.
+//
+// Two spellings are checked:
+//   Tailwind  one class string holding both `bg-X-tint` / `bg-X/NN` and `text-X`
+//   CSS       one rule block holding both a `color-mix(… var(--fs-X) N%,
+//             transparent)` background and `color: var(--fs-X)`
+//
+// A pair split across two strings (a tint in one class: directive, the text
+// in another) is not seen. The lookbehind on `color:` keeps border-color and
+// outline-color out: a border is a graphic with a 3:1 floor, not text.
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export const HUES = {
+  accent: 'accent-fg',
+  warning: 'warning-fg',
+  error: 'error-fg',
+  info: 'info-fg',
+  moss: 'success-fg'
+};
+
+// The quoted string around index i. Read outward from the tint class rather
+// than pairing every quote in the file, which an apostrophe in prose
+// ("Couldn't") throws out of step.
+function enclosingString(source, i) {
+  const start = Math.max(...['"', "'", '`'].map((q) => source.lastIndexOf(q, i)));
+  if (start < 0) return '';
+  const end = source.indexOf(source[start], i);
+  return end < 0 ? '' : source.slice(start, end + 1);
+}
+
+/** Tailwind class strings that put text-X on a bg-X tint. */
+export function findTailwind(source) {
+  const found = [];
+  for (const hue of Object.keys(HUES)) {
+    const tint = new RegExp(`(?<=^|[\\s'"\`])bg-${hue}(?:-tint|/\\d+)(?=$|[\\s'"\`])`, 'g');
+    const text = new RegExp(`(?:^|[\\s'"\`])text-${hue}(?=$|[\\s'"\`])`);
+    for (const m of source.matchAll(tint)) {
+      if (text.test(enclosingString(source, m.index))) {
+        found.push({ hue, index: m.index, fix: `text-${hue === 'moss' ? 'success' : hue}-fg` });
+      }
+    }
+  }
+  return found;
+}
+
+/** CSS rule blocks that put color: var(--fs-X) on a color-mix tint of X. */
+export function findCss(source) {
+  const found = [];
+  for (const m of source.matchAll(/\{([^{}]*)\}/g)) {
+    for (const hue of Object.keys(HUES)) {
+      const tint = new RegExp(
+        `background(?:-color)?\\s*:\\s*color-mix\\(\\s*in srgb\\s*,\\s*var\\(--fs-${hue}\\)\\s*\\d+%\\s*,\\s*transparent\\s*\\)`
+      );
+      const text = new RegExp(`(?<![-\\w])color\\s*:\\s*var\\(--fs-${hue}\\)`);
+      if (tint.test(m[1]) && text.test(m[1])) {
+        found.push({ hue, index: m.index, fix: `var(--fs-${HUES[hue]})` });
+      }
+    }
+  }
+  return found;
+}
+
+function lineOf(source, index) {
+  return source.slice(0, index).split('\n').length;
+}
+
+function* walk(dir) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) yield* walk(path);
+    else if (/\.(svelte|ts|js|css)$/.test(name) && !/\.test\.(ts|js)$/.test(name)) yield path;
+  }
+}
+
+/** Every violation under root, as "path:line hue → fix". */
+export function scan(root, base = root) {
+  const out = [];
+  for (const path of walk(root)) {
+    const source = readFileSync(path, 'utf8');
+    for (const f of [...findTailwind(source), ...findCss(source)]) {
+      out.push(`${relative(base, path)}:${lineOf(source, f.index)} ${f.hue} → ${f.fix}`);
+    }
+  }
+  return out;
+}

web/scripts/check-tint-contrast.test.js

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'vitest';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { findCss, findTailwind, scan } from './check-tint-contrast.js';
+
+const web = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+describe('hue-on-own-tint check (#3150)', () => {
+  test('no source paints a hue as text on a tint of itself', () => {
+    expect(scan(resolve(web, 'src'), web)).toEqual([]);
+  });
+
+  describe('Tailwind', () => {
+    test('finds text-X on bg-X-tint and bg-X/NN in one class string', () => {
+      expect(findTailwind(`class="rounded bg-accent-tint px-2 text-accent"`)).toHaveLength(1);
+      expect(findTailwind(`'bg-error/15 text-error'`)).toHaveLength(1);
+      expect(findTailwind("`bg-moss/10 text-moss`")[0].fix).toBe('text-success-fg');
+    });
+
+    test('a class string spanning lines is one string', () => {
+      expect(findTailwind(`class="bg-accent-tint\n  text-accent"`)).toHaveLength(1);
+    });
+
+    test('an apostrophe earlier in the file does not hide a pair', () => {
+      expect(
+        findTailwind(`<p>Couldn't add</p>\n<span class={on ? 'bg-accent-tint text-accent' : ''}>`)
+      ).toHaveLength(1);
+    });
+
+    test('passes the -fg partner, another hue, and a tint with no hue text', () => {
+      expect(findTailwind(`"bg-accent-tint text-accent-fg"`)).toEqual([]);
+      expect(findTailwind(`"bg-accent-tint text-error"`)).toEqual([]);
+      expect(findTailwind(`"bg-accent-tint text-text-primary"`)).toEqual([]);
+      expect(findTailwind(`"text-accent"`)).toEqual([]);
+    });
+  });
+
+  describe('CSS', () => {
+    const tinted = (color) =>
+      `.pill { background: color-mix(in srgb, var(--fs-warning) 15%, transparent); ${color} }`;
+
+    test('finds color: var(--fs-X) on a color-mix tint of X', () => {
+      expect(findCss(tinted('color: var(--fs-warning);'))).toHaveLength(1);
+      expect(findCss(tinted('color: var(--fs-warning);'))[0].fix).toBe('var(--fs-warning-fg)');
+    });
+
+    test('passes the -fg partner and border or outline colours', () => {
+      expect(findCss(tinted('color: var(--fs-warning-fg);'))).toEqual([]);
+      expect(findCss(tinted('border-color: var(--fs-warning);'))).toEqual([]);
+      expect(findCss(tinted('outline-color: var(--fs-warning);'))).toEqual([]);
+    });
+
+    test('a tint and a colour in different rules are not a pair', () => {
+      expect(
+        findCss(
+          `.a { background: color-mix(in srgb, var(--fs-accent) 15%, transparent); }\n.b { color: var(--fs-accent); }`
+        )
+      ).toEqual([]);
+    });
+  });
+});

web/scripts/tokens-to-css.js

@@ -19,6 +19,14 @@ export function emit(tokens) {
   for (const [name, value] of Object.entries(tokens.colors.flat)) {
     lines.push(`  --fs-${name}: ${value};`);
   }
+  // The house -fg tokens (FabledSword, 2026-08-27; #3150): a hue as TEXT on a
+  // tint of itself, mixed toward parchment. Parchment inverts in light mode,
+  // so one declaration lightens the text on dark surfaces and darkens it on
+  // light ones. Declared on :root, the element data-theme is set on, so the
+  // var()s resolve against that mode's parchment.
+  for (const [name, value] of Object.entries(tokens.colors.fg ?? {})) {
+    lines.push(`  --fs-${name}: ${value};`);
+  }
   for (const [name, value] of Object.entries(tokens.radii)) {
     lines.push(`  --fs-radius-${name}: ${value};`);
   }

web/scripts/tokens-to-css.test.js

@@ -5,7 +5,8 @@ const sample = {
   colors: {
     dark:  { obsidian: '#000', parchment: '#FFF' },
     light: { obsidian: '#FFF', parchment: '#000' },
-    flat:  { accent: '#4A6B5C', 'on-action': '#E8E4D8' }
+    flat:  { accent: '#4A6B5C', 'on-action': '#E8E4D8' },
+    fg:    { 'accent-fg': 'color-mix(in srgb, var(--fs-accent) 45%, var(--fs-parchment))' }
   },
   radii: { sm: '4px' },
   fontStacks: {
@@ -40,4 +41,13 @@ describe('tokens-to-css emit()', () => {
     expect(css).toContain('--fs-radius-sm: 4px;');
     expect(css).toContain("--fs-font-display: 'Fraunces', serif;");
   });
+
+  test('emits the -fg tokens in :root, not the light block', () => {
+    const css = emit(sample);
+    const root = css.match(/:root \{([\s\S]*?)\}/);
+    expect(root).not.toBeNull();
+    expect(root[1]).toContain('--fs-accent-fg: color-mix(in srgb, var(--fs-accent) 45%, var(--fs-parchment));');
+    const light = css.match(/\[data-theme="light"\] \{([\s\S]*?)\}/);
+    expect(light[1]).not.toContain('-fg');
+  });
 });