@designtools/adherence 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @designtools/adherence
 
+## 0.1.1
+
+### Patch Changes
+
+- 3da728f: The default exclude leaves out the `(design)` route group (`app/(design)/**`, `src/app/(design)/**`), where the skills put the docs and every other design page. A project laid out that way had its docs and copied blocks counted as product, and its headline share understated by nine points in the first end-to-end run.
+
+- Layout is not off-system: a bracketed width, measure, grid template, aspect ratio or z-index (`max-w-[40rem]`, `grid-cols-[auto_1fr]`) is art direction the system deliberately does not tokenise. An `auto` margin (`mt-auto`) is not a spacing override.
+
+- A status fill used as text (`text-destructive`, `text-success`, `text-warning`) is reported as off-system (`status-text`), pointing to its `-subdued-foreground` or, for a warning, neutral text with an icon.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -27,7 +27,7 @@ None beyond the manifest. It finds `components.json` from `designtools.json` at
 
 ## What it scans
 
-The product: `app/` and `src/`, by default. Never the system folder, the docs pages under `app/design/`, tests, `__tests__` folders, fixtures, examples, stories or `node_modules`. `--include <glob>` replaces the product globs, `--exclude <glob>` adds to what is left out; repeat either, or record them under `adherence` in `designtools.json`. A Next folder name in a glob means the folder: `--exclude "app/(app)/system/**"` leaves out that route group.
+The product: `app/` and `src/`, by default. Never the system folder, the docs and design pages under `app/design/` or the `app/(design)/` route group, tests, `__tests__` folders, fixtures, examples, stories or `node_modules`. `--include <glob>` replaces the product globs, `--exclude <glob>` adds to what is left out; repeat either, or record them under `adherence` in `designtools.json`. A Next folder name in a glob means the folder: `--exclude "app/(app)/system/**"` leaves out that route group.
 
 ## What it reports
 
@@ -40,11 +40,12 @@ From these comes the share: system component uses ÷ (system component uses + ra
 | Kind | Examples |
 | --- | --- |
 | palette | `bg-blue-500`, `hover:text-primary-500/80`, `bg-(--color-primary-500)`: any `--color-<family>-<step>` ramp step in `tokens.json`, and Tailwind's default palette, used directly |
-| arbitrary | `p-[13px]`, `md:bg-[#fff]`, `grid-cols-[1fr_2fr]`, `[mask-type:alpha]`. A token reference in brackets, `w-[var(--size-md)]`, is not one |
+| arbitrary | `p-[13px]`, `md:bg-[#fff]`, `h-[18px]`, `[mask-type:alpha]`. A token reference in brackets, `w-[var(--size-md)]`, is not one, and neither is layout the system does not tokenise: widths and measures (`w-`, `min-w-`, `max-w-`), grid templates (`grid-cols-`, `grid-rows-`, `columns-`), `aspect-` and `z-` |
+| status text | `text-destructive`, `text-success`, `md:text-warning`: a status fill used as text. The fill is measured against its own label, not the page, and fails there (red on a dark page, 2.4:1). Use `-subdued-foreground`, which the generator guarantees on every background of its mode, or neutral text with an icon for a warning |
 
 They are found wherever Tailwind classes live, `className`, `cn()`, `clsx()`, `tv()`, `cva()` and the like, by [eslint-plugin-better-tailwindcss](https://github.com/schoero/eslint-plugin-better-tailwindcss)'s `no-restricted-classes` rule, run through ESLint's Node API with an in-memory config generated from `tokens.json`. The project's own ESLint setup is neither read nor changed.
 
-**Overrides.** A `className` on a system component that changes its colour (`bg-`, `text-`, `border-`, `ring-` … with a colour), spacing (`p-`, `m-`, `gap-`, `space-`) or radius (`rounded-`). That usually means someone fought the component instead of choosing a variant, or that the component is missing one. Classes inside `cn()` count; layout and size (`w-full`, `flex-1`, `text-sm`) do not.
+**Overrides.** A `className` on a system component that changes its colour (`bg-`, `text-`, `border-`, `ring-` … with a colour), spacing (`p-`, `m-`, `gap-`, `space-`) or radius (`rounded-`). That usually means someone fought the component instead of choosing a variant, or that the component is missing one. Classes inside `cn()` count; layout and size (`w-full`, `flex-1`, `text-sm`, and an `auto` margin such as `mt-auto`) do not.
 
 All of it per file, per route and in total. A route is a Next app router page, `app/**/page.tsx`, with route groups dropped (`app/(shop)/checkout/page.tsx` is `/checkout`). A route counts its page, the files beside it, and files in folders under it that lead to no other page, such as a private `_components` folder. A layout shared by several routes counts per file only. Per component, it also counts which props are passed and which variant options are picked, and lists the components the product never uses.
 

package/dist/{chunk-AZ7JFJQ6.js → chunk-7FM4ZQLW.js}

@@ -8,6 +8,9 @@ var DEFAULT_INCLUDE = ["app/**/*.{tsx,jsx,ts,js}", "src/**/*.{tsx,jsx,ts,js}"];
 var DEFAULT_EXCLUDE = [
   "app/design/**",
   "src/app/design/**",
+  // the (design) route group, where the skills put the docs and every other design page
+  "app/(design)/**",
+  "src/app/(design)/**",
   "**/node_modules/**",
   "**/*.d.ts",
   "**/*.{test,spec}.*",
@@ -85,7 +88,7 @@ function formatMarkdown(report) {
   );
   lines.push(
     "",
-    `${s.offSystemValues} off-system ${plural(s.offSystemValues, "value")} (${s.offSystem.palette} palette, ${s.offSystem.arbitrary} arbitrary) \xB7 ${s.overrides} ${plural(s.overrides, "override")} \xB7 ${s.files} ${plural(s.files, "file")} scanned, ${s.filesWithFindings} with findings.`
+    `${s.offSystemValues} off-system ${plural(s.offSystemValues, "value")} (${s.offSystem.palette} palette, ${s.offSystem.arbitrary} arbitrary, ${s.offSystem["status-text"] ?? 0} status text) \xB7 ${s.overrides} ${plural(s.overrides, "override")} \xB7 ${s.files} ${plural(s.files, "file")} scanned, ${s.filesWithFindings} with findings.`
   );
   lines.push("", "Warnings only: nothing here blocks a merge.");
   if (!s.replaceable.length) {
@@ -144,7 +147,7 @@ function fileBlock(f) {
     ...f.offSystem.map((v) => [
       v.line,
       v.column,
-      `\`${v.class}\`: ${v.kind === "palette" ? "a palette step; use a semantic colour" : "an arbitrary value; use a token"}`
+      `\`${v.class}\`: ${OFF_SYSTEM_ADVICE[v.kind]}`
     ]),
     ...f.overrides.map((o) => [
       o.line,
@@ -170,6 +173,11 @@ function shareCell(c) {
 function plural(n, word) {
   return n === 1 ? word : `${word}s`;
 }
+var OFF_SYSTEM_ADVICE = {
+  palette: "a palette step; use a semantic colour",
+  arbitrary: "an arbitrary value; use a token",
+  "status-text": "a status fill as text, unchecked on the page; use its `-subdued-foreground`, or neutral text with an icon for a warning"
+};
 
 // src/discipline.ts
 import { existsSync as existsSync2 } from "fs";
@@ -237,6 +245,7 @@ var COLOUR_UTILITIES = [
 ];
 var esc = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
 var wrap = (utility) => `^((?:\\S*:)?!?-?${utility}!?)$`;
+var LAYOUT = `(?:z|w|min-w|max-w|grid-cols|grid-rows|columns|aspect)-\\[`;
 function restrictionsFor(families) {
   const fams = [...new Set(families)].sort((a, b) => b.length - a.length || cmp(a, b)).map(esc).join("|");
   const utils = [...COLOUR_UTILITIES].sort((a, b) => b.length - a.length).map(esc).join("|");
@@ -244,8 +253,14 @@ function restrictionsFor(families) {
   const palette = `(?:${utils})-(?:${step}|\\(--color-${step}\\)|\\[var\\(--color-${step}\\)\\])(?:\\/\\S+)?`;
   return [
     { pattern: wrap(palette), message: "[designtools:palette] $1" },
-    // a bracketed value that is not a token reference, or an arbitrary property
-    { pattern: wrap(`(?:[a-z][\\w-]*-\\[(?!var\\(--)[^\\]]+\\](?:\\/\\S+)?|\\[[a-z-]+:[^\\]]+\\])`), message: "[designtools:arbitrary] $1" }
+    // a bracketed value that is not a token reference, or an arbitrary property. Layout is left
+    // alone: container widths, grid templates, aspect ratios and z-index are not tokens
+    // (mxa-tokens, "Deliberately not tokenised"), so `max-w-[40rem]` is art direction, not drift.
+    // a status colour's fill used as text: it is measured against its own label, not the page, and
+    // fails there (red text on a dark page, 2.4:1 for every brand tested). Its subdued label is the
+    // text tone that reads on every background; warning text is neutral text with an icon.
+    { pattern: wrap(`text-(?:success|warning|destructive)(?:\\/\\S+)?`), message: "[designtools:status-text] $1" },
+    { pattern: wrap(`(?:(?!${LAYOUT})[a-z][\\w-]*-\\[(?!var\\(--)[^\\]]+\\](?:\\/\\S+)?|\\[[a-z-]+:[^\\]]+\\])`), message: "[designtools:arbitrary] $1" }
   ];
 }
 function familiesFromTokens(tokens) {
@@ -293,7 +308,7 @@ async function checkDiscipline(root, files, families) {
         failed.push({ file, reason: m.message });
         continue;
       }
-      const hit = /\[designtools:(palette|arbitrary)\] (\S+)/.exec(m.message);
+      const hit = /\[designtools:(palette|arbitrary|status-text)\] (\S+)/.exec(m.message);
       if (hit) found.push({ class: hit[2], kind: hit[1], line: m.line, column: m.column });
     }
     if (found.length) values.set(file, found.sort((a, b) => a.line - b.line || a.column - b.column || cmp(a.class, b.class)));
@@ -390,7 +405,7 @@ function findOverrides(uses, ctx) {
 function overrideKind(cls, ctx) {
   const utility = stripVariants(cls).replace(/^!/, "").replace(/!$/, "").replace(/^-/, "");
   if (RADIUS.test(utility)) return "radius";
-  if (SPACING.test(utility)) return "spacing";
+  if (SPACING.test(utility) && !/-auto$/.test(utility)) return "spacing";
   for (const prefix of [...COLOUR_UTILITIES].sort((a, b) => b.length - a.length)) {
     if (!utility.startsWith(`${prefix}-`)) continue;
     const value = utility.slice(prefix.length + 1).replace(/\/[^/]+$/, "");
@@ -889,7 +904,8 @@ async function buildReport(config) {
       filesWithFindings: fileEntries.filter((f) => f.raw.length || f.offSystem.length || f.overrides.length).length,
       offSystem: {
         palette: all.filter((v) => v.kind === "palette").length,
-        arbitrary: all.filter((v) => v.kind === "arbitrary").length
+        arbitrary: all.filter((v) => v.kind === "arbitrary").length,
+        "status-text": all.filter((v) => v.kind === "status-text").length
       },
       overrideKinds: {
         colour: overrideClasses.filter((c) => c.kind === "colour").length,

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   formatMarkdown,
   loadConfig,
   serialise
-} from "./chunk-AZ7JFJQ6.js";
+} from "./chunk-7FM4ZQLW.js";
 
 // src/cli.ts
 import { mkdirSync, writeFileSync } from "fs";
@@ -27,7 +27,7 @@ Usage
 Options
   --manifest <file>    The components.json to read (default: from designtools.json)
   --include <glob>     Product files to scan; repeat for each (default: app/** and src/**)
-  --exclude <glob>     Files to leave out, on top of the system folder, app/design,
+  --exclude <glob>     Files to leave out, on top of the system folder, app/design, app/(design),
                        tests, fixtures, examples and stories; repeat for each
   --format <md|json>   What to print (default: md)
   --json <file>        Write the JSON report to a file as well

package/dist/index.d.ts

@@ -162,8 +162,10 @@ interface RawElement {
 /**
  * `palette`: a primitive ramp step used directly, `bg-blue-500` or `text-primary-500`.
  * `arbitrary`: a value in brackets, `p-[13px]` or `bg-[#fff]`.
+ * `status-text`: a status fill used as text, `text-destructive`: use `text-destructive-subdued-foreground`,
+ * which reads on every background, or neutral text with an icon for a warning.
  */
-type OffSystemKind = "palette" | "arbitrary";
+type OffSystemKind = "palette" | "arbitrary" | "status-text";
 interface OffSystemValue {
     /** The class as written, variants included: `hover:bg-blue-500`. */
     class: string;

package/dist/index.js

@@ -28,7 +28,7 @@ import {
   routeOf,
   scanJsx,
   serialise
-} from "./chunk-AZ7JFJQ6.js";
+} from "./chunk-7FM4ZQLW.js";
 export {
   ADHERENCE_SCHEMA,
   COLOUR_UTILITIES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designtools/adherence",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A warn-only report on how closely a React product follows its design system: system components against the raw elements they replace, classes that bypass the tokens, and classNames that override a component. Reads the @designtools/manifest JSON; markdown for a pull request, JSON for docs.",
   "type": "module",
   "license": "MIT",