@x12i/kit-cli 1.0.0 → 1.1.0

package/dist/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { readFileSync } from 'fs';
-import { writeFile, readFile, stat, access, readdir } from 'fs/promises';
-import path2 from 'path';
+import { writeFile, access, readFile, stat, readdir } from 'fs/promises';
+import path3 from 'path';
 import { parseArgs } from 'util';
 import { themeNames, densityNames } from '@x12i/tokens';
+import { createDesignMd } from '@x12i/tokens/design-md';
 
 var CONFIG_FILE = "kit.config.json";
 var CONFIG_VERSION = 1;
+var RULE_SETTINGS = ["off", "warn", "error"];
 function isThemeName(value) {
   return themeNames.includes(value);
 }
@@ -24,7 +26,7 @@ function createConfig(options = {}) {
 async function loadConfig(cwd) {
   let text;
   try {
-    text = await readFile(path2.join(cwd, CONFIG_FILE), "utf8");
+    text = await readFile(path3.join(cwd, CONFIG_FILE), "utf8");
   } catch (error) {
     if (error.code === "ENOENT") return null;
     throw error;
@@ -38,15 +40,344 @@ async function loadConfig(cwd) {
   const input = typeof raw === "object" && raw !== null ? raw : {};
   const defaults = createConfig();
   const ignore = input.doctor?.ignore;
+  const rawRules = input.doctor?.rules;
+  const rules = {};
+  if (typeof rawRules === "object" && rawRules !== null) {
+    for (const [id, setting] of Object.entries(rawRules)) {
+      if (typeof setting !== "string" || !RULE_SETTINGS.includes(setting)) {
+        throw new Error(`${CONFIG_FILE}: doctor.rules.${id} must be "off", "warn" or "error".`);
+      }
+      rules[id] = setting;
+    }
+  }
   return {
     version: CONFIG_VERSION,
     theme: typeof input.theme === "string" && isThemeName(input.theme) ? input.theme : defaults.theme,
     density: typeof input.density === "string" && isDensityName(input.density) ? input.density : defaults.density,
     doctor: {
-      ignore: Array.isArray(ignore) ? ignore.filter((item) => typeof item === "string") : []
+      ignore: Array.isArray(ignore) ? ignore.filter((item) => typeof item === "string") : [],
+      rules
+    }
+  };
+}
+var RULES = [
+  { id: "hardcoded-color", severity: "error", description: "A #hex color. Use a --kit-color-* token." },
+  {
+    id: "hardcoded-color-function",
+    severity: "warn",
+    description: "An rgb(), hsl(), oklch() or similar color with literal numbers. Use a --kit-color-* token."
+  },
+  { id: "hardcoded-font-size", severity: "warn", description: "A literal font size. Use a --kit-text-*-size token." },
+  { id: "hardcoded-font-family", severity: "warn", description: "A literal font stack. Use --kit-font-family-sans or -mono." },
+  { id: "hardcoded-spacing", severity: "warn", description: "A literal padding, margin or gap. Use a --kit-space-* token." },
+  { id: "hardcoded-radius", severity: "warn", description: "A literal border radius. Use a --kit-radius-* token." },
+  { id: "hardcoded-duration", severity: "warn", description: "A literal animation time. Use a --kit-duration-* token." },
+  { id: "hardcoded-easing", severity: "warn", description: "A literal cubic-bezier curve. Use a --kit-easing-* token." },
+  { id: "bounce-easing", severity: "warn", description: "An easing curve that overshoots. Application UI should be crisp, not bouncy." },
+  { id: "transition-all", severity: "warn", description: "`transition: all`. List the properties you animate." },
+  {
+    id: "layout-animation",
+    severity: "warn",
+    description: "A transition on width, height, margin, padding or position. Animate transform and opacity instead."
+  },
+  {
+    id: "missing-reduced-motion",
+    severity: "warn",
+    description: "The project animates but nothing handles prefers-reduced-motion."
+  },
+  {
+    id: "physical-property",
+    severity: "warn",
+    description: "A left or right property. Use the logical one (inline-start, inline-end) so right to left works."
+  },
+  { id: "outline-none", severity: "warn", description: "The focus outline is removed with no replacement style." },
+  { id: "important", severity: "warn", description: "`!important`. Kit styles have zero specificity, so plain selectors win." }
+];
+var RULE_IDS = new Set(RULES.map((rule) => rule.id));
+var CSS_FILES = /* @__PURE__ */ new Set([".css", ".scss", ".less"]);
+var SCRIPT_FILES = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
+var MARKUP_FILES = /* @__PURE__ */ new Set([".html", ".vue", ".svelte"]);
+var toKebab = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+function blankComments(text, lineComments) {
+  const blank = (match) => match.replace(/[^\n]/g, " ");
+  let result = text.replace(/\/\*[\s\S]*?\*\//g, blank);
+  if (lineComments) result = result.replace(/(?<![:"'`\w])\/\/[^\n]*/g, blank);
+  return result;
+}
+function styleRegions(text, extension) {
+  if (CSS_FILES.has(extension)) return [{ start: 0, end: text.length }];
+  const patterns = [];
+  if (SCRIPT_FILES.has(extension)) patterns.push(/`((?:[^`\\]|\\[\s\S])*)`/gd);
+  if (MARKUP_FILES.has(extension)) {
+    patterns.push(/<style\b[^>]*>([\s\S]*?)<\/style>/gid, /\sstyle\s*=\s*"([^"]*)"/gd, /\sstyle\s*=\s*'([^']*)'/gd);
+  }
+  const regions = [];
+  for (const pattern of patterns) {
+    for (const match of text.matchAll(pattern)) {
+      const span = match.indices?.[1];
+      if (span) regions.push({ start: span[0], end: span[1] });
+    }
+  }
+  return regions;
+}
+function cssDeclarations(text, region) {
+  const found = [];
+  const slice = text.slice(region.start, region.end);
+  const pattern = /(?<![\w$@#.:-])(-?[a-zA-Z][\w-]*)[ \t]*:[ \t\r\n]*([^;{}]*?)[ \t\r\n]*(?=;|}|$)/g;
+  for (const match of slice.matchAll(pattern)) {
+    const [, prop, raw] = match;
+    if (prop === void 0 || raw === void 0 || raw === "") continue;
+    const important = /!\s*important\s*$/i.test(raw);
+    const value = important ? raw.replace(/!\s*important\s*$/i, "").trim() : raw;
+    found.push({ prop: prop.toLowerCase(), value, important, index: region.start + (match.index ?? 0), source: "css" });
+  }
+  return found;
+}
+function jsDeclarations(text) {
+  const found = [];
+  const pattern = /(?<![\w$.])([a-z][A-Za-z]*)\s*:\s*(["'`])((?:(?!\2)[^\\\n]|\\.)*)\2/g;
+  for (const match of text.matchAll(pattern)) {
+    const [, prop, , value] = match;
+    if (prop === void 0 || value === void 0) continue;
+    found.push({ prop: toKebab(prop), value, important: false, index: match.index ?? 0, source: "js" });
+  }
+  return found;
+}
+var hasVar = (value) => /\bvar\(/.test(value);
+function closingParen(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i += 1) {
+    if (text[i] === "(") depth += 1;
+    else if (text[i] === ")") {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return text.length - 1;
+}
+function literalPart(value) {
+  let result = "";
+  let cursor = 0;
+  for (const match of value.matchAll(/\b(var|calc|clamp|min|max)\(/g)) {
+    const start = match.index ?? 0;
+    if (start < cursor) continue;
+    const end = closingParen(value, start + match[0].length - 1);
+    const group = value.slice(start, end + 1);
+    if (match[1] === "var" || hasVar(group)) {
+      result += `${value.slice(cursor, start)} `;
+      cursor = end + 1;
+    }
+  }
+  return result + value.slice(cursor);
+}
+function lengths(value) {
+  return [...value.matchAll(/(?<![\w.#-])(-?\d*\.?\d+)(px|rem|em)\b/g)].map(
+    (match) => Number.parseFloat(match[1] ?? "0") * (match[2] === "px" ? 1 : 16)
+  );
+}
+function times(value) {
+  return [...value.matchAll(/(?<![\w.#-])(\d*\.?\d+)(ms|s)\b/g)].map(
+    (match) => Number.parseFloat(match[1] ?? "0") * (match[2] === "s" ? 1e3 : 1)
+  );
+}
+var SPACING = /^(?:(?:padding|margin)(?:-(?:top|right|bottom|left|block|inline)(?:-(?:start|end))?)?|(?:row-|column-)?gap)$/;
+var RADIUS = /^border-(?:(?:top|bottom)-(?:left|right)-|(?:start|end)-(?:start|end)-)?radius$/;
+var MOTION = /^(?:transition(?:-duration|-delay|-timing-function|-property)?|animation(?:-duration|-delay|-timing-function|-name)?)$/;
+var TRANSITION = /^transition(?:-property)?$/;
+var LAYOUT_PROPERTY = /^(?:width|height|min-width|min-height|max-width|max-height|top|right|bottom|left|inset(?:-[a-z-]+)?|margin(?:-[a-z-]+)?|padding(?:-[a-z-]+)?|border-width|font-size|flex-basis|gap)$/;
+var splitTopLevel = (value) => value.split(/,(?![^(]*\))/).map((part) => part.trim());
+var PHYSICAL = /* @__PURE__ */ new Map([
+  ["margin-left", "margin-inline-start"],
+  ["margin-right", "margin-inline-end"],
+  ["padding-left", "padding-inline-start"],
+  ["padding-right", "padding-inline-end"],
+  ["border-left", "border-inline-start"],
+  ["border-right", "border-inline-end"],
+  ["border-left-width", "border-inline-start-width"],
+  ["border-right-width", "border-inline-end-width"],
+  ["border-left-color", "border-inline-start-color"],
+  ["border-right-color", "border-inline-end-color"],
+  ["border-left-style", "border-inline-start-style"],
+  ["border-right-style", "border-inline-end-style"],
+  ["border-top-left-radius", "border-start-start-radius"],
+  ["border-top-right-radius", "border-start-end-radius"],
+  ["border-bottom-left-radius", "border-end-start-radius"],
+  ["border-bottom-right-radius", "border-end-end-radius"]
+]);
+var PHYSICAL_SIDE_SELECTOR = /(?:^|[^a-z0-9])(?:left|right)(?![a-z0-9])/i;
+var PHYSICAL_STYLESHEET_ONLY = /* @__PURE__ */ new Map([
+  ["left", "inset-inline-start"],
+  ["right", "inset-inline-end"]
+]);
+var FOCUS_REPLACEMENT = /\b(?:box-shadow|border[\w-]*|background[\w-]*|text-decoration[\w-]*)\s*:/i;
+function enclosing(text, index) {
+  const blocks = [];
+  let depth = 0;
+  for (let i = index - 1; i >= 0; i -= 1) {
+    const char = text[i];
+    if (char === "}") depth += 1;
+    else if (char === "{") {
+      if (depth > 0) {
+        depth -= 1;
+        continue;
+      }
+      let start = i;
+      while (start > 0 && !";{}".includes(text[start - 1] ?? "")) start -= 1;
+      blocks.push({ header: text.slice(start, i).trim(), open: i });
+    }
+  }
+  return blocks;
+}
+function bodyOf(text, open) {
+  let depth = 0;
+  for (let i = open + 1; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === "{") depth += 1;
+    else if (char === "}") {
+      if (depth === 0) return text.slice(open + 1, i);
+      depth -= 1;
+    }
+  }
+  return text.slice(open + 1);
+}
+function snippet(declaration) {
+  const text = `${declaration.prop}: ${declaration.value}${declaration.important ? " !important" : ""}`;
+  return text.length > 60 ? `${text.slice(0, 57)}...` : text;
+}
+function checkDeclaration(declaration, text, report) {
+  const { prop, value } = declaration;
+  const literal = literalPart(value);
+  if (prop === "font-size" && lengths(literal).some((px) => px !== 0)) {
+    report("hardcoded-font-size", declaration, "Use a --kit-text-*-size token.");
+  }
+  if (prop === "font-family" && !hasVar(value) && !/^(?:inherit|initial|unset|revert(?:-layer)?)$/i.test(value)) {
+    const isFontFace = declaration.source === "css" && enclosing(text, declaration.index).some((block) => /^@font-face\b/i.test(block.header));
+    if (!isFontFace) report("hardcoded-font-family", declaration, "Use --kit-font-family-sans or --kit-font-family-mono.");
+  }
+  if (SPACING.test(prop) && lengths(literal).some((px) => Math.abs(px) > 1)) {
+    report("hardcoded-spacing", declaration, "Use a --kit-space-* token.");
+  }
+  if (RADIUS.test(prop) && lengths(literal).some((px) => px > 0)) {
+    report("hardcoded-radius", declaration, "Use a --kit-radius-* token.");
+  }
+  if (MOTION.test(prop)) {
+    if (times(literal).some((ms) => ms > 0)) {
+      report("hardcoded-duration", declaration, "Use a --kit-duration-* token.");
+    }
+    const curves = [...literal.matchAll(/cubic-bezier\(([^)]*)\)/gi)];
+    if (curves.length > 0) {
+      report("hardcoded-easing", declaration, "Use a --kit-easing-* token.");
+    }
+    const overshoots = curves.some((curve) => {
+      const numbers = (curve[1] ?? "").split(",").map((part) => Number.parseFloat(part));
+      return [numbers[1], numbers[3]].some((y) => y !== void 0 && !Number.isNaN(y) && (y < 0 || y > 1));
+    });
+    if (overshoots) {
+      report("bounce-easing", declaration, "This curve overshoots, so the motion bounces. Use a --kit-easing-* token.");
+    }
+  }
+  if (TRANSITION.test(prop)) {
+    const properties = prop === "transition-property" ? value.split(/[\s,]+/).filter(Boolean) : splitTopLevel(value).map((part) => part.split(/\s+/)[0] ?? "");
+    if (properties.some((name) => name.toLowerCase() === "all")) {
+      report("transition-all", declaration, "List the properties you animate. `all` also animates layout and anything added later.");
+    }
+    const layout = properties.find((name) => LAYOUT_PROPERTY.test(name.toLowerCase()));
+    if (layout !== void 0) {
+      report("layout-animation", declaration, `Animating ${layout} runs layout and paint on every frame. Animate transform and opacity.`);
+    }
+  }
+  const namesSide = declaration.source === "css" && PHYSICAL_SIDE_SELECTOR.test(enclosing(text, declaration.index)[0]?.header ?? "");
+  const bareInset = declaration.source === "css" && !value.includes("%") ? PHYSICAL_STYLESHEET_ONLY.get(prop) : void 0;
+  const logical = PHYSICAL.get(prop) ?? bareInset;
+  if (namesSide) ; else if (logical !== void 0) {
+    report("physical-property", declaration, `Use ${logical}, so the layout mirrors in right to left languages.`);
+  } else if (/^(?:text-align|float|clear)$/.test(prop) && /^(?:left|right)$/i.test(value)) {
+    const side = value.toLowerCase() === "left" ? "start" : "end";
+    const replacement = prop === "text-align" ? side : `inline-${side}`;
+    report("physical-property", declaration, `Use ${prop}: ${replacement}, so the layout mirrors in right to left languages.`);
+  }
+  if (declaration.source !== "css") return;
+  const removesOutline = prop === "outline" && /^(?:none|0|0px)$/i.test(value) || prop === "outline-style" && /^none$/i.test(value) || prop === "outline-width" && /^0(?:px)?$/i.test(value);
+  if (removesOutline) {
+    const [block] = enclosing(text, declaration.index);
+    const replaced = block !== void 0 && (FOCUS_REPLACEMENT.test(bodyOf(text, block.open)) || /:not\(\s*:focus-visible\s*\)/i.test(block.header));
+    if (!replaced) {
+      report(
+        "outline-none",
+        declaration,
+        "Removing the outline hides keyboard focus. Add a visible focus style, such as --kit-color-border-focus."
+      );
+    }
+  }
+  if (declaration.important) {
+    const allowed = enclosing(text, declaration.index).some((block) => /prefers-reduced-motion|@media\s+print/i.test(block.header));
+    if (!allowed) report("important", declaration, "Kit styles have zero specificity, so a plain selector wins. Remove !important.");
+  }
+}
+function lineStarts(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i += 1) if (text[i] === "\n") starts.push(i + 1);
+  return starts;
+}
+function positionOf(starts, index) {
+  let low = 0;
+  let high = starts.length - 1;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if ((starts[middle] ?? 0) <= index) low = middle;
+    else high = middle - 1;
+  }
+  return { line: low + 1, column: index - (starts[low] ?? 0) + 1 };
+}
+var FUNCTION_COLOR = /(?<![\w-])(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch)\(\s*[-+]?[\d.][^)]*\)/gi;
+var REDUCED_MOTION = /prefers-reduced-motion|useReducedMotion|reducedMotion/i;
+var NO_MOTION = /^(?:none|initial|unset)\b/i;
+function checkText(text, file, ignoreMarker) {
+  const extension = path3.extname(file).toLowerCase();
+  const stripped = blankComments(text, extension !== ".css");
+  const starts = lineStarts(text);
+  const rawLines = text.split(/\r?\n/);
+  const hits = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (rule, index, match, message) => {
+    const { line, column } = positionOf(starts, index);
+    if ((rawLines[line - 1] ?? "").includes(ignoreMarker)) return;
+    const key = `${rule}:${line}:${column}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    hits.push({ rule, line, column, match, message });
+  };
+  for (const match of stripped.matchAll(FUNCTION_COLOR)) {
+    push("hardcoded-color-function", match.index ?? 0, match[0], "Use a --kit-color-* token.");
+  }
+  const declarations = [
+    ...styleRegions(stripped, extension).flatMap((region) => cssDeclarations(stripped, region)),
+    ...SCRIPT_FILES.has(extension) ? jsDeclarations(stripped) : []
+  ];
+  let firstMotion = null;
+  const sawMotion = (index) => {
+    firstMotion = firstMotion === null ? index : Math.min(firstMotion, index);
+  };
+  for (const declaration of declarations) {
+    checkDeclaration(declaration, stripped, (rule, source, message) => push(rule, source.index, snippet(source), message));
+    const { prop, value } = declaration;
+    const animates = (/^animation(?:-name)?$/.test(prop) || TRANSITION.test(prop)) && !NO_MOTION.test(value) || /^(?:animation|transition)-duration$/.test(prop) && times(value).some((ms) => ms > 0);
+    if (animates) sawMotion(declaration.index);
+  }
+  if (CSS_FILES.has(extension)) {
+    for (const match of stripped.matchAll(/@keyframes\b/gi)) sawMotion(match.index ?? 0);
+  }
+  hits.sort((a, b) => a.line - b.line || a.column - b.column);
+  return {
+    hits,
+    motion: {
+      first: firstMotion === null ? null : positionOf(starts, firstMotion),
+      handlesReducedMotion: REDUCED_MOTION.test(stripped)
     }
   };
 }
+
+// src/doctor.ts
 var SCANNED_EXTENSIONS = /* @__PURE__ */ new Set([
   ".css",
   ".scss",
@@ -77,7 +408,7 @@ var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set([
 var MAX_FILE_BYTES = 1e6;
 var HEX_COLOR = /(?<![\w&#/-])(?<!\bhref=["'])#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![\w-])/g;
 var IGNORE_MARKER = "kit-ignore";
-var toPosix = (value) => value.split(path2.sep).join("/");
+var toPosix = (value) => value.split(path3.sep).join("/");
 function isIgnored(relativePath, ignore) {
   return ignore.some((entry) => {
     const prefix = entry.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
@@ -100,7 +431,7 @@ async function* walk(directory) {
   entries.sort((a, b) => a.name.localeCompare(b.name));
   for (const entry of entries) {
     if (entry.isSymbolicLink()) continue;
-    const full = path2.join(directory, entry.name);
+    const full = path3.join(directory, entry.name);
     if (entry.isDirectory()) {
       if (!SKIPPED_DIRECTORIES.has(entry.name)) yield* walk(full);
     } else if (entry.isFile()) {
@@ -109,15 +440,14 @@ async function* walk(directory) {
   }
 }
 function isScannable(file) {
-  const name = path2.basename(file);
+  const name = path3.basename(file);
   if (name.includes(".min.") || name.endsWith(".d.ts")) return false;
-  return SCANNED_EXTENSIONS.has(path2.extname(name));
+  return SCANNED_EXTENSIONS.has(path3.extname(name));
 }
-async function scanForHardcodedColors(cwd, targets = ["."], { ignore = [] } = {}) {
-  const findings = [];
+async function* sourceFiles(cwd, targets, ignore) {
   const seen = /* @__PURE__ */ new Set();
   for (const target of targets) {
-    const root = path2.resolve(cwd, target);
+    const root = path3.resolve(cwd, target);
     const info = await stat(root);
     const files = info.isDirectory() ? walk(root) : (async function* () {
       yield root;
@@ -125,15 +455,47 @@ async function scanForHardcodedColors(cwd, targets = ["."], { ignore = [] } = {}
     for await (const file of files) {
       if (seen.has(file)) continue;
       seen.add(file);
-      const relative = toPosix(path2.relative(cwd, file));
+      const relative = toPosix(path3.relative(cwd, file));
       if (isIgnored(relative, ignore) || !isScannable(file)) continue;
       const { size } = await stat(file);
       if (size > MAX_FILE_BYTES) continue;
-      const text = await readFile(file, "utf8");
-      for (const finding of findHexColors(text)) {
-        findings.push({ file: relative, ...finding });
-      }
+      yield { relative, text: await readFile(file, "utf8") };
+    }
+  }
+}
+function severityOf(rule, overrides) {
+  const setting = overrides[rule] ?? RULES.find((item) => item.id === rule)?.severity ?? "warn";
+  return setting === "off" ? null : setting;
+}
+async function scanProject(cwd, targets = ["."], { ignore = [], rules = {} } = {}) {
+  const findings = [];
+  const animated = [];
+  let handlesReducedMotion = false;
+  const add2 = (finding) => {
+    const severity = severityOf(finding.rule, rules);
+    if (severity !== null) findings.push({ ...finding, severity });
+  };
+  for await (const { relative, text } of sourceFiles(cwd, targets, ignore)) {
+    const found = [];
+    for (const hex of findHexColors(text)) {
+      found.push({ file: relative, ...hex, rule: "hardcoded-color", message: "Use a --kit-color-* token." });
     }
+    const { hits, motion } = checkText(text, relative, IGNORE_MARKER);
+    for (const hit of hits) found.push({ file: relative, ...hit });
+    found.sort((a, b) => a.line - b.line || a.column - b.column);
+    for (const finding of found) add2(finding);
+    if (motion.first) animated.push({ file: relative, ...motion.first });
+    if (motion.handlesReducedMotion) handlesReducedMotion = true;
+  }
+  const [first] = animated;
+  if (first && !handlesReducedMotion) {
+    const files = animated.length === 1 ? "1 file animates" : `${animated.length} files animate`;
+    add2({
+      ...first,
+      match: "prefers-reduced-motion",
+      rule: "missing-reduced-motion",
+      message: `${files}, and nothing scanned handles prefers-reduced-motion. Add a @media (prefers-reduced-motion: reduce) rule that drops movement.`
+    });
   }
   return findings;
 }
@@ -151,9 +513,15 @@ Commands
         Add a component to your project. Planned.
   theme [name]
         List the themes and densities. Generating a theme is planned.
-  doctor [paths...] [--json]
-        Find hard-coded hex colors that should be --kit- tokens.
-        Exits with 1 when it finds any.
+  doctor [paths...] [--json] [--strict] [--list-rules]
+        Check code against the kit's conventions: colors, sizes and motion that
+        should be --kit- tokens, left and right properties that will not mirror,
+        removed focus outlines, and more. Hex colors are errors and the rest are
+        warnings. Exits with 1 on an error, or on any finding with --strict.
+        Set a rule to off, warn or error in ${CONFIG_FILE} under doctor.rules.
+  design [--theme <name>] [--out <file>] [--force]
+        Write the kit's DESIGN.md, a description of the design system that coding
+        agents read. Defaults to DESIGN.md. Use --out - to print it.
 
 Options
   -h, --help       Show this help.
@@ -182,7 +550,7 @@ async function init(values, io) {
 `);
     return 2;
   }
-  const target = path2.join(io.cwd, CONFIG_FILE);
+  const target = path3.join(io.cwd, CONFIG_FILE);
   if (!values.force && await exists(target)) {
     io.err(`${CONFIG_FILE} already exists. Use --force to replace it.
 `);
@@ -222,12 +590,43 @@ function theme(name, io) {
   );
   return 1;
 }
-async function doctor(paths, json, io) {
-  const config = await loadConfig(io.cwd);
+async function readConfig(io) {
+  try {
+    return await loadConfig(io.cwd);
+  } catch (error) {
+    io.err(`${error.message}
+`);
+    return void 0;
+  }
+}
+var plural = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+function listRules(io) {
+  const width = Math.max(...RULES.map((rule) => rule.id.length));
+  for (const rule of RULES) {
+    io.out(`${rule.id.padEnd(width)}  ${rule.severity.padEnd(5)}  ${rule.description}
+`);
+  }
+  return 0;
+}
+async function doctor(paths, options, io) {
+  if (options.listRules) return listRules(io);
+  const config = await readConfig(io);
+  if (config === void 0) return 2;
+  const unknown = Object.keys(config?.doctor.rules ?? {}).filter((id) => !RULE_IDS.has(id));
+  if (unknown.length > 0) {
+    io.err(
+      `${CONFIG_FILE}: unknown doctor rule ${unknown.map((id) => `"${id}"`).join(", ")}. Run "kit doctor --list-rules" for the rule names.
+`
+    );
+    return 2;
+  }
   const targets = paths.length > 0 ? paths : ["."];
   let findings;
   try {
-    findings = await scanForHardcodedColors(io.cwd, targets, { ignore: config?.doctor.ignore });
+    findings = await scanProject(io.cwd, targets, {
+      ignore: config?.doctor.ignore,
+      rules: config?.doctor.rules
+    });
   } catch (error) {
     if (error.code === "ENOENT") {
       io.err(`Path not found: ${error.path ?? targets.join(", ")}
@@ -236,26 +635,65 @@ async function doctor(paths, json, io) {
     }
     throw error;
   }
-  if (json) {
+  const errors = findings.filter((finding) => finding.severity === "error").length;
+  const failed = errors > 0 || options.strict && findings.length > 0;
+  if (options.json) {
     io.out(`${JSON.stringify(findings, null, 2)}
 `);
-    return findings.length > 0 ? 1 : 0;
+    return failed ? 1 : 0;
   }
   if (findings.length === 0) {
-    io.out("No hard-coded colors found.\n");
+    io.out("No problems found.\n");
     return 0;
   }
   for (const finding of findings) {
-    io.out(`${finding.file}:${finding.line}:${finding.column}  ${finding.match}  Use a --kit- color token.
-`);
+    io.out(
+      `${finding.file}:${finding.line}:${finding.column}  ${finding.match}  ${finding.message}  (${finding.severity} ${finding.rule})
+`
+    );
   }
   const files = new Set(findings.map((finding) => finding.file)).size;
   io.out(
     `
-${findings.length} hard-coded ${findings.length === 1 ? "color" : "colors"} found in ${files} ${files === 1 ? "file" : "files"}.
+${plural(errors, "error", "errors")} and ${plural(findings.length - errors, "warning", "warnings")} in ${plural(files, "file", "files")}.
 `
   );
-  return 1;
+  return failed ? 1 : 0;
+}
+async function design(values, io) {
+  if (values.theme !== void 0 && !isThemeName(values.theme)) {
+    io.err(`Unknown theme "${values.theme}". Choose one of: ${themeNames.join(", ")}.
+`);
+    return 2;
+  }
+  const config = await readConfig(io);
+  if (config === void 0) return 2;
+  const theme2 = values.theme !== void 0 && isThemeName(values.theme) ? values.theme : config?.theme ?? "light";
+  const markdown = createDesignMd({ theme: theme2 });
+  const out = values.out ?? "DESIGN.md";
+  if (out === "-") {
+    io.out(markdown);
+    return 0;
+  }
+  const target = path3.resolve(io.cwd, out);
+  if (!values.force && await exists(target)) {
+    io.err(`${out} already exists. Use --force to replace it, or --out to write somewhere else.
+`);
+    return 1;
+  }
+  try {
+    await writeFile(target, markdown, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      io.err(`Cannot write ${out}: the folder does not exist.
+`);
+      return 2;
+    }
+    throw error;
+  }
+  io.out(`Created ${out} (${theme2} theme)
+`);
+  return 0;
 }
 async function run(argv, io) {
   let parsed;
@@ -268,6 +706,9 @@ async function run(argv, io) {
         version: { type: "boolean", short: "v" },
         force: { type: "boolean" },
         json: { type: "boolean" },
+        strict: { type: "boolean" },
+        "list-rules": { type: "boolean" },
+        out: { type: "string" },
         theme: { type: "string" },
         density: { type: "string" }
       }
@@ -297,7 +738,13 @@ ${HELP}`);
     case "theme":
       return theme(rest[0], io);
     case "doctor":
-      return doctor(rest, values.json ?? false, io);
+      return doctor(
+        rest,
+        { json: values.json ?? false, strict: values.strict ?? false, listRules: values["list-rules"] ?? false },
+        io
+      );
+    case "design":
+      return design(values, io);
     default:
       io.err(`Unknown command "${command}".