haus-tokens 0.2.0 → 1.0.0

package/README.md

@@ -44,11 +44,21 @@ Two kinds of primitive read are documented rather than hidden. Sizes: 31
 declarations across the haus components take a size off the space ladder, on
 `height`, `width`, `min-*`/`max-*` and `transform` offsets, because a size is a
 value rather than a role. They are the avatar sizes, the checkbox and radio
-boxes, the toggle track and thumb, and a few min/max bounds. And 56 read a primitive that has no semantic alias
-because the primitive's own name already is the role: `--font-sans`,
-`--weight-*`, `--border-width-*`, `--opacity-disabled`, `--icon-sm`,
-`--z-modal`. No component reads a colour, radius, shadow or motion primitive,
-and a test in `haus-components` holds that line.
+boxes, the toggle track and thumb, and a few min/max bounds. And 41 read a primitive that has no semantic
+alias because the primitive's own name already is the role: 32 read
+`--haus-font-sans`, five a control height, three `--haus-icon-sm` and one
+`--haus-tracking-normal`. A font family is not a role and there is no honest
+alias to invent for it. No component reads a colour, radius, shadow, stacking or
+motion primitive, and a test in `haus-components` holds that line.
+
+That second number went 61 to 77 when the six overlay components landed, then
+**77 to 41 at the 1.0 cut**, and the fall is the part worth reading. `Popover`
+and `Tooltip` had to reach for `--haus-z-*` directly because eight z-index
+primitives had no role between them, and a product wanting the stacking order
+had to read `primitives.css` for it, which is why drift and vault each settled
+one for themselves. haus#27 put the ladders in `primitives.css` and the names in
+`semantics.css`. **No component declaration changed**: the same reads resolve
+one layer higher.
 
 ## Typed constants
 
@@ -80,17 +90,80 @@ numbers, a composite is an alias:
 "motion": { "fade-in": { "$type": "string", "$value": "{duration.normal} {easing.enter}" } }
 ```
 
+## The guard
+
+`var(--x)` for an undefined `--x` is invalid at computed-value time: the
+declaration is dropped and the property inherits. No console warning, no build
+error, nothing in review: a focus ring is simply absent, and a missing duration
+looks like a design choice.
+
+That makes *have you loaded what my components read* a question worth failing a
+build over, and it is a question this package can answer because this package
+defines the contract. Import it from your own suite:
+
+```ts
+import { readFileSync } from 'node:fs'
+import { findUndefinedTokens } from 'haus-tokens/guard'
+
+const read = (p: string) => readFileSync(p, 'utf8')
+
+it('reads no role this app does not load', () => {
+  const { missing, read: reads } = findUndefinedTokens({
+    reads: [read('node_modules/haus-components/dist/styles.css')],
+    defines: [
+      read('node_modules/haus-tokens/dist/primitives.css'),
+      read('node_modules/haus-tokens/dist/motion.css'),
+      read('node_modules/haus-tokens/dist/semantics.css'),
+      read('src/tokens/overrides.css'),
+    ],
+  })
+
+  // Assert the floor as well as the failure: a wrong path makes the check pass
+  // by finding nothing.
+  expect(reads.length).toBeGreaterThan(50)
+  expect(missing).toEqual([])
+})
+```
+
+It is **pure and does no file reading**, so it runs anywhere and this package
+gains no dependency on `node:fs`. You know which files you load; it only knows
+what the contract is.
+
+`alsoDefined` takes properties set outside CSS, a component doing
+`style={{ '--haus-avatar-bg': v }}` defines one that no stylesheet will show.
+
+A read carrying a fallback, `var(--x, 0.2s)`, is a real value either way and is
+not a failure. `findFallbackTokens` lists those separately, because a fallback
+that never loses is a hardcoded value wearing a token's clothes and that is
+worth reading occasionally rather than failing a build over.
+
+**Why it exists.** drift wrote this check for itself and it caught five roles
+before they reached a screen: `--color-ink-on-primary`, `--elevation-floating`,
+`--motion-duration-emphasis`, `--radius-marker` and `--haus-focus-ring-error`.
+Every consumer after it would have written the same test or shipped the same
+silent hole.
+
+It is also run against this package. `src/guard.test.ts` checks `semantics.css`
+and `brands/vault.css` resolve against the layers below them: which is how the
+guard's own regex bug was found, a missing `m` flag that reported 41 undefined
+roles in a file that has none.
+
 ## Three copies, one truth
 
-Stating the same tokens three times invites exactly the drift this design
-system exists to prevent. So two of the three are not stated at all:
-`tokens.json` is the source, and `primitives.css` and `index.ts` are generated
-from it by `scripts/build-tokens.ts`. `pnpm run tokens:check` regenerates them
-in memory and fails if what is committed differs, which is the first step CI
-runs. Change a value in `tokens.json` and `pnpm run tokens` writes the other
-two; change one of the other two by hand and CI says so.
+Stating the same tokens more than once invites exactly the drift this design
+system exists to prevent, so most of the restatements are not stated at all.
+`scripts/build-tokens.ts` writes five files: `primitives.css` and `motion.css`
+from `tokens.json`, `index.ts` as the typed export, `brand.ts` as the `BrandMap`
+type from `brand.css`, and `tokens.json`'s own `semantic.color` block from
+`brand.css` as well.
+
+`pnpm run tokens:check` regenerates all five in memory and fails if what is
+committed differs, which is the first step CI runs. Change a source and
+`pnpm run tokens` writes the derived files; change a derived file by hand and CI
+says so, which has already caught someone editing a comment inside one.
 
-`semantics.css` is the one token file still written by hand, because a role is a
+Two token files are written by hand. `brand.css` says which primitive each role
+takes, and `semantics.css` says what each role means, because a role is a
 decision rather than a derivation. `semantics.test.ts` holds it to the rules
 this package states: every token it reads is declared in the layers below, no
 declaration carries a raw value, every subtle and default surface has its

package/dist/brand.css

@@ -0,0 +1,97 @@
+/* ─── haus / brand ───────────────────────────────────────────────────────────
+   Which primitive each role takes. The one file a consumer replaces.
+
+   It contains nothing else: no new names, no raw values, no structure. A brand
+   author sees a flat list of ramp choices; a component author sees an unchanged
+   role name in semantics.css. That separation is the whole of ruling A3 — before
+   it, the brand and the role system were the same file, so taking haus's roles
+   meant taking haus's palette, and two products declared their own tokens rather
+   than do that.
+
+   Every entry here is required. `BrandMap` in the package's TypeScript export is
+   generated from this file, so a brand that omits a role or misnames one fails a
+   consumer's build instead of rendering an unresolved var().
+
+   The default brand applies at :root, so the common case needs no attribute. A
+   named brand applies at [data-haus-theme="<name>"] and nests, because custom
+   properties inherit. See brands/vault.css for a complete second brand.
+   ─────────────────────────────────────────────────────────────────────────── */
+
+@layer haus.brand {
+
+  :root {
+
+    /* ── Surfaces ────────────────────────────────────────────────────────── */
+    --haus-brand-surface-default:        var(--haus-damson-0);
+    --haus-brand-surface-subtle:         var(--haus-damson-100);
+    --haus-brand-surface-raised:         var(--haus-damson-0);    /* elevation via shadow, not colour */
+    --haus-brand-surface-overlay:        var(--haus-damson-50);   /* modal / popover, barely off-white */
+    --haus-brand-surface-sunken:         var(--haus-damson-200);
+    --haus-brand-surface-inverse:        var(--haus-damson-900);  /* dark chip, tooltip bg in light mode */
+    --haus-brand-surface-disabled:       var(--haus-damson-100);
+    --haus-brand-surface-inverse-hover:  oklch(from var(--haus-damson-0) l c h / 0.10);
+
+    /* ── Ink ─────────────────────────────────────────────────────────────── */
+    --haus-brand-ink-primary:    var(--haus-damson-900);
+    --haus-brand-ink-secondary:  var(--haus-damson-700);
+    --haus-brand-ink-tertiary:   var(--haus-damson-500);
+    --haus-brand-ink-disabled:   var(--haus-damson-400);
+    --haus-brand-ink-inverse:    var(--haus-damson-0);
+    --haus-brand-ink-link:       var(--haus-aronia-500);
+    --haus-brand-ink-on-primary:  var(--haus-damson-0);
+
+    /* ── Borders ─────────────────────────────────────────────────────────── */
+    --haus-brand-border-subtle:         var(--haus-damson-100);
+    --haus-brand-border-default:        var(--haus-damson-200);
+    --haus-brand-border-strong:         var(--haus-damson-300);
+    --haus-brand-border-disabled:       var(--haus-damson-200);
+    --haus-brand-border-inverse:        oklch(from var(--haus-damson-0) l c h / 0.30);
+    --haus-brand-border-inverse-hover:  oklch(from var(--haus-damson-0) l c h / 0.50);
+
+    /* ── Primary ─────────────────────────────────────────────────────────── */
+    --haus-brand-primary-default:    var(--haus-aronia-500);
+    --haus-brand-primary-hover:      var(--haus-aronia-600);
+    --haus-brand-primary-pressed:    var(--haus-aronia-700);
+    --haus-brand-primary-subtle:     var(--haus-aronia-100);
+    --haus-brand-primary-on-subtle:  var(--haus-aronia-700);
+    --haus-brand-primary-disabled:   var(--haus-damson-200);
+
+    /* ── Info ────────────────────────────────────────────────────────────── */
+    --haus-brand-info-subtle:      var(--haus-elderberry-100);
+    --haus-brand-info-border:      var(--haus-elderberry-200);
+    --haus-brand-info-default:     var(--haus-elderberry-500);
+    --haus-brand-info-on-subtle:   var(--haus-elderberry-700);
+    --haus-brand-info-on-default:  var(--haus-damson-0);
+    --haus-brand-info-emphasis:    var(--haus-elderberry-900);
+
+    /* ── Success ─────────────────────────────────────────────────────────── */
+    --haus-brand-success-subtle:      var(--haus-greengage-100);
+    --haus-brand-success-border:      var(--haus-greengage-200);
+    --haus-brand-success-default:     var(--haus-greengage-500);
+    --haus-brand-success-on-subtle:   var(--haus-greengage-700);
+    --haus-brand-success-on-default:  var(--haus-damson-900);  /* dark text, because greengage-500 fails with white */
+    --haus-brand-success-solid:       var(--haus-greengage-700);  /* 700-level: white text passes at 6.82:1 */
+    --haus-brand-success-emphasis:    var(--haus-greengage-900);
+
+    /* ── Warning ─────────────────────────────────────────────────────────── */
+    --haus-brand-warning-subtle:      var(--haus-mango-100);
+    --haus-brand-warning-border:      var(--haus-mango-200);
+    --haus-brand-warning-default:     var(--haus-mango-500);
+    --haus-brand-warning-on-subtle:   var(--haus-mango-700);
+    --haus-brand-warning-on-default:  var(--haus-damson-900);  /* dark text, because mango-500 fails with white */
+    --haus-brand-warning-solid:       var(--haus-mango-700);   /* 700-level: white text passes at 7.05:1 */
+    --haus-brand-warning-emphasis:    var(--haus-mango-900);
+
+    /* ── Error ───────────────────────────────────────────────────────────── */
+    --haus-brand-error-subtle:      var(--haus-cherry-100);
+    --haus-brand-error-border:      var(--haus-cherry-200);
+    --haus-brand-error-default:     var(--haus-cherry-500);
+    --haus-brand-error-on-subtle:   var(--haus-cherry-700);
+    --haus-brand-error-on-default:  var(--haus-damson-0);
+    --haus-brand-error-emphasis:    var(--haus-cherry-900);
+
+    /* ── Everything else ─────────────────────────────────────────────────── */
+    --haus-brand-backdrop:  oklch(from var(--haus-damson-950) l c h / var(--haus-opacity-60));
+
+  }
+}

package/dist/brands/vault.css

@@ -0,0 +1,125 @@
+/* ─── haus / brands / vault ──────────────────────────────────────────────────
+   A second, complete brand, and the reason it exists is that **a contract with
+   one implementation is not a contract**. The split in brand.css only proves
+   anything if a different brand can be written against it without touching
+   semantics.css or a single component, and this is that proof.
+
+   It is vault's ruby, not an invention. vault is a shipped product with its own
+   palette that declared 159 custom properties rather than take haus's, and its
+   migration is a later step, so writing the brand here is rehearsal rather than
+   decoration.
+
+   **The brand is `vault` and the ramp stays `ruby`, renamed at the 1.0 cut.**
+   Brand answers *whose* and ramp answers *which colour*. vault ships six
+   gemstone ramps, ruby among them, so naming the ramp `--haus-vault-500` would
+   claim vault has one colour. `[data-haus-theme='vault']` holding
+   `--haus-ruby-500` reads correctly in both directions.
+
+   The ten ramp steps gained the `--haus-` prefix in the same cut. They were the
+   only unprefixed custom properties in the system, and the prefix is not
+   tidiness: an unprefixed `--ruby-500` collides with a consumer running
+   Tailwind.
+
+   Applied by attribute, and it nests:
+
+     <div data-haus-theme="vault"> … </div>
+
+   Every entry brand.css declares appears here. That is not tidiness: `BrandMap`
+   is generated from brand.css, so an omission is a type error rather than an
+   unresolved var() that silently drops a declaration.
+   ─────────────────────────────────────────────────────────────────────────── */
+
+@layer haus.brand {
+
+  [data-haus-theme='vault'] {
+
+    /* ── The ruby palette ──────────────────────────────────────────────────
+       Declared here rather than in primitives.css: a brand brings its own ramp.
+       Values are vault's, unchanged — this is a real brand rather than a
+       plausible one, which is the point of shipping it. */
+    --haus-ruby-100: oklch(96.5% 0.016 3);
+    --haus-ruby-200: oklch(91%   0.044 3);
+    --haus-ruby-300: oklch(82%   0.082 3);
+    --haus-ruby-400: oklch(64%   0.15  3);
+    --haus-ruby-500: oklch(48.2% 0.186 2.5);
+    --haus-ruby-600: oklch(44%   0.176 1.7);
+    --haus-ruby-700: oklch(40.5% 0.164 0.9);
+    --haus-ruby-800: oklch(33%   0.116 0);
+    --haus-ruby-900: oklch(23%   0.09  358);
+    --haus-ruby-950: oklch(15%   0.056 356);
+
+
+    /* ── Surface ───────────────────────────────────────────────────────── */
+    --haus-brand-surface-default:        var(--haus-damson-0);
+    --haus-brand-surface-subtle:         var(--haus-damson-100);
+    --haus-brand-surface-raised:         var(--haus-damson-0);
+    --haus-brand-surface-overlay:        var(--haus-damson-50);
+    --haus-brand-surface-sunken:         var(--haus-damson-200);
+    --haus-brand-surface-inverse:        var(--haus-damson-900);
+    --haus-brand-surface-disabled:       var(--haus-damson-100);
+    --haus-brand-surface-inverse-hover:  oklch(from var(--haus-damson-0) l c h / 0.10);
+
+    /* ── Ink ───────────────────────────────────────────────────────────── */
+    --haus-brand-ink-primary:            var(--haus-damson-900);
+    --haus-brand-ink-secondary:          var(--haus-damson-700);
+    --haus-brand-ink-tertiary:           var(--haus-damson-500);
+    --haus-brand-ink-disabled:           var(--haus-damson-400);
+    --haus-brand-ink-inverse:            var(--haus-damson-0);
+    --haus-brand-ink-link:               var(--haus-ruby-500);
+    --haus-brand-ink-on-primary:          var(--haus-damson-0);
+
+    /* ── Border ────────────────────────────────────────────────────────── */
+    --haus-brand-border-subtle:          var(--haus-damson-100);
+    --haus-brand-border-default:         var(--haus-damson-200);
+    --haus-brand-border-strong:          var(--haus-damson-300);
+    --haus-brand-border-disabled:        var(--haus-damson-200);
+    --haus-brand-border-inverse:         oklch(from var(--haus-damson-0) l c h / 0.30);
+    --haus-brand-border-inverse-hover:   oklch(from var(--haus-damson-0) l c h / 0.50);
+
+    /* ── Primary ───────────────────────────────────────────────────────── */
+    --haus-brand-primary-default:        var(--haus-ruby-500);
+    --haus-brand-primary-hover:          var(--haus-ruby-600);
+    --haus-brand-primary-pressed:        var(--haus-ruby-700);
+    --haus-brand-primary-subtle:         var(--haus-ruby-100);
+    --haus-brand-primary-on-subtle:      var(--haus-ruby-700);
+    --haus-brand-primary-disabled:       var(--haus-damson-200);
+
+    /* ── Info ──────────────────────────────────────────────────────────── */
+    --haus-brand-info-subtle:            var(--haus-elderberry-100);
+    --haus-brand-info-border:            var(--haus-elderberry-200);
+    --haus-brand-info-default:           var(--haus-elderberry-500);
+    --haus-brand-info-on-subtle:         var(--haus-elderberry-700);
+    --haus-brand-info-on-default:        var(--haus-damson-0);
+    --haus-brand-info-emphasis:          var(--haus-elderberry-900);
+
+    /* ── Success ───────────────────────────────────────────────────────── */
+    --haus-brand-success-subtle:         var(--haus-greengage-100);
+    --haus-brand-success-border:         var(--haus-greengage-200);
+    --haus-brand-success-default:        var(--haus-greengage-500);
+    --haus-brand-success-on-subtle:      var(--haus-greengage-700);
+    --haus-brand-success-on-default:     var(--haus-damson-900);
+    --haus-brand-success-solid:          var(--haus-greengage-700);
+    --haus-brand-success-emphasis:       var(--haus-greengage-900);
+
+    /* ── Warning ───────────────────────────────────────────────────────── */
+    --haus-brand-warning-subtle:         var(--haus-mango-100);
+    --haus-brand-warning-border:         var(--haus-mango-200);
+    --haus-brand-warning-default:        var(--haus-mango-500);
+    --haus-brand-warning-on-subtle:      var(--haus-mango-700);
+    --haus-brand-warning-on-default:     var(--haus-damson-900);
+    --haus-brand-warning-solid:          var(--haus-mango-700);
+    --haus-brand-warning-emphasis:       var(--haus-mango-900);
+
+    /* ── Error ─────────────────────────────────────────────────────────── */
+    --haus-brand-error-subtle:           var(--haus-cherry-100);
+    --haus-brand-error-border:           var(--haus-cherry-200);
+    --haus-brand-error-default:          var(--haus-cherry-500);
+    --haus-brand-error-on-subtle:        var(--haus-cherry-700);
+    --haus-brand-error-on-default:       var(--haus-damson-0);
+    --haus-brand-error-emphasis:         var(--haus-cherry-900);
+
+    /* ── Backdrop ──────────────────────────────────────────────────────── */
+    --haus-brand-backdrop:               oklch(from var(--haus-damson-950) l c h / var(--haus-opacity-60));
+
+  }
+}

package/dist/guard.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+// src/guard.ts
+var READ_NO_FALLBACK = /var\(\s*(--[a-zA-Z0-9-]+)\s*\)/g;
+var READ_WITH_FALLBACK = /var\(\s*(--[a-zA-Z0-9-]+)\s*,/g;
+var DECLARATION = /(?:^|[;{])\s*(--[a-zA-Z0-9-]+)\s*:/gm;
+function collect(sources, pattern) {
+  const found = /* @__PURE__ */ new Set();
+  for (const css of sources) {
+    pattern.lastIndex = 0;
+    for (const m of css.matchAll(pattern)) found.add(m[1]);
+  }
+  return found;
+}
+function findUndefinedTokens(input) {
+  const read = collect(input.reads, READ_NO_FALLBACK);
+  const defined = collect(input.defines, DECLARATION);
+  for (const name of input.alsoDefined ?? []) defined.add(name);
+  return {
+    missing: [...read].filter((name) => !defined.has(name)).sort(),
+    read: [...read].sort(),
+    defined: [...defined].sort()
+  };
+}
+function findFallbackTokens(input) {
+  const withFallback = collect(input.reads, READ_WITH_FALLBACK);
+  const defined = collect(input.defines, DECLARATION);
+  return [...withFallback].filter((name) => !defined.has(name)).sort();
+}
+
+exports.findFallbackTokens = findFallbackTokens;
+exports.findUndefinedTokens = findUndefinedTokens;
+//# sourceMappingURL=guard.cjs.map
+//# sourceMappingURL=guard.cjs.map

package/dist/guard.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/guard.ts"],"names":[],"mappings":";;;AAuDA,IAAM,gBAAA,GAAmB,iCAAA;AACzB,IAAM,kBAAA,GAAqB,gCAAA;AAK3B,IAAM,WAAA,GAAc,sCAAA;AAuBpB,SAAS,OAAA,CAAQ,SAAmB,OAAA,EAA8B;AAChE,EAAA,MAAM,KAAA,uBAAY,GAAA,EAAY;AAC9B,EAAA,KAAA,MAAW,OAAO,OAAA,EAAS;AAGzB,IAAA,OAAA,CAAQ,SAAA,GAAY,CAAA;AACpB,IAAA,KAAA,MAAW,CAAA,IAAK,IAAI,QAAA,CAAS,OAAO,GAAG,KAAA,CAAM,GAAA,CAAI,CAAA,CAAE,CAAC,CAAE,CAAA;AAAA,EACxD;AACA,EAAA,OAAO,KAAA;AACT;AASO,SAAS,oBAAoB,KAAA,EAA0C;AAC5E,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,KAAA,CAAM,KAAA,EAAO,gBAAgB,CAAA;AAClD,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,KAAA,CAAM,OAAA,EAAS,WAAW,CAAA;AAClD,EAAA,KAAA,MAAW,QAAQ,KAAA,CAAM,WAAA,IAAe,EAAC,EAAG,OAAA,CAAQ,IAAI,IAAI,CAAA;AAE5D,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,CAAC,GAAG,IAAI,EAAE,MAAA,CAAO,CAAC,IAAA,KAAS,CAAC,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAC,EAAE,IAAA,EAAK;AAAA,IAC7D,IAAA,EAAM,CAAC,GAAG,IAAI,EAAE,IAAA,EAAK;AAAA,IACrB,OAAA,EAAS,CAAC,GAAG,OAAO,EAAE,IAAA;AAAK,GAC7B;AACF;AAUO,SAAS,mBAAmB,KAAA,EAA6D;AAC9F,EAAA,MAAM,YAAA,GAAe,OAAA,CAAQ,KAAA,CAAM,KAAA,EAAO,kBAAkB,CAAA;AAC5D,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,KAAA,CAAM,OAAA,EAAS,WAAW,CAAA;AAClD,EAAA,OAAO,CAAC,GAAG,YAAY,CAAA,CAAE,MAAA,CAAO,CAAC,IAAA,KAAS,CAAC,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAC,EAAE,IAAA,EAAK;AACrE","file":"guard.cjs","sourcesContent":["/**\n * The token guard: every custom property a stylesheet reads must be defined\n * somewhere the consumer actually loads.\n *\n * CSS fails silently here, which is what makes this worth shipping. `var(--x)`\n * for an undefined `--x` is invalid at computed-value time: the declaration is\n * dropped and the property inherits. No console warning, no build error,\n * nothing in review: a focus ring is simply absent, and a missing duration\n * looks like a design choice.\n *\n * drift wrote this check for itself and it caught five roles before they\n * reached a screen: `--color-ink-on-primary`, `--elevation-floating`,\n * `--motion-duration-emphasis`, `--radius-marker` and `--haus-focus-ring-error`.\n * The contract is defined in this package, so the check belongs here rather\n * than being rewritten by every consumer (haus#19). Shipping it is also the\n * point: a design system that can say *you have not loaded what my components\n * read* is a different thing from one that hopes you did.\n *\n * **Pure, and it does no file reading.** It takes CSS as strings, so it runs in\n * a Vitest suite, a Node script, a build step or a browser without this package\n * growing a dependency on `node:fs`. The consumer knows which files it loads;\n * this only knows what the contract is.\n *\n * @example\n * ```ts\n * import { readFileSync } from 'node:fs'\n * import { findUndefinedTokens } from 'haus-tokens/guard'\n *\n * const read = (p: string) => readFileSync(p, 'utf8')\n *\n * it('reads no role this app does not load', () => {\n *   const { missing } = findUndefinedTokens({\n *     reads:   [read('node_modules/haus-components/dist/styles.css')],\n *     defines: [\n *       read('node_modules/haus-tokens/dist/primitives.css'),\n *       read('node_modules/haus-tokens/dist/semantics.css'),\n *       read('node_modules/haus-tokens/dist/motion.css'),\n *       read('src/tokens/overrides.css'),\n *     ],\n *   })\n *   expect(missing).toEqual([])\n * })\n * ```\n */\n\n/**\n * `var(--x)` with no fallback.\n *\n * A reference with a fallback, `var(--x, 0.2s)`, is a real value whether or\n * not the property is set, so it cannot fail at computed-value time and is\n * excluded. It is still usually a sign the name is wrong: a fallback that never\n * loses is a hardcoded value wearing a token's clothes. `findFallbackTokens`\n * below is for looking at those deliberately, rather than failing a build on\n * something that works.\n */\nconst READ_NO_FALLBACK = /var\\(\\s*(--[a-zA-Z0-9-]+)\\s*\\)/g\nconst READ_WITH_FALLBACK = /var\\(\\s*(--[a-zA-Z0-9-]+)\\s*,/g\n// `m` is load-bearing: without it `^` only matches the start of the whole\n// string, so every declaration on its own indented line after a newline is\n// missed and only the first in each block is seen. Caught by this package's\n// own guard test: semantics.css came back with 41 undefined roles.\nconst DECLARATION = /(?:^|[;{])\\s*(--[a-zA-Z0-9-]+)\\s*:/gm\n\nexport interface TokenGuardInput {\n  /** The CSS doing the reading: the component stylesheet, your own modules. */\n  reads: string[]\n  /** The CSS doing the defining: the token layers you load, plus your own. */\n  defines: string[]\n  /**\n   * Names defined outside CSS. A component that sets `style={{ '--x': v }}`\n   * defines the property on the element, and no stylesheet will show it.\n   */\n  alsoDefined?: string[]\n}\n\nexport interface TokenGuardResult {\n  /** Read with no fallback and defined nowhere. Sorted, so a diff is stable. */\n  missing: string[]\n  /** Every property read without a fallback. */\n  read: string[]\n  /** Every property declared across `defines` and `alsoDefined`. */\n  defined: string[]\n}\n\nfunction collect(sources: string[], pattern: RegExp): Set<string> {\n  const found = new Set<string>()\n  for (const css of sources) {\n    // A fresh lastIndex per source: a /g regex is stateful, and reusing one\n    // across inputs silently skips the start of every source after the first.\n    pattern.lastIndex = 0\n    for (const m of css.matchAll(pattern)) found.add(m[1]!)\n  }\n  return found\n}\n\n/**\n * Which properties are read but never defined.\n *\n * An empty `missing` is the assertion. The other two fields are for a consumer\n * that wants to report rather than fail: `read.length` is also worth asserting\n * as a floor, because a wrong path makes every check pass by finding nothing.\n */\nexport function findUndefinedTokens(input: TokenGuardInput): TokenGuardResult {\n  const read = collect(input.reads, READ_NO_FALLBACK)\n  const defined = collect(input.defines, DECLARATION)\n  for (const name of input.alsoDefined ?? []) defined.add(name)\n\n  return {\n    missing: [...read].filter((name) => !defined.has(name)).sort(),\n    read: [...read].sort(),\n    defined: [...defined].sort(),\n  }\n}\n\n/**\n * Which properties are only ever read with a fallback.\n *\n * Not a failure, and deliberately a separate function so it cannot be mistaken\n * for one. A fallback that never loses is a hardcoded value wearing a token's\n * clothes, and the list is worth reading occasionally rather than failing a\n * build over.\n */\nexport function findFallbackTokens(input: Pick<TokenGuardInput, 'reads' | 'defines'>): string[] {\n  const withFallback = collect(input.reads, READ_WITH_FALLBACK)\n  const defined = collect(input.defines, DECLARATION)\n  return [...withFallback].filter((name) => !defined.has(name)).sort()\n}\n"]}

package/dist/guard.d.cts

@@ -0,0 +1,82 @@
+/**
+ * The token guard: every custom property a stylesheet reads must be defined
+ * somewhere the consumer actually loads.
+ *
+ * CSS fails silently here, which is what makes this worth shipping. `var(--x)`
+ * for an undefined `--x` is invalid at computed-value time: the declaration is
+ * dropped and the property inherits. No console warning, no build error,
+ * nothing in review: a focus ring is simply absent, and a missing duration
+ * looks like a design choice.
+ *
+ * drift wrote this check for itself and it caught five roles before they
+ * reached a screen: `--color-ink-on-primary`, `--elevation-floating`,
+ * `--motion-duration-emphasis`, `--radius-marker` and `--haus-focus-ring-error`.
+ * The contract is defined in this package, so the check belongs here rather
+ * than being rewritten by every consumer (haus#19). Shipping it is also the
+ * point: a design system that can say *you have not loaded what my components
+ * read* is a different thing from one that hopes you did.
+ *
+ * **Pure, and it does no file reading.** It takes CSS as strings, so it runs in
+ * a Vitest suite, a Node script, a build step or a browser without this package
+ * growing a dependency on `node:fs`. The consumer knows which files it loads;
+ * this only knows what the contract is.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs'
+ * import { findUndefinedTokens } from 'haus-tokens/guard'
+ *
+ * const read = (p: string) => readFileSync(p, 'utf8')
+ *
+ * it('reads no role this app does not load', () => {
+ *   const { missing } = findUndefinedTokens({
+ *     reads:   [read('node_modules/haus-components/dist/styles.css')],
+ *     defines: [
+ *       read('node_modules/haus-tokens/dist/primitives.css'),
+ *       read('node_modules/haus-tokens/dist/semantics.css'),
+ *       read('node_modules/haus-tokens/dist/motion.css'),
+ *       read('src/tokens/overrides.css'),
+ *     ],
+ *   })
+ *   expect(missing).toEqual([])
+ * })
+ * ```
+ */
+interface TokenGuardInput {
+    /** The CSS doing the reading: the component stylesheet, your own modules. */
+    reads: string[];
+    /** The CSS doing the defining: the token layers you load, plus your own. */
+    defines: string[];
+    /**
+     * Names defined outside CSS. A component that sets `style={{ '--x': v }}`
+     * defines the property on the element, and no stylesheet will show it.
+     */
+    alsoDefined?: string[];
+}
+interface TokenGuardResult {
+    /** Read with no fallback and defined nowhere. Sorted, so a diff is stable. */
+    missing: string[];
+    /** Every property read without a fallback. */
+    read: string[];
+    /** Every property declared across `defines` and `alsoDefined`. */
+    defined: string[];
+}
+/**
+ * Which properties are read but never defined.
+ *
+ * An empty `missing` is the assertion. The other two fields are for a consumer
+ * that wants to report rather than fail: `read.length` is also worth asserting
+ * as a floor, because a wrong path makes every check pass by finding nothing.
+ */
+declare function findUndefinedTokens(input: TokenGuardInput): TokenGuardResult;
+/**
+ * Which properties are only ever read with a fallback.
+ *
+ * Not a failure, and deliberately a separate function so it cannot be mistaken
+ * for one. A fallback that never loses is a hardcoded value wearing a token's
+ * clothes, and the list is worth reading occasionally rather than failing a
+ * build over.
+ */
+declare function findFallbackTokens(input: Pick<TokenGuardInput, 'reads' | 'defines'>): string[];
+
+export { type TokenGuardInput, type TokenGuardResult, findFallbackTokens, findUndefinedTokens };

package/dist/guard.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The token guard: every custom property a stylesheet reads must be defined
+ * somewhere the consumer actually loads.
+ *
+ * CSS fails silently here, which is what makes this worth shipping. `var(--x)`
+ * for an undefined `--x` is invalid at computed-value time: the declaration is
+ * dropped and the property inherits. No console warning, no build error,
+ * nothing in review: a focus ring is simply absent, and a missing duration
+ * looks like a design choice.
+ *
+ * drift wrote this check for itself and it caught five roles before they
+ * reached a screen: `--color-ink-on-primary`, `--elevation-floating`,
+ * `--motion-duration-emphasis`, `--radius-marker` and `--haus-focus-ring-error`.
+ * The contract is defined in this package, so the check belongs here rather
+ * than being rewritten by every consumer (haus#19). Shipping it is also the
+ * point: a design system that can say *you have not loaded what my components
+ * read* is a different thing from one that hopes you did.
+ *
+ * **Pure, and it does no file reading.** It takes CSS as strings, so it runs in
+ * a Vitest suite, a Node script, a build step or a browser without this package
+ * growing a dependency on `node:fs`. The consumer knows which files it loads;
+ * this only knows what the contract is.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs'
+ * import { findUndefinedTokens } from 'haus-tokens/guard'
+ *
+ * const read = (p: string) => readFileSync(p, 'utf8')
+ *
+ * it('reads no role this app does not load', () => {
+ *   const { missing } = findUndefinedTokens({
+ *     reads:   [read('node_modules/haus-components/dist/styles.css')],
+ *     defines: [
+ *       read('node_modules/haus-tokens/dist/primitives.css'),
+ *       read('node_modules/haus-tokens/dist/semantics.css'),
+ *       read('node_modules/haus-tokens/dist/motion.css'),
+ *       read('src/tokens/overrides.css'),
+ *     ],
+ *   })
+ *   expect(missing).toEqual([])
+ * })
+ * ```
+ */
+interface TokenGuardInput {
+    /** The CSS doing the reading: the component stylesheet, your own modules. */
+    reads: string[];
+    /** The CSS doing the defining: the token layers you load, plus your own. */
+    defines: string[];
+    /**
+     * Names defined outside CSS. A component that sets `style={{ '--x': v }}`
+     * defines the property on the element, and no stylesheet will show it.
+     */
+    alsoDefined?: string[];
+}
+interface TokenGuardResult {
+    /** Read with no fallback and defined nowhere. Sorted, so a diff is stable. */
+    missing: string[];
+    /** Every property read without a fallback. */
+    read: string[];
+    /** Every property declared across `defines` and `alsoDefined`. */
+    defined: string[];
+}
+/**
+ * Which properties are read but never defined.
+ *
+ * An empty `missing` is the assertion. The other two fields are for a consumer
+ * that wants to report rather than fail: `read.length` is also worth asserting
+ * as a floor, because a wrong path makes every check pass by finding nothing.
+ */
+declare function findUndefinedTokens(input: TokenGuardInput): TokenGuardResult;
+/**
+ * Which properties are only ever read with a fallback.
+ *
+ * Not a failure, and deliberately a separate function so it cannot be mistaken
+ * for one. A fallback that never loses is a hardcoded value wearing a token's
+ * clothes, and the list is worth reading occasionally rather than failing a
+ * build over.
+ */
+declare function findFallbackTokens(input: Pick<TokenGuardInput, 'reads' | 'defines'>): string[];
+
+export { type TokenGuardInput, type TokenGuardResult, findFallbackTokens, findUndefinedTokens };

package/dist/guard.js

@@ -0,0 +1,31 @@
+// src/guard.ts
+var READ_NO_FALLBACK = /var\(\s*(--[a-zA-Z0-9-]+)\s*\)/g;
+var READ_WITH_FALLBACK = /var\(\s*(--[a-zA-Z0-9-]+)\s*,/g;
+var DECLARATION = /(?:^|[;{])\s*(--[a-zA-Z0-9-]+)\s*:/gm;
+function collect(sources, pattern) {
+  const found = /* @__PURE__ */ new Set();
+  for (const css of sources) {
+    pattern.lastIndex = 0;
+    for (const m of css.matchAll(pattern)) found.add(m[1]);
+  }
+  return found;
+}
+function findUndefinedTokens(input) {
+  const read = collect(input.reads, READ_NO_FALLBACK);
+  const defined = collect(input.defines, DECLARATION);
+  for (const name of input.alsoDefined ?? []) defined.add(name);
+  return {
+    missing: [...read].filter((name) => !defined.has(name)).sort(),
+    read: [...read].sort(),
+    defined: [...defined].sort()
+  };
+}
+function findFallbackTokens(input) {
+  const withFallback = collect(input.reads, READ_WITH_FALLBACK);
+  const defined = collect(input.defines, DECLARATION);
+  return [...withFallback].filter((name) => !defined.has(name)).sort();
+}
+
+export { findFallbackTokens, findUndefinedTokens };
+//# sourceMappingURL=guard.js.map
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/guard.ts"],"names":[],"mappings":";AAuDA,IAAM,gBAAA,GAAmB,iCAAA;AACzB,IAAM,kBAAA,GAAqB,gCAAA;AAK3B,IAAM,WAAA,GAAc,sCAAA;AAuBpB,SAAS,OAAA,CAAQ,SAAmB,OAAA,EAA8B;AAChE,EAAA,MAAM,KAAA,uBAAY,GAAA,EAAY;AAC9B,EAAA,KAAA,MAAW,OAAO,OAAA,EAAS;AAGzB,IAAA,OAAA,CAAQ,SAAA,GAAY,CAAA;AACpB,IAAA,KAAA,MAAW,CAAA,IAAK,IAAI,QAAA,CAAS,OAAO,GAAG,KAAA,CAAM,GAAA,CAAI,CAAA,CAAE,CAAC,CAAE,CAAA;AAAA,EACxD;AACA,EAAA,OAAO,KAAA;AACT;AASO,SAAS,oBAAoB,KAAA,EAA0C;AAC5E,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,KAAA,CAAM,KAAA,EAAO,gBAAgB,CAAA;AAClD,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,KAAA,CAAM,OAAA,EAAS,WAAW,CAAA;AAClD,EAAA,KAAA,MAAW,QAAQ,KAAA,CAAM,WAAA,IAAe,EAAC,EAAG,OAAA,CAAQ,IAAI,IAAI,CAAA;AAE5D,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,CAAC,GAAG,IAAI,EAAE,MAAA,CAAO,CAAC,IAAA,KAAS,CAAC,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAC,EAAE,IAAA,EAAK;AAAA,IAC7D,IAAA,EAAM,CAAC,GAAG,IAAI,EAAE,IAAA,EAAK;AAAA,IACrB,OAAA,EAAS,CAAC,GAAG,OAAO,EAAE,IAAA;AAAK,GAC7B;AACF;AAUO,SAAS,mBAAmB,KAAA,EAA6D;AAC9F,EAAA,MAAM,YAAA,GAAe,OAAA,CAAQ,KAAA,CAAM,KAAA,EAAO,kBAAkB,CAAA;AAC5D,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,KAAA,CAAM,OAAA,EAAS,WAAW,CAAA;AAClD,EAAA,OAAO,CAAC,GAAG,YAAY,CAAA,CAAE,MAAA,CAAO,CAAC,IAAA,KAAS,CAAC,OAAA,CAAQ,GAAA,CAAI,IAAI,CAAC,EAAE,IAAA,EAAK;AACrE","file":"guard.js","sourcesContent":["/**\n * The token guard: every custom property a stylesheet reads must be defined\n * somewhere the consumer actually loads.\n *\n * CSS fails silently here, which is what makes this worth shipping. `var(--x)`\n * for an undefined `--x` is invalid at computed-value time: the declaration is\n * dropped and the property inherits. No console warning, no build error,\n * nothing in review: a focus ring is simply absent, and a missing duration\n * looks like a design choice.\n *\n * drift wrote this check for itself and it caught five roles before they\n * reached a screen: `--color-ink-on-primary`, `--elevation-floating`,\n * `--motion-duration-emphasis`, `--radius-marker` and `--haus-focus-ring-error`.\n * The contract is defined in this package, so the check belongs here rather\n * than being rewritten by every consumer (haus#19). Shipping it is also the\n * point: a design system that can say *you have not loaded what my components\n * read* is a different thing from one that hopes you did.\n *\n * **Pure, and it does no file reading.** It takes CSS as strings, so it runs in\n * a Vitest suite, a Node script, a build step or a browser without this package\n * growing a dependency on `node:fs`. The consumer knows which files it loads;\n * this only knows what the contract is.\n *\n * @example\n * ```ts\n * import { readFileSync } from 'node:fs'\n * import { findUndefinedTokens } from 'haus-tokens/guard'\n *\n * const read = (p: string) => readFileSync(p, 'utf8')\n *\n * it('reads no role this app does not load', () => {\n *   const { missing } = findUndefinedTokens({\n *     reads:   [read('node_modules/haus-components/dist/styles.css')],\n *     defines: [\n *       read('node_modules/haus-tokens/dist/primitives.css'),\n *       read('node_modules/haus-tokens/dist/semantics.css'),\n *       read('node_modules/haus-tokens/dist/motion.css'),\n *       read('src/tokens/overrides.css'),\n *     ],\n *   })\n *   expect(missing).toEqual([])\n * })\n * ```\n */\n\n/**\n * `var(--x)` with no fallback.\n *\n * A reference with a fallback, `var(--x, 0.2s)`, is a real value whether or\n * not the property is set, so it cannot fail at computed-value time and is\n * excluded. It is still usually a sign the name is wrong: a fallback that never\n * loses is a hardcoded value wearing a token's clothes. `findFallbackTokens`\n * below is for looking at those deliberately, rather than failing a build on\n * something that works.\n */\nconst READ_NO_FALLBACK = /var\\(\\s*(--[a-zA-Z0-9-]+)\\s*\\)/g\nconst READ_WITH_FALLBACK = /var\\(\\s*(--[a-zA-Z0-9-]+)\\s*,/g\n// `m` is load-bearing: without it `^` only matches the start of the whole\n// string, so every declaration on its own indented line after a newline is\n// missed and only the first in each block is seen. Caught by this package's\n// own guard test: semantics.css came back with 41 undefined roles.\nconst DECLARATION = /(?:^|[;{])\\s*(--[a-zA-Z0-9-]+)\\s*:/gm\n\nexport interface TokenGuardInput {\n  /** The CSS doing the reading: the component stylesheet, your own modules. */\n  reads: string[]\n  /** The CSS doing the defining: the token layers you load, plus your own. */\n  defines: string[]\n  /**\n   * Names defined outside CSS. A component that sets `style={{ '--x': v }}`\n   * defines the property on the element, and no stylesheet will show it.\n   */\n  alsoDefined?: string[]\n}\n\nexport interface TokenGuardResult {\n  /** Read with no fallback and defined nowhere. Sorted, so a diff is stable. */\n  missing: string[]\n  /** Every property read without a fallback. */\n  read: string[]\n  /** Every property declared across `defines` and `alsoDefined`. */\n  defined: string[]\n}\n\nfunction collect(sources: string[], pattern: RegExp): Set<string> {\n  const found = new Set<string>()\n  for (const css of sources) {\n    // A fresh lastIndex per source: a /g regex is stateful, and reusing one\n    // across inputs silently skips the start of every source after the first.\n    pattern.lastIndex = 0\n    for (const m of css.matchAll(pattern)) found.add(m[1]!)\n  }\n  return found\n}\n\n/**\n * Which properties are read but never defined.\n *\n * An empty `missing` is the assertion. The other two fields are for a consumer\n * that wants to report rather than fail: `read.length` is also worth asserting\n * as a floor, because a wrong path makes every check pass by finding nothing.\n */\nexport function findUndefinedTokens(input: TokenGuardInput): TokenGuardResult {\n  const read = collect(input.reads, READ_NO_FALLBACK)\n  const defined = collect(input.defines, DECLARATION)\n  for (const name of input.alsoDefined ?? []) defined.add(name)\n\n  return {\n    missing: [...read].filter((name) => !defined.has(name)).sort(),\n    read: [...read].sort(),\n    defined: [...defined].sort(),\n  }\n}\n\n/**\n * Which properties are only ever read with a fallback.\n *\n * Not a failure, and deliberately a separate function so it cannot be mistaken\n * for one. A fallback that never loses is a hardcoded value wearing a token's\n * clothes, and the list is worth reading occasionally rather than failing a\n * build over.\n */\nexport function findFallbackTokens(input: Pick<TokenGuardInput, 'reads' | 'defines'>): string[] {\n  const withFallback = collect(input.reads, READ_WITH_FALLBACK)\n  const defined = collect(input.defines, DECLARATION)\n  return [...withFallback].filter((name) => !defined.has(name)).sort()\n}\n"]}