@reqvire-org/ads 0.0.0-stage → 0.2.9

package/dist/showcase/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en" data-theme="light">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>ADS Showcase</title><link rel="stylesheet" href="/style.css"></head>
+<body>
+  <header id="header">
+    <div id="brand"><span class="mark">ADS</span><span id="title">Design System</span><button id="pane-toggle" aria-label="Hide navigation pane" aria-expanded="true" aria-controls="sidebar" title="Hide navigation pane"><svg viewBox="0 0 16 16"><path d="M10 4l-4 4 4 4"/></svg></button></div>
+    <nav id="sections" aria-label="Showcase sections">
+      <button data-section="tokens" aria-current="page"><svg viewBox="0 0 16 16"><path d="m8 2 6 3-6 3-6-3 6-3Zm-6 6 6 3 6-3M2 11l6 3 6-3"/></svg>Tokens</button>
+      <button data-section="components"><svg viewBox="0 0 16 16"><path d="m8 1 6 3.5v7L8 15l-6-3.5v-7L8 1Zm-6 3.5 6 3.5 6-3.5M8 8v7"/></svg>Components</button>
+      <button data-section="patterns"><svg viewBox="0 0 16 16"><rect x="2" y="2" width="5" height="5"/><rect x="10" y="2" width="4" height="5"/><rect x="2" y="10" width="5" height="4"/><rect x="10" y="10" width="4" height="4"/></svg>Patterns</button>
+      <button data-section="composition"><svg viewBox="0 0 16 16"><path d="M2 2h4v4H2zM10 2h4v4h-4zM2 10h4v4H2zM10 10h4v4h-4z"/></svg>Composition</button>
+    </nav>
+    <div class="actions"><button id="theme" aria-label="Use dark theme" title="Use dark theme"><svg viewBox="0 0 16 16"><path d="M13.5 9a5.5 5.5 0 0 1-6.5-6.5A5.5 5.5 0 1 0 13.5 9Z"/></svg></button><button id="minimize" aria-label="Minimize showcase menu" title="Minimize showcase menu (refresh to restore)"><svg viewBox="0 0 16 16"><path d="m4 10 4-4 4 4"/></svg></button></div>
+  </header>
+  <main><aside id="sidebar"><nav id="entries" aria-label="Tokens"></nav></aside><section id="preview" aria-label="Preview"><p id="status" role="status">Connecting to ADS MCP…</p><div id="loader" role="status" aria-label="Loading preview" hidden><span class="spinner" aria-hidden="true"></span></div><div id="frame-slot"></div></section></main>
+  <script type="module" src="/client.js"></script>
+</body></html>

package/dist/showcase/sandbox.js

@@ -0,0 +1,30 @@
+const parentOrigin = new URL(location.href).searchParams.get("parent");
+let view;
+function domains(values = []) {
+  return values.filter(value => /^(?:https?:\/\/[a-z0-9.*:[\]-]+(?::\d+)?|data:|blob:|about:)$/i.test(value)).join(" ");
+}
+function policy(csp = {}) {
+  const resources = domains(csp.resourceDomains);
+  return `default-src 'none';script-src 'unsafe-inline' ${resources};style-src 'unsafe-inline' ${resources};img-src data: ${resources};font-src ${resources || "'none'"};media-src ${resources || "'none'"};worker-src ${resources || "'none'"};connect-src ${domains(csp.connectDomains) || "'none'"};frame-src ${domains(csp.frameDomains) || "'none'"};base-uri ${domains(csp.baseUriDomains) || "'none'"};object-src 'none'`;
+}
+window.addEventListener("message", event => {
+  if (event.source === parent && event.origin === parentOrigin) {
+    const message = event.data;
+    if (message?.method === "ui/notifications/sandbox-resource-ready") {
+      const { html, csp } = message.params ?? {};
+      if (typeof html !== "string") return;
+      const document = new DOMParser().parseFromString(html, "text/html");
+      const meta = document.createElement("meta");
+      meta.httpEquiv = "Content-Security-Policy";
+      meta.content = policy(csp);
+      document.head.prepend(meta);
+      view?.remove();
+      view = window.document.createElement("iframe");
+      view.title = "Design-system App";
+      view.setAttribute("sandbox", "allow-scripts");
+      window.document.body.append(view);
+      view.srcdoc = "<!doctype html>" + document.documentElement.outerHTML;
+    } else if (message?.jsonrpc === "2.0" && !message.method?.startsWith("ui/notifications/sandbox-")) view?.contentWindow.postMessage(message, "*");
+  } else if (event.source === view?.contentWindow && event.data?.jsonrpc === "2.0" && !event.data.method?.startsWith("ui/notifications/sandbox-")) parent.postMessage(event.data, parentOrigin);
+});
+parent.postMessage({ jsonrpc: "2.0", method: "ui/notifications/sandbox-proxy-ready", params: {} }, parentOrigin);

package/dist/showcase/style.css

@@ -0,0 +1,7 @@
+:root{font:13px/1.5 system-ui,sans-serif;color-scheme:light;background:#fafafa;color:#444;--frame-bg:#fafafa;--frame-ink:#444;--frame-line:#ddd;--pane-width:min(276px,42vw)}
+:root[data-theme="dark"]{color-scheme:dark;--frame-bg:#181818;--frame-ink:#ddd;--frame-line:#444;background:var(--frame-bg);color:var(--frame-ink)}
+*{box-sizing:border-box}body{margin:0;height:100vh;display:flex;flex-direction:column;overflow:hidden}button,a{font:inherit;color:inherit}button{cursor:pointer;background:transparent;border:1px solid var(--frame-line);border-radius:4px}button:focus-visible,a:focus-visible{outline:2px solid var(--frame-ink);outline-offset:2px}svg{width:14px;height:14px;fill:none;stroke:currentColor;stroke-width:1.5;stroke-linecap:round;stroke-linejoin:round;flex:none}svg:not([aria-label]){pointer-events:none}
+header{height:52px;display:flex;flex:none;border-bottom:1px solid var(--frame-line);align-items:stretch;background:var(--frame-bg)}#brand{width:var(--pane-width);display:flex;flex:none;gap:8px;align-items:center;padding:0 12px;border-right:1px solid var(--frame-line);font-weight:600;white-space:nowrap}#brand .mark{font-weight:700}#title{min-width:0;overflow:hidden;text-overflow:ellipsis}#pane-toggle{width:28px;height:28px;margin-inline-start:auto;display:grid;place-items:center;flex:none}.collapsed #brand{width:44px;padding:0 8px;border-right:0}.collapsed #brand .mark,.collapsed #title{display:none}
+#sections{display:flex;gap:4px;align-items:center;min-width:0;overflow-x:auto;padding:8px}#sections button{display:flex;align-items:center;gap:8px;flex:none;border-color:transparent;padding:6px 10px}#sections button[aria-current="page"]{border-color:var(--frame-line)}#sections svg{opacity:.7}.actions{display:flex;align-items:center;gap:4px;margin-inline-start:auto;padding:8px;flex:none}.actions button{width:28px;height:28px;display:grid;place-items:center}
+main{flex:1;min-height:0;display:flex}#sidebar{width:var(--pane-width);flex:none;border-right:1px solid var(--frame-line);overflow-y:auto;background:var(--frame-bg)}#entries{display:flex;flex-direction:column;gap:4px;padding:8px}#entries a{flex:none;padding:8px;border:1px solid transparent;border-radius:4px;text-decoration:none;overflow-wrap:anywhere}#entries a:hover,#entries a[aria-current="page"]{border-color:var(--frame-line)}#entries a[aria-current="page"]{font-weight:600}
+#preview{position:relative;flex:1;min-width:0;min-height:0;display:flex;flex-direction:column;overflow:hidden}#frame-slot{flex:1;min-height:0;min-width:0}iframe{display:block;width:100%;height:100%;border:0}#status{position:absolute;z-index:1;inset:12px 12px auto;margin:0;padding:12px 16px;border:1px solid var(--frame-line);border-radius:4px;background:var(--frame-bg);white-space:pre-wrap;overflow-wrap:anywhere;max-height:30vh;overflow:auto}#status[data-error="true"]{color:CanvasText;background:Canvas;border-color:GrayText}#loader{position:absolute;inset:0;z-index:2;display:grid;place-items:center;background:var(--frame-bg)}.spinner{width:24px;height:24px;border:2px solid var(--frame-line);border-top-color:var(--frame-ink);border-radius:50%;animation:spin .8s linear infinite}@keyframes spin{to{transform:rotate(360deg)}}@media(prefers-reduced-motion:reduce){.spinner{animation:none}}[hidden],.collapsed #sidebar{display:none!important}@media(max-width:760px){#title{display:none}}

package/dist/showcase-coverage.mjs

@@ -0,0 +1,118 @@
+import path from "node:path";
+import ts from "typescript";
+import { uiOperation } from "./ui-framework.mjs";
+import { isInside, isTestFile, isDevelopmentFile } from "./config.mjs";
+
+// Compare statically rendered public UI, not imports or every value in a barrel.
+// Symbol identity keeps aliases, same-file exports, and shadowed names distinct.
+export function inspectShowcaseCoverage(options, program, report) {
+  const { dsRoot, sourceRoot, config } = options;
+  const checker = program.getTypeChecker();
+  const entry = program.getSourceFile(path.join(dsRoot, config.publicEntry));
+  const module = entry && checker.getSymbolAtLocation(entry);
+  if (!module) return;
+  const showcase = path.join(dsRoot, "showcase");
+  const implementations = [path.join(dsRoot, "components"), path.join(dsRoot, "patterns")];
+
+  function symbolOf(expression) {
+    while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isNonNullExpression(expression))) expression = expression.expression;
+    if (!expression) return null;
+    if (ts.isElementAccessExpression(expression) && expression.argumentExpression && ts.isStringLiteralLike(expression.argumentExpression)) {
+      return checker.getPropertyOfType(checker.getTypeAtLocation(expression.expression), expression.argumentExpression.text);
+    }
+    return checker.getSymbolAtLocation(expression);
+  }
+  function canonical(symbol, seen = new Set()) {
+    if (!symbol || seen.has(symbol)) return null;
+    seen.add(symbol);
+    if (symbol.flags & ts.SymbolFlags.Alias) return canonical(checker.getAliasedSymbol(symbol), seen);
+    for (const declaration of symbol.declarations ?? []) {
+      if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+        const target = symbolOf(declaration.initializer);
+        if (target) return canonical(target, seen);
+      }
+      if (ts.isBindingElement(declaration) && ts.isObjectBindingPattern(declaration.parent) && ts.isVariableDeclaration(declaration.parent.parent)) {
+        const initializer = declaration.parent.parent.initializer;
+        const key = declaration.propertyName ?? declaration.name;
+        if (initializer && (ts.isIdentifier(key) || ts.isStringLiteralLike(key))) {
+          const target = checker.getPropertyOfType(checker.getTypeAtLocation(initializer), key.text);
+          if (target) return canonical(target, seen);
+        }
+      }
+    }
+    return symbol.declarations?.length ? symbol : null;
+  }
+  // The declaration also unifies a named default export with its local name.
+  function identity(symbol) { return symbol?.valueDeclaration ?? symbol?.declarations?.[0]; }
+  const publicUi = new Map();
+  for (const exported of checker.getExportsOfModule(module)) {
+    const symbol = canonical(exported);
+    const declaration = identity(symbol);
+    if (!declaration || !(symbol.flags & ts.SymbolFlags.Value)) continue;
+    if (!implementations.some((directory) => isInside(directory, declaration.getSourceFile().fileName))) continue;
+    const item = publicUi.get(declaration) ?? { symbol, names: [] };
+    item.names.push(exported.name);
+    publicUi.set(declaration, item);
+  }
+  if (!publicUi.size) return;
+
+
+  function uses(node, consume, helpers = false) {
+    function visit(child) {
+      if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child)) {
+        if (!(ts.isIdentifier(child.tagName) && /^[a-z]/.test(child.tagName.text))) consume(canonical(symbolOf(child.tagName)), child, true);
+      }
+      if (ts.isCallExpression(child)) {
+        const operation = uiOperation(child.expression, checker);
+        if (operation === "createElement" || helpers && ["memo", "forwardRef"].includes(operation)) consume(canonical(symbolOf(child.arguments[0])), child, true);
+        // A shared render helper can contain the actual component JSX.
+        if (helpers && !operation) consume(canonical(symbolOf(child.expression)), child, false);
+      }
+      ts.forEachChild(child, visit);
+    }
+    visit(node);
+  }
+  const dependencies = new Map();
+  function children(symbol) {
+    const key = identity(symbol);
+    if (dependencies.has(key)) return dependencies.get(key);
+    const result = new Map();
+    dependencies.set(key, result);
+    for (const declaration of symbol.declarations ?? []) {
+      const file = declaration.getSourceFile().fileName;
+      if (isTestFile(file) || ![sourceRoot, showcase, ...implementations].some((directory) => isInside(directory, file))) continue;
+      uses(declaration, (child, _node, ui) => { if (child) result.set(child, ui || result.get(child) || false); }, true);
+    }
+    return result;
+  }
+  function rendered(symbol, consume, seen = new Map(), ui = true) {
+    const key = identity(symbol);
+    if (!key || seen.has(key) && (!ui || seen.get(key))) return;
+    seen.set(key, ui || seen.get(key) || false);
+    if (ui && publicUi.has(key)) consume(key);
+    for (const [child, childUi] of children(symbol)) rendered(child, consume, seen, childUi);
+  }
+
+  const production = new Map();
+  const demonstrated = new Set();
+  for (const source of program.getSourceFiles()) {
+    const file = source.fileName;
+    if (isTestFile(file)) continue;
+    const example = isDevelopmentFile(file, options);
+    const application = isInside(sourceRoot, file) && !isInside(dsRoot, file);
+    if (!example && !application) continue;
+    uses(source, (symbol, node) => rendered(symbol, (key) => {
+      if (example) demonstrated.add(key);
+      else {
+        const direct = identity(symbol) === key;
+        if (!production.has(key) || direct && !production.get(key).direct) production.set(key, { node, direct });
+      }
+    }));
+  }
+  for (const [key, { node }] of production) {
+    if (demonstrated.has(key)) continue;
+    const source = node.getSourceFile();
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    report(source.fileName, "showcase-coverage", `Public ADS UI ${publicUi.get(key).names.join(" / ")} is rendered by application source but has no showcase render reference. Add an example using the public API; an import alone or a test harness does not count.`, position.line + 1, position.character + 1);
+  }
+}

package/dist/showcase.mjs

@@ -0,0 +1,77 @@
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { isInside, isTestFile } from "./config.mjs";
+
+export const showcasePages = ["TokensPage", "ComponentsPage", "PatternsPage", "CompositionPage"];
+
+export function inspectShowcasePages({ dsRoot, config }, program, resolve, report) {
+  const pages = path.join(dsRoot, "showcase/pages");
+  if (!existsSync(pages)) return; // A project with no showcase yet still checks.
+  const entries = readdirSync(pages, { withFileTypes: true }).filter((entry) => entry.isFile() && /\.[cm]?[jt]sx?$/.test(entry.name) && !isTestFile(entry.name));
+  if (!entries.length) return; // The built-in MCP client needs no project browser pages.
+  for (const entry of entries) {
+    if (!showcasePages.includes(entry.name.replace(/\.[^.]+$/, ""))) report(path.join(pages, entry.name), "showcase-pages", "Showcase pages are TokensPage, ComponentsPage, PatternsPage, and CompositionPage. Put scenarios beside their owners or under composition/.");
+  }
+  for (const name of showcasePages) {
+    if (!entries.some((entry) => entry.name.replace(/\.[^.]+$/, "") === name)) report(pages, "showcase-pages", `Missing ${name}: use the standard Tokens, Components, Patterns, and Composition showcase pages.`);
+  }
+  const cache = new Map();
+  function exports(file, chain = new Set()) {
+    if (cache.has(file)) return cache.get(file);
+    if (chain.has(file)) return new Map();
+    chain = new Set([...chain, file]);
+    const result = new Map();
+    const source = program.getSourceFile(file);
+    if (!source) return result;
+    for (const node of source.statements) {
+      if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+        const target = resolve(node.moduleSpecifier.text, file)[0];
+        const nested = exports(target, chain);
+        if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+          for (const item of node.exportClause.elements) result.set(item.name.text, nested.get((item.propertyName ?? item.name).text) ?? target);
+        } else if (!node.exportClause) for (const [name, owner] of nested) result.set(name, owner);
+      } else if (node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+        if (node.name && ts.isIdentifier(node.name)) result.set(node.name.text, file);
+        if (ts.isVariableStatement(node)) for (const decl of node.declarationList.declarations) if (ts.isIdentifier(decl.name)) result.set(decl.name.text, file);
+      }
+    }
+    cache.set(file, result);
+    return result;
+  }
+  const publicExports = exports(path.join(dsRoot, config.publicEntry));
+  const visited = new Set();
+  function catalogue(file) {
+    if (visited.has(file)) return;
+    visited.add(file);
+    const source = program.getSourceFile(file);
+    if (!source) return;
+    function visit(node) {
+      let specifier;
+      if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
+      const dynamic = ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword;
+      if (dynamic && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) specifier = node.arguments[0].text;
+      if (specifier === config.publicAlias && !node.importClause?.isTypeOnly && !node.isTypeOnly) {
+        const bindings = node.importClause?.namedBindings ?? node.exportClause;
+        // Named imports/re-exports keep the catalogue's dependency ownership explicit.
+        // Namespace/dynamic imports can select arbitrary exports, so check their whole surface.
+        const named = bindings && (ts.isNamedImports(bindings) || ts.isNamedExports(bindings));
+        const imported = named ? bindings.elements.filter((item) => !item.isTypeOnly).map((item) => (item.propertyName ?? item.name).text)
+          : dynamic || bindings || ts.isExportDeclaration(node) ? [...publicExports.keys()]
+          : node.importClause?.name ? ["default"] : [];
+        for (const name of imported) {
+          const owner = publicExports.get(name);
+          if (owner && isInside(path.join(dsRoot, "patterns"), owner) && !isInside(path.join(dsRoot, "patterns/showcase"), owner)) {
+            const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+            report(file, "showcase-catalogue", `${name} is a pattern. Demonstrate it in PatternsPage or CompositionPage; TokensPage and ComponentsPage use primitives and the shared showcase frame.`, position.line + 1, position.character + 1);
+          }
+        }
+      } else if (specifier) {
+        for (const target of resolve(specifier, file)) if (isInside(path.join(dsRoot, "showcase"), target)) catalogue(target);
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  }
+  for (const entry of entries) if (/^(?:TokensPage|ComponentsPage)\./.test(entry.name)) catalogue(path.join(pages, entry.name));
+}

package/dist/skills/README.md

@@ -0,0 +1,68 @@
+# ADS skills
+
+Install the skills you need with `npx skills`:
+
+```sh
+npx skills add reqvire-org/design-system --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+```
+
+For local development, install from this checkout:
+
+```sh
+npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+```
+
+Each skill includes its own instructions and references. `ads-designer` also
+includes an empty bootstrap scaffold, so starting from zero needs no example
+repository. Skills operate on a project's local ADS; they do not install a UI
+catalogue or replace the project's theme values.
+
+The [stdio MCP server](../docs/MCP.md#skills) also serves these skills and supporting
+files from the npm distribution. Native Skills discovery is available on the
+newer protocol; ordinary tools/resources provide explicit access on older
+clients. MCP serving does not install or automatically activate a skill.
+
+For inspection, start with `ads_status`, search the public API with `ads_catalog`,
+read its source/available guides and relevant tokens, then discover an entry with
+`ads_scenarios` and render it with `ads_show_scenario`. Check build freshness after
+edits. The [MCP inspection guide](../docs/MCP.md#inspect-the-design-system) explains
+the sequence, resource-only fallback and limits of metadata versus rendered review.
+
+Each workflow updates relevant showcase examples, runs build guards, inspects
+the browser, and provides a running URL or exact command for review. See the
+[architecture](../docs/ARCHITECTURE.md) for the rationale and tooling requirements.
+
+| Skill | Use | Example |
+|-------|-----|---------|
+| [ads-designer](ads-designer/SKILL.md) | Bootstrap or build UI using the local ADS, with craft/mobile guidance | `$ads-designer build a settings page using this project's ADS` |
+| [ads-import](ads-import/SKILL.md) | Import selected external ADS source, brand artwork, or compatible source token values | `$ads-import /path/to/source-repo component Toast` |
+| [ads-assimilate](ads-assimilate/SKILL.md) | Study an external component library and implement a native counterpart | `$ads-assimilate https://github.com/emilkowalski/sonner` |
+| [ads-break-ui](ads-break-ui/SKILL.md) | Stress-test real components/patterns; optionally fix demonstrated failures | `$ads-break-ui AppShell +fix` |
+| [ads-motion](ads-motion/SKILL.md) | Implement, review, audit, or profile motion | `$ads-motion review Toast` |
+
+For token values, use `$ads-import /path/to/source-repo tokens`; for original
+artwork and its guidance, use `$ads-import /path/to/source-repo brand`. ADS token
+names and ownership prefixes are fixed; imports conform to that architecture.
+For motion, the
+request selects the mode, for example `build`, `audit`, or `performance`.
+Review/audit requests report findings; a fix request authorizes implementation.
+The import workflow is a skill, not a CLI `ads import` command.
+
+`ads-break-ui`, `ads-motion`, and the craft/mobile references in `ads-designer`
+adapt [Emil Kowalski's MIT-licensed skills](https://github.com/emilkowalski/skills).
+Their local READMEs record pinned source revisions and specific influences;
+each folder retains the upstream MIT notice. Preserve those notices when
+redistributing the skills. Component-library notices belong beside the imported component in its receiving
+project, separate from these skill notices.
+
+The showcase is a tool-owned minimal shell plus an MCP client and Apps host.
+Its four sections discover token categories and scenario entries through MCP.
+The skills use the connected runtime URL, or `ads showcase` for browser-only work;
+they do not generate page browsers or duplicate the tool shell. Scenarios,
+fixtures and adapters remain colocated with their owners; larger entries live in
+`composition/`. One managed project compiler supplies both human and agent views.
+
+Project/component rules are registered in `ds.config.json`. Scoped Oxlint settings
+do not disable independent architecture checks. Each skill contains the workflow
+needed when installed on its own; the designer includes the empty foundation and
+a React/Vite preview compiler adapter, without any component catalogue.

package/dist/skills/ads-assimilate/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: ads-assimilate
+description: "Implement or refine a native design-system component from a component-library URL, studying the original implementation and verifying behavior, visuals, and motion against the real reference. Use for component assimilation, including local documentation and justified usage lint rules; not for simply installing or wrapping a dependency."
+---
+
+# ADS Assimilate
+
+When ADS MCP is connected, discover public UI and addressable scenarios with
+`ads_status`/`ads_catalog`; use `ads_tokens` for definitions and values, and
+`ads_scenarios`/`ads_show_scenario` for real project scenarios. Keep the external
+library as the behavioral reference.
+If Apps are unavailable, inspect the normal showcase. Resolve MCP-served skill
+references relative to this `SKILL.md` URI and load them lazily; a resource read
+does not itself activate the skill.
+Use the returned `projectRoot` and `project.commands`; the connected ADS may be
+inside a different or nested repository. Inspect the selected public API, owning
+source/available guides and relevant tokens, then mount its discovered scenario.
+Metadata and source reads do not prove rendered behavior.
+
+When `ads_status.mutations.enabled`, discover the owner with `ads_units`, read
+relevant ranges with `ads_read_file` and send only a Git unified diff through
+`ads_apply_patch({ unit, patch, dryRun })`. A unit includes its own implementation,
+scenarios and fixtures; imported peers remain separate. `tokens` is the token
+foundation unit. Unit discovery and file ownership are distinct from preview IDs.
+Include only that owner's required re-exports in the public entry. Use
+`dryRun: true` to inspect validation; applying re-runs the gates. Fix rejected
+patches in their owner. Shared styles/helpers use `foundation`, root guides use
+`documentation`, and branding/fonts use their discovered `assets/*` unit.
+Intentional configuration, rule exceptions, registered guard code and compiler
+changes use `configuration`; validate the proposed settings and keep mandatory
+ADS gates. For binary/large assets, generate `git diff --binary --full-index` into
+`.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
+stay out of model context. Binary changes require Git. When editing is disabled,
+use the client's normal source-editing tools.
+
+Before trusting a preview after edits, check `ads_status.build` or
+`ads://project/build`. Fix build diagnostics in owned source; an older view or
+unreported freshness is not evidence of current code. Notifications may not
+reach the agent.
+
+Turn a supplied component-library reference into a native component in the current
+design-system repository. Preserve the requested interaction contract while
+using the target system's primitives, tokens, styling architecture, and public API.
+Aim for a close adaptation: the reference's function, layout, interaction details,
+and animation style should remain recognizable. Change what native integration
+requires; broader redesign belongs to an explicit user request.
+
+React and native Preact are supported. Preserve the target runtime in both
+production and scenario builds; never alias React to Preact just to shrink a
+preview. Native Preact uses its own JSX transform, hooks and DOM events (live
+text updates use `onInput`). Native SVG uses DOM names such as `stroke-width`,
+not React presentation aliases. Keep Linaria extraction and the same public APIs.
+The shipped empty starter uses React; the tool repository's working example
+uses Preact. Neither is a component dependency of the receiving project.
+
+ADS is tooling only. Implement in the target project's
+local ADS folder: the project owns the component source and theme values, and
+the app imports its local public barrel (normally `@ds`). Shared tooling supplies
+contracts, rules, skills, and empty scaffolding. Component libraries, patterns,
+themes and scenarios are external sources, loaded through explicit ADS
+workflows. Do not look for a built-in or optional UI catalogue in the tool.
+
+## Input
+
+Invocation accepts a library/repository/documentation URL as its first argument:
+
+```text
+$ads-assimilate <library-url> [component-name] [requirements]
+$ads-assimilate https://github.com/emilkowalski/sonner toast
+```
+
+The URL is the required reference, not a request to install the library into the
+product. Use the current repository as the target unless the user names another.
+Infer the component from the request or a single-component library. If the URL
+is missing, ask for it. If a multi-component library leaves the component
+ambiguous, inspect its catalogue and clarify the target while doing independent
+repository research. Optional requirements can specify API compatibility,
+appearance, behavior, migrations, and a playground.
+
+Read [references/cli.md](references/cli.md) and invoke supported ADS CLI commands
+through `npx` using the actual published version or a local tarball. Use the CLI
+for setup and checks while this skill owns reference research and implementation.
+
+## Establish the contract
+
+Read repository instructions, the main README, architecture/token documentation
+such as `docs/ARCHITECTURE.md` and `docs/ADS.md` when present (or existing project guides), relevant component guides,
+public exports, and lint/build scripts.
+Reuse the target's structure; do not redesign the system to accommodate the reference.
+ADS requires Linaria for component and pattern styling. Adapt reference styles to
+colocated `@linaria/atomic` blocks and verify extraction in application and
+preview builds. Preserve the target framework; `ads init` does not configure
+Linaria for it.
+
+Open the supplied URL and the relevant primary source, official usage docs, CSS,
+animation code, tests, and license. Record the version or commit inspected.
+Published-package behavior can differ from repository HEAD: use one identified
+runtime reference for the comparison and call out source-version differences.
+
+Establish what should match: supported states, lifecycle, keyboard/pointer
+behavior, focus, timing, layout/stacking, motion, and responsive behavior. Treat
+token/brand adaptation and API reshaping as explicit design decisions. When the
+user requests matching UX, reproduce the observed behavior, including quirks.
+Do not silently improve timers, focus restoration, cleanup, gestures, or placement.
+Propose any necessary deviation with its concrete effect and obtain a direction
+when existing instructions do not resolve the tradeoff.
+
+## Implement and integrate
+
+Use [native-implementation.md](references/native-implementation.md) for research
+and implementation mechanics. Keep state, geometry, and visual policy in their
+owning layers. Export the native API through the public barrel, add real showcase
+examples, and migrate authorized consumers without changing unrelated surfaces.
+
+Write the component-local README with usage, API, behavior, motion, token hooks,
+validation, and any agreed differences. Include a References and credits section:
+link the original library, studied source/docs/articles, identify the reference
+version or commit, credit its authors, and say which features influenced the
+native implementation. Keep shared project architecture in its ADS guide; the
+receiving project's main README also credits inspiration and links to the local
+guide. Do not add the imported component's catalogue or API to core tooling docs.
+
+Read [lint-and-docs.md](references/lint-and-docs.md) when documenting the component
+or evaluating usage rules. Add local rules only for concrete misuse that static
+analysis can establish. Colocate rule ownership with the component and register
+it through shared tooling; avoid duplicating existing TypeScript or lint checks.
+
+## Verify against the original
+
+Use the project showcase as the permanent native demonstration and shared
+review surface for agents and humans. Discover its existing run/build commands;
+use the built-in MCP client and configure project preview compilation. Examples and
+composition scenarios import the real public ADS API and the same token/foundation styles
+as the application. Put reusable UI discovered while building a mock in ADS
+components/patterns first. Colocate sample data and state/callback adapters with
+the scenario; larger entries belong under `composition/`. Browsing pages only
+select these entries. The scenario labels, controls and review layouts are public ADS entities with defined
+APIs. The outer shell belongs to the tool client. Showcase/scenario files define no CSS, custom classes, or widget markup.
+Change the owning ADS pattern when a frame layout is missing; do not recreate
+the assimilated UI there or override its internals.
+
+The showcase is a minimal shell plus an MCP client and Apps host, supplied by ADS
+tooling. It discovers Tokens/Components/Patterns/Composition entries through MCP
+tools and renders their scenarios in the preview App. Navigation, theme and
+pane/header visibility belong to the tool client. Do not create page files,
+copy its shell into the project or assemble a second catalogue/rendering pipeline.
+
+When MCP is connected, open the running URL from `ads_status`. Otherwise run the
+installed `ads showcase` or the project's `dev:showcase` script. Do not launch a
+second runtime/compiler for the same connected project. A configured project
+preview watcher publishes a shared graph on first demand and after source
+changes. The built-in client refreshes discovery and the active scenario in the
+same App after a successful build. Shared runtime, foundation CSS, fonts and
+selected scenario modules load through MCP
+resources inside the sandboxed App. Never inject project styles/runtime into
+the outer host. Keep the configured framework, compiler and mount/unmount adapter
+consistent; scenario teardown must release owned timers, portals and workers.
+The host shows errors and marks retained output as stale. Other hosts may need an
+explicit preview-tool invocation. Compilation remains project-owned and required
+for TSX/Linaria; it is automatic, not eliminated.
+
+Reusable review layouts belong in public project ADS patterns, while scenario
+files define no CSS, custom classes or widget replicas. Keep real presentation in
+its component/pattern owner. The tooling shell's CSS is outside that project
+contract. Legacy custom showcase pages may be retained during migration; new
+projects require no TokensPage/ComponentsPage/PatternsPage/CompositionPage files.
+
+Colocate `Scenario.tsx` and `fixture.ts` with tokens and each component/pattern; flat owners
+may use `<Owner>.scenario.tsx` and `<Owner>.fixture.ts`. Put larger entries under
+`composition/<Name>/Scenario.tsx` with their own `fixture.ts`. Export a default
+zero-input mountable view and literal metadata, for example
+`export const scenario = { title: "Button states", covers: ["Button"] };`.
+Import the real UI from the public ADS alias. Keep fixture inputs, simulated
+services and initial state/callback adapters beside the scenario. Empty fixtures
+are valid for an entry with no inputs. Extra development helpers use a
+`scenario/` or `fixtures/` subfolder, or `<Owner>.scenario-adapter.ts`, so guards
+recognize their role even beside runtime code. Never require a page, router or store to
+initialize the entry. Several contextual public parts may share one scenario.
+
+IDs derive from ADS-relative filenames: both `components/core/Button/Scenario.tsx`
+and `components/core/Button.scenario.tsx` identify `components/core/Button`.
+Use one form, no duplicate IDs or hand-maintained registry. Renames change IDs.
+The showcase and external hosts mount the same discovered entry. The Vite
+adapter uses `previewEntriesPlugin` and `createPreviewResources` with
+`runScenarioCompiler` to publish the shared graph. Its framework mount adapter
+returns cleanup; the project owns rendering and Linaria extraction. The older
+`scenarioRegistryPlugin` is only for retained legacy browsers. MCP discovers
+metadata without importing executable TSX. Existing apps need an explicitly
+integrated compiler; init alone adds no compiler or extraction setup.
+Use `ads_scenarios` (query/kind/limit) and `ads_show_scenario({id})` to open an exact
+entry. Check its build freshness; HTML delivery is not browser verification.
+If Apps or resource forwarding are unavailable, open that scenario in the real
+showcase, using the tool result's URL. Do not build a preview-only replica.
+
+For a production screen, find and render the application's public screen pattern.
+Its owner supplies structure, controls, layout and presentation. Scenario fixtures
+supply data/state/callbacks. Move shared presentation into a pattern if needed,
+preserving existing behavior and lazy imports, workers, caching and cancellation.
+Do not reassemble an alternative screen or substitute placeholder content.
+Screen reuse remains skill guidance, not a dedicated screen-parity lint.
+
+Resolve `scenario-contract`, `scenario-render` and `scenario-coverage` findings
+with meaningful entries. Every public renderable component and pattern needs an
+addressable scenario, including unused exports; types/constants/utilities do not.
+Only public render references reachable from the default entry count. Tests and
+unused imports/functions do not. Static reachability does not prove successful
+mounting, correct content, every branch/state or visual parity: open each affected
+entry independently and verify real behavior at narrow/wide sizes in both themes.
+The older `showcase-coverage` policy separately checks application references.
+
+Token previews use that same scenario pipeline. Colocate a token scenario and
+fixture under the configured token directory. Use static metadata
+`{ title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens }` with
+literal const fixture fields; names/sample text are fixture data, values come
+from the real foundation CSS. Reuse a public project review pattern for styled
+samples. The minimal starter's foundation value scenario can have `covers: []`.
+Every declared token needs reachable scenario coverage; adding/removing a token
+requires fixture updates. Fix `token-scenario-reference`, `token-scenario-render`
+and `token-scenario-coverage` findings. Metadata and unused fixture fields do not
+count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
+with `ads_show_scenario({id})` or `ads_show_tokens({category:id})`. With the shared
+resource compiler, omitting category opens the first project token scenario.
+Legacy compilers retain the generic definition inspector. Use `ads_tokens` for
+source definitions and values; inspecting definitions does not prove UI parity.
+The tool keeps the shared naming contract; sample templates and their token
+lists belong to the project.
+
+Scenarios, colocated fixtures and helpers are development-only. Never export them
+from the runtime barrel or import them in production, including through aliases,
+re-exports or dynamic imports. They may not import application stores, routers,
+providers or HTTP clients. Live business data is application-owned; UI uses typed
+inputs or injected services/callbacks. Direct global fetch/XHR/WebSocket/EventSource
+is rejected; custom clients and computed access require review/project guards.
+Use local simulated services in fixtures. Tests may import fixtures; load real
+foundation CSS rather than assigning shared token values in JavaScript. Keep
+full-app integration harnesses and workflow coverage in application test support.
+
+
+
+Register component/project Oxlint plugins and rules in `ds.config.json`. Use
+scoped `oxlint.overrides` for justified file-specific settings; never edit
+`.ds/oxlintrc.json`. These overrides configure Oxlint, not the independent
+architecture checks in `ads check`. Measured renderer properties and documented
+non-state hooks use explicit `boundaries`; shared token writes and primitive
+state overrides cannot be allowlisted. Add generic architectural protections to
+ADS core and keep domain/component-specific rules registered in project setup.
+
+Update meaningful variants, states, content, themes, and container sizes in the
+showcase. Run ADS/project guards before its build as well as the app build.
+Fix appearance and motion in the shared implementation so both consumers change
+together. Temporary upstream comparison pages are separate from the permanent
+native showcase and use the actual upstream runtime.
+
+Use [testing.md](references/testing.md) to select meaningful tests and compare the
+native component with the **actual original component**, not another native demo.
+Use matching content, configuration, theme intent, viewport, and input modality.
+Measure state changes, computed geometry, timing, and animation frames, then
+inspect screenshots. A screenshot alone does not establish behavior or motion parity.
+
+Keep browser automation in isolated pages/contexts. Rebuild static playgrounds
+after source changes. Test the public consumer path as well as component internals;
+check root mounting and routing where the component has shared lifecycle.
+
+Preserve the target's performance strategy when changing ownership: lazy imports,
+worker execution, caches, memoization, cancellation, and stale-result rejection.
+Public exports must not eagerly load heavy renderers for unrelated consumers.
+Compare relevant bundle loading and existing performance/lifecycle tests before
+and after a migration. Shared screen patterns can accept injected services;
+architectural reuse does not require moving application services into the ADS.
+
+Run the target's required lint, type checking, build, and relevant component/rule
+tests. Inspect the target's actual scripts; an imported component or upstream
+example may have its own test entry. Do not assume `test:toast` or a showcase
+build exists in every project. Repeat only affected checks after new changes.
+
+Follow [references/cli.md](references/cli.md) to integrate the tool as a
+development dependency in the target's actual lint/build pipeline.
+Register applicable local rules through its project-owned plugin adapter and
+`ds.config.json`, then run the normal project build. Its lint step refreshes
+configuration and runs ADS/core/project rules automatically. Use npx for bootstrap
+or ad hoc checks. Core checks complement component/rule tests and the browser
+comparison; they do not establish runtime or motion parity.
+
+## Deliver
+
+Report what was implemented, verified matches, remaining agreed differences,
+test evidence, and any concrete limits of the comparison. Link the component
+guide and give full local URLs for running playgrounds, clearly identifying
+which page is native and which uses the original. State the reference version.
+Do not claim complete parity for untested states, or call a native replica a real
+upstream reference. Keep comparison dependencies and downloaded source outside
+the production dependency graph unless the user chose otherwise.

package/dist/skills/ads-assimilate/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ADS Assimilate"
+  short_description: "Adapt reference components into a native design system"
+  default_prompt: "Use $ads-assimilate with a component-library URL to implement and verify a native design-system component."