@reqvire-org/ads 0.0.0-stage → 0.3.0

package/dist/bootstrap-ds/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "native-design-system",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Private starter workspace for a project's local React design system.",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "ads showcase",
+    "dev:showcase": "ads showcase",
+    "lint": "oxlint --deny-warnings src design-system && biome lint --config-path=biome.css.json .",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run lint && npm run typecheck && npm run build:lib",
+    "build:lib": "vite build && tsc --project tsconfig.build.json",
+    "build:showcase": "node scripts/build-mcp-previews.mjs",
+    "preview": "ads showcase",
+    "preview:showcase": "ads showcase",
+    "build:mcp-previews": "node scripts/build-mcp-previews.mjs"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@babel/preset-react": "7.29.7",
+    "@babel/preset-typescript": "7.29.7",
+    "@linaria/atomic": "8.0.0",
+    "@types/node": "25.9.4",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "4.7.0",
+    "@wyw-in-js/vite": "2.1.3",
+    "oxlint": "1.72.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "typescript": "5.9.3",
+    "vite": "6.4.3"
+  }
+}

package/dist/bootstrap-ds/scripts/build-mcp-previews.mjs

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { build } from "vite";
+import wyw from "@wyw-in-js/vite";
+import react from "@vitejs/plugin-react";
+import { runScenarioCompiler } from "@reqvire-org/ads/scenarios/compiler";
+import { createPreviewResources, previewEntriesPlugin } from "@reqvire-org/ads/scenarios/vite";
+
+const root = path.resolve(import.meta.dirname, "..");
+const runScript = promisify(execFile);
+const projectPackage = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+const manager = projectPackage.packageManager?.split("@")[0] ?? (existsSync(path.join(root, "bun.lock")) || existsSync(path.join(root, "bun.lockb")) ? "bun" : "npm");
+await runScenarioCompiler(root, {
+  watched: process.argv.includes("--watch"),
+  compilerFiles: [import.meta.filename],
+  async validate() {
+    try { await runScript(manager, ["run", "lint"], { cwd: root }); }
+    catch (error) { throw new Error([error.stdout, error.stderr].map(value => value?.toString() ?? "").join("\n") || error.message); }
+  },
+  async buildGraph(entries, options, track) {
+    const mount = path.join(options.dsRoot, "showcase/mcp/main.tsx");
+    const output = await build({ configFile: false, root, base: "./", publicDir: false,
+      plugins: [previewEntriesPlugin(entries.map(entry => ({ ...entry, root })), mount), wyw({ include: ["**/*.{ts,tsx}"], exclude: ["**/node_modules/**"] }), react(), track],
+      resolve: { alias: { "@ds": path.join(options.dsRoot, options.config.publicEntry) } },
+      worker: { format: "iife" },
+      build: { write: false, cssCodeSplit: true, assetsInlineLimit: 0, modulePreload: false,
+        rollupOptions: { preserveEntrySignatures: "strict", input: Object.fromEntries(entries.map((_entry, index) => [`scenario-${index}`, `ads-preview-entry:${index}`])) } },
+    });
+    return createPreviewResources(output, options, entries);
+  },
+});

package/dist/bootstrap-ds/src/vite-env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module "@scenario" {
+  import type { ComponentType } from "react";
+  const Scenario: ComponentType;
+  export default Scenario;
+}

package/dist/bootstrap-ds/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "rootDir": "design-system",
+    "outDir": "dist"
+  },
+  "include": ["design-system/**/*.ts", "design-system/**/*.tsx"],
+  "exclude": ["design-system/showcase"]
+}

package/dist/bootstrap-ds/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": { "@ds": ["design-system/index.ts"] }
+  },
+  "include": ["src", "design-system", "vite.config.ts"]
+}

package/dist/bootstrap-ds/vite.config.ts

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import wyw from "@wyw-in-js/vite";
+
+export default defineConfig({
+  plugins: [wyw(), react()],
+  resolve: {
+    alias: { "@ds": path.resolve(import.meta.dirname, "design-system/index.ts") },
+  },
+  build: {
+    outDir: "dist",
+    lib: {
+      entry: path.resolve(import.meta.dirname, "design-system/index.ts"),
+      formats: ["es"],
+      fileName: () => "index.js",
+      cssFileName: "styles",
+    },
+    rollupOptions: { external: [/^react(?:\/.*)?$/, /^react-dom(?:\/.*)?$/] },
+  },
+});

package/dist/boundaries.mjs

@@ -0,0 +1,130 @@
+import path from "node:path";
+import ts from "typescript";
+import { importedUiName } from "./ui-framework.mjs";
+import { isInside, isStateVariable, isTestFile, isDevelopmentFile } from "./config.mjs";
+import { isSharedToken } from "./token-policy.mjs";
+
+export function projectCompilerOptions({ root }) {
+  const file = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json");
+  let compiler = {};
+  if (file && isInside(root, file)) {
+    const parsed = ts.readConfigFile(file, ts.sys.readFile);
+    if (!parsed.error) compiler = ts.parseJsonConfigFileContent(parsed.config, ts.sys, path.dirname(file)).options;
+  }
+  return compiler;
+}
+
+export function importResolver(options) {
+  const { root } = options;
+  const compiler = projectCompilerOptions(options);
+  return (specifier, filename) => {
+    // Vite and other bundlers attach resource queries to the same source file.
+    // They cannot turn a private file into a public import.
+    specifier = specifier.replace(/[?#].*$/, "");
+    const resolved = ts.resolveModuleName(specifier, filename, compiler, ts.sys).resolvedModule?.resolvedFileName;
+    if (resolved) return [path.resolve(resolved)];
+    // Unresolved local imports are still boundaries, even before their files exist.
+    if (specifier.startsWith(".")) return [path.resolve(path.dirname(filename), specifier)];
+    for (const [alias, targets] of Object.entries(compiler.paths ?? {})) {
+      const index = alias.indexOf("*");
+      const prefix = index < 0 ? alias : alias.slice(0, index);
+      const suffix = index < 0 ? "" : alias.slice(index + 1);
+      if (index < 0 ? specifier !== alias : !specifier.startsWith(prefix) || !specifier.endsWith(suffix)) continue;
+      const matched = index < 0 ? "" : specifier.slice(prefix.length, specifier.length - suffix.length);
+      return targets.map((target) => path.resolve(compiler.baseUrl ?? compiler.pathsBasePath ?? root, target.replace("*", matched)));
+    }
+    return [path.resolve(compiler.baseUrl ?? root, specifier)];
+  };
+}
+
+export function appImportViolation(specifier, filename, options, resolve = importResolver(options)) {
+  const { root, dsRoot, config } = options;
+  if (!isInside(dsRoot, filename) || isTestFile(filename)) return false;
+  const sourceRoot = path.resolve(root, config.sourceDir);
+  return resolve(specifier, filename).some((file) => isInside(sourceRoot, file) && !isInside(dsRoot, file));
+}
+
+export function showcaseImportViolation(specifier, filename, options, resolve = importResolver(options)) {
+  if (isTestFile(filename)) return false;
+  if (isDevelopmentFile(filename, options)) return false;
+  return resolve(specifier, filename).some((file) => isDevelopmentFile(file, options) || isTestFile(file));
+}
+
+
+export function checkComponentVariable(name, filename, options) {
+  const { dsRoot, config } = options;
+  if (!name.startsWith("--")) return null;
+  const tokens = isInside(path.join(dsRoot, config.tokenDir), filename);
+  const development = isDevelopmentFile(filename, options);
+  const components = !development && isInside(path.join(dsRoot, "components"), filename);
+  const patterns = !development && isInside(path.join(dsRoot, "patterns"), filename);
+  const showcase = development;
+  if (isSharedToken(name)) return tokens ? null : { rule: "token-ownership", message: `Define ${name} in ADS tokens, not component, pattern, showcase, or app styles.` };
+  if (name.startsWith("--ux-")) return patterns || showcase ? null : { rule: "variable-ownership", message: "--ux-* variables belong to ADS patterns and showcase composition." };
+  if (name.startsWith("--showcase-")) return showcase ? null : { rule: "variable-ownership", message: "--showcase-* variables belong to the ADS showcase." };
+  if (!name.startsWith("--ds-")) return { rule: "token-name", message: `${name} does not follow ADS's fixed token naming contract. Use a shared token, --ds-*, --ux-*, or --showcase-* in its owning layer.` };
+  if (components) return null;
+  if (isStateVariable(name)) return { rule: "primitive-state", message: "Primitive interaction variables belong to components. Add a typed primitive variant instead of overriding state policy." };
+  if (tokens) return { rule: "variable-ownership", message: "Component --ds-* variables belong to components, not shared token files." };
+  if (!config.boundaries.componentVariables.includes(name)) return { rule: "component-variable", message: `Undocumented component customization ${name}. Register a documented non-state variable or use a public prop.` };
+  return null;
+}
+
+function memberName(node) {
+  if (ts.isPropertyAccessExpression(node)) return node.name.text;
+  if (ts.isElementAccessExpression(node) && node.argumentExpression && ts.isStringLiteralLike(node.argumentExpression)) return node.argumentExpression.text;
+  return null;
+}
+
+function isMember(node) { return ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node); }
+function unwrapped(node) {
+  while (node?.parent && (ts.isParenthesizedExpression(node.parent) || ts.isAsExpression(node.parent) || ts.isNonNullExpression(node.parent) || ts.isSatisfiesExpression(node.parent))) node = node.parent;
+  return node;
+}
+function cssName(name) { return name?.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`); }
+function isWrite(node) {
+  node = unwrapped(node);
+  const parent = node.parent;
+  return (ts.isBinaryExpression(parent) && parent.left === node && parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+    || ((ts.isPrefixUnaryExpression(parent) || ts.isPostfixUnaryExpression(parent)) && [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(parent.operator))
+    || ts.isDeleteExpression(parent);
+}
+
+// Inspects style access itself, so aliases, computed keys, cssText and bulk writes
+// cannot silently turn a narrow property exception into a whole-file exception.
+export function styleWriteViolation(node, filename, { root, config }) {
+  const allowed = config.boundaries.styleWrites.find((boundary) => path.resolve(root, boundary.file) === filename)?.properties ?? [];
+  if (isMember(node) && memberName(node) === "style") {
+    const access = unwrapped(node);
+    const parent = access.parent;
+    let property;
+    if (isMember(parent) && parent.expression === access) {
+      property = cssName(memberName(parent));
+      const target = unwrapped(parent);
+      if (ts.isCallExpression(target.parent) && target.parent.expression === target) {
+        if (["set-property", "remove-property"].includes(property)) {
+          const name = target.parent.arguments[0];
+          property = name && ts.isStringLiteralLike(name) ? name.text : null;
+        } else if (["get-property-value", "get-property-priority", "item"].includes(property)) return null;
+        else property = null;
+      } else if (!isWrite(target)) {
+        // Plain property reads are allowed. Passing a method reference or a
+        // computed member elsewhere is not a known property read.
+        if (property && !["set-property", "remove-property"].includes(property)) return null;
+        property = null;
+      }
+    }
+    if (property && property !== "css-text" && allowed.includes(property)) return null;
+    return "Imperative styles require a file boundary and an explicit property. Bulk writes, computed property names, and style-object escapes are forbidden.";
+  }
+  if (ts.isCallExpression(node) && isMember(node.expression) && ["setAttribute", "setAttributeNS"].includes(memberName(node.expression))) {
+    const index = memberName(node.expression) === "setAttributeNS" ? 1 : 0;
+    const name = node.arguments[index];
+    if (name && ts.isStringLiteralLike(name) && name.text.toLowerCase() === "style") return "Do not write a style attribute. Use ADS props or a narrowly configured property boundary.";
+  }
+  return null;
+}
+
+export function isUiCssProperties(node, checker) {
+  return ts.isTypeReferenceNode(node) && ["CSSProperties", "JSX.CSSProperties"].includes(importedUiName(node.typeName, checker));
+}

package/dist/brand-assets.mjs

@@ -0,0 +1,82 @@
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { isInside, loadConfig } from "./config.mjs";
+
+export const brandFiles = ["favicon.svg", "favicon.ico", "apple-touch-icon.png", "icon-192.png", "icon-512.png"];
+
+export function brandSourceDiagnostic({ root, dsRoot, config }) {
+  if (!config.assets.iconSource) return null;
+  const file = path.join(dsRoot, config.assets.iconSource);
+  let valid = true;
+  for (let current = file; isInside(root, current); current = path.dirname(current)) {
+    const stat = lstatSync(current, { throwIfNoEntry: false });
+    if (!stat || stat.isSymbolicLink() || (current === file ? !stat.isFile() : !stat.isDirectory())) valid = false;
+    if (current === root) break;
+  }
+  if (valid && /<svg\b[\s\S]*<\/svg\s*>|<svg\b[^>]*\/>/i.test(readFileSync(file, "utf8"))) return null;
+  return { rule: "asset-source", file: path.relative(root, file).replaceAll("\\", "/"), line: 1, column: 1, message: "assets.iconSource must be an existing SVG master inside assets/brand/, without symlinked paths." };
+}
+
+function assertOutput(root, file, { directory = false } = {}) {
+  for (let current = file; isInside(root, current); current = path.dirname(current)) {
+    const stat = lstatSync(current, { throwIfNoEntry: false });
+    if (stat && (stat.isSymbolicLink() || (current === file && !directory ? !stat.isFile() : !stat.isDirectory()))) throw new Error(`Invalid generated asset path: ${current}`);
+    if (current === root) break;
+  }
+}
+
+function ico(entries) {
+  const offset = 6 + entries.length * 16;
+  const result = Buffer.alloc(offset + entries.reduce((size, entry) => size + entry.buffer.length, 0));
+  result.writeUInt16LE(1, 2);
+  result.writeUInt16LE(entries.length, 4);
+  let position = offset;
+  entries.forEach(({ size, buffer }, index) => {
+    const start = 6 + index * 16;
+    result.writeUInt8(size, start);
+    result.writeUInt8(size, start + 1);
+    result.writeUInt16LE(1, start + 4);
+    result.writeUInt16LE(32, start + 6);
+    result.writeUInt32LE(buffer.length, start + 8);
+    result.writeUInt32LE(position, start + 12);
+    buffer.copy(result, position);
+    position += buffer.length;
+  });
+  return result;
+}
+
+export async function generateBrandAssets(directory = process.cwd()) {
+  const options = loadConfig(directory);
+  const { root, dsRoot, config } = options;
+  const output = path.join(root, ".ds/assets");
+  if (!config.assets.iconSource) return { directory: output, files: [], skipped: true };
+  const diagnostic = brandSourceDiagnostic(options);
+  if (diagnostic) throw new Error(`${diagnostic.file} [${diagnostic.rule}] ${diagnostic.message}`);
+  assertOutput(root, output, { directory: true });
+  for (const name of brandFiles) {
+    assertOutput(root, path.join(output, name));
+    for (const mount of [path.join(dsRoot, "assets"), path.join(dsRoot, "showcase/public/assets"), ...config.assets.publicDirs.map((entry) => path.join(root, entry))]) {
+      if (lstatSync(path.join(mount, name), { throwIfNoEntry: false })) throw new Error(`[asset-collision] ${path.relative(root, mount)}/${name} conflicts with a generated brand asset.`);
+    }
+  }
+  // Load rendering only when the project has selected artwork. Render everything
+  // before writing, so invalid SVG cannot replace the last successful outputs.
+  const { default: sharp } = await import("sharp");
+  const source = readFileSync(path.join(dsRoot, config.assets.iconSource));
+  const outputs = new Map([["favicon.svg", source]]);
+  const sizes = [16, 32, 48, 180, 192, 512];
+  const rendered = new Map();
+  for (const size of sizes) rendered.set(size, await sharp(source, { density: 512 }).resize(size, size, { fit: "contain", background: { r: 0, g: 0, b: 0, alpha: 0 } }).png().toBuffer());
+  outputs.set("favicon.ico", ico([16, 32, 48].map((size) => ({ size, buffer: rendered.get(size) }))));
+  outputs.set("apple-touch-icon.png", rendered.get(180));
+  outputs.set("icon-192.png", rendered.get(192));
+  outputs.set("icon-512.png", rendered.get(512));
+  mkdirSync(path.dirname(output), { recursive: true });
+  const staging = mkdtempSync(path.join(root, ".ds/assets-staging-"));
+  try {
+    for (const [name, buffer] of outputs) writeFileSync(path.join(staging, name), buffer);
+    mkdirSync(output, { recursive: true });
+    for (const name of brandFiles) renameSync(path.join(staging, name), path.join(output, name));
+  } finally { rmSync(staging, { recursive: true, force: true }); }
+  return { directory: output, files: brandFiles.map((name) => path.join(output, name)), skipped: false };
+}

package/dist/check.mjs

@@ -0,0 +1,222 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import postcss from "postcss";
+import valueParser from "postcss-value-parser";
+import { importViolation, isInside, loadConfig, sourceFiles, isDevelopmentFile, isTestFile } from "./config.mjs";
+import { inspectTokens, references } from "./tokens.mjs";
+import { foundationFiles, isSharedToken } from "./token-policy.mjs";
+import { inspectAssets } from "./assets.mjs";
+import { appImportViolation, showcaseImportViolation, checkComponentVariable, importResolver, projectCompilerOptions, isUiCssProperties, styleWriteViolation } from "./boundaries.mjs";
+import { inspectPublicProps } from "./public-props.mjs";
+import { inspectHtml, isMountCss } from "./html.mjs";
+import { inspectShowcasePages } from "./showcase.mjs";
+import { inspectShowcaseCoverage } from "./showcase-coverage.mjs";
+import { inspectScenarioCoverage } from "./scenarios.mjs";
+import { uiOperation, importedUiApi } from "./ui-framework.mjs";
+
+const showcaseControls = new Set(["a", "button", "input", "select", "textarea", "option", "optgroup", "table", "thead", "tbody", "tfoot", "tr", "td", "th", "dialog", "details", "summary", "progress", "meter"]);
+const svgTags = new Set(["svg", "g", "path", "circle", "rect", "ellipse", "line", "polyline", "polygon", "text", "tspan", "use", "defs", "clipPath", "mask", "filter", "linearGradient", "radialGradient", "stop", "marker", "pattern"]);
+const svgPresentation = new Set(["strokeWidth", "strokeLinecap", "strokeLinejoin", "strokeDasharray", "strokeDashoffset", "strokeOpacity", "strokeMiterlimit", "fillRule", "fillOpacity", "clipRule", "clipPath", "colorInterpolation", "colorInterpolationFilters", "floodColor", "floodOpacity", "stopColor", "stopOpacity", "fontFamily", "fontSize", "fontStyle", "fontWeight", "letterSpacing", "textAnchor", "dominantBaseline", "markerStart", "markerMid", "markerEnd", "vectorEffect", "shapeRendering", "textRendering", "paintOrder", "alignmentBaseline", "baselineShift", "transformOrigin"]);
+const widgetRoles = new Set(["button", "link", "checkbox", "radio", "switch", "combobox", "textbox", "listbox", "option", "slider", "spinbutton", "tab", "tablist", "menu", "menuitem", "tree", "treeitem", "grid", "dialog", "alertdialog", "progressbar"]);
+
+export function checkProject(directory, { trackingRoot } = {}) {
+  const options = { ...loadConfig(directory), ...(trackingRoot ? { trackingRoot: path.resolve(trackingRoot) } : {}) };
+  const { root, config, dsRoot, sourceRoot } = options;
+  const diagnostics = [];
+  for (const [field, file] of [["dsDir", dsRoot], ["publicEntry", path.join(dsRoot, config.publicEntry)], ["stylesEntry", path.join(dsRoot, config.stylesEntry)]]) {
+    if (!existsSync(file) || (field === "dsDir" ? !statSync(file).isDirectory() : !statSync(file).isFile())) diagnostics.push({ rule: "project-structure", file: path.relative(root, file), line: 1, column: 1, message: `Missing or invalid ${field}. Bootstrap an empty ADS or configure its actual path.` });
+  }
+  if (diagnostics.length) return { ok: false, diagnostics };
+  const tokenInventory = inspectTokens(root);
+  const declaredTokens = new Set(tokenInventory.tokens.map((token) => token.name));
+  diagnostics.push(...tokenInventory.diagnostics);
+  diagnostics.push(...inspectAssets(options));
+  const resolveImport = importResolver(options);
+  const rootHtml = path.join(root, "index.html");
+  const files = [...new Set([...sourceFiles(sourceRoot), ...sourceFiles(dsRoot), ...(existsSync(rootHtml) ? [rootHtml] : [])])];
+  const scriptFiles = files.filter((file) => /\.[cm]?[jt]sx?$/.test(file));
+  const compiler = projectCompilerOptions(options);
+  const program = ts.createProgram(scriptFiles, { ...compiler, paths: { ...compiler.paths, [config.publicAlias]: [path.join(dsRoot, config.publicEntry)] }, allowJs: true, noResolve: true, noLib: true, types: [], target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, jsx: ts.JsxEmit.Preserve });
+  const checker = program.getTypeChecker();
+  function report(file, rule, message, line = 1, column = 1) {
+    diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line, column });
+  }
+  inspectShowcasePages(options, program, resolveImport, report);
+  inspectShowcaseCoverage(options, program, report);
+  inspectScenarioCoverage(options, program, report);
+  // The foundation remains a fixed import-only entry, not an extra styling layer.
+  const foundationEntry = path.join(dsRoot, config.stylesEntry);
+  try {
+    const css = postcss.parse(readFileSync(foundationEntry, "utf8"), { from: foundationEntry });
+    const imports = css.nodes.filter((node) => node.type !== "comment");
+    const expected = foundationFiles.filter((name) => name !== "fonts.css" || existsSync(path.join(dsRoot, config.tokenDir, name))).map((name) => path.join(dsRoot, config.tokenDir, name));
+    const actual = imports.map((node) => {
+      if (node.type !== "atrule" || node.name !== "import" || node.nodes) return null;
+      const parts = valueParser(node.params).nodes.filter((part) => part.type !== "space" && part.type !== "comment");
+      if (parts.length !== 1) return null;
+      const part = parts[0];
+      const value = part.type === "string" ? part.value : part.type === "function" && part.value === "url" && part.nodes.length === 1 ? part.nodes[0].value : null;
+      return value ? path.resolve(path.dirname(foundationEntry), value) : null;
+    });
+    if (actual.length !== expected.length || actual.some((file, index) => file !== expected[index] || !existsSync(file))) report(foundationEntry, "styles-entry", "Foundation CSS must import only fonts (when present), colors, typography, spacing, elevation, and base, in that order.");
+  } catch (error) { report(foundationEntry, "css-syntax", error.reason ?? error.message, error.line ?? 1); }
+  function checkCss(file, text, offset = { line: 1, column: 1 }) {
+    let css;
+    try { css = postcss.parse(text, { from: file }); }
+    catch (error) { report(file, "css-syntax", error.reason ?? error.message, offset.line + (error.line ?? 1) - 1); return; }
+    if (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "components"), file) && !isInside(path.join(dsRoot, "patterns"), file) && file !== foundationEntry) report(file, "style-ownership", "Visual CSS belongs to the local ADS's runtime components or patterns.");
+    if (isDevelopmentFile(file, options) && css.nodes.some((node) => node.type !== "comment" && !(node.type === "atrule" && node.name === "import"))) report(file, "showcase-style", "Scenarios and fixtures define no styles. Put the frame/layout in a public ADS pattern and product UI in ADS components or patterns.", offset.line);
+    css.walkAtRules("import", (rule) => {
+      const first = valueParser(rule.params).nodes.find((node) => node.type !== "space" && node.type !== "comment");
+      const specifier = first?.type === "string" ? first.value : first?.type === "function" && first.value === "url" ? first.nodes[0]?.value : null;
+      if (!specifier || /^(?:[a-z]+:|\/\/)/i.test(specifier)) return;
+      const line = offset.line + rule.source.start.line - 1;
+      if (importViolation(specifier, file, options, resolveImport)) report(file, "public-import", `Import through ${config.publicAlias}, not ADS implementation paths.`, line);
+      if (showcaseImportViolation(specifier, file, options, resolveImport)) report(file, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.", line);
+    });
+    css.walkRules((rule) => {
+      if (isInside(path.join(dsRoot, "showcase"), file) && /:(?:hover|active|focus(?:-visible|-within)?|checked|disabled|enabled)\b|\[(?:aria-(?:selected|pressed|checked|disabled|expanded)|data-state)\b/.test(rule.selector)) report(file, "showcase-state", "Interactive state styling belongs to the real ADS component or pattern, not showcase or mock styles.", offset.line + rule.source.start.line - 1);
+      if (/\.ads-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "components"), file)) report(file, "style-ownership", "ADS component internals are owned by components, not app or showcase CSS.", offset.line + rule.source.start.line - 1);
+      if (/\.ux-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "patterns"), file)) report(file, "style-ownership", "Pattern internals are owned by patterns, not app or showcase CSS.", offset.line + rule.source.start.line - 1);
+      if (/\.showcase-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "showcase"), file)) report(file, "style-ownership", "Showcase internals are owned by showcase scaffolding.", offset.line + rule.source.start.line - 1);
+    });
+    css.walkDecls((decl) => {
+      const variable = checkComponentVariable(decl.prop, file, options);
+      if (variable) report(file, variable.rule, variable.message, offset.line + decl.source.start.line - 1, decl.source.start.column);
+      for (const ref of references(decl.value)) {
+        const local = /^(?:--ds-|--ux-|--showcase-)/.test(ref.name);
+        if (!local && !isSharedToken(ref.name)) report(file, "token-name", `${ref.name} does not follow ADS's fixed token naming contract.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
+        else if (!local && !declaredTokens.has(ref.name) && !ref.fallback) report(file, "token-reference", `Undefined shared token ${ref.name}.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
+      }
+      const violations = new Set();
+      valueParser(decl.value).walk((node) => {
+        if (node.type === "function" && node.value === "url") return false;
+        if (node.type === "word" && /^(?:#[\da-f]{3,8}|[-+]?(?:\d*\.)?\d+(?:px|rem|em|m?s))$/i.test(node.value)) violations.add("Use a token for colors, dimensions, and durations.");
+        if (node.type === "function" && /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix|cubic-bezier)$/.test(node.value)) violations.add("Define color formulas and easing in tokens.");
+        if (node.type === "function" && /^(?:blur|brightness|contrast|drop-shadow|grayscale|hue-rotate|invert|saturate|sepia)$/.test(node.value)) violations.add("Define visual filter effects in tokens.");
+        if (node.type === "word" && /^ease(?:-in|-out|-in-out)?$/.test(node.value)) violations.add("Use a motion token for easing.");
+        if (node.type === "word" && /^(?:color|background-color|(?:border|outline|caret|text-decoration|column-rule)(?:-[a-z]+)?-color|fill|stroke)$/.test(decl.prop) && /^[a-z]+$/i.test(node.value) && !/^(?:inherit|initial|unset|revert|currentcolor|transparent|none)$/i.test(node.value)) violations.add("Use a semantic color token.");
+      });
+      if (/^(?:font-family|font-weight|z-index)$/.test(decl.prop) && !/^(?:var\(|inherit$|auto$)/.test(decl.value)) violations.add("Use a semantic typography or layering token.");
+      for (const message of violations) report(file, "style-token", message, offset.line + decl.source.start.line - 1, decl.source.start.column);
+    });
+  }
+  for (const file of files) {
+    if (file.endsWith(".css") && isInside(path.join(dsRoot, config.tokenDir), file) && !isDevelopmentFile(file, options)) continue;
+    if (file.endsWith(".html")) { inspectHtml(readFileSync(file, "utf8"), (rule, message, line) => report(file, rule, message, line)); continue; }
+    if (file.endsWith(".css")) {
+      const text = readFileSync(file, "utf8");
+      if (file === path.join(sourceRoot, "app-mount.css") && isMountCss(text)) continue;
+      checkCss(file, text); continue;
+    }
+    const source = program.getSourceFile(file);
+    if (!source) continue;
+    for (const diagnostic of program.getSyntacticDiagnostics(source)) {
+      const position = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+      report(file, "source-syntax", ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"), position.line + 1, position.character + 1);
+    }
+    const inlineAllowed = config.inlineStyleFiles.some((allowed) => path.resolve(root, allowed) === file);
+    const showcase = isDevelopmentFile(file, options) && !isTestFile(file);
+    function nodeReport(node, rule, message) {
+      const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+      report(file, rule, message, position.line + 1, position.character + 1);
+    }
+    if (!showcase && (isInside(path.join(dsRoot, "components"), file) || isInside(path.join(dsRoot, "patterns"), file))) inspectPublicProps(source, checker, nodeReport);
+    function isLinariaTag(tag) {
+      if (ts.isCallExpression(tag)) tag = tag.expression;
+      let symbolNode = tag;
+      while (ts.isPropertyAccessExpression(symbolNode)) symbolNode = symbolNode.expression;
+      const symbol = checker.getSymbolAtLocation(symbolNode);
+      return symbol?.declarations?.some((decl) => {
+        if (ts.isImportSpecifier(decl)) {
+          const module = decl.parent.parent.parent.moduleSpecifier;
+          return ["css", "styled"].includes((decl.propertyName ?? decl.name).text) && ts.isStringLiteral(module) && module.text.startsWith("@linaria/");
+        }
+        if (ts.isNamespaceImport(decl) && ts.isPropertyAccessExpression(tag) && /^(?:css|styled)(?:\.|$)/.test(tag.getText(source).slice(symbolNode.getText(source).length + 1))) {
+          const module = decl.parent.parent.moduleSpecifier;
+          return ts.isStringLiteral(module) && module.text.startsWith("@linaria/");
+        }
+        return false;
+      });
+    }
+    function inspectProperty(value) {
+      if (ts.isPropertyAssignment(value) && (ts.isStringLiteralLike(value.name) || ts.isIdentifier(value.name))) {
+        const variable = checkComponentVariable(value.name.text, file, options);
+        if (variable) nodeReport(value.name, variable.rule, variable.message);
+      }
+      ts.forEachChild(value, inspectProperty);
+    }
+    function inspectClass(value) {
+      if (ts.isStringLiteralLike(value)) {
+        if (/(?:^|\s)ads-[\w-]+/.test(value.text) && !isInside(path.join(dsRoot, "components"), file)) nodeReport(value, "style-ownership", "Primitive ads-* classes must be emitted by components, not consumers.");
+        if (/(?:^|\s)ux-[\w-]+/.test(value.text) && !isInside(path.join(dsRoot, "patterns"), file)) nodeReport(value, "style-ownership", "Pattern ux-* classes must be emitted by patterns, not consumers.");
+        if (/(?:^|\s)showcase-[\w-]+/.test(value.text) && !isInside(path.join(dsRoot, "showcase"), file)) nodeReport(value, "style-ownership", "Showcase hooks must be emitted by the showcase, not runtime implementations.");
+      }
+      ts.forEachChild(value, inspectClass);
+    }
+    const nativePreact = (source.pragmas?.get("jsximportsource")?.arguments.factory ?? compiler.jsxImportSource) === "preact";
+    function checkSvgAttribute(node, name) {
+      if (svgPresentation.has(name)) nodeReport(node, "svg-attribute", `Native Preact SVG needs ${name.replace(/[A-Z]/g, letter => "-" + letter.toLowerCase())}; React-style ${name} is not normalized by its native renderer.`);
+    }
+    function visit(node) {
+      if (nativePreact && ts.isJsxAttribute(node) && ts.isIdentifier(node.name)) {
+        const parent = node.parent.parent;
+        if ((ts.isJsxOpeningElement(parent) || ts.isJsxSelfClosingElement(parent)) && ts.isIdentifier(parent.tagName) && svgTags.has(parent.tagName.text)) checkSvgAttribute(node, node.name.text);
+      }
+      if (ts.isCallExpression(node) && uiOperation(node.expression, checker) === "createElement") {
+        const [tag, props] = node.arguments;
+        const properties = props && ts.isObjectLiteralExpression(props) ? props.properties : [];
+        for (const property of properties) {
+          if (!ts.isPropertyAssignment(property) || !(ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name))) continue;
+          if (tag && ts.isStringLiteralLike(tag) && svgTags.has(tag.text) && importedUiApi(node.expression, checker)?.module === "preact") checkSvgAttribute(property, property.name.text);
+          if (property.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(property, "no-inline-style", "UI factories follow the same style ownership as JSX. Use semantic ADS props or a narrow renderer boundary.");
+          if (property.name.text === "style") inspectProperty(property.initializer);
+          if (property.name.text === "className") inspectClass(property.initializer);
+          if (showcase && property.name.text === "className") nodeReport(property, "showcase-class", "Scenarios use public ADS props, not custom class names.");
+        }
+        if (showcase && tag && ts.isStringLiteralLike(tag)) {
+          const role = properties.find(property => ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) && property.name.text === "role")?.initializer;
+          if (showcaseControls.has(tag.text) || role && ts.isStringLiteralLike(role) && widgetRoles.has(role.text)) nodeReport(node, "showcase-control", "Scenario controls must render public ADS components.");
+        }
+      }
+      if (isInside(dsRoot, file) && (ts.isIdentifier(node) && ["fetch", "XMLHttpRequest", "WebSocket", "EventSource"].includes(node.text) && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node))) {
+        const declarations = checker.getSymbolAtLocation(node)?.declarations ?? [];
+        if (!declarations.some((declaration) => !declaration.getSourceFile().isDeclarationFile)) nodeReport(node, "data-access", "ADS UI and scenarios receive business data through typed inputs or injected services. Direct network access belongs in an application adapter; fixture services remain local.");
+      }
+      if (isInside(dsRoot, file) && ts.isPropertyAccessExpression(node) && ["window", "globalThis", "self"].includes(node.expression.getText(source)) && ["fetch", "XMLHttpRequest", "WebSocket", "EventSource"].includes(node.name.text)) nodeReport(node, "data-access", "Inject the data service instead of using a global network API in ADS UI or scenarios.");
+      if (showcase && (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName) && /^[a-z]/.test(node.tagName.text)) {
+        const role = node.attributes.properties.find((attr) => ts.isJsxAttribute(attr) && attr.name.text === "role")?.initializer;
+        const roleValue = role && ts.isStringLiteralLike(role) ? role.text : role && ts.isJsxExpression(role) && role.expression && ts.isStringLiteralLike(role.expression) ? role.expression.text : null;
+        if (showcaseControls.has(node.tagName.text) || widgetRoles.has(roleValue)) nodeReport(node, "showcase-control", "Showcase and mock controls must use public ADS components. Implement missing reusable controls in the ADS, then import them here.");
+      }
+      if (showcase && ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className") nodeReport(node, "showcase-class", "Showcase and mocks use known public ADS entities and props, not custom class names. Put styling in the owning ADS component or frame pattern.");
+      let specifier;
+      if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
+      if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) specifier = node.arguments[0].text;
+      if (specifier && importViolation(specifier, file, options, resolveImport)) nodeReport(node, "public-import", `Import through ${config.publicAlias}, not ADS implementation paths.`);
+      if (specifier && resolveImport(specifier, file).some((target) => (specifier.startsWith(".") || existsSync(target)) && target.endsWith(".css") && isInside(root, target) && !isInside(dsRoot, target) && target !== path.join(sourceRoot, "app-mount.css") && !isInside(path.join(root, "node_modules"), target))) nodeReport(node, "style-ownership", "Imported project CSS belongs to ADS components, patterns, or the foundation. Only structural app-mount.css is allowed outside the ADS.");
+      if (specifier && appImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "no-app-import", "ADS implementations and showcase fixtures must not import app code. Use public ADS APIs with local fixture data; keep application integration harnesses in application tests.");
+      if (specifier && showcaseImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.");
+      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(node, "no-inline-style", "Move visual policy into the local ADS, or document a narrow measured-geometry exception in inlineStyleFiles.");
+      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && node.initializer) {
+        inspectProperty(node.initializer);
+      }
+      const mutation = styleWriteViolation(node, file, options);
+      if (mutation) nodeReport(node, "style-mutation", mutation);
+      if (!inlineAllowed && isUiCssProperties(node, checker)) nodeReport(node, "css-properties", "Do not expose CSSProperties-based visual plumbing. Use semantic props, or document a narrow JSX renderer boundary.");
+      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className" && node.initializer) {
+        inspectClass(node.initializer);
+      }
+      if (ts.isTaggedTemplateExpression(node) && isLinariaTag(node.tag)) {
+        const template = node.template;
+        const text = ts.isNoSubstitutionTemplateLiteral(template) ? template.text : template.head.text + template.templateSpans.map((span) => `__ds_expression__${span.literal.text}`).join("");
+        const position = source.getLineAndCharacterOfPosition(template.getStart(source) + 1);
+        checkCss(file, text, { line: position.line + 1, column: position.character + 1 });
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  }
+  return { ok: diagnostics.length === 0, diagnostics };
+}