@domandigital/craft 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @domandigital/craft
 
+## 0.4.0
+
+### Minor Changes
+
+- 1b2e8bf: `checkRestraint` resolves token references instead of skipping them.
+
+  The old rule skipped any value starting with `var(`, on the reasoning that a
+  token reference is the token layer doing its job rather than a new value. True
+  of a hand-written sheet. On a Tailwind v4 sheet it is close to measuring
+  nothing: `text-sm` compiles to `font-size: var(--text-sm)` and `rounded-lg` to
+  `border-radius: var(--radius-lg)`, and `shadow-[…]` emits no `box-shadow` at
+  all — it assigns `--tw-shadow` and lets one shared composite read it.
+
+  Measured on the estate this was hiding, per surface: 19 font sizes reported
+  against 28 shipped, 5 shadows against 18, 7 radii against 13. A second surface
+  reported `ok: true` on every axis and is over budget on four.
+
+  What changes:
+
+  - A value that is exactly one `var()` is resolved through the token chain to
+    the value that renders, and counted.
+  - `--tw-shadow` assignments count as shadows; Tailwind's composite plumbing
+    value does not, and neither does its `0 0 #0000` initial.
+  - `var(--tw-shadow-color, X)` is unwrapped to `X`, so the report names what a
+    reader would see.
+  - Definitions are read from the whole sheet, including ignored layers, while
+    usage is still read only from kept ones. The layer exclusion is unchanged in
+    intent and now works: a framework default nothing uses still counts for
+    nothing. Used versus unused was always the real distinction; which layer the
+    definition sat in never was.
+  - New `unresolved-token` warning for a declaration whose token is defined
+    nowhere and which carries no fallback. It applies nothing, so it is not
+    vocabulary — it is a bug, and it now says so. It found two on first contact.
+
+  **Every consumer's baseline will move**, upward, on surfaces built with a
+  utility framework. That is the correction, not a regression.
+
 ## 0.3.0
 
 ### Minor Changes

package/STANDARD.md

@@ -117,13 +117,34 @@ Differentiation guards pass anything that differs from its siblings, however
 ugly. What they cannot see is accumulation — eighteen font sizes, six shadows,
 four competing accents, each added reasonably, together reading as noise.
 
-The budget counts the vocabulary a surface **chose**. A compiled stylesheet also
-carries the framework's reset and theme, and `@layer theme` / `@layer base` are
-excluded by default for that reason — counting them reports a surface as over
-budget for values its author never wrote, and real findings then get triaged
-away with the noise.
-
-*Source: measured against the estate; the budget is the observed ceiling of the surfaces that read as designed. The layer exclusion is measured too — Tailwind v4's reset and theme contribute three font sizes and two timing functions to every sheet built with it.*
+The budget counts the vocabulary a surface **chose**, and the whole difficulty
+is telling that apart from what the framework brought.
+
+The first rule drew the line at the layer: `@layer theme` and `@layer base` were
+excluded, because counting them reported a surface as over budget for values its
+author never wrote. Right about the noise, wrong about the boundary. Tailwind v4
+compiles `text-sm` to `font-size: var(--text-sm)` and `rounded-lg` to
+`border-radius: var(--radius-lg)`, so with the definitions excluded *and* token
+references skipped, a surface using `text-sm` seven hundred times reported it
+zero times. One estate measured 19 font sizes and shipped 28; 5 shadows and
+shipped 18. A count wrong in the under-reporting direction is worse than the
+over-reporting kind it replaced: the first buries real findings in noise, the
+second reports a pass.
+
+The line is **used versus unused**, which is not a property of the layer:
+
+- References are **resolved**, not skipped — through the token chain, to the
+  value that renders.
+- A definition is only ever reached from a declaration in a kept layer, so a
+  framework default nothing uses still counts for nothing.
+- `--tw-shadow` assignments count as shadows. `shadow-[…]` emits no literal
+  `box-shadow` at all; it assigns that property and lets one shared composite
+  read it.
+- A reference that resolves to nothing is **not** vocabulary. It is a
+  declaration that silently applies nothing, and it is reported as its own
+  warning.
+
+*Source: measured against the estate. The budget is the observed ceiling of the surfaces that read as designed; the resolution rule is what it took to measure them at all.*
 
 ## 10. What is deliberately not a rule
 

package/dist/index.cjs

@@ -852,10 +852,19 @@ function stripLayers(css, ignored) {
   }
   return out;
 }
-var CSS_WIDE_KEYWORDS = /* @__PURE__ */ new Set(["inherit", "initial", "unset", "revert", "revert-layer"]);
+var CSS_WIDE_KEYWORDS = /* @__PURE__ */ new Set([
+  "inherit",
+  "initial",
+  "unset",
+  "revert",
+  "revert-layer"
+]);
 function atRuleBodies(css, prelude) {
   const out = [];
-  const pattern = new RegExp(prelude.source, prelude.flags.includes("g") ? prelude.flags : `${prelude.flags}g`);
+  const pattern = new RegExp(
+    prelude.source,
+    prelude.flags.includes("g") ? prelude.flags : `${prelude.flags}g`
+  );
   let match;
   while ((match = pattern.exec(css)) !== null) {
     const start = match.index + match[0].length;
@@ -871,13 +880,64 @@ function atRuleBodies(css, prelude) {
   }
   return out;
 }
-function distinctValues(css, property) {
+function customProperties(css) {
+  const out = /* @__PURE__ */ new Map();
+  for (const match of css.matchAll(/(--[\w-]+)\s*:\s*([^;}]+)/g)) {
+    out.set(match[1].toLowerCase(), match[2].trim().replace(/\s+/g, " "));
+  }
+  return out;
+}
+function unwrapShadowColor(value) {
+  return value.replace(
+    /var\(\s*--tw-shadow-color\s*,\s*([^)]*(?:\([^)]*\))?[^)]*)\)/g,
+    "$1"
+  );
+}
+var SINGLE_VAR = /^var\(\s*(--[\w-]+)\s*(?:,([\s\S]*))?\)$/;
+function resolveValue(value, props, depth = 0) {
+  if (depth > 8) return null;
+  const match = SINGLE_VAR.exec(value.trim());
+  if (match === null) return value.trim();
+  const target = props.get(match[1].toLowerCase());
+  if (target !== void 0 && target !== "initial")
+    return resolveValue(target, props, depth + 1);
+  const fallback = match[2]?.trim();
+  return fallback === void 0 || fallback === "" ? null : resolveValue(fallback, props, depth + 1);
+}
+function isVarOnlyList(value) {
+  const parts = value.split(",");
+  return parts.length > 1 && parts.every((part) => /^\s*var\(\s*--[\w-]+\s*\)\s*$/.test(part));
+}
+function distinctValues(css, property, props, unresolved) {
   const pattern = new RegExp(`(?:^|[;{\\s])${property}\\s*:\\s*([^;}]+)`, "gi");
   const seen = /* @__PURE__ */ new Set();
   for (const match of css.matchAll(pattern)) {
-    const value = match[1].trim().replace(/\s+/g, " ").toLowerCase();
-    if (value.startsWith("var(") || CSS_WIDE_KEYWORDS.has(value)) continue;
-    seen.add(value);
+    const raw = match[1].trim().replace(/\s+/g, " ").toLowerCase();
+    if (CSS_WIDE_KEYWORDS.has(raw)) continue;
+    const value = unwrapShadowColor(raw);
+    if (isVarOnlyList(value)) continue;
+    if (!SINGLE_VAR.test(value)) {
+      seen.add(value);
+      continue;
+    }
+    if (props === void 0) continue;
+    const resolved = resolveValue(value, props);
+    if (resolved === null) {
+      unresolved?.add(`${property}: ${value}`);
+      continue;
+    }
+    seen.add(unwrapShadowColor(resolved).toLowerCase());
+  }
+  return [...seen];
+}
+function twShadowValues(css, props) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const match of css.matchAll(/--tw-shadow\s*:\s*([^;}]+)/g)) {
+    const raw = match[1].trim().replace(/\s+/g, " ").toLowerCase();
+    if (raw === "0 0 #0000" || raw === "none") continue;
+    const value = SINGLE_VAR.test(raw) ? resolveValue(raw, props) : raw;
+    if (value === null) continue;
+    seen.add(unwrapShadowColor(value).toLowerCase());
   }
   return [...seen];
 }
@@ -892,15 +952,18 @@ function durationsMs(css) {
 }
 function checkRestraint(input) {
   const budget = { ...HOUSE_BUDGET, ...input.budget };
+  const whole = stripComments(input.css);
+  const props = customProperties(whole);
   const css = stripLayers(
-    stripComments(input.css),
+    whole,
     input.ignoreAtLayers ?? DEFAULT_IGNORED_LAYERS
   );
+  const unresolved = /* @__PURE__ */ new Set();
   const violations = [];
   const push = (rule, severity, message, found) => {
     violations.push({ rule, severity, message, found });
   };
-  const fontSizes = distinctValues(css, "font-size");
+  const fontSizes = distinctValues(css, "font-size", props, unresolved);
   if (fontSizes.length > budget.maxFontSizes) {
     push(
       "font-sizes",
@@ -909,10 +972,15 @@ function checkRestraint(input) {
       fontSizes
     );
   }
-  const weights = distinctValues(css, "font-weight").filter((w) => w !== "normal" && w !== "bold");
-  const namedWeights = distinctValues(css, "font-weight").filter(
-    (w) => w === "normal" || w === "bold"
+  const weights = distinctValues(css, "font-weight", props, unresolved).filter(
+    (w) => w !== "normal" && w !== "bold"
   );
+  const namedWeights = distinctValues(
+    css,
+    "font-weight",
+    props,
+    unresolved
+  ).filter((w) => w === "normal" || w === "bold");
   const allWeights = [.../* @__PURE__ */ new Set([...weights, ...namedWeights])];
   if (allWeights.length > budget.maxFontWeights) {
     push(
@@ -922,7 +990,7 @@ function checkRestraint(input) {
       allWeights
     );
   }
-  const families = distinctValues(css, "font-family").filter(
+  const families = distinctValues(css, "font-family", props, unresolved).filter(
     (f) => !/\bmonospace\b|\bmono\b/.test(f)
   );
   if (families.length > budget.maxFontFamilies) {
@@ -933,11 +1001,23 @@ function checkRestraint(input) {
       families
     );
   }
-  const radii = distinctValues(css, "border-radius").filter((r) => r !== "0" && r !== "0px");
+  const radii = distinctValues(css, "border-radius", props, unresolved).filter(
+    (r) => r !== "0" && r !== "0px"
+  );
   if (radii.length > budget.maxRadii) {
-    push("radii", "error", `${radii.length} corner radii, budget ${budget.maxRadii}.`, radii);
+    push(
+      "radii",
+      "error",
+      `${radii.length} corner radii, budget ${budget.maxRadii}.`,
+      radii
+    );
   }
-  const shadows = distinctValues(css, "box-shadow").filter((s) => s !== "none");
+  const shadows = [
+    .../* @__PURE__ */ new Set([
+      ...distinctValues(css, "box-shadow", props, unresolved),
+      ...twShadowValues(css, props)
+    ])
+  ].filter((s) => s !== "none");
   if (shadows.length > budget.maxShadows) {
     push(
       "shadows",
@@ -946,6 +1026,14 @@ function checkRestraint(input) {
       shadows
     );
   }
+  if (unresolved.size > 0) {
+    push(
+      "unresolved-token",
+      "warning",
+      `${unresolved.size} declaration(s) reference a custom property that is never defined and carry no fallback. Each one applies nothing.`,
+      [...unresolved].sort()
+    );
+  }
   const accentHexes = [
     ...css.matchAll(/--[a-z0-9-]*accent[a-z0-9-]*\s*:\s*(#[0-9a-fA-F]{3,8})/g)
   ].map((m) => m[1]);
@@ -997,7 +1085,9 @@ function checkRestraint(input) {
       [...new Set(easeIn)]
     );
   }
-  const overBudget = durationsMs(css).filter((d) => d.ms > budget.maxUiDurationMs);
+  const overBudget = durationsMs(css).filter(
+    (d) => d.ms > budget.maxUiDurationMs
+  );
   if (overBudget.length > 0) {
     push(
       "duration",
@@ -1014,7 +1104,10 @@ function checkRestraint(input) {
       ["scale(0)"]
     );
   }
-  const reducedMotionBlocks = atRuleBodies(css, /@media[^{]*prefers-reduced-motion:\s*reduce[^{]*\{/gi);
+  const reducedMotionBlocks = atRuleBodies(
+    css,
+    /@media[^{]*prefers-reduced-motion:\s*reduce[^{]*\{/gi
+  );
   if (reducedMotionBlocks.length === 0) {
     if (/@keyframes|animation\s*:|transition\s*:/.test(css)) {
       push(

package/dist/index.js

@@ -780,10 +780,19 @@ function stripLayers(css, ignored) {
   }
   return out;
 }
-var CSS_WIDE_KEYWORDS = /* @__PURE__ */ new Set(["inherit", "initial", "unset", "revert", "revert-layer"]);
+var CSS_WIDE_KEYWORDS = /* @__PURE__ */ new Set([
+  "inherit",
+  "initial",
+  "unset",
+  "revert",
+  "revert-layer"
+]);
 function atRuleBodies(css, prelude) {
   const out = [];
-  const pattern = new RegExp(prelude.source, prelude.flags.includes("g") ? prelude.flags : `${prelude.flags}g`);
+  const pattern = new RegExp(
+    prelude.source,
+    prelude.flags.includes("g") ? prelude.flags : `${prelude.flags}g`
+  );
   let match;
   while ((match = pattern.exec(css)) !== null) {
     const start = match.index + match[0].length;
@@ -799,13 +808,64 @@ function atRuleBodies(css, prelude) {
   }
   return out;
 }
-function distinctValues(css, property) {
+function customProperties(css) {
+  const out = /* @__PURE__ */ new Map();
+  for (const match of css.matchAll(/(--[\w-]+)\s*:\s*([^;}]+)/g)) {
+    out.set(match[1].toLowerCase(), match[2].trim().replace(/\s+/g, " "));
+  }
+  return out;
+}
+function unwrapShadowColor(value) {
+  return value.replace(
+    /var\(\s*--tw-shadow-color\s*,\s*([^)]*(?:\([^)]*\))?[^)]*)\)/g,
+    "$1"
+  );
+}
+var SINGLE_VAR = /^var\(\s*(--[\w-]+)\s*(?:,([\s\S]*))?\)$/;
+function resolveValue(value, props, depth = 0) {
+  if (depth > 8) return null;
+  const match = SINGLE_VAR.exec(value.trim());
+  if (match === null) return value.trim();
+  const target = props.get(match[1].toLowerCase());
+  if (target !== void 0 && target !== "initial")
+    return resolveValue(target, props, depth + 1);
+  const fallback = match[2]?.trim();
+  return fallback === void 0 || fallback === "" ? null : resolveValue(fallback, props, depth + 1);
+}
+function isVarOnlyList(value) {
+  const parts = value.split(",");
+  return parts.length > 1 && parts.every((part) => /^\s*var\(\s*--[\w-]+\s*\)\s*$/.test(part));
+}
+function distinctValues(css, property, props, unresolved) {
   const pattern = new RegExp(`(?:^|[;{\\s])${property}\\s*:\\s*([^;}]+)`, "gi");
   const seen = /* @__PURE__ */ new Set();
   for (const match of css.matchAll(pattern)) {
-    const value = match[1].trim().replace(/\s+/g, " ").toLowerCase();
-    if (value.startsWith("var(") || CSS_WIDE_KEYWORDS.has(value)) continue;
-    seen.add(value);
+    const raw = match[1].trim().replace(/\s+/g, " ").toLowerCase();
+    if (CSS_WIDE_KEYWORDS.has(raw)) continue;
+    const value = unwrapShadowColor(raw);
+    if (isVarOnlyList(value)) continue;
+    if (!SINGLE_VAR.test(value)) {
+      seen.add(value);
+      continue;
+    }
+    if (props === void 0) continue;
+    const resolved = resolveValue(value, props);
+    if (resolved === null) {
+      unresolved?.add(`${property}: ${value}`);
+      continue;
+    }
+    seen.add(unwrapShadowColor(resolved).toLowerCase());
+  }
+  return [...seen];
+}
+function twShadowValues(css, props) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const match of css.matchAll(/--tw-shadow\s*:\s*([^;}]+)/g)) {
+    const raw = match[1].trim().replace(/\s+/g, " ").toLowerCase();
+    if (raw === "0 0 #0000" || raw === "none") continue;
+    const value = SINGLE_VAR.test(raw) ? resolveValue(raw, props) : raw;
+    if (value === null) continue;
+    seen.add(unwrapShadowColor(value).toLowerCase());
   }
   return [...seen];
 }
@@ -820,15 +880,18 @@ function durationsMs(css) {
 }
 function checkRestraint(input) {
   const budget = { ...HOUSE_BUDGET, ...input.budget };
+  const whole = stripComments(input.css);
+  const props = customProperties(whole);
   const css = stripLayers(
-    stripComments(input.css),
+    whole,
     input.ignoreAtLayers ?? DEFAULT_IGNORED_LAYERS
   );
+  const unresolved = /* @__PURE__ */ new Set();
   const violations = [];
   const push = (rule, severity, message, found) => {
     violations.push({ rule, severity, message, found });
   };
-  const fontSizes = distinctValues(css, "font-size");
+  const fontSizes = distinctValues(css, "font-size", props, unresolved);
   if (fontSizes.length > budget.maxFontSizes) {
     push(
       "font-sizes",
@@ -837,10 +900,15 @@ function checkRestraint(input) {
       fontSizes
     );
   }
-  const weights = distinctValues(css, "font-weight").filter((w) => w !== "normal" && w !== "bold");
-  const namedWeights = distinctValues(css, "font-weight").filter(
-    (w) => w === "normal" || w === "bold"
+  const weights = distinctValues(css, "font-weight", props, unresolved).filter(
+    (w) => w !== "normal" && w !== "bold"
   );
+  const namedWeights = distinctValues(
+    css,
+    "font-weight",
+    props,
+    unresolved
+  ).filter((w) => w === "normal" || w === "bold");
   const allWeights = [.../* @__PURE__ */ new Set([...weights, ...namedWeights])];
   if (allWeights.length > budget.maxFontWeights) {
     push(
@@ -850,7 +918,7 @@ function checkRestraint(input) {
       allWeights
     );
   }
-  const families = distinctValues(css, "font-family").filter(
+  const families = distinctValues(css, "font-family", props, unresolved).filter(
     (f) => !/\bmonospace\b|\bmono\b/.test(f)
   );
   if (families.length > budget.maxFontFamilies) {
@@ -861,11 +929,23 @@ function checkRestraint(input) {
       families
     );
   }
-  const radii = distinctValues(css, "border-radius").filter((r) => r !== "0" && r !== "0px");
+  const radii = distinctValues(css, "border-radius", props, unresolved).filter(
+    (r) => r !== "0" && r !== "0px"
+  );
   if (radii.length > budget.maxRadii) {
-    push("radii", "error", `${radii.length} corner radii, budget ${budget.maxRadii}.`, radii);
+    push(
+      "radii",
+      "error",
+      `${radii.length} corner radii, budget ${budget.maxRadii}.`,
+      radii
+    );
   }
-  const shadows = distinctValues(css, "box-shadow").filter((s) => s !== "none");
+  const shadows = [
+    .../* @__PURE__ */ new Set([
+      ...distinctValues(css, "box-shadow", props, unresolved),
+      ...twShadowValues(css, props)
+    ])
+  ].filter((s) => s !== "none");
   if (shadows.length > budget.maxShadows) {
     push(
       "shadows",
@@ -874,6 +954,14 @@ function checkRestraint(input) {
       shadows
     );
   }
+  if (unresolved.size > 0) {
+    push(
+      "unresolved-token",
+      "warning",
+      `${unresolved.size} declaration(s) reference a custom property that is never defined and carry no fallback. Each one applies nothing.`,
+      [...unresolved].sort()
+    );
+  }
   const accentHexes = [
     ...css.matchAll(/--[a-z0-9-]*accent[a-z0-9-]*\s*:\s*(#[0-9a-fA-F]{3,8})/g)
   ].map((m) => m[1]);
@@ -925,7 +1013,9 @@ function checkRestraint(input) {
       [...new Set(easeIn)]
     );
   }
-  const overBudget = durationsMs(css).filter((d) => d.ms > budget.maxUiDurationMs);
+  const overBudget = durationsMs(css).filter(
+    (d) => d.ms > budget.maxUiDurationMs
+  );
   if (overBudget.length > 0) {
     push(
       "duration",
@@ -942,7 +1032,10 @@ function checkRestraint(input) {
       ["scale(0)"]
     );
   }
-  const reducedMotionBlocks = atRuleBodies(css, /@media[^{]*prefers-reduced-motion:\s*reduce[^{]*\{/gi);
+  const reducedMotionBlocks = atRuleBodies(
+    css,
+    /@media[^{]*prefers-reduced-motion:\s*reduce[^{]*\{/gi
+  );
   if (reducedMotionBlocks.length === 0) {
     if (/@keyframes|animation\s*:|transition\s*:/.test(css)) {
       push(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/craft",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "description": "The Doman Digital house craft standard as numbers: OKLCh colour ramps that snap to existing anchors, derived semantic tokens with measured WCAG and APCA contrast, one shared motion vocabulary for CSS and JS, and a base stylesheet. Zero dependencies.",
   "license": "Apache-2.0",