@atelier-ui/create-workspace 0.2.41 → 0.2.43

package/src/generators/preset/files/tools/stylelint-rules/no-token-bypass.js

@@ -0,0 +1,497 @@
+'use strict';
+
+/**
+ * atelier/no-token-bypass
+ *
+ * Catches a literal whose value a token already holds — the one kind of
+ * unbound value that is objectively wrong. This rule deliberately does NOT
+ * demand that every value be a token: of the ~190 literals in the component
+ * stylesheets, most are component dimensions (an avatar size, a toggle
+ * track, a step circle) with exactly one user, and tokenising them would
+ * produce a hundred single-use tokens — the rule of three violated in token
+ * form. What IS wrong is a literal that duplicates a token in the FAMILY its
+ * own property should draw from — two real, invisible defects were found
+ * this way (AtlTab and AtlCodeBlock's header both hardcoding `2.5rem` where
+ * `--ui-control-height-md` already said 2.5rem, ADR-0047).
+ *
+ * Family per property (z-index → --ui-z-*, opacity → --ui-opacity-*,
+ * font-size/line-height/font-weight/letter-spacing → their own --ui-* family,
+ * border-radius → --ui-radius-*, box-shadow → --ui-shadow-*, transition/
+ * animation-duration → --ui-duration-*, padding/margin/gap → --ui-spacing-*,
+ * min-height/height/width/min-width → --ui-control-height-*), so the rule
+ * never suggests a spacing token for a width. Border widths get their own
+ * check: any literal length on a `border*` property is a bypass, because
+ * `--ui-border-width`/`--ui-border-width-thick` are the only two values that
+ * family holds and neither aliases a "normal" CSS default the way `0` does.
+ *
+ * `TOKEN_BYPASS_EXEMPT` (kept in tools/scripts/lib/allowlists.js — see
+ * no-primitive-token.js's header for why these exemption maps were not
+ * relocated out of that file) carries the same two kinds as every other
+ * allowlist there (ADR-0034): `kind: 'design'` — the shared value is a
+ * coincidence, binding it would be wrong — stays silent; `kind: 'gap'` — it
+ * should bind and hasn't yet — warns on every run via a per-report
+ * `severity: 'warning'` override.
+ *
+ * Staleness is checked the same way no-primitive-token.js checks it: once
+ * per `componentRoot` per process, against a direct filesystem scan of THAT
+ * root's own `**\/*.css` tree, not any other project's — see that file's
+ * header for the full reasoning and the one known gap (a root-asymmetric
+ * exemption would be falsely reported stale by the root(s) that don't
+ * reference it; none of today's four entries are asymmetric, verified
+ * 2026-09-12).
+ *
+ * One thing this port improves rather than copies: the retired script
+ * hand-rolled a `(^|[;{])\s*([a-z-]+)\s*:\s*([^;{}]+)` regex over
+ * comment-stripped CSS text to recover `prop: value` pairs. A stylelint rule
+ * gets that for free, correctly, from `root.walkDecls` — no hand-rolled
+ * parsing needed for the per-file violation check. The pre-scan used only
+ * for staleness still uses the same regex, because at that point there is no
+ * PostCSS AST — it exists purely to answer "is this literal referenced
+ * anywhere", not to attribute a violation to a location.
+ *
+ * Scope is deliberately component CSS only — every framework's own
+ * `src/lib` component stylesheets — the retired script never touched the
+ * docs app, and neither does this rule.
+ *
+ * THREE secondary options, all repo-relative POSIX paths, none guessed —
+ * the config declares topology the way `no-undeclared-token`'s `tokenFiles`
+ * already does:
+ *   - `tokenFile` (required in practice): the single canonical token source
+ *     to read DECLARED VALUES from (`tokenValue` below) — this repo passes
+ *     the same `libs/create-workspace/.../tokens.css` `no-undeclared-token`
+ *     uses. Omitted, `tokenValue` is `{}` and the family-match half of this
+ *     rule silently finds nothing to match (the border-width half is
+ *     unaffected — it never reads token values).
+ *   - `componentRoot` (required for staleness): the one directory this
+ *     invocation's `libs/<fw>/src/lib` (or a scaffold's own tree) lives at.
+ *     Replaces a `frameworkOf()` regex that used to pattern-match the input
+ *     file's path against `libs/(angular|react|vue)/src/lib/` to guess which
+ *     of three hardcoded trees to scan — the config already knows which
+ *     tree each Nx target lints (one target per project), so asking it to
+ *     say so is not a bigger ask than `tokenFiles` already is. Omitted, the
+ *     staleness scan (which needs a directory to walk) does not run; the
+ *     per-declaration bypass/border check is unaffected — it never depended
+ *     on knowing the framework, only on `dir` (a plain basename).
+ *   - `allowlistsFile` (optional): repo-relative path to a CommonJS module
+ *     exporting `TOKEN_BYPASS_EXEMPT`. This repo passes
+ *     `tools/scripts/lib/allowlists.js`, unchanged. **Absent — the
+ *     documented default for a scaffold, which starts with ZERO
+ *     exemptions — `TOKEN_BYPASS_EXEMPT` is `{}`.** An empty exemption
+ *     object also means the staleness scan is skipped outright, not just
+ *     "runs and finds nothing": scanning a tree to police an empty map is
+ *     work with no finding it could ever produce, so the scan (and the
+ *     per-root cache it would populate) is short-circuited before it
+ *     touches the filesystem. Loaded lazily, per file, from inside the rule
+ *     closure (cached by resolved absolute path) rather than at module
+ *     `require()` time — the old code's top-level `require('../scripts/lib/
+ *     allowlists')` ran the instant `index.js` loaded this file into the
+ *     `plugins` array, which happens whenever ANY rule in the plugin is
+ *     used, whether or not `no-token-bypass` itself is turned on for that
+ *     project. A scaffold has no such file at all, so that top-level
+ *     `require()` would throw `MODULE_NOT_FOUND` merely from loading the
+ *     plugin — before any config decision about whether to enable this rule
+ *     even applies.
+ *
+ *     **The empty default applies only when `allowlistsFile` is absent.**
+ *     When it IS supplied, the loaded module's exports are validated:
+ *     `TOKEN_BYPASS_EXEMPT` must be a plain object. A module that fails to
+ *     load resolution still throws `MODULE_NOT_FOUND` as before (unchanged,
+ *     already loud); a module that DOES load but doesn't actually export
+ *     that name — a typo, a rename on one side only — used to be silently
+ *     treated as the same "zero exemptions" default, which is exactly
+ *     ADR-0124's failure class: the staleness scan skips outright (nothing
+ *     to report), unconditionally, regardless of whether any exempted
+ *     literal elsewhere in the tree also loses its exemption and starts
+ *     reporting on its own — the rule never signals that its configured
+ *     allowlist never actually loaded, only that SOME check silently didn't
+ *     run (2026-09-12 stylelint review, claim 2, reproduced with a fixture
+ *     that has no exempted literal in scope at all: a genuinely stale entry
+ *     went from a blocking `[STALE-EXEMPT]` to total silence, exit 0, the
+ *     moment the export name was misspelled). Now a mis-shaped supplied
+ *     module reports `[INVALID-ALLOWLISTS]` at `error` severity on every
+ *     file this override touches, via `stylelint.utils.report()` rather
+ *     than a thrown exception — see `no-primitive-token.js`'s header for
+ *     the full reasoning (verified there that a thrown error aborts the
+ *     entire stylelint run rather than reporting per file); this rule makes
+ *     the same call for the same reason.
+ *
+ * Formerly tools/scripts/check-token-bypass.js (check:token-bypass).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const stylelint = require('stylelint');
+const {
+  REPO_ROOT,
+  toRepoRelative,
+  isNonEmptyString,
+  normalizeRepoRelative,
+} = require('./utils');
+
+const ruleName = 'atelier/no-token-bypass';
+
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  bypass: (prop, value, holders) =>
+    `[BYPASS] sets ${prop}: ${value}, which is exactly what ${holders
+      .map((h) => `var(${h})`)
+      .join(
+        ' / ',
+      )} holds. Bind it, or exempt it in TOKEN_BYPASS_EXEMPT with a reason.`,
+  border: (prop, value) =>
+    `[BORDER] sets ${prop}: ${value} with a literal width. Use var(--ui-border-width) ` +
+    'or var(--ui-border-width-thick); if the value is a graphic device rather than a border ' +
+    'weight, exempt it in TOKEN_BYPASS_EXEMPT with a reason.',
+  stale: (key) =>
+    `[STALE-EXEMPT] TOKEN_BYPASS_EXEMPT lists '${key}', but no stylesheet under the configured componentRoot has that literal any more. Remove the entry.`,
+  invalidAllowlists: (allowlistsFile, reason) =>
+    `[INVALID-ALLOWLISTS] '${allowlistsFile}' ${reason}. A supplied allowlistsFile must actually export it — a missing or misspelled export is a broken configuration, not the documented empty default (which only applies when allowlistsFile is omitted entirely).`,
+});
+
+const meta = {
+  url: 'tools/stylelint-rules/no-token-bypass.js',
+};
+
+/** Which token family a property may draw from. Copied verbatim from the retired script. */
+const FAMILY = {
+  'z-index': /^--ui-z-/,
+  opacity: /^--ui-opacity-/,
+  'letter-spacing': /^--ui-letter-spacing-/,
+  'font-weight': /^--ui-font-weight-/,
+  'font-size': /^--ui-font-size-/,
+  'line-height': /^--ui-line-height-/,
+  'border-radius': /^--ui-radius-/,
+  'box-shadow': /^--ui-shadow-/,
+  'transition-duration': /^--ui-duration-/,
+  'animation-duration': /^--ui-duration-/,
+  padding: /^--ui-spacing-/,
+  'padding-top': /^--ui-spacing-/,
+  'padding-right': /^--ui-spacing-/,
+  'padding-bottom': /^--ui-spacing-/,
+  'padding-left': /^--ui-spacing-/,
+  margin: /^--ui-spacing-/,
+  'margin-top': /^--ui-spacing-/,
+  'margin-right': /^--ui-spacing-/,
+  'margin-bottom': /^--ui-spacing-/,
+  'margin-left': /^--ui-spacing-/,
+  gap: /^--ui-spacing-/,
+  'row-gap': /^--ui-spacing-/,
+  'column-gap': /^--ui-spacing-/,
+  'min-height': /^--ui-control-height-/,
+  height: /^--ui-control-height-/,
+  width: /^--ui-control-height-/,
+  'min-width': /^--ui-control-height-/,
+};
+
+/** Border widths get their own rule: any literal length is a bypass. */
+const BORDER_PROP = /^border(-top|-right|-bottom|-left)?(-width)?$/;
+
+/** Values that mean "nothing", not "a measurement". */
+const STRUCTURAL = new Set([
+  '0',
+  'none',
+  'auto',
+  'inherit',
+  'initial',
+  'unset',
+  'currentColor',
+  'transparent',
+]);
+
+/** Token → value, read once per resolved `tokenFile` path from the light
+ *  (`:root`) block of the canonical token source and cached by absolute
+ *  path — the same single file for every framework, unlike
+ *  no-undeclared-token's `tokenFiles`, because token-bypass never scopes to
+ *  docs. Already a declared nx.json `stylelint` input since stage 1. */
+function readTokenValues(absPath) {
+  const tokensCss = fs
+    .readFileSync(absPath, 'utf-8')
+    .replace(/\/\*[\s\S]*?\*\//g, '');
+  const darkAt = tokensCss.indexOf('@media (prefers-color-scheme: dark)');
+  const lightBlock = darkAt === -1 ? tokensCss : tokensCss.slice(0, darkAt);
+  const tokenValue = {};
+  for (const m of lightBlock.matchAll(/(--ui-[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+    const value = m[2].trim();
+    if (value.startsWith('var(')) continue; // an alias, not a value of its own
+    tokenValue[m[1]] = value;
+  }
+  return tokenValue;
+}
+
+const tokenValueCache = new Map(); // absolute tokenFile path -> tokenValue map
+
+/** `{}` when `tokenFile` is absent — the family-match check then never
+ *  matches anything (nothing to compare against); the border-width check is
+ *  unaffected, since it never reads token values. */
+function getTokenValues(tokenFile) {
+  if (!tokenFile) return {};
+  const absPath = path.resolve(REPO_ROOT, tokenFile);
+  if (!tokenValueCache.has(absPath)) {
+    tokenValueCache.set(absPath, readTokenValues(absPath));
+  }
+  return tokenValueCache.get(absPath);
+}
+
+/** Human-readable description of what `require()` actually returned, for the
+ *  `[INVALID-ALLOWLISTS]` message. */
+function describeExport(value) {
+  if (value === undefined) return 'is undefined (no such export)';
+  if (Array.isArray(value)) return 'is an array';
+  if (value === null) return 'is null';
+  return `is a ${typeof value}`;
+}
+
+const allowlistsCache = new Map(); // absolute allowlistsFile path -> result below
+
+/**
+ * `{ module: null, invalidReason: null }` when `allowlistsFile` is absent —
+ * the documented default for a scaffold, which starts with ZERO exemptions
+ * (see header).
+ *
+ * When `allowlistsFile` IS supplied, the loaded module's shape is validated:
+ * `TOKEN_BYPASS_EXEMPT` must be a plain object (not an array, not `null`,
+ * not missing). Missing or wrongly-shaped yields `{ module: null,
+ * invalidReason: <string> }` instead of silently falling back to the same
+ * empty default the absent-option case uses — see header for why (claim 2).
+ * A module that itself fails to `require()` (a typo'd PATH, not a typo'd
+ * EXPORT) still throws `MODULE_NOT_FOUND` here, unchanged and already loud.
+ */
+function getAllowlists(allowlistsFile) {
+  if (!allowlistsFile) return { module: null, invalidReason: null };
+  const absPath = path.resolve(REPO_ROOT, allowlistsFile);
+  if (!allowlistsCache.has(absPath)) {
+    const required = require(absPath);
+    const value = required.TOKEN_BYPASS_EXEMPT;
+    const isValidShape =
+      value !== null && typeof value === 'object' && !Array.isArray(value);
+    allowlistsCache.set(
+      absPath,
+      isValidShape
+        ? { module: required, invalidReason: null }
+        : {
+            module: null,
+            invalidReason: `'TOKEN_BYPASS_EXEMPT' ${describeExport(value)}, expected an object`,
+          },
+    );
+  }
+  return allowlistsCache.get(absPath);
+}
+
+/** Which declared tokens in `family` hold exactly `value`. */
+function tokensHolding(value, family, tokenValue) {
+  return Object.keys(tokenValue).filter(
+    (name) => family.test(name) && tokenValue[name] === value,
+  );
+}
+
+/**
+ * Every `TOKEN_BYPASS_EXEMPT` key (`<dir>:<prop>:<value>`) actually
+ * referenced anywhere under `componentRoot`'s own `**\/*.css` — a direct
+ * filesystem scan over raw text (no PostCSS AST available here), independent
+ * of which files stylelint hands this rule during this run.
+ */
+function scanComponentRootForSeenKeys(absBase, tokenValue) {
+  const seen = new Set();
+  if (!fs.existsSync(absBase)) return seen;
+  for (const dir of fs.readdirSync(absBase)) {
+    const dirPath = path.join(absBase, dir);
+    if (!fs.statSync(dirPath).isDirectory()) continue;
+    for (const file of fs
+      .readdirSync(dirPath)
+      .filter((f) => f.endsWith('.css'))) {
+      const css = fs
+        .readFileSync(path.join(dirPath, file), 'utf-8')
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+      for (const m of css.matchAll(/(^|[;{])\s*([a-z-]+)\s*:\s*([^;{}]+)/g)) {
+        const prop = m[2];
+        const value = m[3].trim().replace(/\s+/g, ' ');
+        if (value.includes('var(--ui-')) continue;
+        if (STRUCTURAL.has(value)) continue;
+
+        if (BORDER_PROP.test(prop)) {
+          const width = value.match(/^([\d.]+)(px|rem|em)\b/);
+          if (width) seen.add(`${dir}:${prop}:${width[0]}`);
+          continue;
+        }
+        const family = FAMILY[prop];
+        if (!family) continue;
+        if (tokensHolding(value, family, tokenValue).length > 0) {
+          seen.add(`${dir}:${prop}:${value}`);
+        }
+      }
+    }
+  }
+  return seen;
+}
+
+// Keyed on (componentRoot, tokenFile, allowlistsFile), not on componentRoot
+// alone — the scan result depends on `tokenValue` (which comes from
+// `tokenFile`), and whether the once-per-root stale-report loop below even
+// RUNS depends on `TOKEN_BYPASS_EXEMPT` (which comes from `allowlistsFile`).
+// Two overrides sharing a `componentRoot` but differing in either used to
+// serve the first one's scan (and its `staleReportedForRoot` flag) to the
+// second, silently suppressing the second's own staleness check — see
+// `no-primitive-token.js` for the full reasoning and its own reproduction
+// of the same shape of bug (2026-09-12 stylelint review, claim 3).
+function cacheKey(componentRoot, tokenFile, allowlistsFile) {
+  // JSON-encode the tuple rather than joining with a separator character:
+  // that's unambiguous no matter what any of the three strings contain,
+  // unlike a literal join (space, NUL, or any other single character) which
+  // two different (componentRoot, tokenFile, allowlistsFile) triples could
+  // in principle both produce.
+  return JSON.stringify([componentRoot, tokenFile || '', allowlistsFile || '']);
+}
+const seenByRoot = new Map();
+const staleReportedForRoot = new Set();
+
+/** @type {import('stylelint').Rule} */
+const rule = (primary, secondaryOptions) => {
+  return (root, result) => {
+    const validOptions = stylelint.utils.validateOptions(
+      result,
+      ruleName,
+      { actual: primary, possible: [true] },
+      {
+        actual: secondaryOptions,
+        possible: {
+          tokenFile: [isNonEmptyString],
+          componentRoot: [isNonEmptyString],
+          allowlistsFile: [isNonEmptyString],
+        },
+      },
+    );
+    if (!validOptions) return;
+
+    // Normalized BEFORE the `inScope` compare below and before it's used in
+    // any cache key — see `no-primitive-token.js` / `normalizeRepoRelative`'s
+    // header for why a raw `componentRoot: './libs/react/src/lib'`, a
+    // trailing slash, or an absolute path would otherwise disagree with
+    // `toRepoRelative(inputFile)` and silently disable every staleness check
+    // for this override (claim 4).
+    const rawComponentRoot = secondaryOptions && secondaryOptions.componentRoot;
+    const componentRoot = rawComponentRoot
+      ? normalizeRepoRelative(rawComponentRoot)
+      : undefined;
+    const tokenFile = secondaryOptions && secondaryOptions.tokenFile;
+    const tokenValue = getTokenValues(tokenFile);
+    const allowlistsFile = secondaryOptions && secondaryOptions.allowlistsFile;
+    const { module: allowlists, invalidReason } = getAllowlists(allowlistsFile);
+    if (invalidReason) {
+      stylelint.utils.report({
+        message: messages.invalidAllowlists(allowlistsFile, invalidReason),
+        node: root,
+        result,
+        ruleName,
+      });
+    }
+    const TOKEN_BYPASS_EXEMPT =
+      (allowlists && allowlists.TOKEN_BYPASS_EXEMPT) || {};
+
+    const inputFile = root.source && root.source.input.file;
+    const relFile = inputFile ? toRepoRelative(inputFile) : undefined;
+    const dir = relFile ? path.basename(path.dirname(relFile)) : undefined;
+    const inScope =
+      Boolean(componentRoot) &&
+      Boolean(relFile) &&
+      (relFile === componentRoot || relFile.startsWith(`${componentRoot}/`));
+    // Scanning a tree to police an empty map is work with no finding it
+    // could ever produce — skip the scan (and the staleness report loop)
+    // outright rather than run it and find nothing, every file, forever.
+    const hasExemptions = Object.keys(TOKEN_BYPASS_EXEMPT).length > 0;
+    const rootKey = cacheKey(componentRoot, tokenFile, allowlistsFile);
+
+    if (inScope && hasExemptions && !seenByRoot.has(rootKey)) {
+      seenByRoot.set(
+        rootKey,
+        scanComponentRootForSeenKeys(
+          path.resolve(REPO_ROOT, componentRoot),
+          tokenValue,
+        ),
+      );
+    }
+    const seenKeys =
+      inScope && hasExemptions ? seenByRoot.get(rootKey) : new Set();
+
+    // Allowlist hygiene, reported once per (componentRoot, tokenFile,
+    // allowlistsFile) per run — see no-primitive-token.js for why this is
+    // the anchor and its limitation.
+    if (inScope && hasExemptions && !staleReportedForRoot.has(rootKey)) {
+      staleReportedForRoot.add(rootKey);
+      for (const key of Object.keys(TOKEN_BYPASS_EXEMPT)) {
+        if (!seenKeys.has(key)) {
+          stylelint.utils.report({
+            message: messages.stale(key),
+            node: root,
+            result,
+            ruleName,
+          });
+        }
+      }
+    }
+
+    root.walkDecls((decl) => {
+      const prop = decl.prop.toLowerCase();
+      const value = decl.value.trim().replace(/\s+/g, ' ');
+      if (value.includes('var(--ui-')) return;
+      if (STRUCTURAL.has(value)) return;
+
+      if (BORDER_PROP.test(prop)) {
+        const width = value.match(/^([\d.]+)(px|rem|em)\b/);
+        if (!width) return;
+
+        const key = `${dir}:${prop}:${width[0]}`;
+        const exempt = TOKEN_BYPASS_EXEMPT[key];
+        if (exempt) {
+          if (exempt.kind === 'gap') {
+            stylelint.utils.report({
+              message: `[GAP] ${prop}: ${width[0]} still unbound. ${exempt.why}`,
+              node: decl,
+              result,
+              ruleName,
+              severity: 'warning',
+            });
+          }
+          return;
+        }
+        stylelint.utils.report({
+          message: messages.border(prop, value),
+          node: decl,
+          result,
+          ruleName,
+        });
+        return;
+      }
+
+      const family = FAMILY[prop];
+      if (!family) return;
+      const holders = tokensHolding(value, family, tokenValue);
+      if (holders.length === 0) return;
+
+      const key = `${dir}:${prop}:${value}`;
+      const exempt = TOKEN_BYPASS_EXEMPT[key];
+      if (exempt) {
+        if (exempt.kind === 'gap') {
+          stylelint.utils.report({
+            message: `[GAP] ${prop}: ${value} should bind to var(${holders[0]}). ${exempt.why}`,
+            node: decl,
+            result,
+            ruleName,
+            severity: 'warning',
+          });
+        }
+        return;
+      }
+      stylelint.utils.report({
+        message: messages.bypass(prop, value, holders),
+        node: decl,
+        result,
+        ruleName,
+      });
+    });
+  };
+};
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+rule.meta = meta;
+
+module.exports = stylelint.createPlugin(ruleName, rule);

package/src/generators/preset/files/tools/stylelint-rules/no-undeclared-token.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * atelier/no-undeclared-token
+ *
+ * Every `--ui-*` custom property a stylesheet READS via `var(--ui-x, ...)`
+ * must be declared somewhere in the token source(s) named by the `tokenFiles`
+ * secondary option (repo-root-relative paths, e.g.
+ * `['libs/create-workspace/src/generators/preset/files/styles/tokens.css']`).
+ * A `var()` fallback is what makes an undeclared reference silent: the
+ * component still renders, plausibly, at a value the design system does not
+ * control. Two real incidents motivated this (not hypothetical):
+ *
+ *   - all three code-block stylesheets read `var(--ui-font-mono, …)` while
+ *     nothing declared it, so every code block silently rendered in the
+ *     Menlo fallback until ADR-0035 declared the token.
+ *   - AtlTooltip read `var(--ui-z-tooltip, 200)`, which no token source had
+ *     ever declared, so the tooltip's stacking level was the literal 200
+ *     while every other floating layer used --ui-z-dropdown (ADR-0075).
+ *
+ * `tokenFiles` is a required secondary option, not a hardcoded path, because
+ * the declared-token SET differs by scope: component CSS is checked only
+ * against the shared `tokens.css` (one file, three frameworks' own copies
+ * kept byte-identical to it by `check:tokens`), while the docs site's CSS is
+ * checked against that file UNION `docs/src/styles/docs-theme.css` (which
+ * both declares docs-only tokens and re-declares/overrides some `--ui-*`
+ * ones). A stylelint config wires the two scopes to two different
+ * `tokenFiles` lists via per-glob overrides, rather than this rule guessing
+ * which file(s) apply to which CSS.
+ *
+ * `--ui-` itself (as opposed to `--docs-*` or any other custom-property
+ * prefix) is NOT an option: unlike `tokenFiles`, there is no known reason
+ * this repo would ever want to police a different prefix, so it stays a
+ * constant the way `atelier/host-attr-guard`'s `HOST_GUARD_KEY` does.
+ *
+ * Reports once per `var(--ui-x)` occurrence, attributed to the declaration
+ * that reads it — the formerly-`check-css-tokens.js` script instead
+ * aggregated one message per undeclared token name across the whole repo
+ * ("read by N component stylesheet(s)"); a linter reporting per file, at
+ * the exact line, is the more useful shape for the same fact and is what a
+ * `root.walkDecls` visitor naturally produces.
+ *
+ * Formerly Pass C of `tools/scripts/check-css-tokens.js`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const stylelint = require('stylelint');
+const { REPO_ROOT, isNonEmptyString } = require('./utils');
+
+const ruleName = 'atelier/no-undeclared-token';
+
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  rejected: (name) =>
+    `[UNDECLARED] '${name}' is read here via var() but is declared in no ` +
+    'configured token source. The component silently renders at its ' +
+    "var() fallback (if any), which the design system doesn't control. " +
+    'Declare the token, or reference one that exists.',
+});
+
+const meta = {
+  url: 'tools/stylelint-rules/no-undeclared-token.js',
+};
+
+// Matches a `var(--ui-...)` READ inside a declaration's value.
+const TOKEN_READ = /var\(\s*(--ui-[a-z0-9-]+)/g;
+// Matches a `--ui-...` DECLARATION (`--ui-x: <value>;`) inside a token
+// source file. A token may be re-declared across selectors (light / dark /
+// [data-theme] blocks); only its existence matters here.
+const TOKEN_DECLARATION = /(--ui-[a-zA-Z0-9-]+)\s*:/g;
+
+/** The set of `--ui-*` names declared in `tokenFiles` (repo-root-relative paths). */
+function readDeclaredTokens(tokenFiles) {
+  const declared = new Set();
+  for (const relFile of tokenFiles) {
+    const absFile = path.resolve(REPO_ROOT, relFile);
+    const src = fs.readFileSync(absFile, 'utf-8');
+    for (const match of src.matchAll(TOKEN_DECLARATION)) {
+      declared.add(match[1]);
+    }
+  }
+  return declared;
+}
+
+/** @type {import('stylelint').Rule} */
+const rule = (primary, secondaryOptions) => {
+  return (root, result) => {
+    const validOptions = stylelint.utils.validateOptions(
+      result,
+      ruleName,
+      { actual: primary, possible: [true] },
+      {
+        actual: secondaryOptions,
+        possible: { tokenFiles: [isNonEmptyString] },
+      },
+    );
+    if (!validOptions) return;
+
+    const tokenFiles = secondaryOptions.tokenFiles;
+    const declaredTokens = readDeclaredTokens(tokenFiles);
+
+    root.walkDecls((decl) => {
+      for (const match of decl.value.matchAll(TOKEN_READ)) {
+        const name = match[1];
+        if (declaredTokens.has(name)) continue;
+
+        stylelint.utils.report({
+          message: messages.rejected(name),
+          node: decl,
+          result,
+          ruleName,
+        });
+      }
+    });
+  };
+};
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+rule.meta = meta;
+
+module.exports = stylelint.createPlugin(ruleName, rule);

package/src/generators/preset/files/tools/stylelint-rules/utils.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Small, dependency-free helpers shared by the local rules in this
+ * directory. Deliberately does not import anything from `stylelint/lib/*`
+ * beyond the public API (`stylelint.utils.*`, `stylelint.createPlugin`) —
+ * those subpaths happen to be resolvable (the package's `exports` map
+ * allows `./lib/utils/*`), but they are stylelint's own internals, not part
+ * of its documented `PublicApi`, so a rule in this repo doesn't take a
+ * dependency on them staying stable across versions.
+ */
+
+const path = require('path');
+
+/**
+ * Absolute path to the repository root, computed from this file's own
+ * location rather than from `process.cwd()` — `tools/stylelint-rules/` sits
+ * at the same depth as `tools/scripts/` (two levels under the root), so this
+ * resolves correctly regardless of which directory stylelint is invoked
+ * from (an Nx target may run with `cwd` set to a project root, not the
+ * workspace root).
+ */
+const REPO_ROOT = path.resolve(__dirname, '../..');
+
+/**
+ * `absPath` expressed relative to `REPO_ROOT`, POSIX-separated so an option
+ * written as `'docs/src/styles/global.css'` matches on every platform.
+ *
+ * @param {string} absPath
+ */
+function toRepoRelative(absPath) {
+  return path.relative(REPO_ROOT, absPath).split(path.sep).join('/');
+}
+
+/** Is `value` a non-empty string? Used to validate rule options without
+ *  depending on stylelint's internal `validateTypes` module (see header). */
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * A `componentRoot`-shaped option, normalized exactly the way a linted
+ * file's own path already is by `toRepoRelative` above: resolved to an
+ * absolute path, then re-expressed relative to `REPO_ROOT` with POSIX
+ * separators. Without this, a rule comparing an option value directly
+ * against `toRepoRelative(inputFile)` (a plain `===`/`startsWith` string
+ * compare) silently disagrees on a leading `./`, a trailing slash, or an
+ * absolute path — all three name the same directory as the plain
+ * `libs/<fw>/src/lib` form every config in this repo happens to use today,
+ * but nothing enforced that shape until this normalization existed
+ * (2026-09-12 stylelint review, claim 4: reproduced — `componentRoot:
+ * 'scratch-claim4/'` (trailing slash), `'./scratch-claim4'` (leading dot),
+ * and the equivalent absolute path each turned a genuinely stale
+ * `PRIMITIVE_EXEMPTIONS` entry from a blocking `[STALE]` into total silence,
+ * exit 0 — the staleness scan never ran because `inScope` never matched).
+ * Both `no-primitive-token.js` and `no-token-bypass.js` normalize
+ * `componentRoot` through this before using it either in the `inScope`
+ * check or as (part of) a cache key.
+ *
+ * @param {string} relOrAbsPath
+ */
+function normalizeRepoRelative(relOrAbsPath) {
+  return toRepoRelative(path.resolve(REPO_ROOT, relOrAbsPath));
+}
+
+module.exports = {
+  REPO_ROOT,
+  toRepoRelative,
+  isNonEmptyString,
+  normalizeRepoRelative,
+};