@josueavalosjim/taste-check 0.1.0 → 0.2.0

package/README.md

@@ -50,6 +50,8 @@ Each of these exits 1 rather than passing quietly:
 - a pair naming a token that does not exist
 - a file pattern matching no files
 - a theme whose scopes resolve no tokens
+- a single scope inside a theme that selects nothing, even when the theme has
+  tokens from its other scopes
 - a colour value the parser does not understand
 - an unknown key in the config, which is usually a typo doing nothing
 
@@ -85,16 +87,24 @@ in code, because the floor for a decorative hairline and the floor for body
 text are different decisions and both are yours.
 
 A theme is an ordered list of scopes and later scopes win, which is the cascade
-for equal specificity. Declarations inside an at-rule are ignored unless a
-scope opts in:
+for equal specificity.
+
+`@layer` is transparent. A `:root` inside `@layer tokens` resolves exactly as a
+top-level `:root` does, because a layer changes cascade priority rather than
+whether the declarations apply at all.
+
+Conditional at-rules are different. `@media`, `@supports`, `@container` and
+`@scope` only apply when their condition holds, so their declarations are
+ignored unless a scope opts in by name:
 
 ```json
 { "name": "dark-system", "scopes": [":root", { "selector": ":root", "atRule": "prefers-color-scheme: dark" }] }
 ```
 
-Without that rule a `@media (prefers-color-scheme: dark)` block containing
-`:root` would overwrite the light theme, and the light checks would silently
-measure against colours the light theme never paints.
+Without that, a `@media (prefers-color-scheme: dark)` block containing `:root`
+would overwrite the light theme, and the light checks would measure against
+colours the light theme never paints. You can also name a layer this way to
+narrow a scope to it, but you should never need to just to see your tokens.
 
 Two details make the numbers match a browser rather than approximate it.
 Translucent foregrounds are composited over their background before measuring,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josueavalosjim/taste-check",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Deterministic design-system checks: WCAG contrast over your own tokens, and a one-off value linter over your own approved list. No palette, no class list, no opinions shipped.",
   "keywords": [
     "accessibility",

package/schema/config.schema.json

@@ -45,7 +45,7 @@
                         "selector": { "type": "string", "minLength": 1 },
                         "atRule": {
                           "type": "string",
-                          "description": "Opt into declarations nested in a matching at-rule prelude, for example \"prefers-color-scheme: dark\". Without this, at-rule declarations are ignored."
+                          "description": "Opt into declarations nested in a matching at-rule prelude, for example \"prefers-color-scheme: dark\". Conditional at-rules (@media, @supports, @container, @scope) are ignored without this. Grouping at-rules like @layer are always transparent, so you only name one to narrow a scope to it."
                         }
                       }
                     }

package/src/contrast.mjs

@@ -18,7 +18,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { contrastRatio, isOpaque, parseColor } from './color.mjs';
-import { parseDeclarations, resolveScopes, resolveValue } from './css.mjs';
+import { parseDeclarations, resolveScopes, resolveValue, unmatchedScopes } from './css.mjs';
 import { expand, label } from './files.mjs';
 
 /** A token name, or a literal colour, resolved to rgba for one theme. */
@@ -62,6 +62,20 @@ export function runContrast(config, cwd) {
       continue;
     }
 
+    // A scope that selects nothing is not a smaller theme, it is a typo. The
+    // theme above still has tokens, so nothing else here would notice.
+    const dead = unmatchedScopes(decls, theme.scopes);
+    if (dead.length) {
+      for (const scope of dead) {
+        const shown = typeof scope === 'string' ? scope : JSON.stringify(scope);
+        problems.push(
+          `theme "${theme.name}": the scope ${shown} matched no declaration. ` +
+            `Every token it was meant to contribute is coming from another scope instead.`,
+        );
+      }
+      continue;
+    }
+
     for (const pair of pairs) {
       if (pair.themes && !pair.themes.includes(theme.name)) continue;
       const where = `${pair.fg} on ${pair.bg}`;

package/src/css.mjs

@@ -13,11 +13,31 @@
  * relies on `.a.b` beating `.b`, list the scopes in the order you want them
  * applied and the result is the one you asked for.
  *
- * Declarations inside an at-rule are ignored unless a scope opts into that
- * at-rule by name. Without that rule, a `@media (prefers-color-scheme: dark)`
- * block containing `:root` would silently overwrite the light theme, and the
- * light theme would be checked against colours it never paints.
+ * At-rules split into two kinds, and they are treated differently because
+ * they mean different things.
+ *
+ * A CONDITIONAL at-rule (`@media`, `@supports`, `@container`, `@scope`) only
+ * applies when its condition holds, so its declarations are ignored unless a
+ * scope opts into it by name. Without that, a
+ * `@media (prefers-color-scheme: dark)` block containing `:root` would
+ * overwrite the light theme, and light would be checked against colours it
+ * never paints.
+ *
+ * A GROUPING at-rule, `@layer` above all, always applies. It changes cascade
+ * priority, not whether the declarations exist. So it is transparent here: a
+ * `:root` inside `@layer tokens` resolves exactly as a top-level `:root`
+ * would. A scope can still name a layer to narrow to it, but nobody should
+ * have to write that just to see their own tokens.
+ *
+ * Layer order is not modelled. Within the scopes a theme lists, the last
+ * declaration still wins, same as everywhere else here.
+ */
+
+/**
+ * At-rules whose contents are conditional, and so must be opted into.
+ * Anything else wrapping a rule is grouping, and is looked straight through.
  */
+const CONDITIONAL = /^@(media|supports|container|scope|document)\b/;
 
 /** Blank out comments, keeping every offset and newline so lines stay true. */
 function blankComments(css) {
@@ -104,22 +124,42 @@ function selectorMatches(list, scope) {
  * The token table for one theme: a Map of `--name` to { value, selector }.
  * Scopes are applied in order, later winning.
  */
+/** The declarations one scope selects, in source order. */
+function declsForScope(decls, scope) {
+  const selector = typeof scope === 'string' ? scope : scope.selector;
+  const atRule = typeof scope === 'string' ? null : (scope.atRule ?? null);
+  return decls.filter((d) => {
+    if (!selectorMatches(d.selector, selector)) return false;
+    if (atRule === null) {
+      // Only a conditional wrapper hides a declaration by default. A grouping
+      // one like @layer does not.
+      return !d.atRules.some((a) => CONDITIONAL.test(a));
+    }
+    return d.atRules.some((a) => a.includes(atRule));
+  });
+}
+
 export function resolveScopes(decls, scopes) {
   const table = new Map();
   for (const scope of scopes) {
-    const selector = typeof scope === 'string' ? scope : scope.selector;
-    const atRule = typeof scope === 'string' ? null : (scope.atRule ?? null);
-    for (const d of decls) {
-      if (!selectorMatches(d.selector, selector)) continue;
-      if (atRule === null) {
-        if (d.atRules.length) continue;
-      } else if (!d.atRules.some((a) => a.includes(atRule))) continue;
-      table.set(d.prop, d);
-    }
+    for (const d of declsForScope(decls, scope)) table.set(d.prop, d);
   }
   return table;
 }
 
+/**
+ * The scopes in a theme that selected nothing at all.
+ *
+ * A theme can resolve plenty of tokens while one of its scopes is quietly
+ * dead: write `[data-theme="dark"]` when the stylesheet says
+ * `:root[data-theme="dark"]` and the base scope still fills the table, so the
+ * dark theme gets measured against the light values and reports a pass. The
+ * numbers look right, they are just the wrong theme's numbers.
+ */
+export function unmatchedScopes(decls, scopes) {
+  return scopes.filter((scope) => declsForScope(decls, scope).length === 0);
+}
+
 /**
  * Follow `var(--other)` indirection to a concrete value.
  *