@crewlethq/ui 0.2.0 → 0.3.0

package/dist/utils/cx.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Joining a class list, once for the whole package.
+ *
+ * Every component had its own copy of `[a, b].filter(Boolean).join(' ')`, and
+ * Skeleton declared a named one beside it. A helper spelled nine times is a
+ * helper whose copies come to disagree about what a `0` means; this one drops
+ * every falsy part, so a `count && 'has-count'` guard cannot render the number
+ * into the class attribute.
+ */
+export declare function cx(...parts: (string | false | null | undefined)[]): string;

package/dist/utils/headingLevel.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+/** The heading elements a component may render. */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export interface HeadingLevelProviderProps {
+    /** The level the children's own headings start at. */
+    level: HeadingLevel;
+    children?: ReactNode;
+}
+/** Declares the level a surface's contents start at. */
+export declare function HeadingLevelProvider({ level, children }: HeadingLevelProviderProps): import("react/jsx-runtime").JSX.Element;
+/** The level a heading rendered here should be. Defaults to 2, under a page title. */
+export declare function useHeadingLevel(): HeadingLevel;
+/** One level deeper, clamped at 6. */
+export declare function nextHeadingLevel(level: HeadingLevel): HeadingLevel;
+/** The tag name for a level, for a component that renders one. */
+export declare function headingTag(level: HeadingLevel): `h${HeadingLevel}`;

package/dist/utils/index.d.ts

@@ -0,0 +1,6 @@
+export { cx } from './cx.js';
+export { useClipboard } from './useClipboard.js';
+export type { Clipboard, ClipboardOptions, ClipboardState } from './useClipboard.js';
+export type { PhaseTone, Tone } from './tone.js';
+export { HeadingLevelProvider, headingTag, nextHeadingLevel, useHeadingLevel } from './headingLevel.js';
+export type { HeadingLevel, HeadingLevelProviderProps } from './headingLevel.js';

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+import '../chunk-IJ7QXNIJ.js';
+export { useClipboard } from '../chunk-V663QU4R.js';
+export { HeadingLevelProvider, headingTag, nextHeadingLevel, useHeadingLevel } from '../chunk-PQADV6P6.js';
+export { cx } from '../chunk-ODEQTPFM.js';

package/dist/utils/tone.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The two colour vocabularies a component is allowed to take as a prop.
+ *
+ * ONE SPELLING. The package shipped `warn` in Tag and Toaster and `warning` in
+ * StatCard and Callout, and `danger` beside `error`, so the same state had two
+ * names depending on which component drew it. A union declared once is what
+ * stops the next component inventing a third.
+ *
+ * A tone says what a thing IS, never who it is: success, warning, danger and
+ * info are states, `brand` is where the reader is, and everything else is
+ * neutral. Identity (a seat, a node, a vendor, a tool) takes neutral colour and
+ * is carried by its name, its glyph and its position.
+ */
+export type Tone = 'neutral' | 'info' | 'success' | 'warning' | 'danger' | 'brand';
+/**
+ * The phase vocabulary, and nothing else.
+ *
+ * Three phases, because that is the whole of the engine's phase model. A
+ * per-model or per-worker breakdown is a CHART SERIES SET and takes the data
+ * ramp (`--color-data-1` and the rest) inside a legend, not this family: a
+ * reader compares phase marks against each other, so the three are separated
+ * from one another and from every status hue, which a growing set of series
+ * could not be.
+ */
+export type PhaseTone = 'phase-onboarding' | 'phase-execute' | 'phase-review';

package/dist/utils/useClipboard.d.ts

@@ -0,0 +1,30 @@
+export type ClipboardState = 'idle' | 'copied' | 'failed';
+export interface ClipboardOptions {
+    /** How long the copied or failed answer stands before the control settles back. */
+    resetMs?: number;
+}
+export interface Clipboard {
+    state: ClipboardState;
+    copy: (text: string | (() => string)) => Promise<boolean>;
+}
+/**
+ * Putting text on the clipboard, and saying whether it arrived.
+ *
+ * TWO THINGS ARE LOAD BEARING, and both were wrong before this existed.
+ *
+ * 1. THE CLIPBOARD API IS NOT ALWAYS THERE. It is gated on a secure context,
+ *    so `navigator.clipboard` is simply undefined on the plain http origin
+ *    anybody reads a dashboard at that is not their own laptop. An optional
+ *    call made that failure silent: the button clicked, nothing was copied,
+ *    and nothing said so. The `execCommand` fallback is deprecated and is
+ *    also the only thing that works there, so it stays, and its boolean
+ *    result is honoured rather than assumed.
+ * 2. A COPY WITH NO FEEDBACK IS A DEAD BUTTON. The clipboard is invisible;
+ *    the only way a reader learns it worked is if the control says so, which
+ *    is what `state` is for.
+ *
+ * The text may be a THUNK, resolved on the press. On a live screen the thing
+ * worth copying is assembled from everything on it, so a string prop means
+ * building it again on every push for a control nobody has touched.
+ */
+export declare function useClipboard({ resetMs }?: ClipboardOptions): Clipboard;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewlethq/ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Crewlet shared React components built on @crewlethq/tokens and @crewlethq/icons.",
   "license": "MIT",
   "repository": {
@@ -24,21 +24,26 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./styles.css": "./dist/styles.css"
+    "./styles.css": "./dist/styles.css",
+    "./*": {
+      "types": "./dist/*/index.d.ts",
+      "import": "./dist/*/index.js"
+    }
   },
   "files": [
-    "dist"
+    "dist",
+    "scripts"
   ],
   "scripts": {
-    "build": "tsup && node scripts/bundle-css.mjs",
-    "dev": "tsup --watch --onSuccess \"node scripts/bundle-css.mjs\"",
-    "lint": "eslint src scripts && node scripts/check-css-variables.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist"
+    "build": "node scripts/write-barrel.mjs && tsup && tsc -p tsconfig.build.json && node scripts/bundle-css.mjs",
+    "dev": "node scripts/write-barrel.mjs && tsup --watch --onSuccess \"node scripts/bundle-css.mjs\"",
+    "lint": "node scripts/write-barrel.mjs && eslint src scripts && node scripts/check-css-variables.mjs && node scripts/check-css-literals.mjs src/Avatar src/Layer src/Listbox src/Announcer src/Modal src/Tooltip src/CommandPalette src/VisuallyHidden src/utils src/Count src/StatusDot src/EmptyValue src/Button src/IconButton src/Popover src/Menu src/DataView src/DataTable src/Input src/Tag src/TagGroup src/FilterChip src/EntityChip src/Callout src/Toaster src/Skeleton src/EmptyState src/Meter src/StatCard src/StatGroup src/NewItemsNotice src/PricingCard src/ImageUpload src/Tabs src/SegmentedControl src/PageHeader src/Card src/Section src/Charts src/Layout src/Canvas src/Tree src/TreeCanvas src/TreeGrid src/OrgNode src/OrgLabel src/AddPill src/OrgTable",
+    "typecheck": "node scripts/write-barrel.mjs && tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist src/generated"
   },
   "dependencies": {
-    "@crewlethq/icons": "0.2.0",
-    "@crewlethq/tokens": "0.2.0"
+    "@crewlethq/icons": "0.3.0",
+    "@crewlethq/tokens": "0.3.0"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -54,5 +59,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "crewlet-css-check": "./scripts/check-css.mjs"
   }
 }

package/scripts/bundle-css.mjs

@@ -0,0 +1,25 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// tsup emits hashed CSS chunks that the compiled JS imports via side-effect.
+// We additionally publish a single dist/styles.css containing the same rules,
+// so consumers can do either:
+//   (1) import { Button } from '@crewlethq/ui'      // CSS auto-loads via side-effect
+//   (2) import '@crewlethq/ui/styles.css'           // single bundle (SSR / non-tree-shaking consumers)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const dist = resolve(__dirname, '..', 'dist');
+
+const all = await readdir(dist);
+const chunks = all.filter((f) => f.endsWith('.css') && f !== 'styles.css').sort();
+
+const parts = await Promise.all(
+  chunks.map(async (f) => `/* ${f} */\n${await readFile(resolve(dist, f), 'utf8')}`),
+);
+
+await writeFile(
+  resolve(dist, 'styles.css'),
+  parts.length === 0 ? '/* empty */\n' : parts.join('\n\n'),
+);
+
+console.warn(`[ui] bundled ${chunks.length} css chunk(s) into styles.css`);

package/scripts/check-css-literals.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Refuses a value a component should have taken from a token, over the folders
+// it is given.
+//
+// WHY IT TAKES FOLDERS. Its sibling, check-css-variables.mjs, runs over the
+// whole package and holds rules no component may break at any point. This one
+// holds the rules a folder OPTS INTO as it is rewritten onto the token layer,
+// so a component that has not been rewritten yet does not have to be
+// allow-listed to keep the build green. The list of folders in the package's
+// lint script is the record of which are done; when the last one lands, the
+// list becomes `src` and this paragraph goes with it.
+//
+// It is also the published bin, `crewlet-css-check`, so a consumer can hold
+// its own stylesheets to the same rules.
+//
+// THE RULES.
+//
+//  1. No colour literal. A hex, an rgb(), an hsl() or a named colour is a
+//     colour that does not follow the theme, and a fallback literal inside
+//     var() is the same thing with a comforting shape: it is what renders
+//     whenever the token name is misspelt, so it hides the very failure it
+//     looks like insurance against.
+//  2. No px font size, no literal radius, no literal duration, no literal
+//     z-index. Each of those is a scale, and a component that spends a number
+//     off the scale is a component that drifts from the one beside it.
+//  3. No color-mix(). Mixing two tokens produces a third colour nobody
+//     measured, which is how a "warning text" step ended up at 4.41:1.
+//  4. An animation or a transition is paired with a reduced-motion rule IN THE
+//     SAME FILE. The document baseline collapses motion too, but a component
+//     is also used in an application that does not import the baseline.
+//  5. A media query's length is one of the breakpoint tokens. A media query
+//     cannot read a custom property, so the number has to be written out; this
+//     is what says it is still the same number.
+//  6. No hover overlay on a pseudo element. A row shows the selected tint or
+//     the hover overlay, never both, because both are a background on the same
+//     element and the selected state wins. Drawing the hover on a ::before is
+//     the one way to stack them, and it produces a composite nothing measured.
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { lineOf, readSources, report, rules } from './css-source.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const NAMED_COLOURS =
+  /\b(aqua|black|blue|fuchsia|gray|grey|green|lime|maroon|navy|olive|purple|red|silver|teal|white|yellow|orange|pink|brown|violet|indigo|gold|beige|coral|crimson|cyan|magenta|salmon|tan|turquoise)\b/;
+const HEX = /#[0-9a-fA-F]{3,8}\b/;
+const COLOUR_FUNCTION = /\b(rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\s*\(/;
+const DURATION = /(?<![\w-])\d*\.?\d+m?s\b/;
+const LENGTH_IN_QUERY = /(\d*\.?\d+)px/g;
+
+/** Properties whose value is a colour, so a literal in one is a colour literal. */
+const COLOUR_PROPERTY =
+  /^(color|background|background-color|border(-(top|right|bottom|left))?-color|border|border-(top|right|bottom|left)|outline|outline-color|fill|stroke|box-shadow|text-shadow|caret-color|column-rule-color|text-decoration-color|accent-color|scrollbar-color|--crewlet-[\w-]*)$/;
+
+function declarations(body) {
+  const found = [];
+  for (const part of body.split(';')) {
+    const at = part.indexOf(':');
+    if (at < 0) continue;
+    found.push({ property: part.slice(0, at).trim().toLowerCase(), value: part.slice(at + 1).trim() });
+  }
+  return found;
+}
+
+/** A value with every var() reference removed, so only its own literals remain. */
+function withoutTokens(value) {
+  let text = value;
+  let previous;
+  do {
+    previous = text;
+    // Innermost var() first, so a nested fallback is stripped with its parent.
+    text = text.replace(/var\(\s*--[\w-]+\s*(?:,[^()]*)?\)/g, ' ');
+  } while (text !== previous);
+  return text;
+}
+
+/**
+ * The breakpoint steps, from the tokens package's own typed export.
+ *
+ * `import.meta.resolve` rather than `createRequire().resolve`: the tokens
+ * package declares only an `import` condition, so CJS resolution refuses its
+ * main entry outright.
+ */
+async function breakpoints() {
+  const { breakpoint } = await import(import.meta.resolve('@crewlethq/tokens'));
+  return new Set(Object.values(breakpoint).map((value) => Number.parseFloat(String(value))));
+}
+
+export async function findings(roots, base = packageRoot) {
+  const files = readSources(roots, base, /\.css$/);
+  const problems = [];
+  const allowed = await breakpoints();
+
+  for (const file of files) {
+    const at = (index) => `${file.where}:${lineOf(file.text, index)}`;
+    const hasReducedMotion = file.text.includes('prefers-reduced-motion');
+
+    for (const { selector, body, index } of rules(file.text)) {
+      const where = at(index);
+      const inQuery = /@media/.test(selector);
+
+      if (inQuery) {
+        for (const match of selector.matchAll(LENGTH_IN_QUERY)) {
+          if (!allowed.has(Number(match[1]))) {
+            problems.push(
+              `${where}: the media query switches at ${match[0]}, which is not a breakpoint token. Use one of ${[...allowed].sort((a, b) => a - b).join('px, ')}px, or add the step to packages/tokens/tokens/breakpoint.json`,
+            );
+          }
+        }
+      }
+
+      if (/:hover\s*::?(before|after)\b/.test(selector) && /(^|;|\s)background/.test(body)) {
+        problems.push(
+          `${where}: draws a hover overlay on a pseudo element. A row shows the selected tint or the hover overlay, never both, and a pseudo element is the one way to stack them into a composite nothing has measured`,
+        );
+      }
+
+      for (const { property, value } of declarations(body)) {
+        const bare = withoutTokens(value);
+        const colourish = COLOUR_PROPERTY.test(property);
+        if (colourish && (HEX.test(bare) || COLOUR_FUNCTION.test(bare) || NAMED_COLOURS.test(bare))) {
+          problems.push(`${where}: ${property} carries a colour literal (${value.trim()}). Every colour comes from a token`);
+        }
+        if (value.includes('color-mix(')) {
+          problems.push(
+            `${where}: ${property} uses color-mix(), which makes a colour nobody measured. Add the step to packages/tokens/tokens/ instead`,
+          );
+        }
+        if (property === 'font-size' && /(?<![\w-])\d*\.?\d+(px|rem|em)\b/.test(bare)) {
+          problems.push(`${where}: font-size is a literal (${value.trim()}). Use a --font-size-* token`);
+        }
+        if (/^border(-[a-z]+)?-radius$/.test(property) && /(?<![\w-])\d*\.?\d+(px|rem|em)\b/.test(bare)) {
+          problems.push(`${where}: ${property} is a literal (${value.trim()}). Use a --radius-* token`);
+        }
+        if (/^(transition|animation)(-duration|-delay)?$/.test(property) && DURATION.test(bare)) {
+          problems.push(`${where}: ${property} carries a literal duration (${value.trim()}). Use a --motion-duration-* token`);
+        }
+        if (property === 'z-index' && /^-?\d+$/.test(bare.trim()) && Math.abs(Number(bare.trim())) > 1) {
+          problems.push(`${where}: z-index is a literal (${value.trim()}). Use a --z-index-* token, or the Layer module's own depth`);
+        }
+      }
+    }
+
+    if (!hasReducedMotion && /(^|[;{\s])(animation|transition)\s*:/.test(file.text)) {
+      problems.push(
+        `${file.where}: animates or transitions with no prefers-reduced-motion rule in the file. The document baseline is opt-in, so a component states its own`,
+      );
+    }
+  }
+
+  return { problems, checked: `${files.length} stylesheets in ${roots.length} folder(s)` };
+}
+
+async function main() {
+  const roots = process.argv.slice(2).map((path) => resolve(process.cwd(), path));
+  if (roots.length === 0) {
+    console.error('usage: check-css-literals.mjs <folder> [folder...]');
+    process.exitCode = 2;
+    return;
+  }
+  const { problems, checked } = await findings(roots);
+  report('CSS literal check', problems, checked);
+}
+
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) await main();

package/scripts/check-css-variables.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// The rules EVERY component in the package keeps, checked over all of src/.
+//
+// Its sibling, check-css-literals.mjs, holds the rules a folder opts into as
+// it is rewritten onto the token layer. These are the ones nothing may break
+// at any point, because each of them fails silently in production:
+//
+//   1. A name in a token namespace (--color-*, --font-*, --spacing-* and the
+//      rest of TOKEN_PREFIXES) must be one the @crewlethq/tokens build emits,
+//      whether or not the reference carries a fallback. A `var(--name)` that
+//      resolves to nothing is not an error the browser reports: the property
+//      falls back to its initial value, and a `var(--name, x)` with a misspelt
+//      name quietly renders `x` forever.
+//   2. Every other name belongs to a component and is namespaced --crewlet-*,
+//      both where it is read and where it is declared, so a component never
+//      claims a name an application stylesheet may already use.
+//   3. A --crewlet-* name read without a fallback must be declared somewhere
+//      in the scanned source.
+//   4. No glyph is drawn as a Material Symbols ligature. A component that
+//      spells `material-symbols-outlined` renders the WORD until a stylesheet
+//      it does not own has fetched a font from a third-party host, and renders
+//      that word for good on a closed network.
+//   5. Nothing loads from a host: no `url()` with a scheme or a protocol
+//      relative path, and no `@import` of a remote stylesheet. A design system
+//      that phones home is one an air-gapped deployment cannot use and a
+//      strict Content-Security-Policy refuses.
+//   6. No `body.theme-*` selector. The theme is a contract on the ROOT element
+//      now, and a body class silently paints nothing.
+//   7. `--color-text-muted` is the DECORATION step, measured into the 2.8 to
+//      4.5 band on purpose, so it is never the `color` of anything but an svg.
+//      Anything a reader has to make out takes --color-text-tertiary.
+//   8. A `:focus-visible` rule does not turn the outline off without putting
+//      one back. Forced-colors mode drops every box-shadow and keeps outlines,
+//      so a ring drawn as a shadow alone disappears for exactly the readers
+//      who most need one. A component that also wants a shadow pairs it with a
+//      transparent outline, which forced colors then substitutes into.
+//
+// It reads the built token stylesheets, so it runs after the tokens build; the
+// turbo lint task depends on it.
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { lineOf, readSources, report, rules, withoutComments } from './css-source.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const TOKEN_PREFIXES = [
+  '--blur-',
+  '--breakpoint-',
+  '--color-',
+  '--density',
+  '--font-',
+  '--motion-',
+  '--radius-',
+  '--shadow-',
+  '--size-',
+  '--spacing-',
+  '--z-index-',
+];
+const COMPONENT_PREFIX = '--crewlet-';
+
+const NAME = '--[A-Za-z0-9_-]+';
+const REFERENCE = new RegExp(`var\\(\\s*(${NAME})\\s*(,)?`, 'g');
+// A declaration in a stylesheet: the name at the start of a declaration.
+const CSS_DECLARATION = new RegExp(`(?:^|[{;\\s])(${NAME})\\s*:`, 'g');
+// A declaration from a script: a quoted name used as a style key or passed to
+// style.setProperty().
+const SCRIPT_DECLARATION = new RegExp(`['"\`](${NAME})['"\`]`, 'g');
+
+const REMOTE_URL = /url\(\s*['"]?(?:[a-z][a-z0-9+.-]*:)?\/\//i;
+const REMOTE_IMPORT = /@import\s+(?:url\()?\s*['"]?(?:[a-z][a-z0-9+.-]*:)?\/\//i;
+
+function tokenNames() {
+  const require = createRequire(import.meta.url);
+  let tokensCss;
+  try {
+    tokensCss = require.resolve('@crewlethq/tokens/css');
+  } catch (error) {
+    throw new Error(
+      `cannot resolve @crewlethq/tokens/css (${error.message}). Build the tokens package first: npm run build --workspace @crewlethq/tokens`,
+    );
+  }
+  const directory = dirname(tokensCss);
+  const names = new Set();
+  for (const file of readdirSync(directory).filter((name) => name.endsWith('.css'))) {
+    const text = withoutComments(readFileSync(join(directory, file), 'utf8'), true);
+    for (const match of text.matchAll(CSS_DECLARATION)) names.add(match[1]);
+  }
+  if (names.size === 0) {
+    throw new Error(`found no custom properties in ${directory}; the tokens build output is empty`);
+  }
+  return names;
+}
+
+export async function findings(roots, base = packageRoot) {
+  const tokens = tokenNames();
+  const files = readSources(roots, base);
+  const declared = new Set();
+  const references = [];
+  const problems = [];
+
+  for (const file of files) {
+    const { text, isStylesheet } = file;
+    const where = (index) => `${file.where}:${lineOf(text, index)}`;
+
+    for (const match of text.matchAll(isStylesheet ? CSS_DECLARATION : SCRIPT_DECLARATION)) {
+      const name = match[1];
+      declared.add(name);
+      if (!name.startsWith(COMPONENT_PREFIX)) {
+        problems.push(
+          `${where(match.index)}: declares ${name}; a component declares only ${COMPONENT_PREFIX}* names (token values belong in @crewlethq/tokens)`,
+        );
+      }
+    }
+    for (const match of text.matchAll(REFERENCE)) {
+      references.push({ name: match[1], hasFallback: match[2] === ',', where: where(match.index) });
+    }
+
+    const ligature = text.indexOf('material-symbols-outlined');
+    if (ligature >= 0) {
+      problems.push(
+        `${where(ligature)}: draws a glyph as a Material Symbols ligature. Use a component from @crewlethq/icons/glyphs, which ships the drawing`,
+      );
+    }
+    for (const [pattern, said] of [
+      [REMOTE_URL, 'loads from a host with url(). Inline the asset or ship it in the package'],
+      [REMOTE_IMPORT, 'imports a remote stylesheet. A design system must not phone home'],
+      [/body\.theme-[a-z]+/, 'selects a body theme class. The theme is a contract on the root element'],
+    ]) {
+      const found = text.search(pattern);
+      if (found >= 0) problems.push(`${where(found)}: ${said}`);
+    }
+
+    if (!isStylesheet) continue;
+
+    for (const { selector, body, index } of rules(text)) {
+      if (/(^|[;{\s])color\s*:[^;]*--color-text-muted/.test(body) && !/\bsvg\b/.test(selector)) {
+        problems.push(
+          `${where(index)}: paints text with --color-text-muted, which is the decoration step (2.8 to 4.5:1 by design). Use --color-text-tertiary for anything a reader has to make out`,
+        );
+      }
+      if (!selector.includes(':focus')) continue;
+      const turnsOff = /(^|[;{\s])outline\s*:\s*(none|0)\s*(;|$)/.test(body);
+      const putsBack = /outline\s*:[^;]*(solid|auto|dashed|dotted)/.test(body) || /forced-colors/.test(selector);
+      if (turnsOff && !putsBack) {
+        problems.push(
+          `${where(index)}: turns the outline off on ${selector.trim()} without putting one back. Forced-colors mode drops every box-shadow and keeps outlines, so a shadow-only ring is no ring at all there. Draw the ring as an outline, or pair --shadow-focus with "outline: 2px solid transparent"`,
+        );
+      }
+    }
+  }
+
+  for (const { name, hasFallback, where } of references) {
+    if (TOKEN_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+      if (!tokens.has(name)) {
+        problems.push(
+          `${where}: reads ${name}, which @crewlethq/tokens does not emit. Use an existing token or add it to packages/tokens/tokens/`,
+        );
+      }
+    } else if (!name.startsWith(COMPONENT_PREFIX)) {
+      problems.push(
+        `${where}: reads ${name}, which is neither a @crewlethq/tokens variable nor a ${COMPONENT_PREFIX}* component variable`,
+      );
+    } else if (!hasFallback && !declared.has(name)) {
+      problems.push(`${where}: reads ${name} without a fallback, and nothing in the scanned source declares it`);
+    }
+  }
+
+  return {
+    problems,
+    checked: `${references.length} custom property references over ${files.length} files, against ${tokens.size} token variables and ${declared.size} component declarations`,
+  };
+}
+
+async function main() {
+  const given = process.argv.slice(2).map((path) => resolve(process.cwd(), path));
+  const roots = given.length > 0 ? given : [join(packageRoot, 'src')];
+  const { problems, checked } = await findings(roots, given.length > 0 ? process.cwd() : packageRoot);
+  report('CSS custom property check', problems, checked);
+}
+
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) await main();

package/scripts/check-css.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// `crewlet-css-check`: both CSS checks, over the folders you give it.
+//
+// The bin a consumer runs over its own stylesheets, so an application holds
+// itself to the same rules the design system holds itself to:
+//
+//     npx crewlet-css-check src/styles src/features
+//
+// With no folder it checks the package's own src/. The two checks are separate
+// files because they answer different questions (see each one's header), and
+// this runs them together because a caller almost never wants one of them.
+
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findings as literalFindings } from './check-css-literals.mjs';
+import { findings as variableFindings } from './check-css-variables.mjs';
+import { report } from './css-source.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const roots = process.argv.slice(2).map((path) => resolve(process.cwd(), path));
+const scanned = roots.length > 0 ? roots : [join(packageRoot, 'src')];
+const base = roots.length > 0 ? process.cwd() : packageRoot;
+
+const variables = await variableFindings(scanned, base);
+report('CSS custom property check', variables.problems, variables.checked);
+const literals = await literalFindings(scanned, base);
+report('CSS literal check', literals.problems, literals.checked);

package/scripts/css-source.mjs

@@ -0,0 +1,67 @@
+// What both CSS checks read, so the two cannot come to disagree about which
+// files they cover or where a finding is.
+//
+// Comments are BLANKED rather than removed, so a line number in a finding is
+// the line a person will open, and so prose about a rule is never mistaken for
+// the rule being broken: `check-css-variables` had already caught a stylesheet
+// whose own header explained why a style element is forbidden.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export function sourceFiles(directory, extensions = /\.(css|tsx?)$/) {
+  const found = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) found.push(...sourceFiles(path, extensions));
+    else if (extensions.test(entry.name)) found.push(path);
+  }
+  return found;
+}
+
+export function withoutComments(text, isStylesheet) {
+  const pattern = isStylesheet ? /\/\*[\s\S]*?\*\//g : /\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
+  return text.replace(pattern, (comment) => comment.replace(/[^\n]/g, ' '));
+}
+
+export function lineOf(text, index) {
+  return text.slice(0, index).split('\n').length;
+}
+
+/** Every file under the given roots, with its comments blanked. */
+export function readSources(roots, base, extensions) {
+  const files = [];
+  for (const root of roots) {
+    if (!statSync(root).isDirectory()) throw new Error(`${root} is not a directory`);
+    for (const path of sourceFiles(root, extensions)) {
+      const raw = readFileSync(path, 'utf8');
+      files.push({
+        path,
+        where: relative(base, path),
+        isStylesheet: path.endsWith('.css'),
+        text: withoutComments(raw, path.endsWith('.css')),
+      });
+    }
+  }
+  return files;
+}
+
+/** Every rule body in a stylesheet, with its selector and its start offset. */
+export function rules(text) {
+  const found = [];
+  const pattern = /([^{}]+)\{([^{}]*)\}/g;
+  for (const match of text.matchAll(pattern)) {
+    found.push({ selector: match[1].trim(), body: match[2], index: match.index });
+  }
+  return found;
+}
+
+export function report(name, problems, checked) {
+  if (problems.length > 0) {
+    console.error(`${name} failed:\n${problems.map((problem) => `  ${problem}`).join('\n')}`);
+    process.exitCode = 1;
+    return false;
+  }
+  console.warn(`[ui] ${name}: ${checked}`);
+  return true;
+}