@pieai/swimmer-ui-kit 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -3,6 +3,85 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 1.5.0 — 2026-08-22
+
+`swimmer-ui-check` now also fails on token pairs that cannot be read.
+
+The raw-colour rule kept consumers on tokens. It never stopped them choosing
+two tokens that do not contrast, and one pairing is genuinely inviting:
+`--game-ui-accent-ink` reads like "the ink for accent things" and means the
+opposite — accent-COLOURED ink, for a surface. Painted on `--game-ui-accent`
+it measures 1.48:1 on night and 1.91:1 on light. It reached a shipping
+product's primary button, the one control every user has to find, and every
+test that product had was green.
+
+PRODUCT.md promises contrast-safe token combinations. That promise only ever
+covered the pairs the kit uses itself; nothing checked the pairs a consumer
+built. Now something does.
+
+### Added
+
+- Contrast checking in `swimmer-ui-check`. Rules that set both a background
+  and a colour from bare tokens are resolved against this package's own
+  `dist/styles.css`, per theme, and reported below WCAG AA (4.5:1) with the
+  ratio and the theme named.
+
+### Notes on what it deliberately does not do
+
+- Only bare `var(--game-ui-x)` values are judged. `color-mix`, gradients and
+  anything composited are skipped: a tint of the accent behind accent-coloured
+  text is readable, and reading the first token out of the expression scores it
+  1.00:1. The first draft did that and flagged four rules that were fine — a
+  linter that cries wolf gets the next real finding skimmed too.
+- Tokens carrying alpha are skipped for the same reason. What they composite
+  against is not knowable from a stylesheet.
+
+### Compatibility
+
+Additive. Existing raw-colour behaviour is unchanged; a project that was clean
+stays clean unless it genuinely has an unreadable pair.
+
+## 1.4.0 — 2026-08-22
+
+The kit shipped an icon set that no consumer could see. Nothing was broken and
+nothing errored, which was the problem: with no setup the kit draws lettered
+placeholder squares, and a placeholder that looks deliberate gets shipped. A
+product could put eight identical coloured squares in its navigation and never
+file a bug, because it reads as a design choice rather than a missing step.
+
+The sculpted PNGs were never missing — 350 files travel inside the package, in
+`dist/assets`. What was missing was any route from there to a path the host
+actually serves. `CLAY_ASSET_BASE_PATH` names an absolute URL on the
+*consumer's* origin, and nothing copied, exported or explained it. The kit's own
+Storybook worked throughout, because its assets sit in `public/`.
+
+### Added
+
+- `swimmer-ui-assets [dir] [--base=…] [--force]` — a `bin` that copies the
+  sculpted set into a host's static root. Bundler-agnostic and explicit; no
+  postinstall, because a package that writes into your repo on install is worse
+  than the problem it solves.
+- `"./assets/*"` export, so bundler-based consumers can import an individual
+  file and get a content-hashed URL instead of copying the whole tree.
+- `setClayAssetBasePath()` / `getClayAssetBasePath()` for a CDN or a sub-path
+  deploy. Resolution rebases on the way out, so the variant table stays a
+  single source of truth.
+- A one-time `console.warn` the first time a placeholder is actually drawn,
+  naming the two commands that fix it, and `acknowledgeClayPlaceholders()` for
+  anyone using them on purpose.
+
+### Changed
+
+- README states plainly that the default is placeholders rather than the icon
+  set, and records that the sculpted family is 96px art which cannot take a
+  `currentColor` tint — so it is the wrong family for a dense nav rail or
+  toolbar however correctly it is served.
+
+### Compatibility
+
+Additive only. Defaults are unchanged, so every existing consumer renders
+exactly what it rendered before and gains one console line telling it why.
+
 ## 1.3.2 — 2026-08-17
 
 Follows 1.3.1 with the contrast work that release only half did. The new off

package/README.md

@@ -71,10 +71,39 @@ import '@pieai/swimmer-ui-kit/tailwind.css';
 - **Official themes**: light (default) and `night`
   (`<html data-game-ui-theme="night">`). Downstream theming = overriding
   semantic tokens; see the design system guide.
-- **Clay assets**: inline SVG mode by default (no asset hosting needed);
-  `setClayAssetMode('source')` switches to the sculpted PNG set, which
-  ships in `dist/assets/` for hosts to copy under
-  `/assets/game/ui/clay/…`.
+- **`swimmer-ui-check`**: lints your CSS for raw colour literals in component
+  rules *and* for token pairs that cannot be read. Two tokens are not
+  automatically safe together — `--game-ui-accent-ink` is accent-COLOURED ink
+  for a surface, `--game-ui-accent-contrast` is the ink meant to sit **on**
+  `--game-ui-accent`. Pairing the first with the accent measures 1.48:1.
+
+  ```bash
+  npx swimmer-ui-check src
+  ```
+
+- **Clay assets**: two lines of setup, and **skipping them is not a no-op**.
+  Out of the box the kit draws *placeholders* — one rounded square per icon
+  with a letter in it — not the icon set. They exist so a fresh install
+  renders something instead of a broken image, and they are not shippable.
+  The real sculpted PNGs travel inside the package and need serving:
+
+  ```bash
+  npx swimmer-ui-assets public      # copies dist/assets into your static root
+  ```
+  ```ts
+  import { setClayAssetMode } from '@pieai/swimmer-ui-kit';
+  setClayAssetMode('source');       // once, at your entry
+  ```
+
+  Serving them somewhere else — a CDN, a sub-path deploy — is
+  `setClayAssetBasePath('/my/path')`, and `swimmer-ui-assets public --base=/my/path`
+  mirrors the layout to match. If you *want* placeholders, say so with
+  `acknowledgeClayPlaceholders()` and the console notice goes quiet.
+
+  Note on sizing: the sculpted family is 96px art. Below roughly 24px it turns
+  to mud, and being PNG it cannot take a `currentColor` tint, so it is the
+  wrong family for a dense navigation rail or toolbar. Use the `line` style
+  there, or your own glyphs.
 - **Audio helper**: `playGameInteractionSound` (SSR-safe, opt-in via the
   `sound` prop on `GameButton`).
 

package/bin/swimmer-ui-assets.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Copy the sculpted clay asset set out of the package and into a directory the
+// consuming app actually serves.
+//
+// The kit resolves sculpted icons to absolute URLs under CLAY_ASSET_BASE_PATH
+// ('/assets/game/ui/clay/…'), which is a path on the *host's* origin. The files
+// themselves ship inside the package, in dist/assets. Nothing was closing that
+// gap, so every consumer had to discover it, and the default placeholder mode
+// meant the failure looked like a design choice rather than a missing step.
+//
+// Usage: swimmer-ui-assets [targetDir] [--base=/assets/game/ui/clay/...] [--force]
+//   targetDir  where the host serves static files from. Default "public".
+//   --base     the URL path to mirror under targetDir. Defaults to the kit's
+//              CLAY_ASSET_BASE_PATH, which is what setClayAssetMode('source')
+//              expects with no further configuration.
+//   --force    overwrite files that already exist (default: skip them).
+//
+// After running this, call setClayAssetMode('source') once at your app entry.
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_BASE = '/assets/game/ui/clay/phase03-clay-kit';
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith('--')));
+const positional = args.filter((a) => !a.startsWith('--'));
+
+// Two different paths that are easy to conflate: where the files sit inside
+// this package (fixed, mirrors the default URL under dist/) and where the host
+// will serve them from (--base, defaults to the same thing so the common case
+// needs no configuration).
+const trim = (p) => p.replace(/^\/+|\/+$/g, '');
+const baseFlag = args.find((a) => a.startsWith('--base='));
+const servedBase = trim(baseFlag ? baseFlag.slice('--base='.length) : DEFAULT_BASE);
+const targetRoot = resolve(process.cwd(), positional[0] ?? 'public');
+const force = flags.has('--force');
+
+const source = join(packageRoot, 'dist', trim(DEFAULT_BASE));
+if (!existsSync(source)) {
+  console.error(`swimmer-ui-assets: nothing to copy — ${source} does not exist.`);
+  console.error('This package may have been installed without its dist/assets tree.');
+  process.exit(1);
+}
+
+const destination = join(targetRoot, servedBase);
+
+function count(dir) {
+  let files = 0;
+  let bytes = 0;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      const inner = count(full);
+      files += inner.files;
+      bytes += inner.bytes;
+    } else {
+      files += 1;
+      bytes += stat.size;
+    }
+  }
+  return { files, bytes };
+}
+
+const { files, bytes } = count(source);
+
+mkdirSync(dirname(destination), { recursive: true });
+cpSync(source, destination, { recursive: true, force, errorOnExist: false });
+
+const megabytes = (bytes / 1024 / 1024).toFixed(1);
+console.log(`swimmer-ui-assets: copied ${files} files (${megabytes} MB)`);
+console.log(`  from  ${source}`);
+console.log(`  to    ${destination}`);
+console.log('');
+console.log('Now call this once at your app entry, or the kit keeps drawing placeholders:');
+console.log("  import { setClayAssetMode } from '@pieai/swimmer-ui-kit';");
+console.log("  setClayAssetMode('source');");
+if (!force) {
+  console.log('');
+  console.log('Existing files were left alone. Re-run with --force to overwrite.');
+}

package/bin/swimmer-ui-check.mjs

@@ -16,7 +16,8 @@
 //   dir      directory to scan, default "src"
 //   --ext    comma-separated extensions to scan, default "css"
 import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { extname, join, relative } from 'node:path';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const RAW_COLOR = /#[0-9a-fA-F]{3,8}\b|\brgba?\(|\bhsla?\(|\boklch\(/g;
 const TOKEN_BLOCK_SELECTOR = /:root\b|\[data-[\w-]*(?:theme|tone)[\w-]*\s*=/i;
@@ -94,6 +95,139 @@ function findViolations(css) {
   return violations;
 }
 
+/* ---------------------------------------------------------------------------
+ * Token pairs that cannot be read.
+ *
+ * The raw-colour rule above keeps consumers on tokens. It does not stop them
+ * choosing two tokens that do not contrast, and the names make one pairing
+ * genuinely inviting: `--game-ui-accent-ink` sounds like "the ink for accent
+ * things" and means the opposite — accent-COLOURED ink for a surface. Painted
+ * on `--game-ui-accent` it measured 1.48:1 in a shipping product, on that
+ * product's primary button, and every test it had was green.
+ *
+ * PRODUCT.md promises "contrast-safe token combinations". That promise only
+ * covers the pairs the kit uses itself unless something checks the consumer's.
+ * So: read the theme values out of the kit's own styles.css, find rules that
+ * set both a token background and a token colour, and compute the ratio.
+ * ------------------------------------------------------------------------- */
+
+const AA_NORMAL = 4.5;
+
+function parseHex(value) {
+  const hex = value.trim().replace(/^#/, '');
+  if (!/^[0-9a-fA-F]{3,8}$/.test(hex)) return null;
+  const full =
+    hex.length === 3 || hex.length === 4
+      ? hex
+          .slice(0, 3)
+          .split('')
+          .map((c) => c + c)
+          .join('')
+      : hex.slice(0, 6);
+  if (full.length !== 6) return null;
+  return [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16));
+}
+
+function relativeLuminance([r, g, b]) {
+  const channel = (v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+function contrastRatio(a, b) {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/**
+ * Token values per theme, read from the kit's shipped stylesheet.
+ *
+ * Only fully opaque hex values are kept. A token carrying alpha composites
+ * against whatever is behind it, and guessing that would produce confident
+ * numbers about a colour nobody can know from here.
+ */
+function themeTokens() {
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  // dist/ is what a consumer installs. src/theme.css is what exists in this
+  // repository before a build — and `pnpm test` runs before `pnpm build`, so
+  // reading only dist made the check a silent no-op in its own CI while
+  // passing locally off a stale dist. Silence is the failure mode this whole
+  // check exists to remove, so it must not be the failure mode of the check.
+  const sources = [join(packageRoot, 'dist', 'styles.css'), join(packageRoot, 'src', 'theme.css')];
+  let css = null;
+  for (const candidate of sources) {
+    try {
+      css = readFileSync(candidate, 'utf8');
+      break;
+    } catch {
+      // try the next one
+    }
+  }
+  if (css === null) return null;
+  const themes = new Map();
+  // The built stylesheet is minified and the attribute value loses its quotes,
+  // so both forms have to match or every theme but the default is invisible.
+  const blockRe = /(:root|\[data-game-ui-theme=['"]?([\w-]+)['"]?\])\s*\{([^}]*)\}/g;
+  for (const match of css.matchAll(blockRe)) {
+    const name = match[2] ?? 'light';
+    const values = themes.get(name) ?? new Map(themes.get('light') ?? []);
+    for (const decl of match[3].matchAll(/(--game-ui-[\w-]+)\s*:\s*(#[0-9a-fA-F]{3,8})/g)) {
+      const rgb = decl[2].length === 9 || decl[2].length === 5 ? null : parseHex(decl[2]);
+      if (rgb) values.set(decl[1], rgb);
+    }
+    themes.set(name, values);
+  }
+  return themes;
+}
+
+/**
+ * A bare token reference and nothing else: `var(--game-ui-x)` or
+ * `var(--game-ui-x, #fallback)`.
+ *
+ * Deliberately refuses `color-mix(in srgb, var(--game-ui-accent) 18%,
+ * transparent)` and gradients. A tint of the accent behind accent-coloured
+ * text is perfectly readable, and reading the first token out of the
+ * expression would call it 1.00:1 — the first draft of this check did exactly
+ * that and flagged four rules that were fine. A linter that cries wolf is
+ * worse than no linter, because the next real finding gets skimmed too.
+ */
+const BARE_TOKEN = /^\s*var\(\s*(--game-ui-[\w-]+)\s*(?:,[^()]*)?\)\s*$/;
+
+function findContrastViolations(css, themes) {
+  if (!themes || themes.size === 0) return [];
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+  const lineOf = lineFinder(withoutComments);
+  const out = [];
+  const ruleRe = /\{([^{}]*)\}/g;
+  for (const rule of withoutComments.matchAll(ruleRe)) {
+    const body = rule[1];
+    const bg = /(?:^|[;\s])background(?:-color)?\s*:\s*([^;]+)/.exec(body);
+    const fg = /(?:^|[;\s])color\s*:\s*([^;]+)/.exec(body);
+    if (!bg || !fg) continue;
+    const bgToken = BARE_TOKEN.exec(bg[1])?.[1];
+    const fgToken = BARE_TOKEN.exec(fg[1])?.[1];
+    if (!bgToken || !fgToken) continue;
+    for (const [theme, values] of themes) {
+      const bgRgb = values.get(bgToken);
+      const fgRgb = values.get(fgToken);
+      if (!bgRgb || !fgRgb) continue;
+      const ratio = contrastRatio(bgRgb, fgRgb);
+      if (ratio >= AA_NORMAL) continue;
+      out.push({
+        line: lineOf(rule.index + 1),
+        theme,
+        fgToken,
+        bgToken,
+        ratio: ratio.toFixed(2),
+      });
+    }
+  }
+  return out;
+}
+
 const args = process.argv.slice(2);
 const target = args.find((a) => !a.startsWith('--')) ?? 'src';
 const extArg = args.find((a) => a.startsWith('--ext='));
@@ -111,9 +245,24 @@ try {
   process.exit(2);
 }
 
+const themes = themeTokens();
+if (!themes || themes.size === 0) {
+  console.error(
+    "swimmer-ui-check: could not read this package's theme tokens, so contrast was NOT checked. " +
+      'Raw-colour linting below still ran.',
+  );
+}
+let contrastCount = 0;
 let violationCount = 0;
 for (const file of files) {
   const text = readFileSync(file, 'utf8');
+  for (const pair of findContrastViolations(text, themes)) {
+    console.log(
+      `${relative(process.cwd(), file)}:${pair.line}: ${pair.fgToken} on ${pair.bgToken} is ` +
+        `${pair.ratio}:1 on the ${pair.theme} theme — below AA (${AA_NORMAL}:1)`,
+    );
+    contrastCount += 1;
+  }
   for (const violation of findViolations(text)) {
     console.log(
       `${relative(process.cwd(), file)}:${violation.line}: raw color literal "${violation.text}" — use var(--game-ui-*) instead`,
@@ -122,7 +271,15 @@ for (const file of files) {
   }
 }
 
-if (violationCount > 0) {
+if (contrastCount > 0) {
+  console.error(
+    `\nswimmer-ui-check: ${contrastCount} unreadable token pair(s). Two tokens are not ` +
+      'automatically safe together: --game-ui-accent-ink is accent-COLOURED ink for a surface, ' +
+      'while --game-ui-accent-contrast is the ink meant to sit on --game-ui-accent.',
+  );
+}
+
+if (violationCount > 0 || contrastCount > 0) {
   console.error(
     `\nswimmer-ui-check: ${violationCount} raw color literal(s) in ${files.length} file(s) under "${target}". ` +
       'Raw colors are expected inside :root / [data-*theme*=...] / [data-*tone*=...] token blocks ' +

package/dist/index.d.ts

@@ -6,6 +6,9 @@ import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
 import { TextareaHTMLAttributes } from 'react';
 
+/** Opt in to placeholders on purpose, and stop being told about it. */
+export declare function acknowledgeClayPlaceholders(): void;
+
 export declare const CLAY_ASSET_BASE_PATH: "/assets/game/ui/clay/phase03-clay-kit";
 
 export declare const CLAY_ASSET_SIZE_TOKENS: {
@@ -1852,6 +1855,8 @@ export declare interface GameWindowPanelProps extends Omit<HTMLAttributes<HTMLEl
 
 export declare type GameWindowState = 'normal' | 'minimized' | 'maximized';
 
+export declare function getClayAssetBasePath(): string;
+
 export declare function getClayAssetMode(): ClayAssetMode;
 
 export declare function getClayCatalogPaths(): typeof CLAY_ASSETS.catalog;
@@ -1867,11 +1872,23 @@ export declare function playGameInteractionSound(options?: GameInteractionSoundO
 
 export declare function playGameInteractionSoundForContext(audioContext: GameInteractionAudioContext, options?: GameInteractionSoundOptions): boolean;
 
+/**
+ * Point the sculpted set at somewhere other than the default path — a CDN, a
+ * sub-path deploy, a host whose static root is not `/`. Pass no trailing slash.
+ *
+ * The copy command mirrors the default layout, so a consumer that runs
+ * `swimmer-ui-assets public` never needs this.
+ */
+export declare function setClayAssetBasePath(basePath: string): void;
+
 /**
  * Switch how clay icons resolve globally.
- * - 'inline' (default): zero-dependency SVG placeholders, no assets required.
- * - 'source': the real clay game-icon PNG paths under CLAY_ASSET_BASE_PATH.
- *   The host app must serve those assets (e.g. copy them into its public/).
+ * - 'inline' (default): lettered placeholders. They are not the icon set —
+ *   every one is the same rounded square with a different glyph and colour.
+ *   They exist so a fresh install renders *something* rather than a broken
+ *   image, and shipping them is a bug.
+ * - 'source': the real sculpted PNGs under the base path. Get the files there
+ *   with `npx swimmer-ui-assets <publicDir>`.
  */
 export declare function setClayAssetMode(mode: ClayAssetMode): void;