open-ds 0.0.0-stage → 0.1.0

package/src/context.mjs

@@ -0,0 +1,143 @@
+// Context on demand: one call returns only the slice an agent needs for a target, built from the
+// scheme, the grammar and the built tokens. The CLI (open-ds context) and the MCP (get_context) share it.
+import { guidanceFor, guidanceId } from "./guidance.mjs";
+import {
+  assetRoots,
+  grammar,
+  keyInfo,
+  loadScheme,
+  schemeIds,
+  valuesFor,
+  when,
+} from "./schemes.mjs";
+
+export const TASKS = ["choose", "build", "write", "change", "review"];
+
+const brief = (g) =>
+  (g.semantics?.keys ?? []).map((k) => ({
+    id: k.id,
+    intent: k.intent,
+    not_for: k.not_for.map((n) => `${n.when}: use ${n.use}`),
+    ...(k.pairs && { sits_on: k.pairs.on, contrast: k.pairs.contrast }),
+  }));
+
+const rules = (scheme, g) =>
+  g.situations.map((x) => {
+    const r = scheme.usage.find((u) => u.situation === x.id) ?? {};
+    return {
+      situation: x.id,
+      title: x.title,
+      use: r.use,
+      not: r.not,
+      why: r.why,
+    };
+  });
+
+function task(name, scheme, g, roots) {
+  const urgency = g.semantics?.urgency;
+  const base = {
+    target: name,
+    kind: "task",
+    skill: `open-ds-${name}`,
+    scheme: scheme.id,
+  };
+  if (name === "choose")
+    return {
+      ...base,
+      read: "Pick the scheme whose use_when fits the product and whose avoid_when does not.",
+      schemes: schemeIds(roots).map((id) => {
+        const s = loadScheme(id, roots);
+        return { id, name: s.name, summary: s.summary, ...s.ai };
+      }),
+    };
+  if (name === "build")
+    return {
+      ...base,
+      read: "Find the situation and follow its rule. Read only component keys and semantic tokens. Check a semantic's not_for before you use it.",
+      components: g.components.map((c) => ({
+        id: c.id,
+        description: c.description,
+        keys: c.keys,
+      })),
+      rules: rules(scheme, g),
+      semantics: brief(g),
+      urgency,
+    };
+  if (name === "write")
+    return {
+      ...base,
+      read: "Write in the scheme's voice. Use the words in content for common actions.",
+      voice: scheme.voice,
+      content: scheme.tokens.content,
+    };
+  if (name === "change")
+    return {
+      ...base,
+      read: "Change an answer in the scheme JSON, with its why and because. Then rebuild the tokens.",
+      how_to_read: g.ai?.how_to_read,
+      answers: scheme.answers,
+    };
+  return {
+    ...base,
+    read: "Check each colour against its not_for and its pairs, each status against the urgency order, and each situation against its rule.",
+    rules: rules(scheme, g),
+    semantics: brief(g),
+    urgency,
+  };
+}
+
+/**
+ * The context for a target in a scheme. A target is a task (choose, build, write, change, review), a
+ * component (button), a component key (button/primary/background), a semantic token
+ * (color.status.danger) or a situation (status-label). Null when nothing matches.
+ */
+export function context(
+  schemeId,
+  target,
+  roots = assetRoots(),
+  g = grammar(roots),
+) {
+  const scheme = loadScheme(schemeId, roots);
+  if (TASKS.includes(target)) return task(target, scheme, g, roots);
+
+  const comp = g.components.find((c) => c.id === target);
+  if (comp) {
+    const keys = comp.keys
+      .map((k) => keyInfo(schemeId, k, roots, g))
+      .filter(Boolean);
+    const sems = [...new Set(keys.map((k) => k.semantic))];
+    return {
+      target,
+      kind: "component",
+      scheme: scheme.id,
+      description: comp.description,
+      keys: keys.map(({ guidance, ...k }) => k),
+      guidance: sems.map((p) => guidanceFor(g, p)).filter(Boolean),
+      rules: rules(scheme, g).filter((r) =>
+        `${r.use} ${r.not}`.toLowerCase().includes(target),
+      ),
+    };
+  }
+
+  const key = target.includes("/") && keyInfo(schemeId, target, roots, g);
+  if (key) return { target, kind: "component key", scheme: scheme.id, ...key };
+
+  const id = guidanceId(g, target);
+  if (id)
+    return {
+      target,
+      kind: "semantic",
+      scheme: scheme.id,
+      guidance: guidanceFor(g, id),
+      values: valuesFor(schemeId, id, roots),
+      read_by: g.component_keys
+        .filter((k) => k.default === id)
+        .map((k) => k.id),
+    };
+
+  if (g.situations.some((x) => x.id === target)) {
+    const rule = when(scheme, target, g);
+    return { target, kind: "situation", scheme: scheme.id, ...rule };
+  }
+  return null;
+}

package/src/create.mjs

@@ -0,0 +1,377 @@
+// Writes a full design system project for one scheme: its own Style Dictionary token build,
+// the components, Storybook, Docusaurus docs, the answer map, the agent files and CI.
+// The project depends on the open-ds package for why, when and add.
+
+import { themeName } from "./tokens.mjs";
+import { withGuidance } from "./guidance.mjs";
+import { tokenReadmes } from "./readmes.mjs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentsMd, skillSection } from "./agents.mjs";
+import { componentsFor, packagesFor } from "./components.mjs";
+import { docsLlms, docsPages } from "./docs.mjs";
+import { assetRoots, focusedSkills, grammar, loadScheme } from "./schemes.mjs";
+
+const VERSION = JSON.parse(
+  readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"),
+    "utf8",
+  ),
+).version;
+
+const DEV_DEPENDENCIES = {
+  "@docusaurus/core": "^3.10.2",
+  "@docusaurus/preset-classic": "^3.10.2",
+  "@docusaurus/types": "^3.10.2",
+  "@mdx-js/react": "^3.1.0",
+  "@storybook/addon-docs": "^10.6.5",
+  "@storybook/react-vite": "^10.6.5",
+  "@tailwindcss/vite": "^4.3.3",
+  "@types/react": "^19.1.13",
+  "@types/react-dom": "^19.1.9",
+  "@vitejs/plugin-react": "^6.1.2",
+  "prism-react-renderer": "^2.4.1",
+  storybook: "^10.6.5",
+  "style-dictionary": "^5.7.1",
+  tailwindcss: "^4.3.3",
+  typescript: "^5.9.2",
+  vite: "^8.3.5",
+};
+
+const json = (data) => JSON.stringify(data, null, 2) + "\n";
+
+const walk = (dir) =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)],
+  );
+
+function readme(scheme, name, brands) {
+  return [
+    `# ${name}`,
+    "",
+    `A design system built from the Open DS scheme **${scheme.name}** (${scheme.id} ${scheme.version}). ${scheme.summary}`,
+    "",
+    "## Run it",
+    "",
+    "```bash",
+    "npm install",
+    "npm run storybook   # the components, at http://localhost:6006",
+    "npm run docs        # the docs, at http://localhost:3000",
+    "```",
+    "",
+    "`npm run build` builds the tokens, type-checks the components and builds Storybook and the docs.",
+    "",
+    "## What is here",
+    "",
+    "| Folder | What it holds |",
+    "| --- | --- |",
+    "| `tokens/src/` | The DTCG token source, one file per group: `primitive/` (steps only: colour by hue with light and dark ramps; space, size, radius, font, shadow, motion), `theme/` (each brand's decisions per mode, on the semantic paths, with a base `@` per concept), `semantic/`, `component/` and content. Each folder has a README. Only semantic and component keys ship as CSS variables. |",
+    "| `tokens/build.mjs` | The Style Dictionary build. `npm run tokens` writes CSS, the shadcn and Tailwind theme and JSON to `build/`. |",
+    "| `src/components/ui/` | The components. Each reads only component keys such as `--button-primary-background`. |",
+    "| `src/styles/index.css` | Tailwind, the built tokens, the theme and the base styles. |",
+    "| `stories/` | Storybook stories, with the usage rules next to each component. |",
+    "| `docs/` | The Docusaurus docs: reasons, voice, foundations, components, themes. |",
+    "| `scheme.json` | The answer map: every decision with why and because, every usage rule, the voice. |",
+    "| `AGENTS.md`, `.claude/skills/` | What a coding agent reads before it writes UI. |",
+    "",
+    `Themes: ${scheme.themes.map((t) => t.id).join(", ")}.${brands.length > 1 ? ` Set \`data-brand\` on \`<html>\` to pick a brand.` : ""} Add the class \`dark\` for dark mode.`,
+    "",
+    "## Ask why",
+    "",
+    "```bash",
+    "npm run why -- typography.definition",
+    "npm run when -- destructive action",
+    "```",
+    "",
+    "## Built on open source",
+    "",
+    "This design system is built on open-source projects, used as their authors intend and under their own licences:",
+    "[shadcn/ui](https://ui.shadcn.com) (the component patterns), [Radix UI](https://www.radix-ui.com) (accessible primitives),",
+    "[Tailwind CSS](https://tailwindcss.com), [Style Dictionary](https://styledictionary.com) (the token build),",
+    "[Storybook](https://storybook.js.org), [Docusaurus](https://docusaurus.io), [TanStack Table](https://tanstack.com/table)",
+    "and [Lucide](https://lucide.dev) icons. Each package's licence is in `node_modules`.",
+    "",
+  ].join("\n");
+}
+
+/** Writes a design system project for a scheme into dir. Returns what it wrote. */
+export function createProject(
+  schemeId,
+  dir,
+  {
+    brand,
+    openDs = `^${VERSION}`,
+    overwrite = false,
+    roots = assetRoots(),
+  } = {},
+) {
+  const scheme = loadScheme(schemeId, roots);
+  const g = grammar(roots);
+  const brands = Object.keys(scheme.tokens.brands);
+  if (brand && !brands.includes(brand))
+    throw new Error(
+      `${scheme.name} has no brand "${brand}". Brands: ${brands.join(", ")}.`,
+    );
+  if (!existsSync(join(roots.tokens, schemeId, "tokens.css")))
+    throw new Error(
+      `Tokens for ${schemeId} are not built. Run: pnpm --dir tokens build`,
+    );
+  // A fresh git folder, a vendored package and npm's leftovers do not count as content.
+  const SETUP = new Set([
+    ".git",
+    ".DS_Store",
+    "vendor",
+    "node_modules",
+    "package-lock.json",
+  ]);
+  const taken = existsSync(dir)
+    ? readdirSync(dir).filter((f) => !SETUP.has(f))
+    : [];
+  if (taken.length && !overwrite) {
+    throw new Error(
+      `${dir} is not empty (${taken.slice(0, 5).join(", ")}). Run create again with --yes to write into it.`,
+    );
+  }
+  const name = basename(dir);
+  const files = [];
+  const write = (rel, text) => {
+    mkdirSync(dirname(join(dir, rel)), { recursive: true });
+    writeFileSync(join(dir, rel), text);
+    files.push(rel);
+  };
+
+  // The fixed parts: token build, Storybook, Docusaurus config, CI. "gitignore" becomes .gitignore,
+  // because npm drops .gitignore files from packages.
+  const template = join(roots.templates, "project");
+  for (const path of walk(template)) {
+    const rel = relative(template, path);
+    write(rel === "gitignore" ? ".gitignore" : rel, readFileSync(path, "utf8"));
+  }
+
+  // The token source, as DTCG files the team owns and edits: one file per group, in folders.
+  // Semantic descriptions come from the grammar's guidance, written once for every scheme.
+  const t = withGuidance(scheme, g).tokens;
+  const groups = (tree) =>
+    Object.entries(tree).filter(([k]) => !k.startsWith("$"));
+  // Primitives: color/<hue>, font/<part>, motion/<duration|easing>, and one file for each other group.
+  for (const [group, node] of groups(t.primitive)) {
+    if (group === "color" || group === "font")
+      for (const [part, sub] of groups(node))
+        write(
+          `tokens/src/primitive/${group}/${part}.tokens.json`,
+          json({ [group]: { [part]: sub } }),
+        );
+    else if (group === "duration" || group === "easing")
+      write(
+        `tokens/src/primitive/motion/${group}.tokens.json`,
+        json({ [group]: node }),
+      );
+    else
+      write(
+        `tokens/src/primitive/${group}.tokens.json`,
+        json({ [group]: node }),
+      );
+  }
+  // Themes: one file per brand, with its base, light and dark picks.
+  for (const b of brands)
+    write(
+      `tokens/src/theme/${b}.tokens.json`,
+      json({ [themeName(scheme.id, b)]: { theme: t.brands[b].theme } }),
+    );
+  // Semantics and component keys: one file per group.
+  for (const [group, node] of groups(t.semantic))
+    write(`tokens/src/semantic/${group}.tokens.json`, json({ [group]: node }));
+  for (const [group, node] of groups(t.component))
+    write(`tokens/src/component/${group}.tokens.json`, json({ [group]: node }));
+  if (t.content)
+    write("tokens/src/content.tokens.json", json({ content: t.content }));
+  // Every folder says what it holds and its rules, for people and agents.
+  for (const [dir, text] of Object.entries(tokenReadmes(scheme)))
+    write(`tokens/src/${dir}README.md`, text);
+  // The default brand goes first, so it is the one on :root.
+  const order = brand ? [brand, ...brands.filter((b) => b !== brand)] : brands;
+  write(
+    "tokens/themes.json",
+    json({
+      description:
+        "The brands and themes tokens/build.mjs builds. The first brand is the default, on :root. theme is the name its theme tokens carry: --<theme>-theme-light-<key>.",
+      name: scheme.name,
+      brands: order.map((b) => ({
+        id: b,
+        label: t.brands[b].label ?? b,
+        theme: themeName(scheme.id, b),
+      })),
+      themes: order.flatMap((b) => scheme.themes.filter((x) => x.brand === b)),
+    }),
+  );
+
+  // The scheme's inventory, plus the components those import, and their styles.
+  const components = componentsFor(scheme, roots);
+  for (const c of components) {
+    write(
+      `src/components/ui/${c}.tsx`,
+      readFileSync(join(roots.ui, "components", `${c}.tsx`), "utf8").replaceAll(
+        `from "../lib/`,
+        `from "../../lib/`,
+      ),
+    );
+  }
+  for (const lib of readdirSync(join(roots.ui, "lib")))
+    write(`src/lib/${lib}`, readFileSync(join(roots.ui, "lib", lib), "utf8"));
+  write(
+    "src/styles/base.css",
+    readFileSync(join(roots.ui, "styles.css"), "utf8"),
+  );
+  write(
+    "src/index.ts",
+    `// ${scheme.name} components. Import "./styles/index.css" once in an app.\n` +
+      components
+        .map((c) => `export * from "./components/ui/${c}";`)
+        .join("\n") +
+      "\n",
+  );
+
+  // Storybook stories, with this scheme's usage rules.
+  // A story is copied only when everything it imports from the components is installed here.
+  const exported = new Set(
+    components.flatMap((c) => {
+      const src = readFileSync(
+        join(roots.ui, "components", `${c}.tsx`),
+        "utf8",
+      );
+      const names = [
+        ...src.matchAll(
+          /^export (?:function|const|interface|type) ([A-Za-z]+)/gm,
+        ),
+      ].map((m) => m[1]);
+      for (const m of src.matchAll(/^export \{([^}]+)\}/gm))
+        names.push(
+          ...m[1]
+            .split(",")
+            .map((x) => x.trim())
+            .filter(Boolean),
+        );
+      return names;
+    }),
+  );
+  const storyFits = (text) => {
+    const m = text.match(/import \{([^}]+)\} from "@open-ds\/ui"/);
+    return (
+      !m ||
+      m[1]
+        .split(",")
+        .map((x) => x.trim())
+        .filter(Boolean)
+        .every((n) => exported.has(n))
+    );
+  };
+  for (const f of readdirSync(roots.stories).filter(
+    (x) =>
+      x.endsWith(".stories.tsx") &&
+      storyFits(readFileSync(join(roots.stories, x), "utf8")),
+  )) {
+    write(
+      `stories/${f}`,
+      readFileSync(join(roots.stories, f), "utf8")
+        .replaceAll(`from "@open-ds/ui"`, `from "../src"`)
+        .replaceAll(`from "../src/usage"`, `from "./usage"`)
+        .replaceAll(`from "../src/samples"`, `from "./samples"`)
+        .replaceAll(`from "../src/docs-blocks"`, `from "./docs-blocks"`),
+    );
+  }
+
+  // The answer map and the situations the usage rules name.
+  write("scheme.json", json(scheme));
+  write(
+    ".open-ds/grammar.json",
+    json({
+      situations: g.situations,
+      catalogue: g.catalogue,
+      component_keys: g.component_keys,
+    }),
+  );
+  write(
+    ".open-ds/situations.json",
+    json(
+      g.situations.map((s) => ({
+        id: s.id,
+        title: s.title,
+        description: s.description,
+      })),
+    ),
+  );
+
+  // The docs pages.
+  const pages = docsPages(scheme, g, roots);
+  for (const [rel, text] of Object.entries(pages))
+    write(`docs/docs/${rel}`, text);
+  write("docs/static/llms.txt", docsLlms(scheme, pages));
+
+  // The agent files.
+  const defaultBrand = brands.length > 1 ? order[0] : null;
+  write(
+    "AGENTS.md",
+    agentsMd(scheme, g, { brand: defaultBrand, components, project: true }),
+  );
+  write(
+    ".claude/skills/open-ds/SKILL.md",
+    readFileSync(join(roots.skills, "open-ds", "SKILL.md"), "utf8") +
+      skillSection(scheme, { project: true }),
+  );
+  for (const skill of focusedSkills(roots))
+    write(
+      `.claude/skills/${skill}/SKILL.md`,
+      readFileSync(join(roots.skills, skill, "SKILL.md"), "utf8"),
+    );
+
+  write(
+    "package.json",
+    json({
+      name,
+      version: "0.1.0",
+      private: true,
+      description: `${scheme.name}: a design system built from the Open DS scheme ${scheme.id}.`,
+      main: "src/index.ts",
+      scripts: {
+        tokens: "node tokens/build.mjs",
+        typecheck: "npm run tokens && tsc --noEmit",
+        storybook: "npm run tokens && storybook dev -p 6006",
+        "build-storybook":
+          "npm run tokens && storybook build -o storybook-static --quiet",
+        docs: "npm run tokens && docusaurus start docs",
+        "build-docs": "npm run tokens && docusaurus build docs",
+        build:
+          "npm run typecheck && npm run build-storybook && npm run build-docs",
+        why: `open-ds why ${scheme.id}`,
+        when: `open-ds when ${scheme.id}`,
+      },
+      dependencies: {
+        react: "^19.1.1",
+        "react-dom": "^19.1.1",
+        ...packagesFor(components, roots),
+      },
+      devDependencies: { "open-ds": openDs, ...DEV_DEPENDENCIES },
+    }),
+  );
+  write("README.md", readme(scheme, name, brands));
+
+  const record = {
+    $comment:
+      "Written by open-ds create. The scheme this design system was built from.",
+    kind: "project",
+    scheme: scheme.id,
+    version: scheme.version,
+    brand: defaultBrand,
+    components,
+    files: files.sort(),
+  };
+  writeFileSync(join(dir, "open-ds.json"), json(record));
+  return record;
+}