@actioneer/ads-lint 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @actioneer/ads-lint
+
+A design linter for the **Actioneer Design System (ADS 1.0)**. It flags
+deviations from ADS principles on changed files, so any repo that consumes ADS
+stays on-system without a human catching every stray hex or icon import in review.
+
+It runs in two tiers: the **TypeScript compiler API** when `typescript` is
+resolvable (exact import analysis), degrading to a **regex parser** when it
+isn't — so it works in a fresh repo before `npm i`.
+
+## What it checks
+
+| Rule | Severity | Principle |
+|---|---|---|
+| `external-ui-import` — importing radix/mui/assistant-ui/etc. directly | error | P7 ADS-first |
+| `deep-import` — reaching past the barrel (`@actioneer/ads/button`) | error | P7 |
+| `barrel-default-import` / `-namespace-import` / `-aliased-import` | error | P7 |
+| `icon-package-import` — importing `@hugeicons`/`lucide` outside the registry | error | P4 icons |
+| `hardcoded-hex` — a raw `#rrggbb` in code | error | tokens-only |
+| `arbitrary-color` — `bg-[#fff]` / `text-[rgb(...)]` | error | tokens-only |
+| `arbitrary-dimension` — `w-[13px]` / `gap-[1.5rem]` | warn | tokens-only |
+| Motion: `unbounded-transition`, `sluggish-easing`, `zero-scale-entrance`, `undersized-zoom-entrance`, `hardcoded-duration`, `layout-property-transition`, `layout-keyframe-disclosure` | error | P3 motion |
+
+Errors fail the run (exit 1); warnings don't unless `--strict`.
+
+## Usage
+
+```bash
+ads-lint [files...]        # lint specific files (what lint-staged passes)
+ads-lint --staged          # files staged for commit (pre-commit hook)
+ads-lint --diff origin/main  # files changed vs a ref (CI on a PR)
+ads-lint --all             # everything under the configured root
+ads-lint --strict          # fail on warnings too
+```
+
+## Config — `ads-lint.config.mjs` at the repo root
+
+Deep-merged over the defaults. A **consumer** repo needs almost nothing — just
+point at the published package:
+
+```js
+export default {
+  imports: { libraryPackage: "@actioneer/ads" }, // libraryRoot stays null
+};
+```
+
+The ADS library repo itself runs in **library-dev mode** (see this repo's
+`ads-lint.config.mjs`): `libraryRoot: "src/components"` exempts the library's own
+internals, and `libraryPackage: "@/components"` matches the local alias.
+
+## Wiring into a consumer repo
+
+**Pre-commit (lint-staged)** — lint only what's staged:
+
+```jsonc
+// package.json
+"lint-staged": {
+  "src/**/*.{ts,tsx,css}": "ads-lint"
+}
+```
+
+**CI (GitHub Actions)** — lint only the PR diff, so legacy code doesn't block.
+`--diff` diffs from the merge-base, so the base branch must be present — set
+`fetch-depth: 0` (the default shallow clone omits it):
+
+```yaml
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }
+- run: npx ads-lint --diff origin/${{ github.base_ref }}
+```
+
+## Programmatic API
+
+```js
+import { loadConfig, resolveFiles, lintFiles } from "@actioneer/ads-lint";
+const cfg = await loadConfig();
+const { findings } = lintFiles(resolveFiles({ files: myFiles }, cfg, cwd), cfg, cwd);
+```

package/bin/ads-lint.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// ads-lint — flag deviations from the Actioneer Design System on changed files.
+//
+// Usage:
+//   ads-lint [files...]        Lint the given files.
+//   ads-lint --staged          Lint files staged for commit (pre-commit hook).
+//   ads-lint --diff <ref>      Lint files changed vs <ref> (CI on a PR: origin/main).
+//   ads-lint --all             Lint everything under the configured root.
+//   ads-lint --strict          Exit non-zero on warnings too (default: errors only).
+//   ads-lint --quiet           Print only the summary line.
+//
+// Config: ads-lint.config.mjs at the repo root (deep-merged over defaults).
+
+import process from "node:process";
+import { loadConfig } from "../src/config.mjs";
+import { resolveFiles, lintFiles, formatFindings } from "../src/runner.mjs";
+
+function parseArgs(argv) {
+  const opts = { files: [], staged: false, diff: null, all: false, strict: false, quiet: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--staged") opts.staged = true;
+    else if (a === "--all") opts.all = true;
+    else if (a === "--strict") opts.strict = true;
+    else if (a === "--quiet") opts.quiet = true;
+    else if (a === "--diff") opts.diff = argv[++i];
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else if (a.startsWith("-")) {
+      console.error(`ads-lint: unknown flag ${a}`);
+      process.exit(2);
+    } else opts.files.push(a);
+  }
+  return opts;
+}
+
+const HELP = `ads-lint — Actioneer Design System linter
+
+  ads-lint [files...]     Lint the given files
+  ads-lint --staged       Lint files staged for commit
+  ads-lint --diff <ref>   Lint files changed vs <ref> (e.g. origin/main)
+  ads-lint --all          Lint everything under the configured root
+  ads-lint --strict       Fail on warnings too (default: errors only)
+  ads-lint --quiet        Print only the summary line`;
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    console.log(HELP);
+    return 0;
+  }
+
+  const cwd = process.cwd();
+  const cfg = await loadConfig(cwd);
+  const files = resolveFiles(opts, cfg, cwd);
+  const { findings, fileCount } = lintFiles(files, cfg, cwd);
+
+  const errors = findings.filter((f) => f.severity === "error");
+  const warns = findings.filter((f) => f.severity === "warn");
+
+  if (findings.length && !opts.quiet) {
+    console.error(formatFindings(findings));
+    console.error("");
+  }
+
+  const summary = `ads-lint: ${fileCount} file(s) · ${errors.length} error(s) · ${warns.length} warning(s)`;
+  if (errors.length || (opts.strict && warns.length)) {
+    console.error(summary);
+    return 1;
+  }
+  console.log(summary);
+  return 0;
+}
+
+main().then((code) => process.exit(code));

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@actioneer/ads-lint",
+  "version": "0.1.0",
+  "description": "Design linter for the Actioneer Design System (ADS 1.0). Flags deviations from ADS principles on changed files.",
+  "type": "module",
+  "bin": {
+    "ads-lint": "bin/ads-lint.mjs"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./config": "./src/config.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "typescript": { "optional": true }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/config.mjs

@@ -0,0 +1,152 @@
+// ads-lint — configuration surface.
+//
+// Every rule is governed from here, never hard-coded in a rule module. A
+// consuming repo drops an `ads-lint.config.mjs` at its root that default-exports
+// a partial config; unspecified keys fall back to DEFAULT_CONFIG below.
+//
+// Two modes, one config shape:
+//   • consumer mode   — libraryRoot: null, libraryPackage: "@actioneer/ads".
+//     Every file is a consumer; all import rules apply everywhere.
+//   • library-dev mode — libraryRoot: "src/components", libraryPackage:
+//     "@/components". Files inside the library author the components, so the
+//     barrel / deep-import / banned-UI rules skip them (a sibling may deep-import
+//     a sibling); the icon-registry allowlist still applies.
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** @typedef {"error" | "warn"} Severity */
+
+export const DEFAULT_CONFIG = {
+  // File extensions the runner will read.
+  extensions: [".ts", ".tsx", ".css"],
+
+  // Root walked by `--all` when no explicit files are passed.
+  root: "src",
+
+  // Globs skipped entirely (checked against repo-relative POSIX paths).
+  ignore: [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/*.gen.ts",
+    "**/*.d.ts",
+  ],
+
+  imports: {
+    // The barrel consumers must import components from.
+    libraryPackage: "@actioneer/ads",
+    // Path prefix that IS the library. null in consumer repos (nothing is
+    // exempt); a folder in library-dev mode (its files may cross-import).
+    libraryRoot: null,
+    // Direct imports of these bypass ADS — consumers must go through the barrel.
+    bannedUiPackages: [
+      "^@assistant-ui/react(?:/|$)",
+      "^radix-ui$",
+      "^@radix-ui/",
+      "^@headlessui/",
+      "^@mui/",
+      "^antd(?:/|$)",
+      "^@chakra-ui/",
+      "^@heroui/",
+      "^@nextui-org/",
+      "^@mantine/",
+      "^@ark-ui/",
+      "^react-aria-components$",
+      "^sonner$",
+      "^cmdk$",
+      "^vaul$",
+      "^react-select$",
+      "^react-toastify$",
+    ],
+    // Icon packages may only be imported from the icon registry (principle 4).
+    bannedIconPackages: ["^@hugeicons/", "^lucide-react$", "^@fortawesome/"],
+    // File(s) allowed to import icon packages directly (the ADS registry).
+    iconRegistryAllowlist: ["src/lib/icons.tsx"],
+    // Sanctioned package subpaths a consumer MAY import directly (the design
+    // system's own CSS entries) — exempt from the deep-import rule. Any asset
+    // specifier (.css/.svg/fonts/etc.) is also exempt regardless of this list.
+    sanctionedSubpaths: ["styles.css", "theme.css", "fonts.css", "package.json"],
+  },
+
+  motion: {
+    enabled: true,
+    // Globs where motion rules don't apply (consumer exemption seam, mirroring
+    // literals.allow) — e.g. a consumer's vendored/animation-heavy directory.
+    allow: [],
+  },
+
+  literals: {
+    // Bare hex colors in .ts/.tsx (e.g. "#0a0a0b") — should be a token.
+    hex: true,
+    // Tailwind arbitrary color value in a class (e.g. "bg-[#fff]").
+    arbitraryColor: true,
+    // Tailwind arbitrary dimension (e.g. "w-[13px]") — noisier; warn-level.
+    arbitraryDimension: true,
+    // Files where raw literals are sanctioned (shaders, colorful palettes,
+    // token-swatch documentation, style token definitions).
+    allow: ["src/styles/**"],
+  },
+};
+
+/**
+ * Convert a simple glob to an anchored RegExp with minimatch-ish semantics:
+ *   `** /`  → zero or more leading segments    (?:.*\/)?
+ *   `/ **`  → the dir itself or anything below (?:/.*)?
+ *   `**`    → any run of chars, crossing /      .*
+ *   `*`     → any run within one segment         [^/]*
+ * Placeholders keep the ** forms from being mangled by the single-* pass.
+ */
+export function globToRegExp(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\?]/g, "\\$&");
+  const body = escaped
+    .replace(/\*\*\//g, "%%L%%")
+    .replace(/\/\*\*/g, "%%T%%")
+    .replace(/\*\*/g, "%%A%%")
+    .replace(/\*/g, "[^/]*")
+    .replace(/%%L%%/g, "(?:.*/)?")
+    .replace(/%%T%%/g, "(?:/.*)?")
+    .replace(/%%A%%/g, ".*");
+  return new RegExp(`^${body}$`);
+}
+
+/** True if repo-relative POSIX `file` matches any glob in `patterns`. */
+export function matchesAny(file, patterns) {
+  return patterns.some((p) => globToRegExp(p).test(file));
+}
+
+function mergeConfig(base, override) {
+  if (!override) return base;
+  const out = { ...base };
+  for (const key of Object.keys(override)) {
+    const v = override[key];
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      out[key] = mergeConfig(base[key] ?? {}, v);
+    } else {
+      out[key] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * Load `ads-lint.config.{mjs,js}` from `cwd` (if present) and deep-merge it over
+ * the defaults. Returns the resolved config.
+ */
+export async function loadConfig(cwd = process.cwd()) {
+  // Walk up from cwd so the linter finds the repo-root config even when invoked
+  // from a subdirectory.
+  let dir = cwd;
+  for (;;) {
+    for (const name of ["ads-lint.config.mjs", "ads-lint.config.js"]) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) {
+        const mod = await import(pathToFileURL(candidate).href);
+        return mergeConfig(DEFAULT_CONFIG, mod.default ?? mod.config ?? {});
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return DEFAULT_CONFIG;
+    dir = parent;
+  }
+}

package/src/index.mjs

@@ -0,0 +1,8 @@
+// Programmatic API — for wiring ads-lint into other tools (CI reporters, an
+// eventual ESLint bridge). The CLI in bin/ads-lint.mjs is a thin wrapper.
+
+export { loadConfig, DEFAULT_CONFIG } from "./config.mjs";
+export { resolveFiles, lintFiles, formatFindings } from "./runner.mjs";
+export { lintImports } from "./rules/imports.mjs";
+export { lintMotion } from "./rules/motion.mjs";
+export { lintLiterals } from "./rules/literals.mjs";

package/src/rules/imports.mjs

@@ -0,0 +1,190 @@
+// Import-boundary rules — the ADS governance engine (principle 7 + principle 4),
+// generalized so it runs against any repo, not just the library itself.
+//
+// Parsing has two tiers:
+//   • TypeScript compiler API when `typescript` is resolvable (exact, handles
+//     multi-line specifiers, type-only imports, aliasing) — the same engine as
+//     the library's own check-ads-governance.mjs.
+//   • A regex fallback when it isn't, so the tool works in a fresh repo before
+//     `npm i typescript`. Slightly less precise on exotic import forms.
+
+import { matchesAny } from "../config.mjs";
+
+// Load typescript if available; otherwise fall back to regex parsing.
+let ts = null;
+try {
+  ts = (await import("typescript")).default;
+} catch {
+  ts = null;
+}
+
+/** @returns {{line:number, spec:string, clause:{default?:string, namespace?:string, named?:Array<{name:string, alias?:string}>}}[]} */
+function parseImportsWithTs(relPath, source) {
+  const kind = relPath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  const sf = ts.createSourceFile(relPath, source, ts.ScriptTarget.Latest, true, kind);
+  const out = [];
+  sf.forEachChild((node) => {
+    if (!ts.isImportDeclaration(node) || !ts.isStringLiteral(node.moduleSpecifier)) return;
+    const line = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+    const clause = {};
+    const c = node.importClause;
+    if (c) {
+      if (c.name) clause.default = c.name.text;
+      if (c.namedBindings && ts.isNamespaceImport(c.namedBindings)) {
+        clause.namespace = c.namedBindings.name.text;
+      }
+      if (c.namedBindings && ts.isNamedImports(c.namedBindings)) {
+        clause.named = c.namedBindings.elements.map((el) => ({
+          name: el.propertyName ? el.propertyName.text : el.name.text,
+          alias: el.propertyName ? el.name.text : undefined,
+        }));
+      }
+    }
+    out.push({ line, spec: node.moduleSpecifier.text, clause });
+  });
+  return out;
+}
+
+const IMPORT_RE = /\bimport\s+(?:type\s+)?([\s\S]*?)\s+from\s+['"]([^'"]+)['"]|\bimport\s+['"]([^'"]+)['"]/g;
+
+// Any asset import — never a JS component deep-import, so exempt from the rule.
+const ASSET_RE = /\.(css|scss|sass|less|svg|png|jpe?g|gif|webp|avif|woff2?|ttf|otf|eot|json)$/i;
+
+// Blank out comments so the regex-fallback tier doesn't flag import-like text
+// in `// import X from "@mui/..."` or block comments (the TS-AST tier is immune).
+function stripComments(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+    .replace(/(^|[^:])\/\/[^\n]*/g, (m, p1) => p1 + " ".repeat(m.length - p1.length));
+}
+
+function parseImportsWithRegex(rawSource) {
+  const source = stripComments(rawSource);
+  const out = [];
+  for (const m of source.matchAll(IMPORT_RE)) {
+    const spec = m[2] ?? m[3];
+    const line = source.slice(0, m.index).split("\n").length;
+    const clauseText = (m[1] ?? "").trim();
+    const clause = {};
+    if (clauseText) {
+      const nsMatch = clauseText.match(/^\*\s+as\s+([A-Za-z_$][\w$]*)/);
+      if (nsMatch) clause.namespace = nsMatch[1];
+      const braceMatch = clauseText.match(/\{([\s\S]*)\}/);
+      if (braceMatch) {
+        clause.named = braceMatch[1]
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+          .map((s) => {
+            const parts = s.replace(/^type\s+/, "").split(/\s+as\s+/);
+            return { name: parts[0].trim(), alias: parts[1] ? parts[1].trim() : undefined };
+          });
+      }
+      // A bare leading identifier (before `{` or end) is a default import.
+      const head = clauseText.replace(/\{[\s\S]*\}/, "").replace(/,\s*$/, "").trim();
+      if (head && !head.startsWith("*") && /^[A-Za-z_$][\w$]*$/.test(head)) {
+        clause.default = head;
+      }
+    }
+    out.push({ line, spec, clause });
+  }
+  return out;
+}
+
+export function lintImports(relPath, source, cfg) {
+  const { imports: c } = cfg;
+  if (!/\.(ts|tsx)$/.test(relPath)) return [];
+
+  const parsed = ts ? parseImportsWithTs(relPath, source) : parseImportsWithRegex(source);
+  const findings = [];
+
+  const insideLibrary =
+    c.libraryRoot != null &&
+    (relPath === c.libraryRoot || relPath.startsWith(`${c.libraryRoot}/`));
+  const isIconRegistry = matchesAny(relPath, c.iconRegistryAllowlist ?? []);
+  const uiPatterns = (c.bannedUiPackages ?? []).map((p) => new RegExp(p));
+  const iconPatterns = (c.bannedIconPackages ?? []).map((p) => new RegExp(p));
+  const deepPrefix = `${c.libraryPackage}/`;
+  const sanctioned = new Set(c.sanctionedSubpaths ?? []);
+
+  for (const imp of parsed) {
+    const { spec, line, clause } = imp;
+
+    // Icon-package imports are banned everywhere except the registry (principle 4).
+    if (!isIconRegistry && iconPatterns.some((re) => re.test(spec))) {
+      findings.push({
+        line,
+        rule: "icon-package-import",
+        severity: "error",
+        match: spec,
+        guidance: `Icons come only from the ADS icon registry. Add the stroke icon there and import it, never from "${spec}".`,
+      });
+    }
+
+    // The remaining rules concern the consumer/library boundary; library
+    // internals are exempt (a sibling may cross-import a sibling).
+    if (insideLibrary) continue;
+
+    if (spec.startsWith(deepPrefix)) {
+      const subpath = spec.slice(deepPrefix.length);
+      // Sanctioned CSS entries and any asset import are legitimate, not a
+      // barrel bypass — only JS component deep-imports are flagged.
+      if (!sanctioned.has(subpath) && !ASSET_RE.test(spec)) {
+        findings.push({
+          line,
+          rule: "deep-import",
+          severity: "error",
+          match: spec,
+          guidance: `Deep import bypasses the ADS barrel; import the exact symbol from "${c.libraryPackage}".`,
+        });
+      }
+    }
+
+    if (uiPatterns.some((re) => re.test(spec)) || /^https?:\/\//.test(spec)) {
+      findings.push({
+        line,
+        rule: "external-ui-import",
+        severity: "error",
+        match: spec,
+        guidance: `External UI import bypasses ADS. Use a component from "${c.libraryPackage}" (or extend ADS first).`,
+      });
+    }
+
+    if (spec !== c.libraryPackage) continue;
+
+    if (clause.default) {
+      findings.push({
+        line,
+        rule: "barrel-default-import",
+        severity: "error",
+        match: clause.default,
+        guidance: `Default imports from "${c.libraryPackage}" are forbidden; use exact named exports.`,
+      });
+    }
+    if (clause.namespace) {
+      findings.push({
+        line,
+        rule: "barrel-namespace-import",
+        severity: "error",
+        match: `* as ${clause.namespace}`,
+        guidance: `Namespace imports from "${c.libraryPackage}" are forbidden; use exact named exports.`,
+      });
+    }
+    for (const el of clause.named ?? []) {
+      if (el.alias && el.alias !== el.name) {
+        findings.push({
+          line,
+          rule: "barrel-aliased-import",
+          severity: "error",
+          match: `${el.name} as ${el.alias}`,
+          guidance: `ADS symbol ${el.name} is aliased; use the exact exported name.`,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+/** Which parser tier is active — surfaced by the CLI banner. */
+export const parserTier = ts ? "typescript" : "regex";

package/src/rules/literals.mjs

@@ -0,0 +1,82 @@
+// Hardcoded-literal rules — the core ADS invariant: "No hardcoded
+// color/dimension literals — every value flows from a token."
+//
+//   • bare hex colors in .ts/.tsx          → use a color token          (error)
+//   • Tailwind arbitrary color  bg-[#fff]  → use a token utility        (error)
+//   • Tailwind arbitrary dimension w-[13px]→ prefer a scale/token value (warn)
+//
+// Files where raw values are sanctioned (token definitions, shaders, colorful
+// palettes, token-swatch docs) are exempt via `literals.allow` in config.
+
+import { matchesAny } from "../config.mjs";
+
+// Bare hex color in code: #RGB, #RGBA, #RRGGBB, #RRGGBBAA.
+const HEX = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})\b/g;
+
+// Contexts where a `#xxxxxx` token is an id/selector/fragment, not a color.
+const NON_COLOR_CTX =
+  /(?:querySelector(?:All)?|getElementById|getElementsBy\w+|\.matches|\.closest|location\.hash|URLSearchParams|new URL)\s*\([^)]*$/;
+
+// Tailwind arbitrary color value, e.g. bg-[#fff], text-[rgb(0_0_0)], [color:#111].
+const ARB_COLOR =
+  /-\[(?:#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla|oklch|oklab)\([^\]]*\))\]/g;
+
+// Tailwind arbitrary absolute dimension, e.g. w-[13px], gap-[1.5rem], top-[2em].
+// %, vh, vw and calc() are left alone — they're usually genuinely one-off.
+const ARB_DIM = /-\[-?[0-9.]+(?:px|rem|em)\]/g;
+
+function lineOf(source, index) {
+  return source.slice(0, index).split("\n").length;
+}
+
+export function lintLiterals(relPath, source, cfg) {
+  const c = cfg.literals ?? {};
+  if (matchesAny(relPath, c.allow ?? [])) return [];
+
+  const findings = [];
+  const isCode = /\.(ts|tsx)$/.test(relPath);
+
+  if (c.hex !== false && isCode) {
+    for (const m of source.matchAll(HEX)) {
+      const prev = source[m.index - 1];
+      // arbitrary-color owns the bracketed form; "." / "#" mean a private field
+      // or id-ish token, not a color.
+      if (prev === "[" || prev === "." || prev === "#") continue;
+      // DOM selector / URL-fragment argument, not a color value.
+      if (NON_COLOR_CTX.test(source.slice(Math.max(0, m.index - 48), m.index))) continue;
+      findings.push({
+        line: lineOf(source, m.index),
+        rule: "hardcoded-hex",
+        severity: "error",
+        match: m[0],
+        guidance: "Use an ADS color token, not a raw hex value.",
+      });
+    }
+  }
+
+  if (c.arbitraryColor !== false && (isCode || relPath.endsWith(".css"))) {
+    for (const m of source.matchAll(ARB_COLOR)) {
+      findings.push({
+        line: lineOf(source, m.index),
+        rule: "arbitrary-color",
+        severity: "error",
+        match: m[0],
+        guidance: "Use a token color utility (bg-*/text-*), not an arbitrary value.",
+      });
+    }
+  }
+
+  if (c.arbitraryDimension !== false && isCode) {
+    for (const m of source.matchAll(ARB_DIM)) {
+      findings.push({
+        line: lineOf(source, m.index),
+        rule: "arbitrary-dimension",
+        severity: "warn",
+        match: m[0],
+        guidance: "Prefer a spacing/size token or the Tailwind scale over a raw dimension.",
+      });
+    }
+  }
+
+  return findings;
+}

package/src/rules/motion.mjs

@@ -0,0 +1,75 @@
+// Motion rules (principle 3) — regex over .css/.ts/.tsx. Banned easing,
+// unbounded transitions, undersized entrances, hardcoded/at-or-over-300ms
+// durations, layout-property motion.
+//
+// This RULES table is the SINGLE SOURCE OF TRUTH for the motion policy — the
+// repo's scripts/check-motion.mjs imports it too, so the two never drift.
+
+import { matchesAny } from "../config.mjs";
+
+export const RULES = [
+  {
+    name: "unbounded-transition",
+    severity: "error",
+    pattern: /\btransition-all\b/g,
+    guidance: "List the animated properties explicitly (transform/opacity).",
+  },
+  {
+    name: "sluggish-easing",
+    severity: "error",
+    pattern: /\bease-in(?!-out)\b/g,
+    guidance: "Use the ADS ease-out token for UI entrances and exits.",
+  },
+  {
+    name: "zero-scale-entrance",
+    severity: "error",
+    pattern: /\bscale-0\b|\bscale\s*:\s*0(?=\s*[,}])/g,
+    guidance: "Start at scale 0.9–0.97 with opacity instead of scale(0).",
+  },
+  {
+    name: "undersized-zoom-entrance",
+    severity: "error",
+    pattern: /(?<!cursor-)\bzoom-(?:in|out)\b(?!-(?:9\d|100)\b)/g,
+    guidance: "Use zoom-in/out-95 so the element retains physical presence.",
+  },
+  {
+    name: "hardcoded-duration",
+    severity: "error",
+    pattern: /\bduration-\d+\b|\[animation-duration:\s*\d/g,
+    guidance: "Use an ADS duration token (--duration-fast / --duration-normal).",
+  },
+  {
+    name: "layout-property-transition",
+    severity: "error",
+    pattern:
+      /transition-\[[^\]]*(?:width|height|grid-template|margin|padding|top|right|bottom|left)[^\]]*\]/g,
+    guidance: "Animate transform/opacity, or drop motion for frequent disclosure.",
+  },
+  {
+    name: "layout-keyframe-disclosure",
+    severity: "error",
+    pattern: /animate-(?:accordion|collapsible)-(?:down|up)/g,
+    guidance: "Do not animate height for high-frequency disclosure controls.",
+  },
+];
+
+export function lintMotion(relPath, source, cfg) {
+  if (cfg.motion?.enabled === false) return [];
+  if (matchesAny(relPath, cfg.motion?.allow ?? [])) return [];
+  if (!/\.(ts|tsx|css)$/.test(relPath)) return [];
+
+  const findings = [];
+  for (const rule of RULES) {
+    rule.pattern.lastIndex = 0;
+    for (const m of source.matchAll(rule.pattern)) {
+      findings.push({
+        line: source.slice(0, m.index).split("\n").length,
+        rule: rule.name,
+        severity: rule.severity,
+        match: m[0],
+        guidance: rule.guidance,
+      });
+    }
+  }
+  return findings;
+}

package/src/runner.mjs

@@ -0,0 +1,110 @@
+// Runner — resolve the file set, dispatch each file to every rule, format.
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { matchesAny } from "./config.mjs";
+import { lintImports } from "./rules/imports.mjs";
+import { lintMotion } from "./rules/motion.mjs";
+import { lintLiterals } from "./rules/literals.mjs";
+
+const RULE_FNS = [lintImports, lintMotion, lintLiterals];
+
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+
+/** Recursively collect files with a matching extension under `dir`. */
+function walk(dir, extensions) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".git") return [];
+      return walk(full, extensions);
+    }
+    return extensions.includes(path.extname(entry.name)) ? [full] : [];
+  });
+}
+
+function git(args, cwd) {
+  return execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+}
+
+/** Files changed vs a git ref (committed diff) or the index (--staged). */
+function gitFiles({ diff, staged }, cwd) {
+  // git prints repo-root-relative paths, so resolve against the toplevel, not
+  // cwd (the linter may be invoked from a subdirectory).
+  let root = cwd;
+  try {
+    root = git(["rev-parse", "--show-toplevel"], cwd) || cwd;
+  } catch {
+    /* not a git repo — fall back to cwd */
+  }
+
+  const args = ["diff", "--name-only", "--diff-filter=ACMR"];
+  if (staged) args.push("--cached");
+  // `<ref>...HEAD` diffs from the MERGE-BASE (what a PR actually adds), not the
+  // ref tip. CI note: needs full history — set actions/checkout fetch-depth: 0.
+  if (diff) args.push(`${diff}...HEAD`);
+
+  let out;
+  try {
+    out = git(args, cwd);
+  } catch (err) {
+    const ref = diff ? `"${diff}"` : "the index";
+    throw new Error(
+      `ads-lint: git diff against ${ref} failed — is ${diff ? `${diff} present (shallow clone? set fetch-depth: 0)` : "this a git repo"}?\n${err.message}`
+    );
+  }
+  return out.split("\n").filter(Boolean).map((f) => path.resolve(root, f));
+}
+
+/**
+ * Resolve the list of absolute file paths to lint from CLI options.
+ * Precedence: explicit files > --staged/--diff > --all/root walk.
+ */
+export function resolveFiles(opts, cfg, cwd) {
+  let files;
+  if (opts.files.length > 0) {
+    files = opts.files.map((f) => path.resolve(cwd, f));
+  } else if (opts.staged || opts.diff) {
+    files = gitFiles(opts, cwd);
+  } else {
+    files = walk(path.resolve(cwd, cfg.root), cfg.extensions);
+  }
+
+  return files.filter((abs) => {
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) return false;
+    if (!cfg.extensions.includes(path.extname(abs))) return false;
+    const rel = toPosix(path.relative(cwd, abs));
+    return !matchesAny(rel, cfg.ignore ?? []);
+  });
+}
+
+/** Lint one resolved file set. Returns { findings, fileCount }. */
+export function lintFiles(absFiles, cfg, cwd) {
+  const findings = [];
+  for (const abs of absFiles) {
+    const rel = toPosix(path.relative(cwd, abs));
+    const source = fs.readFileSync(abs, "utf8");
+    for (const fn of RULE_FNS) {
+      for (const f of fn(rel, source, cfg)) {
+        findings.push({ file: rel, ...f });
+      }
+    }
+  }
+  findings.sort(
+    (a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.rule.localeCompare(b.rule)
+  );
+  return { findings, fileCount: absFiles.length };
+}
+
+export function formatFindings(findings) {
+  return findings
+    .map(
+      (f) =>
+        `${f.file}:${f.line} [${f.severity}] ${f.rule}: ${f.match} — ${f.guidance}`
+    )
+    .join("\n");
+}