open-ds 0.0.0-stage → 0.1.0

package/src/docs.mjs

@@ -0,0 +1,570 @@
+// Writes the documentation of a delivered design system: one scheme, as Markdown pages for
+// Docusaurus. The docs site (docs/) and `open-ds init --docs` both use this, so a team that takes
+// a scheme gets the same pages Open DS builds.
+
+import { cssName, semanticView, themeTokens } from "./tokens.mjs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { questions } from "./schemes.mjs";
+
+// Which component keys each shipped component reads.
+const KEY_GROUP = {
+  button: "button",
+  input: "input",
+  select: "input",
+  label: "input",
+  checkbox: "control",
+  switch: "control",
+  badge: "badge",
+  card: "card",
+  table: "table",
+  tabs: "tabs",
+  dialog: "overlay",
+  "dropdown-menu": "overlay",
+  toast: "overlay",
+  tooltip: "overlay",
+};
+
+const fm = (o) =>
+  `---\n${Object.entries(o)
+    .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+    .join("\n")}\n---\n\n`;
+const NOTE =
+  "<!-- Generated by open-ds from the scheme. Do not edit by hand. -->\n\n";
+const esc = (s) =>
+  String(s)
+    .replaceAll("|", "\\|")
+    .replaceAll("\n", " ")
+    .replaceAll("<", "&lt;")
+    .replaceAll("{", "&#123;")
+    .replaceAll("}", "&#125;");
+const title = (id) =>
+  id.charAt(0).toUpperCase() + id.slice(1).replaceAll("-", " ");
+const get = (tree, path) =>
+  path
+    .split(".")
+    .reduce((n, p) => (n && typeof n === "object" ? n[p] : undefined), tree);
+const isToken = (v) => v && typeof v === "object" && "$value" in v;
+
+function merge(a, b) {
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b ?? {}))
+    out[k] =
+      v && typeof v === "object" && !isToken(v) && out[k]
+        ? merge(out[k], v)
+        : v;
+  return out;
+}
+
+function leaves(node, path) {
+  if (isToken(node))
+    return [
+      {
+        path,
+        ref: node.$value,
+        type: node.$type,
+        description: node.$description,
+      },
+    ];
+  if (!node || typeof node !== "object") return [];
+  return Object.entries(node)
+    .filter(([k]) => !k.startsWith("$"))
+    .flatMap(([k, v]) => leaves(v, `${path}.${k}`));
+}
+
+/** The tokens a scope owns in this scheme: semantics, brand primitives, component keys or words. */
+function owned(scheme, owns) {
+  const t = scheme.tokens;
+  const theme = Object.values(t.brands)[0].theme;
+  const sources = [
+    semanticView(scheme, "light"),
+    { theme: merge(theme.base ?? {}, theme.light) },
+    { component: t.component },
+    { content: t.content },
+  ];
+  return owns.flatMap((o) => {
+    const tree = sources.find((x) => get(x, o) !== undefined);
+    return tree ? leaves(get(tree, o), o) : [];
+  });
+}
+
+const show = (v) =>
+  v === undefined
+    ? ""
+    : typeof v === "string"
+      ? v
+      : Array.isArray(v)
+        ? `cubic-bezier(${v.join(", ")})`
+        : typeof v === "object"
+          ? Object.values(v).join(" ")
+          : String(v);
+const px = (v) =>
+  /^-?[\d.]+rem$/.test(v) ? `${v} (${Math.round(parseFloat(v) * 16)}px)` : v;
+
+const cssVar = (path) => `var(--${cssName(path)})`;
+const attr = (s) => String(s).replaceAll('"', "&quot;");
+
+/** One theme's tokens before resolving: primitives, the brand, the semantics for the mode, component keys. */
+function rawTree(scheme, theme) {
+  return themeTokens(scheme, theme.brand, theme.mode);
+}
+
+/** The aliases a token points through, ending at a primitive. Raw is set when the chain ends in a value. */
+function chain(tree, path) {
+  const steps = [];
+  let at = path;
+  for (let i = 0; i < 10; i++) {
+    const node = get(tree, at);
+    if (!isToken(node)) break;
+    const m =
+      typeof node.$value === "string" && node.$value.match(/^\{(.+)\}$/);
+    if (!m) return { steps, raw: node.$value };
+    steps.push(m[1]);
+    at = m[1];
+  }
+  return { steps, raw: undefined };
+}
+
+/** A small live sample of a primitive or semantic value, drawn from its CSS variable. */
+function sample(path, type) {
+  const v = cssVar(path);
+  if (type === "color")
+    return `<span class="ods-swatch" style="background:${v}"></span>`;
+  if (type === "fontFamily")
+    return `<span class="ods-font" style="font-family:${v}">Aa 123</span>`;
+  if (type === "shadow")
+    return `<span class="ods-card" style="box-shadow:${v}"></span>`;
+  if (type === "duration")
+    return `<span class="ods-motion" style="--ods-d:${v}"><span></span></span>`;
+  if (type === "number" && /opacity/.test(path))
+    return `<span class="ods-swatch" style="opacity:${v}"></span>`;
+  if (type === "dimension") {
+    if (/radius/.test(path))
+      return `<span class="ods-tile" style="border-radius:${v}"></span>`;
+    if (/border-width/.test(path))
+      return `<span class="ods-line" style="height:${v}"></span>`;
+    if (/font-size|line-height|letter/.test(path)) return "";
+    return `<span class="ods-bar" style="width:${v}"></span>`;
+  }
+  return "";
+}
+
+/** The specimen at the top of a foundation page: the scope's semantic tokens, drawn live. */
+function specimen(tokens, text) {
+  const roles = [
+    ...new Set(
+      tokens
+        .map((t) => t.path.match(/^type\.([a-z-]+)\.font-size$/)?.[1])
+        .filter(Boolean),
+    ),
+  ];
+  if (roles.length) {
+    return (
+      `<div class="ods-specimen">\n` +
+      roles
+        .map((r) => {
+          const p = `type.${r}`;
+          const style = `font-family:${cssVar(`${p}.font-family`)};font-size:${cssVar(`${p}.font-size`)};line-height:${cssVar(`${p}.line-height`)};font-weight:${cssVar(`${p}.font-weight`)}`;
+          return `<div class="ods-type"><span class="ods-label">${r}</span><span style="${style}">${attr(text)}</span></div>`;
+        })
+        .join("\n") +
+      `\n</div>\n\n`
+    );
+  }
+  const items = tokens
+    .map((t) => ({ t, s: sample(t.path, t.type) }))
+    .filter((x) => x.s)
+    .slice(0, 40);
+  if (!items.length) return "";
+  return (
+    `<div class="ods-specimen">\n` +
+    items
+      .map(
+        ({ t, s }) =>
+          `<span class="ods-item">${s}<span class="ods-label">${t.path}</span></span>`,
+      )
+      .join("\n") +
+    `\n</div>\n\n`
+  );
+}
+
+/** The header comment of a component file, as plain text. */
+function componentIntro(uiDir, name) {
+  const path = join(uiDir, "components", `${name}.tsx`);
+  if (!existsSync(path)) return "";
+  const m = readFileSync(path, "utf8").match(/^\/\*\*([\s\S]*?)\*\//);
+  return m
+    ? m[1]
+        .split("\n")
+        .map((l) => l.replace(/^\s*\* ?/, ""))
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim()
+    : "";
+}
+
+/**
+ * Every page of one scheme's docs, as { "relative/path.md": text }.
+ * roots: { tokens, ui } from assetRoots(). storybook: the Storybook URL to link to.
+ */
+/** The colour scope's guidance, from the grammar: the urgency order, what each key is for, and its pairs. */
+function colourGuidance(g) {
+  const s = g.semantics;
+  if (!s) return "";
+  const keys = s.keys;
+  return (
+    `\n## Status urgency\n\n${s.urgency.description}\n\n${s.urgency.order.map((id) => `\`${id}\``).join(" → ")}\n` +
+    `\n## What each colour is for\n\n| Token | What it is for | Not for |\n| --- | --- | --- |\n` +
+    keys
+      .map(
+        (k) =>
+          `| \`${k.id}\` | ${esc(k.intent)} | ${k.not_for.map((n) => `${esc(n.when)}: \`${n.use}\``).join("<br />") || "—"} |`,
+      )
+      .join("\n") +
+    `\n\n## Pairs at a glance\n\nWhich colour may sit on which fill, and the contrast it keeps there in every brand and mode. The harness checks every pair.\n\n| Token | Sits on | Contrast |\n| --- | --- | --- |\n` +
+    keys
+      .filter((k) => k.pairs)
+      .map(
+        (k) =>
+          `| \`${k.id}\` | ${k.pairs.on.map((o) => `\`${o}\``).join(", ")} | ${k.pairs.contrast ? `${k.pairs.contrast}:1` : esc(k.exempt ?? "exempt")} |`,
+      )
+      .join("\n") +
+    "\n"
+  );
+}
+
+export function docsPages(
+  scheme,
+  g,
+  roots,
+  { storybook = "http://localhost:6006" } = {},
+) {
+  const qs = questions(g);
+  const sits = Object.fromEntries(g.situations.map((s) => [s.id, s]));
+  const answer = (id) => scheme.answers.find((a) => a.question === id);
+  const label = (id) =>
+    qs[id].options.find((o) => o.id === answer(id).option).label;
+  const because = (ids) =>
+    ids.map((b) => `${qs[b].text} ${label(b)}`).join("; ");
+  const themes = Object.fromEntries(
+    scheme.themes.map((t) => [
+      t.id,
+      JSON.parse(
+        readFileSync(
+          join(roots.tokens, scheme.id, `${t.id}.tokens.json`),
+          "utf8",
+        ),
+      ),
+    ]),
+  );
+  const first = scheme.themes[0];
+  const dark = scheme.themes.find(
+    (t) => t.brand === first.brand && t.mode === "dark",
+  );
+  const value = (theme, path, ref) => {
+    const v = get(themes[theme.id], path);
+    return px(show(v === undefined ? ref : v));
+  };
+  const trees = Object.fromEntries(
+    scheme.themes.map((t) => [t.id, rawTree(scheme, t)]),
+  );
+  const primitiveTree = scheme.tokens.primitive;
+  const isPrimitive = (path) => isToken(get(primitiveTree, path));
+  // A semantic or component token shows what it points to, never a raw value. Only primitives have values.
+  const link = (theme, path) => {
+    const { steps, raw } = chain(trees[theme.id], path);
+    if (steps.length) return steps.map((x) => `\`${x}\``).join(" → ");
+    return raw === undefined
+      ? ""
+      : `${esc(px(show(raw)))} (set here, not a primitive)`;
+  };
+  const primitiveOf = (theme, path) => {
+    const { steps } = chain(trees[theme.id], path);
+    return steps.length && isPrimitive(steps.at(-1)) ? steps.at(-1) : undefined;
+  };
+  const primitiveRows = (paths) =>
+    `| Primitive | Value | Sample |\n| --- | --- | --- |\n` +
+    [...new Set(paths)]
+      .filter(Boolean)
+      .sort()
+      .map(
+        (p) =>
+          `| \`${p}\` | ${esc(value(first, p, ""))} | ${sample(p, get(primitiveTree, p)?.$type)} |`,
+      )
+      .join("\n");
+  const rule = (u) =>
+    `| ${esc(sits[u.situation].title)} | ${esc(u.use)} | ${esc(u.not)} | ${esc(u.why)}${u.example ? ` Example: “${esc(u.example)}”` : ""} |`;
+  const RULES = "| Situation | Use | Not | Why |\n| --- | --- | --- | --- |\n";
+  const pages = {};
+
+  // About this system
+  pages["index.md"] =
+    fm({
+      sidebar_position: 1,
+      slug: "/",
+      title: scheme.name,
+      description: scheme.summary,
+    }) +
+    NOTE +
+    `# ${scheme.name}\n\n${scheme.summary}\n\n` +
+    `- **Use it for:** ${scheme.ai.use_when}\n- **Not for:** ${scheme.ai.avoid_when}\n- **Products like:** ${scheme.ai.example_products.join(", ")}\n- **Themes:** ${scheme.themes.map((t) => t.id).join(", ")}\n\n` +
+    `## Use scenarios\n\n${scheme.scenarios.map((s) => `- ${s.text}`).join("\n")}\n\n` +
+    `## Why this design system is the way it is\n\nEvery decision in this system follows from these answers.\n\n` +
+    g.reasons
+      .map(
+        (r) =>
+          `### ${r.title}\n\n${r.questions
+            .map((q) => {
+              const a = answer(q.id);
+              return `- **${q.text}** ${label(q.id)}. ${a.why}${a.because.length ? ` Because: ${because(a.because)}.` : ""}`;
+            })
+            .join("\n")}`,
+      )
+      .join("\n\n") +
+    "\n";
+
+  // Voice and tone
+  const v = scheme.voice;
+  const voiceRules = scheme.usage.filter(
+    (u) => sits[u.situation].scope === "voice",
+  );
+  pages["voice.md"] =
+    fm({
+      sidebar_position: 2,
+      title: "Voice and tone",
+      description: v.summary.text,
+    }) +
+    NOTE +
+    `# Voice and tone\n\n${v.summary.text}\n\n## Principles\n\n${v.principles.map((p) => `- ${p.text}`).join("\n")}\n\n` +
+    (v.brands
+      ? `## Each brand\n\n${Object.entries(v.brands)
+          .map(([b, t]) => `- **${title(b)}:** ${t.text}`)
+          .join("\n")}\n\n`
+      : "") +
+    `## Words\n\n- Use: ${v.words.use.join(", ")}\n- Avoid: ${v.words.avoid.join(", ")}\n\n` +
+    `## Tone for each moment\n\n${RULES}${voiceRules.map(rule).join("\n")}\n`;
+
+  // Foundations: one page per scope, the same parts for every scope.
+  pages["foundations/_category_.json"] =
+    JSON.stringify(
+      {
+        label: "Foundations",
+        position: 3,
+        link: { type: "doc", id: "foundations/index" },
+      },
+      null,
+      2,
+    ) + "\n";
+  // The foundations overview: every scope in one compact table, with the answer that sets its values.
+  pages["foundations/index.md"] =
+    fm({
+      title: "Foundations",
+      description: `${scheme.name}: every scope and the answer that sets its values.`,
+    }) +
+    NOTE +
+    `# Foundations\n\nEvery scope answers the same five questions. This is the answer that sets each scope's values; open a scope for all five, its tokens and its specimen.\n\n` +
+    `| Scope | Values | Why |\n| --- | --- | --- |\n` +
+    g.scopes
+      .map((sc) => {
+        const q =
+          sc.questions.find((x) => x.method === "values") ?? sc.questions[3];
+        return `| [${sc.title}](./${sc.id}.md) | ${esc(label(q.id))} | ${esc(answer(q.id).why)} |`;
+      })
+      .join("\n") +
+    "\n";
+  g.scopes.forEach((sc, i) => {
+    const tokens = owned(scheme, sc.owns ?? []);
+    const usage = scheme.usage.filter((u) => sits[u.situation].scope === sc.id);
+    // Paths for the component scope start with component.; the key itself is the rest.
+    const key = (p) => p.replace(/^component\./, "");
+    const semantics = tokens.filter((t) => !isPrimitive(t.path));
+    const darkDiffers = semantics.some(
+      (t) => link(first, key(t.path)) !== link(dark, key(t.path)),
+    );
+    const prims = [
+      ...tokens.filter((t) => isPrimitive(t.path)).map((t) => t.path),
+      ...semantics.flatMap((t) => [
+        primitiveOf(first, key(t.path)),
+        primitiveOf(dark, key(t.path)),
+      ]),
+    ];
+    const SPECIMEN = ["components", "naming", "voice"].includes(sc.id)
+      ? ""
+      : specimen(
+          semantics.length ? semantics : tokens,
+          scheme.scenarios[0].text,
+        );
+    pages[`foundations/${sc.id}.md`] =
+      fm({
+        sidebar_position: i + 1,
+        title: sc.title,
+        description: `${scheme.name}: ${sc.description}`,
+      }) +
+      NOTE +
+      `# ${sc.title}\n\n${sc.description}\n\n${SPECIMEN}## The five answers\n\n| Question | Answer | Why |\n| --- | --- | --- |\n` +
+      sc.questions
+        .map(
+          (q) =>
+            `| ${esc(q.text)} | ${esc(label(q.id))} | ${esc(answer(q.id).why)} |`,
+        )
+        .join("\n") +
+      `\n\n## Tokens\n\n` +
+      (semantics.length
+        ? `Each token points to another token. Values live only on primitives, below.\n\n` +
+          (darkDiffers
+            ? "| Token | Points to, light | Points to, dark |\n| --- | --- | --- |\n"
+            : "| Token | Points to |\n| --- | --- |\n") +
+          semantics
+            .map((t) =>
+              darkDiffers
+                ? `| \`${t.path}\` | ${link(first, key(t.path))} | ${link(dark, key(t.path))} |`
+                : `| \`${t.path}\` | ${link(first, key(t.path))} |`,
+            )
+            .join("\n")
+        : "This scope sets primitives directly.") +
+      (prims.filter(Boolean).length
+        ? `\n\n## Primitives\n\nThe raw values the tokens above end at.\n\n${primitiveRows(prims)}`
+        : "") +
+      `\n\n## Where it lands\n\n${(sc.lands_in ?? []).map((c) => `- ${title(c)}`).join("\n")}\n\n` +
+      `## When to use what\n\n${RULES}${usage.map(rule).join("\n")}\n` +
+      (sc.id === "color" ? colourGuidance(g) : "");
+  });
+
+  // Components
+  pages["components/_category_.json"] =
+    JSON.stringify(
+      {
+        label: "Components",
+        position: 4,
+        link: { type: "doc", id: "components/inventory" },
+      },
+      null,
+      2,
+    ) + "\n";
+  const built = readdirSync(join(roots.ui, "components"))
+    .filter((f) => f.endsWith(".tsx"))
+    .map((f) => f.replace(/\.tsx$/, ""))
+    .sort();
+  const inventory = Object.fromEntries(
+    (scheme.inventory?.in ?? []).map((i) => [i.id, i.why]),
+  );
+  const out = Object.fromEntries(
+    (scheme.inventory?.out ?? []).map((i) => [i.id, i.why]),
+  );
+  const catalogue = g.catalogue?.items ?? [];
+  // The inventory page: every catalogue item, in or out, and whether it is built yet.
+  pages["components/inventory.md"] =
+    fm({
+      sidebar_position: 0,
+      title: "Inventory",
+      description: `The components ${scheme.name} carries.`,
+    }) +
+    NOTE +
+    `# Inventory
+
+**${Object.keys(inventory).length}** components are in ${esc(scheme.name)}. ` +
+    `The components answers picked them (see [Components](../foundations/components.md)). Anything not in is out.
+
+` +
+    `| Component | Family | In | Built | Why |
+| --- | --- | --- | --- | --- |
+` +
+    [...catalogue]
+      .sort(
+        (a, b) =>
+          Number(b.id in inventory) - Number(a.id in inventory) ||
+          a.id.localeCompare(b.id),
+      )
+      .map(
+        (c) =>
+          `| ${title(c.id)} | ${c.family} | ${c.id in inventory ? "In" : "Out"} | ${built.includes(c.id) ? "Yes" : "Not yet"} | ${esc(inventory[c.id] ?? out[c.id] ?? "")} |`,
+      )
+      .join("\n") +
+    "\n";
+  // A page per component that is in the inventory and built.
+  const names = built.filter((n) => !scheme.inventory || n in inventory);
+  names.forEach((name, i) => {
+    const group = KEY_GROUP[name];
+    const keys = g.component_keys.filter((k) => k.component === group);
+    const word = new RegExp(`\\b${name.replace("-", "[ -]")}`, "i");
+    const usage = scheme.usage.filter((u) => word.test(`${u.use} ${u.not}`));
+    pages[`components/${name}.md`] =
+      fm({
+        sidebar_position: i + 1,
+        title: title(name),
+        description: `${title(name)} in ${scheme.name}.`,
+      }) +
+      NOTE +
+      `# ${title(name)}\n\n${esc(componentIntro(roots.ui, name)).replaceAll("*", "\\*").replaceAll("_", "\\_")}\n\n` +
+      `See it in [Storybook](${storybook}) under Components / ${title(name)}, in every theme.\n\n` +
+      (keys.length
+        ? `## Component keys\n\nThe CSS variable is the key with \`/\` replaced by \`-\` and the base \`@\` dropped. Each key points to a token; values live only on primitives.\n\n| Key | What it controls | Points to, ${first.id} | Points to, ${dark.id} |\n| --- | --- | --- | --- |\n`
+        : `## Tokens it reads\n\nFrom shadcn/ui. It reads shadcn's variables, which theme.css maps onto this system's semantic tokens, and the radius, shadow and text scale in shadcn.css.\n`) +
+      keys
+        .map((k) => {
+          const p = k.id.replaceAll("/", ".");
+          const l = link(first, p);
+          const d = link(dark, p);
+          return `| \`${k.id}\` | ${esc(k.description)} | ${l} | ${d === l ? "same" : d} |`;
+        })
+        .join("\n") +
+      (usage.length
+        ? `\n\n## When to use it\n\n${RULES}${usage.map(rule).join("\n")}`
+        : "") +
+      "\n";
+  });
+
+  // Themes
+  const brands = Object.entries(scheme.tokens.brands);
+  pages["themes.md"] =
+    fm({
+      sidebar_position: 5,
+      title: "Themes",
+      description: `Brands and modes in ${scheme.name}.`,
+    }) +
+    NOTE +
+    `# Themes\n\n${scheme.name} ships ${scheme.themes.length} themes: ${scheme.themes.map((t) => t.id).join(", ")}. Only semantic tokens change between themes; components never do.\n\n` +
+    `## How to switch\n\n- Dark mode: add the class \`dark\` to \`<html>\`.\n` +
+    (brands.length > 1
+      ? `- Brand: set \`data-brand\` on \`<html>\` to ${brands.map(([b]) => `\`${b}\``).join(", ")}.\n`
+      : "") +
+    `\n## Brands\n\n${brands.map(([b, x]) => `- **${x.label}** (\`${b}\`): ${x.description}`).join("\n")}\n\n` +
+    `## Key colors in each theme\n\n| Token | ${scheme.themes.map((t) => t.id).join(" | ")} |\n| --- | ${scheme.themes.map(() => "---").join(" | ")} |\n` +
+    [
+      "color.surface.canvas",
+      "color.surface.default",
+      "color.text.primary",
+      "color.action.primary",
+      "color.border.focus",
+    ]
+      .map(
+        (p) =>
+          `| \`${p}\` | ${scheme.themes.map((t) => esc(value(t, p, ""))).join(" | ")} |`,
+      )
+      .join("\n") +
+    "\n";
+
+  // For agents
+  pages["agents.md"] =
+    fm({
+      sidebar_position: 6,
+      title: "For agents",
+      description: "How an AI agent builds with this design system.",
+    }) +
+    NOTE +
+    `# For agents\n\nThis design system ships an agent layer, so an AI builds the way the system would and can say why.\n\n` +
+    `- **AGENTS.md** in the project root: the usage rules, the voice and tone, and the key decisions.\n` +
+    `- **The agent skill** in \`.claude/skills/open-ds/SKILL.md\`: how to pick, read and follow the scheme.\n` +
+    `- **The full scheme** in \`.open-ds/scheme.json\`: every answer with its reason.\n` +
+    `- **llms.txt** next to these docs: an index of these pages for agents.\n\n` +
+    `Ask the open-ds CLI or MCP server:\n\n\`\`\`bash\nopen-ds why ${scheme.id} typography.definition\nopen-ds when ${scheme.id} "a number in a table"\n\`\`\`\n`;
+  return pages;
+}
+
+/** llms.txt for one scheme's docs: an index of its pages. */
+export function docsLlms(scheme, pages) {
+  const md = Object.keys(pages).filter((p) => p.endsWith(".md"));
+  const href = (p) => (p === "index.md" ? "/" : `/${p.replace(/\.md$/, "")}`);
+  const head = (p) => pages[p].match(/^title: "(.*)"$/m)?.[1] ?? p;
+  return `# ${scheme.name}\n\n> ${scheme.summary}\n\n## Pages\n\n${md.map((p) => `- [${head(p)}](${href(p)})`).join("\n")}\n`;
+}

package/src/guidance.mjs

@@ -0,0 +1,63 @@
+// What each semantic key is for, read from the grammar's "semantics" list. Pure functions: no files.
+
+const ids = (g) => new Map((g.semantics?.keys ?? []).map((k) => [k.id, k]));
+
+/** The guidance id for a token path; a concept with a base resolves to its @ (color.status.danger → .@). */
+export function guidanceId(g, path) {
+  const all = ids(g);
+  if (all.has(path)) return path;
+  if (all.has(`${path}.@`)) return `${path}.@`;
+  return null;
+}
+
+/**
+ * Guidance for one semantic key: its intent, uses, misuses with what to use instead, the fills it may
+ * sit on, the keys that may sit on it, and its place on the urgency order. Null when there is none.
+ */
+export function guidanceFor(g, path) {
+  const id = guidanceId(g, path);
+  if (!id) return null;
+  const k = ids(g).get(id);
+  const takes = (g.semantics.keys ?? [])
+    .filter((x) => x.pairs?.on.includes(id))
+    .map((x) => ({ key: x.id, contrast: x.pairs.contrast }));
+  const order = g.semantics.urgency?.order ?? [];
+  return {
+    id,
+    intent: k.intent,
+    use_for: k.use_for,
+    not_for: k.not_for,
+    ...(k.pairs && { sits_on: k.pairs.on, contrast: k.pairs.contrast }),
+    ...(k.exempt && { exempt: k.exempt }),
+    ...(takes.length && { takes }),
+    ...(order.includes(id) && {
+      urgency: {
+        level: order.indexOf(id) + 1,
+        of: order,
+        rule: g.semantics.urgency.description,
+      },
+    }),
+  };
+}
+
+/** A copy of a scheme whose semantic tokens carry the grammar's intent as their $description. */
+export function withGuidance(scheme, g) {
+  const all = ids(g);
+  const walk = (node, path) =>
+    Object.fromEntries(
+      Object.entries(node).map(([k, v]) => {
+        if (k.startsWith("$") || !v || typeof v !== "object") return [k, v];
+        const p = path ? `${path}.${k}` : k;
+        if ("$value" in v)
+          return [
+            k,
+            all.has(p) ? { ...v, $description: all.get(p).intent } : v,
+          ];
+        return [k, walk(v, p)];
+      }),
+    );
+  return {
+    ...scheme,
+    tokens: { ...scheme.tokens, semantic: walk(scheme.tokens.semantic, "") },
+  };
+}

package/src/index.mjs

@@ -0,0 +1,20 @@
+// The open-ds package as a library: the same engine the CLI, the MCP server and the site use.
+export {
+  assetRoots,
+  focusedSkills,
+  grammar,
+  schemeIds,
+  loadScheme,
+  questions,
+  why,
+  when,
+  keyInfo,
+} from "./schemes.mjs";
+export {
+  componentsFor,
+  packagesFor,
+  builtComponents,
+  withImports,
+} from "./components.mjs";
+export { createProject } from "./create.mjs";
+export { deploy, addComponent } from "./cli.mjs";