@designtools/manifest 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @designtools/manifest
 
+## 0.2.0
+
+### Minor Changes
+
+- 3da728f: From the first end-to-end run:
+  
+  - A comment after a declaration on the same line (`--size-xl: 3rem; /* 48px controls */`) now describes that declaration. It used to become the next token's description, so every description in a scale written that way landed one token late.
+  - A token re-declared in a later stylesheet records it in `overriddenIn`.
+  - Each component records `import`, the specifier an app imports it by through the tsconfig path alias that reaches the system folder (`@ds/button/button`), so the import line in the docs and the agent markdown resolves.
+  - Brand assets keep the order `assets.json` gives them, so the default logo leads.
+  - `prose-check` reads the places listed in `manifest.prose` (a folder contributes its markdown and `*content.ts(x)` files), treats a TypeScript template literal as prose rather than code, and honours `prose-check-ignore`, `prose-check-ignore-next-line` and `prose-check-ignore-start` … `-end` for pages that name wrong forms on purpose.
+  - A prop's JSDoc no longer leaks into other components. react-docgen-typescript caches a prop by the file of its first declaration, so Alert's documented `children` (first declared by React) gave its description, type and declarations to every component with `children`. Each component now reads its props afresh.
+  - `agents` writes to `AGENTS.md` when `CLAUDE.md` imports it (`@AGENTS.md`, as `next dev` writes it), so every agent reads the section; `manifest.agents` in `designtools.json` names another file. The section no longer forbids every ramp step: ramps are for charts, illustration and a decorative colour, never text, surfaces or actions.
+  - `manifest.usage` names the file `@designtools/tokens --usage` writes; every colour that fails somewhere as text or a shape becomes a rule in rules.json (`usage-<colour>`), marked with the new status `measured`: a fact from the tokens, not a client decision. Status fills are left to the default status-text rule.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -28,6 +28,8 @@ Record the system folder and the token stylesheets once, in `designtools.json` a
 
 The manifest is written inside the system folder (`src/ds/manifest/`), so it moves with the system if the system moves to its own package. Flags override the file: `--system`, `--tokens` (repeat it), `--tsconfig`, `--out`, `--root`.
 
+List every stylesheet that declares a token, in the order the app imports them: the generated colour tiers, the authored scale, and wherever the font families live (`base.css` on the suite's default stack). A token re-declared in a later file takes that file's value and records it in `overriddenIn`. `prose` adds places for `prose-check` to read (see [For agents](#for-agents)).
+
 ## What it reads
 
 **Components.** Every exported component in a `.tsx` file under the system folder. Fixtures, tests, stories and `.d.ts` files are skipped. Props come from [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript), run once over a single TypeScript program, so types resolve across files and through the project's path aliases. A component's own props are kept, and so are those of a Base UI primitive it wraps. Props inherited from the DOM, ARIA or React are left out, and recorded as what it `inherits` (`"span"`, `"@base-ui/react/select:Select.Root"`).
@@ -60,7 +62,7 @@ The manifest is written inside the system folder (`src/ds/manifest/`), so it mov
 
 Any other tag is a warning, with a suggestion when it is close to one of these.
 
-**Tokens.** Every custom property in the listed stylesheets: the colour tiers `@designtools/tokens` generates and the scale you author beside them. Each token records its value in every context it is declared in: `default` (`@theme`, `:root`), `light`, `dark`, `p3:` for the wide-gamut layer, and any other selector as written. A `prefers-color-scheme` fallback never overrides an explicit dark block. The comment above a declaration, or above the run of declarations it starts, becomes its description. Tiers follow Tailwind's namespaces (`--text-*`, `--radius-*`, …); semantic colours like `--primary` are recognised by their values.
+**Tokens.** Every custom property in the listed stylesheets: the colour tiers `@designtools/tokens` generates and the scale you author beside them. Each token records its value in every context it is declared in: `default` (`@theme`, `:root`), `light`, `dark`, `p3:` for the wide-gamut layer, and any other selector as written. A `prefers-color-scheme` fallback never overrides an explicit dark block. The comment above a declaration, or above the run of declarations it starts, becomes its description; a comment after a declaration on the same line describes that declaration alone. Tiers follow Tailwind's namespaces (`--text-*`, `--radius-*`, …); semantic colours like `--primary` are recognised by their values.
 
 **Rules.** One `<id>.rule.json` per rule in `<system>/rules`, brand and interface in the same format: title, statement, rationale, threshold, what it applies to, exceptions, the tokens it rests on, whether it is `confirmed` or still an `assumption`, and the check that proves it. [`schemas/rule.schema.json`](schemas/rule.schema.json) validates them in an editor.
 
@@ -68,7 +70,9 @@ Any other tag is a warning, with a suggestion when it is close to one of these.
 
 **Taxonomy.** The canonical names come from everything else: components, variant axes and their meaningful options, semantic colours, patterns and rules. `<system>/taxonomy.json` adds the wrong forms (`{ "name": "destructive", "wrong": ["error", "danger"] }`) and product terms the code never names (`{ "name": "sign in", "kind": "product", "wrong": ["log in"] }`).
 
-**Brand assets.** Every image in `<system>/brand`, with an `assets.json` there saying how to use each: kind, usage, minimum size, clear space, the surfaces it may sit on, alt text. SVG and PNG sizes are read from the files. A file the index does not mention is listed anyway, with a warning.
+**Measured usage rules.** With `manifest.usage` naming the file `@designtools/tokens --usage` writes, every colour that fails somewhere, as text (4.5:1 at AA) or as a shape (3:1), gets a rule in rules.json: `usage-primary`, "`--primary` reads as text on … On … it is neither, down to 1.06:1 …". They are marked `measured`, a fact from the tokens that changes when they do, and sit beside the authored rules on the rules page. A brand colour's limits are then a brand decision, written as a confirmed brand rule.
+
+**Brand assets.** Every image in `<system>/brand`, with an `assets.json` there saying how to use each: kind, usage, minimum size, clear space, the surfaces it may sit on, alt text. SVG and PNG sizes are read from the files. They keep the order `assets.json` gives them, so the default logo can lead. A file the index does not mention is listed anyway, after them, with a warning.
 
 ## The files
 
@@ -84,6 +88,7 @@ Any other tag is a warning, with a suggestion when it is close to one of these.
       "name": "Badge",
       "export": "Badge",
       "source": "src/ds/badge/badge.tsx",
+      "import": "@ds/badge/badge",
       "description": "A pill: soft tinted background, strong text of the same hue.",
       "inherits": ["span"],
       "props": {
@@ -149,9 +154,9 @@ Components are matched by their path inside the system folder, so moving the who
 
 ## For agents
 
-`agents` writes a section of `CLAUDE.md` (or `AGENTS.md`) between markers, and leaves the rest of the file alone. It points agents at each manifest file and the docs, and lists nothing: a list of components or tokens written into prose is a second copy that drifts.
+`agents` writes a section of `CLAUDE.md` or `AGENTS.md` between markers, and leaves the rest of the file alone. It picks `AGENTS.md` when `CLAUDE.md` imports it (`@AGENTS.md`, as `next dev` writes it), so every agent reads the section and Claude reaches it through the import; otherwise `CLAUDE.md` if there is one. `manifest.agents` in `designtools.json`, or `--file`, names another. It points agents at each manifest file and the docs, and lists nothing: a list of components or tokens written into prose is a second copy that drifts.
 
-`prose-check` reads `CLAUDE.md`, `AGENTS.md`, `.claude/`, `docs/` and the system folder's markdown, and warns about a component tag the system does not have (`<Modal>`), a wrong form from the taxonomy (`Dropdown` for `Select`, "log in" for "sign in"), and a paragraph or list that restates several components or tokens. The generated section is skipped.
+`prose-check` reads `CLAUDE.md`, `AGENTS.md`, `.claude/`, `docs/` and the system folder's markdown, plus anything listed in `manifest.prose` (a folder there contributes its markdown and its `*content.ts(x)` files, which is where a docs site keeps its editorial copy), and warns about a component tag the system does not have (`<Modal>`), a wrong form from the taxonomy (`Dropdown` for `Select`, "log in" for "sign in"), and a paragraph or list that restates several components or tokens. The generated section is skipped. In TypeScript a backtick opens a template literal, so its words are read as prose, not code. A page that names wrong forms on purpose, such as a voice page saying "never the customer", marks them: `prose-check-ignore` on a line skips it, `prose-check-ignore-next-line` skips the next, and `prose-check-ignore-start` … `prose-check-ignore-end` skip a block, in any comment syntax.
 
 `provenance` prints the project's version and the commit it was built at (`VERCEL_GIT_COMMIT_SHA` or `GITHUB_SHA` when set, else git), for the header of a generated docs page. A generated page never carries a review date.
 

package/dist/{chunk-EFGVJ5ZQ.js → chunk-PQGMDEUF.js}

@@ -316,6 +316,15 @@ import { basename, dirname, join, relative, resolve, sep } from "path";
 import ts4 from "typescript";
 import { createRequire } from "module";
 var docgen = createRequire(import.meta.url)("react-docgen-typescript");
+var parserProto = docgen.Parser.prototype;
+if (!parserProto.__designtoolsUncached) {
+  const getPropsInfo = parserProto.getPropsInfo;
+  parserProto.getPropsInfo = function(...args) {
+    this.propertiesOfPropsCache.clear();
+    return getPropsInfo.apply(this, args);
+  };
+  parserProto.__designtoolsUncached = true;
+}
 var SKIP_FILE = /\.(examples|pattern|test|spec|stories)\.tsx$|\.d\.ts$/;
 var SKIP_DIR = /* @__PURE__ */ new Set(["node_modules", ".next", "dist", "build", "coverage"]);
 var BASE_UI = /[\\/]@base-ui[\\/]react[\\/]/;
@@ -394,8 +403,37 @@ function readComponents(options, warn) {
     attachExamples(root, file, entries, warn);
     out.push(...entries.map((e) => e.entry));
   }
+  for (const entry of out) {
+    const specifier = importSpecifier(root, entry.source, compiler);
+    if (specifier) entry.import = specifier;
+  }
   return out.sort((a, b) => compare(a.name, b.name) || compare(a.source, b.source));
 }
+function importSpecifier(root, source, compiler) {
+  const paths = compiler.paths;
+  if (!paths) return void 0;
+  const base = compiler.pathsBasePath ?? compiler.baseUrl ?? root;
+  const file = resolve(root, source).replace(/\.(tsx?|jsx?|mts|cts)$/, "").replace(/\/index$/, "");
+  let best;
+  for (const [pattern, targets] of Object.entries(paths)) {
+    for (const target of targets) {
+      const star = target.indexOf("*");
+      const absolute = resolve(base, star === -1 ? target : target.slice(0, star));
+      if (star === -1) {
+        if (absolute.replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "") === file && !pattern.includes("*")) {
+          return pattern;
+        }
+        continue;
+      }
+      const prefix = target.slice(0, star).endsWith("/") ? `${absolute}/` : absolute;
+      const suffix = target.slice(star + 1).replace(/\.(tsx?|jsx?)$/, "");
+      if (!file.startsWith(prefix) || !file.endsWith(suffix)) continue;
+      const middle = file.slice(prefix.length, file.length - suffix.length);
+      if (!best || prefix.length > best.prefix) best = { specifier: pattern.replace("*", middle), prefix: prefix.length };
+    }
+  }
+  return best?.specifier;
+}
 function compare(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
 }
@@ -585,7 +623,7 @@ function parameterTypeText(sf, decl) {
 }
 function configResolver(sf, configs, imported) {
   const local = new Map(configs.map((c) => [c.name, c]));
-  const resolve7 = (name) => local.get(name) ?? imported(sf, name);
+  const resolve8 = (name) => local.get(name) ?? imported(sf, name);
   const aliases = /* @__PURE__ */ new Map();
   for (const stmt of sf.statements) {
     if (!ts4.isVariableStatement(stmt)) continue;
@@ -595,7 +633,7 @@ function configResolver(sf, configs, imported) {
       }
     }
   }
-  const find = (name) => resolve7(name) ?? (aliases.has(name) ? resolve7(aliases.get(name)) : void 0);
+  const find = (name) => resolve8(name) ?? (aliases.has(name) ? resolve8(aliases.get(name)) : void 0);
   return (name) => {
     const config = find(name);
     return config && withBase(config, find, /* @__PURE__ */ new Set([config.name]));
@@ -628,16 +666,16 @@ function withBase(config, find, seen) {
   if (parts.length) entry.parts = parts;
   return { ...config, entry, description: config.description ?? base.description };
 }
-function linkConfig(decl, paramTypes, resolve7) {
+function linkConfig(decl, paramTypes, resolve8) {
   for (const m of paramTypes.matchAll(/VariantProps\s*<\s*typeof\s+(\w+)\s*>/g)) {
-    const c = resolve7(m[1]);
+    const c = resolve8(m[1]);
     if (c) return c;
   }
   let found;
   const visit = (n) => {
     if (found) return;
-    if (ts4.isCallExpression(n) && ts4.isIdentifier(n.expression)) found = resolve7(n.expression.text);
-    else if (ts4.isPropertyAccessExpression(n) && ts4.isIdentifier(n.expression)) found = resolve7(n.expression.text);
+    if (ts4.isCallExpression(n) && ts4.isIdentifier(n.expression)) found = resolve8(n.expression.text);
+    else if (ts4.isPropertyAccessExpression(n) && ts4.isIdentifier(n.expression)) found = resolve8(n.expression.text);
     if (!found) ts4.forEachChild(n, visit);
   };
   visit(decl);
@@ -1122,7 +1160,9 @@ function readAssets(root, brandDir, warn) {
   for (const file of notes.keys()) {
     if (!found.has(file)) warn({ file: rel2(root, indexPath), message: `assets.json lists ${file}, which is not in the brand folder` });
   }
-  return out.sort((a, b) => compare(a.file, b.file));
+  const order = [...notes.keys()];
+  const rank2 = (file) => order.includes(file) ? order.indexOf(file) : order.length;
+  return out.sort((a, b) => rank2(a.file) - rank2(b.file) || compare(a.file, b.file));
 }
 function kindFromFolder(folder) {
   const f = folder.toLowerCase();
@@ -1166,7 +1206,14 @@ function readTokens(root, sources, warn) {
     const walk3 = (container, chain) => {
       let comment;
       let fresh = false;
+      let previous;
       for (const node of container.nodes ?? []) {
+        if (node.type === "comment" && previous && !/\n/.test(node.raws.before ?? "")) {
+          previous.description = cleanComment(node.text);
+          previous = void 0;
+          continue;
+        }
+        previous = void 0;
         if (node.type === "comment") {
           comment = cleanComment(node.text);
           fresh = true;
@@ -1188,11 +1235,15 @@ function readTokens(root, sources, warn) {
           const existing = entry.values[key];
           const explicitAlready = existing !== void 0 && !mediaKeys.has(key);
           if (!(media && explicitAlready)) {
+            if (existing !== void 0 && existing !== value && source !== entry.source && !entry.overriddenIn?.includes(source)) {
+              entry.overriddenIn = [...entry.overriddenIn ?? [], source];
+            }
             entry.values[key] = value;
             if (media) mediaKeys.add(key);
             else mediaKeys.delete(key);
           }
           if (comment && !entry.description) entry.description = comment;
+          previous = entry;
           continue;
         }
         fresh = false;
@@ -1284,14 +1335,72 @@ function tierOf(name, values) {
 var MANIFEST_SCHEMA = "designtools.manifest/1";
 
 // src/build.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { dirname as dirname3, join as join3 } from "path";
 import { fileURLToPath } from "url";
+
+// src/usage.ts
+import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
+import { resolve as resolve4 } from "path";
+var STATUS = /^(success|warning|destructive)$|-subdued-foreground$/;
+function usageRules(root, file, warn) {
+  const path = resolve4(root, file);
+  if (!existsSync3(path)) {
+    warn({ file, message: "usage file not found: run @designtools/tokens with --usage" });
+    return [];
+  }
+  let usage;
+  try {
+    usage = JSON.parse(readFileSync5(path, "utf8"));
+  } catch (e) {
+    warn({ file, message: `usage file is not valid JSON: ${e.message}` });
+    return [];
+  }
+  if (usage.schema !== "designtools.usage/1") {
+    warn({ file, message: `usage file has schema ${usage.schema}; this manifest reads designtools.usage/1` });
+    return [];
+  }
+  const colours = [.../* @__PURE__ */ new Set([...Object.keys(usage.light), ...Object.keys(usage.dark)])].filter((c) => !STATUS.test(c)).sort(compare);
+  const rules = [];
+  for (const colour of colours) {
+    const by = { text: [], shape: [], none: [] };
+    let worst;
+    for (const mode of ["light", "dark"]) {
+      for (const [ground, { ratio, use }] of Object.entries(usage[mode][colour] ?? {})) {
+        by[use].push(`${ground} (${mode})`);
+        if (use !== "text" && (!worst || ratio < worst.ratio)) worst = { ratio, where: `${ground} in ${mode} mode` };
+      }
+    }
+    if (!by.shape.length && !by.none.length) continue;
+    const list2 = (xs) => xs.length > 1 ? `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}` : xs[0];
+    const parts = [
+      by.text.length ? `\`--${colour}\` reads as text on ${list2(by.text)}.` : `\`--${colour}\` is never text on these backgrounds.`,
+      by.shape.length ? `On ${list2(by.shape)} it is a shape only (an icon, a border, a meter), not text.` : "",
+      by.none.length ? `On ${list2(by.none)} it is neither${worst ? `, down to ${worst.ratio}:1 on ${worst.where}` : ""}: use it there only as a fill with its own label.` : ""
+    ].filter(Boolean);
+    rules.push({
+      id: `usage-${colour}`,
+      kind: "interface",
+      title: `Where ${colour} can go`,
+      statement: parts.join(" "),
+      rationale: "Measured from the generated tokens; it changes when they do. No palette makes every colour work on every background, so a brand colour's limits are a brand decision: confirm them as a brand rule.",
+      threshold: `${usage.floors.text}:1 as text, ${usage.floors.shape}:1 as a shape (WCAG 2.2 1.4.3 and 1.4.11)`,
+      appliesTo: [colour],
+      tokens: [`--${colour}`],
+      status: "measured",
+      check: { kind: "test", ref: "mxa-tests", description: "axe measures contrast on every rendered page; this says where to look first." },
+      source: file
+    });
+  }
+  return rules;
+}
+
+// src/build.ts
 var GENERATOR_NAME = "@designtools/manifest";
 var VERSION = (() => {
   try {
     const here = dirname3(fileURLToPath(import.meta.url));
-    return JSON.parse(readFileSync5(join3(here, "../package.json"), "utf8")).version;
+    return JSON.parse(readFileSync6(join3(here, "../package.json"), "utf8")).version;
   } catch {
     return "0.0.0";
   }
@@ -1312,7 +1421,10 @@ function buildManifest(config) {
     components: readComponents({ root: config.root, system: config.system, tsconfig: config.tsconfig, out }, warn)
   };
   const tokens = { ...head, sources: config.tokens, tokens: readTokens(config.root, config.tokens, warn) };
-  const rules = { ...head, rules: readRules(config.root, config.rules ?? `${system}/rules`, warn) };
+  const rules = {
+    ...head,
+    rules: [...readRules(config.root, config.rules ?? `${system}/rules`, warn), ...config.usage ? usageRules(config.root, config.usage, warn) : []]
+  };
   const patterns = {
     ...head,
     patterns: readPatterns(config.root, system, components.components, compilerOptions(config.root, config.tsconfig), warn, out)
@@ -1363,14 +1475,17 @@ function sortKeys(value) {
 
 // src/agents.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync6 } from "fs";
-import { resolve as resolve4 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "fs";
+import { resolve as resolve5 } from "path";
 var AGENTS_START = "<!-- designtools:start \xB7 generated by designtools-manifest agents; edit outside these markers -->";
 var AGENTS_END = "<!-- designtools:end -->";
-function agentsFile(root, given) {
+function agentsFile(root, given, configured) {
   if (given) return given;
-  if (existsSync3(resolve4(root, "CLAUDE.md"))) return "CLAUDE.md";
-  return "AGENTS.md";
+  if (configured) return configured;
+  const claude = readIfExists(resolve5(root, "CLAUDE.md"));
+  if (claude === void 0) return "AGENTS.md";
+  if (/^\s*@AGENTS\.md\s*$/m.test(claude)) return "AGENTS.md";
+  return "CLAUDE.md";
 }
 function agentsSection(config) {
   const out = outDir(config);
@@ -1394,7 +1509,7 @@ function agentsSection(config) {
     "",
     "- Start from a component's canonical example, and follow its do and don't examples.",
     "- Change how a component looks with its variants, not a `className`.",
-    "- Use semantic tokens. Never a ramp step, a hex value or an arbitrary value.",
+    "- Use semantic tokens for colour in UI. Never a hex value or an arbitrary value. A ramp step (`--color-<name>-500`) is for charts, illustration and a decorative colour that has no semantic slot, never for text, surfaces or actions.",
     "- Use the taxonomy's names, never its wrong forms, in code and in copy.",
     "- Carry status when you quote: say when a component is emerging or deprecated, or a rule is still an assumption.",
     AGENTS_END
@@ -1412,12 +1527,12 @@ function withAgentsSection(existing, section) {
   return existing.replace(/\s*$/, "\n\n") + section;
 }
 function readIfExists(path) {
-  return existsSync3(path) ? readFileSync6(path, "utf8") : void 0;
+  return existsSync4(path) ? readFileSync7(path, "utf8") : void 0;
 }
 function provenance(root) {
   let version = "unversioned";
   try {
-    const pkg = JSON.parse(readFileSync6(resolve4(root, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync7(resolve5(root, "package.json"), "utf8"));
     version = `${pkg.name ?? "project"}@${pkg.version ?? "0.0.0"}`;
   } catch {
   }
@@ -1435,18 +1550,18 @@ function provenance(root) {
 }
 
 // src/config.ts
-import { existsSync as existsSync4, readFileSync as readFileSync7 } from "fs";
-import { resolve as resolve5 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync8 } from "fs";
+import { resolve as resolve6 } from "path";
 var CONFIG_FILE = "designtools.json";
-var PATH_FIELDS = ["tsconfig", "out", "rules", "taxonomy", "brand", "docs"];
+var PATH_FIELDS = ["tsconfig", "out", "rules", "taxonomy", "brand", "docs", "agents", "usage"];
 function loadConfig(flags) {
-  const root = resolve5(flags.root ?? ".");
-  const path = resolve5(root, CONFIG_FILE);
+  const root = resolve6(flags.root ?? ".");
+  const path = resolve6(root, CONFIG_FILE);
   let file = {};
-  if (existsSync4(path)) {
+  if (existsSync5(path)) {
     let parsed;
     try {
-      parsed = JSON.parse(readFileSync7(path, "utf8"));
+      parsed = JSON.parse(readFileSync8(path, "utf8"));
     } catch (e) {
       throw new Error(`${CONFIG_FILE} is not valid JSON: ${e.message}`);
     }
@@ -1463,6 +1578,12 @@ function loadConfig(flags) {
     throw new Error(`manifest.tokens in ${CONFIG_FILE} must be a list of stylesheet paths`);
   }
   const config = { root, system, tokens };
+  if (file.prose !== void 0) {
+    if (!Array.isArray(file.prose) || file.prose.some((p) => typeof p !== "string")) {
+      throw new Error(`manifest.prose in ${CONFIG_FILE} must be a list of files or folders`);
+    }
+    config.prose = file.prose;
+  }
   for (const field of PATH_FIELDS) {
     const value = flags[field] ?? file[field];
     if (value !== void 0) config[field] = value;
@@ -1667,25 +1788,33 @@ No changes to components or tokens.
 }
 
 // src/prose.ts
-import { existsSync as existsSync5, readdirSync as readdirSync3, readFileSync as readFileSync8, statSync as statSync3 } from "fs";
-import { join as join4, relative as relative3, resolve as resolve6, sep as sep3 } from "path";
+import { existsSync as existsSync6, readdirSync as readdirSync3, readFileSync as readFileSync9, statSync as statSync3 } from "fs";
+import { join as join4, relative as relative3, resolve as resolve7, sep as sep3 } from "path";
 var NOT_SYSTEM = /* @__PURE__ */ new Set(["Fragment", "Suspense", "StrictMode", "Profiler", "Link", "Image", "Script", "Head", "Html", "Main", "NextScript", "Form"]);
 var LIST_COMPONENTS = 4;
 var LIST_TOKENS = 6;
-function defaultProseFiles(root, system) {
+function defaultProseFiles(root, system, extra = []) {
   const out = [];
-  for (const f of ["CLAUDE.md", "AGENTS.md"]) if (existsSync5(resolve6(root, f))) out.push(f);
-  for (const dir of [".claude", "docs", system]) out.push(...walk2(root, resolve6(root, dir)));
+  for (const f of ["CLAUDE.md", "AGENTS.md"]) if (existsSync6(resolve7(root, f))) out.push(f);
+  for (const dir of [".claude", "docs", system]) out.push(...walk2(root, resolve7(root, dir)));
+  for (const p of extra) {
+    const path = resolve7(root, p);
+    if (!existsSync6(path)) continue;
+    if (statSync3(path).isDirectory()) out.push(...walk2(root, path, true));
+    else out.push(relative3(root, path).split(sep3).join("/"));
+  }
   return [...new Set(out)];
 }
-function walk2(root, dir) {
-  if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
+function walk2(root, dir, content = false) {
+  if (!existsSync6(dir) || !statSync3(dir).isDirectory()) return [];
   const out = [];
   for (const name of readdirSync3(dir).sort()) {
     const path = join4(dir, name);
     if (statSync3(path).isDirectory()) {
-      if (name !== "node_modules" && name !== "manifest") out.push(...walk2(root, path));
-    } else if (/\.mdx?$/.test(name)) out.push(relative3(root, path).split(sep3).join("/"));
+      if (name !== "node_modules" && name !== "manifest" && name !== ".next") out.push(...walk2(root, path, content));
+    } else if (/\.mdx?$/.test(name) || content && /content\.tsx?$/.test(name)) {
+      out.push(relative3(root, path).split(sep3).join("/"));
+    }
   }
   return out;
 }
@@ -1708,10 +1837,13 @@ function checkProse(root, files, inputs) {
   }
   const findings = [];
   for (const file of files) {
-    const path = resolve6(root, file);
-    if (!existsSync5(path)) continue;
-    const lines = stripGenerated(readFileSync8(path, "utf8")).split(/\r?\n/);
+    const path = resolve7(root, file);
+    if (!existsSync6(path)) continue;
+    const lines = stripGenerated(readFileSync9(path, "utf8")).split(/\r?\n/);
+    const script = /\.[cm]?[jt]sx?$/.test(file);
     let inFence = false;
+    let ignoring = false;
+    let skipNext = false;
     let block;
     const closeBlock = () => {
       if (block && block.components.size >= LIST_COMPONENTS) {
@@ -1724,7 +1856,16 @@ function checkProse(root, files, inputs) {
     };
     lines.forEach((line, i) => {
       const n = i + 1;
-      if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+      if (/prose-check-ignore-start/.test(line)) ignoring = true;
+      if (/prose-check-ignore-end/.test(line)) {
+        ignoring = false;
+        return;
+      }
+      const skip = ignoring || skipNext || /prose-check-ignore(?!-)/.test(line);
+      skipNext = /prose-check-ignore-next-line/.test(line);
+      if (skip) return;
+      if (script && /^\s*(import|export\s+(type|interface))\b/.test(line)) return;
+      if (!script && /^\s*(```|~~~)/.test(line)) inFence = !inFence;
       if (!line.trim()) {
         closeBlock();
         return;
@@ -1740,7 +1881,7 @@ function checkProse(root, files, inputs) {
           message: wrong ? `<${name}>: the system calls this ${wrong.name}` : `<${name}> looks like a component, but the system has none by that name`
         });
       }
-      const code = inFence ? [line] : [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+      const code = inFence ? [line] : script ? [] : [...line.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
       for (const span of code) {
         for (const word of span.match(/[A-Za-z][\w-]*/g) ?? []) {
           if (components.has(word)) block.components.add(word);
@@ -1752,7 +1893,7 @@ function checkProse(root, files, inputs) {
         }
       }
       if (!inFence) {
-        for (const word of line.replace(/`[^`]*`/g, " ").match(/\b[A-Z][A-Za-z0-9]+\b/g) ?? []) if (components.has(word)) block.components.add(word);
+        for (const word of (script ? line : line.replace(/`[^`]*`/g, " ")).match(/\b[A-Z][A-Za-z0-9]+\b/g) ?? []) if (components.has(word)) block.components.add(word);
         for (const { re, form, term } of wrongProse) if (re.test(line)) findings.push({ file, line: n, message: `"${form}": the product says "${term.name}"` });
       }
     });

package/dist/cli.js

@@ -14,7 +14,7 @@ import {
   provenance,
   readIfExists,
   withAgentsSection
-} from "./chunk-EFGVJ5ZQ.js";
+} from "./chunk-PQGMDEUF.js";
 
 // src/cli.ts
 import { execFileSync } from "child_process";
@@ -43,7 +43,9 @@ Options
   --tsconfig <file>    tsconfig.json for resolving imports (found from the root when absent)
   --out <dir>          Where the manifest goes (default: <system>/manifest)
   --root <dir>         Project root (default: the current directory)
-  --file <file>        agents: the file to write (default: CLAUDE.md if it exists, else AGENTS.md)
+  --file <file>        agents: the file to write (default: manifest.agents in designtools.json;
+                       else AGENTS.md when CLAUDE.md imports it with @AGENTS.md; else
+                       CLAUDE.md if it exists; else AGENTS.md)
   --check              agents: compare instead of writing
   --json               diff, prose-check, provenance: print JSON
   --fail-on <class>    diff: exit 1 if any change of this class is found (breaking, additive, visual, docs)
@@ -186,7 +188,7 @@ switch (command) {
     process.exit(ok ? 0 : 1);
   }
   case "agents": {
-    const file = agentsFile(config.root, values.file);
+    const file = agentsFile(config.root, values.file, config.agents);
     const path = resolve(config.root, file);
     const existing = readIfExists(path);
     const next = withAgentsSection(existing, agentsSection(config));
@@ -203,7 +205,7 @@ switch (command) {
     process.exit(0);
   }
   case "prose-check": {
-    const files = rest.length ? rest : defaultProseFiles(config.root, config.system);
+    const files = rest.length ? rest : defaultProseFiles(config.root, config.system, config.prose);
     const findings = checkProse(config.root, files, {
       components: built.components.components,
       patterns: built.patterns.patterns,

package/dist/index.d.ts

@@ -34,6 +34,12 @@ interface ComponentEntry {
     export: string;
     /** The file that exports it. */
     source: string;
+    /**
+     * The module specifier an app imports it by, through the tsconfig path alias
+     * that reaches the system folder (`@ds/button/button`). Absent when no alias does,
+     * in which case `source` is the only honest answer.
+     */
+    import?: string;
     /** The component's JSDoc, or its variant config's when the component has none. */
     description?: string;
     /** `@category`. Blocks group components without one under "Components". */
@@ -156,6 +162,8 @@ interface TokenEntry {
     description?: string;
     /** The stylesheet that first declares it. */
     source: string;
+    /** Later stylesheets whose declaration replaced a value, in the order read: an override layer. */
+    overriddenIn?: string[];
 }
 /** rules.json: brand and interface rules in one format. */
 interface RulesManifest extends ManifestFile {
@@ -178,8 +186,11 @@ interface RuleEntry {
     exceptions?: string[];
     /** Tokens it rests on, e.g. `--size-2xl`. */
     tokens?: string[];
-    /** Confirmed with the client, or an assumption still to confirm. */
-    status: "confirmed" | "assumption";
+    /**
+     * Confirmed with the client, an assumption still to confirm, or measured: generated from the
+     * tokens (where a colour can be text), a fact that changes when they do, not a decision.
+     */
+    status: "confirmed" | "assumption" | "measured";
     /** How it is proved: a test, a lint rule, an audit, or a person. */
     check?: {
         kind: "test" | "lint" | "audit" | "manual";
@@ -298,6 +309,19 @@ interface ManifestConfig {
     brand?: string;
     /** Where the docs are served, for the agent pointer file, e.g. `/design/system`. */
     docs?: string;
+    /**
+     * The usage file `@designtools/tokens --usage` writes: every colour on every background with a
+     * verdict. Its failures become measured usage rules in rules.json.
+     */
+    usage?: string;
+    /** The agent file the pointer section goes in, when the default choice is wrong for the project. */
+    agents?: string;
+    /**
+     * More places for prose-check to read, beside the agent files, `.claude/`, `docs/`
+     * and the system folder: files of any kind, or folders, whose markdown and
+     * `*content.ts(x)` files (the docs site's editorial copy) are read.
+     */
+    prose?: string[];
 }
 interface BuiltManifest {
     components: ComponentsManifest;
@@ -422,7 +446,8 @@ declare function classifyExamples(source: string, exports: ExampleRef[]): Exampl
  *
  * The comment above a declaration, or above the run of declarations it starts,
  * is that token's description: the scale's comments already say why each value
- * is what it is.
+ * is what it is. A comment on the same line after a declaration describes that
+ * declaration (`--size-xl: 3rem; /* 48px controls *\/`), and does not start a run.
  */
 
 declare function readTokens(root: string, sources: string[], warn: (w: Warning) => void): TokenEntry[];
@@ -458,7 +483,8 @@ declare function buildTaxonomy(root: string, curatedPath: string, inputs: {
 /**
  * Brand assets from one folder. `assets.json` in it says how to use each file;
  * files it does not mention are listed too, with a warning, so nothing in the
- * folder goes unseen.
+ * folder goes unseen. The order is the author's (the wordmark first, because it
+ * is the default), then anything unlisted by file name.
  */
 declare function readAssets(root: string, brandDir: string, warn: (w: Warning) => void): AssetEntry[];
 
@@ -471,8 +497,13 @@ declare function readAssets(root: string, brandDir: string, warn: (w: Warning) =
 
 declare const AGENTS_START = "<!-- designtools:start \u00B7 generated by designtools-manifest agents; edit outside these markers -->";
 declare const AGENTS_END = "<!-- designtools:end -->";
-/** CLAUDE.md if the project has one, else AGENTS.md. */
-declare function agentsFile(root: string, given?: string): string;
+/**
+ * The file the pointer goes in: the flag, then `manifest.agents` in designtools.json,
+ * then AGENTS.md when CLAUDE.md imports it (`@AGENTS.md`, as `next dev` writes it), so
+ * every agent reads the section and Claude still reaches it through the import; else
+ * CLAUDE.md if the project has one, else AGENTS.md.
+ */
+declare function agentsFile(root: string, given?: string, configured?: string): string;
 declare function agentsSection(config: ManifestConfig & {
     docs?: string;
 }): string;
@@ -500,6 +531,11 @@ declare function provenance(root: string): Provenance;
  *   a wrong form from the taxonomy (`Modal` for `Dialog`, "log in" for "sign in")
  *   a restated list: a paragraph or list naming several components or tokens,
  *   which is a second copy of the manifest that will drift
+ *
+ * A page that names wrong forms on purpose (a voice page: "never the customer")
+ * says so: `prose-check-ignore` on a line skips it, `prose-check-ignore-next-line`
+ * skips the one after, and `prose-check-ignore-start` … `prose-check-ignore-end`
+ * skip everything between, in whatever comment syntax the file uses.
  */
 
 interface ProseFinding {
@@ -513,7 +549,7 @@ interface ProseInputs {
     tokens: TokenEntry[];
     terms: TermEntry[];
 }
-declare function defaultProseFiles(root: string, system: string): string[];
+declare function defaultProseFiles(root: string, system: string, extra?: string[]): string[];
 declare function checkProse(root: string, files: string[], inputs: ProseInputs): ProseFinding[];
 
 /**

package/dist/index.js

@@ -32,7 +32,7 @@ import {
   serialise,
   tierOf,
   withAgentsSection
-} from "./chunk-EFGVJ5ZQ.js";
+} from "./chunk-PQGMDEUF.js";
 export {
   AGENTS_END,
   AGENTS_START,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designtools/manifest",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reads a React design system (components, variants, data-slots, examples, tokens, rules, patterns, taxonomy and brand assets) into committed JSON that docs, checks and agents read from. Deterministic CLI: build, check, diff, agents, prose-check.",
   "type": "module",
   "license": "MIT",