@twoux/ui 0.0.0-stage → 0.1.1

package/bin/init.mjs

@@ -0,0 +1,113 @@
+// twoux init: sets up the current project so AI coding agents build with TwoUX.
+// Never overwrites: appends to AGENTS.md and CLAUDE.md, merges the hook into .claude/settings.json,
+// and skips files that already exist (use --force to replace skills and the proposal template).
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const pkg = new URL("..", import.meta.url).pathname;
+const cwd = process.cwd();
+const force = process.argv.includes("--force");
+// --principles: the app is not built with TwoUX and isn't migrating; agents follow TwoUX's principles with the app's own components.
+const principles = process.argv.includes("--principles");
+const done = [];
+const skip = [];
+
+const AGENTS_LINE = principles
+	? "This app is not built with TwoUX. Follow the principles in `node_modules/@twoux/ui/agent/AGENTS.md` (every rule not marked TwoUX only) using this app's own components, tokens and brand; never import TwoUX components piecemeal, and keep the look of anything you rebuild. Before finishing, run `npx twoux check --principles`, type-check, and open each changed screen in a browser to try the states you changed; say what you could not verify. To move onto TwoUX, follow `node_modules/@twoux/ui/agent/docs-md/migrating.md`."
+	: "Follow `node_modules/@twoux/ui/agent/AGENTS.md` for all UI work: components, tokens, patterns, and how to propose additions. Run `npx twoux check` before finishing.";
+const agents = join(cwd, "AGENTS.md");
+if (!existsSync(agents)) { writeFileSync(agents, `# Agent instructions\n\n## UI: TwoUX\n\n${AGENTS_LINE}\n`); done.push("AGENTS.md (created)"); }
+else if (!readFileSync(agents, "utf8").includes("@twoux/ui/agent/AGENTS.md")) { writeFileSync(agents, `${readFileSync(agents, "utf8").trimEnd()}\n\n## UI: TwoUX\n\n${AGENTS_LINE}\n`); done.push("AGENTS.md (section added)"); }
+else skip.push("AGENTS.md already points to TwoUX");
+
+const claude = join(cwd, "CLAUDE.md");
+const IMPORT = "@node_modules/@twoux/ui/agent/AGENTS.md";
+// In principles mode Claude Code must read the scope line too, not only the imported rules.
+const CLAUDE_BLOCK = principles ? `${AGENTS_LINE}\n\n${IMPORT}` : IMPORT;
+if (!existsSync(claude)) { writeFileSync(claude, `${CLAUDE_BLOCK}\n`); done.push("CLAUDE.md (created)"); }
+else if (!readFileSync(claude, "utf8").includes(IMPORT)) { writeFileSync(claude, `${readFileSync(claude, "utf8").trimEnd()}\n\n${CLAUDE_BLOCK}\n`); done.push("CLAUDE.md (import added)"); }
+else skip.push("CLAUDE.md already imports TwoUX");
+
+// Design skills such as Impeccable take the product's voice from PRODUCT.md ("Brand Commitments"), not from AGENTS.md,
+// so the TwoUX voice is written there too. Created only when Impeccable is in use; otherwise left alone.
+const VOICE = "- Voice (TwoUX): interface copy follows `node_modules/@twoux/ui/agent/docs-md/voice-and-tone.md` and `writing.md`: precise, calm, candid and respectful of expertise; UK English, sentence case, verb-first labels. No humour, playful or celebratory copy, exclamation marks or \"we\"; delight comes from speed and precision, not words. This overrides any general writing or design skill.";
+const product = join(cwd, "PRODUCT.md");
+const home = process.env.HOME ?? "";
+const usesImpeccable = [join(cwd, ".impeccable"), join(cwd, ".claude/skills/impeccable"), join(cwd, ".agents/skills/impeccable"), join(home, ".claude/skills/impeccable")].some((p) => existsSync(p));
+if (existsSync(product)) {
+	const text = readFileSync(product, "utf8");
+	if (text.includes("docs-md/voice-and-tone.md")) skip.push("PRODUCT.md already carries the TwoUX voice");
+	else {
+		const m = text.match(/^## Brand Commitments[^\n]*\n/m);
+		let next = `${text.trimEnd()}\n\n## Brand Commitments\n\n${VOICE}\n`;
+		if (m) {
+			const head = text.slice(0, m.index + m[0].length);
+			const rest = text.slice(m.index + m[0].length);
+			next = rest.startsWith("\n- ") ? `${head}\n${VOICE}${rest}` : `${head}\n${VOICE}\n${rest}`;
+		}
+		writeFileSync(product, next);
+		done.push("PRODUCT.md (TwoUX voice in Brand Commitments)");
+	}
+} else if (usesImpeccable) {
+	writeFileSync(product, `# Product\n\n## Brand Commitments\n\n${VOICE}\n`);
+	done.push("PRODUCT.md (created with the TwoUX voice; /impeccable init fills in the rest)");
+} else skip.push("PRODUCT.md not created (no design skill found that reads it)");
+
+const settingsPath = join(cwd, ".claude/settings.json");
+mkdirSync(join(cwd, ".claude"), { recursive: true });
+const settings = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf8")) : {};
+const hookCmd = 'node "$CLAUDE_PROJECT_DIR/node_modules/@twoux/ui/bin/twoux.mjs" guard';
+settings.hooks ??= {};
+settings.hooks.PreToolUse ??= [];
+if (!JSON.stringify(settings.hooks.PreToolUse).includes("twoux.mjs\\\" guard") && !JSON.stringify(settings.hooks.PreToolUse).includes("twoux.mjs guard")) {
+	settings.hooks.PreToolUse.push({ matcher: "Edit|Write|MultiEdit|NotebookEdit|Bash", hooks: [{ type: "command", command: hookCmd }] });
+	writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+	done.push(".claude/settings.json (guard hook)");
+} else skip.push("guard hook already set");
+
+// MCP: the same knowledge as tools (find_component, get_doc, list_docs, get_rules, check).
+// Claude Code reads .mcp.json; Cursor and VS Code get theirs only when the project already uses them.
+const MCP = { command: "npx", args: ["-y", "@twoux/ui", "mcp"] };
+for (const [file, key, entry, when] of [
+	[".mcp.json", "mcpServers", MCP, true],
+	[".cursor/mcp.json", "mcpServers", MCP, existsSync(join(cwd, ".cursor"))],
+	[".vscode/mcp.json", "servers", { type: "stdio", ...MCP }, existsSync(join(cwd, ".vscode"))],
+]) {
+	if (!when) continue;
+	const path = join(cwd, file);
+	let json = {};
+	if (existsSync(path)) {
+		try { json = JSON.parse(readFileSync(path, "utf8")); } catch { skip.push(`${file} is not valid JSON, so the TwoUX server was not added`); continue; }
+	}
+	json[key] ??= {};
+	if (json[key].twoux) { skip.push(`${file} already lists twoux`); continue; }
+	json[key].twoux = entry;
+	writeFileSync(path, `${JSON.stringify(json, null, 2)}\n`);
+	done.push(`${file} (TwoUX MCP server)`);
+}
+
+// Build, design and propose assume @twoux/ui; an app that only follows the principles gets audit and write.
+for (const s of principles ? ["twoux-audit", "twoux-write"] : ["twoux-audit", "twoux-build", "twoux-design", "twoux-propose", "twoux-write"]) {
+	const to = join(cwd, ".claude/skills", s);
+	if (!existsSync(join(pkg, "agent/skills", s))) continue; // not in this edition
+	if (existsSync(to) && !force) { skip.push(`.claude/skills/${s} exists`); continue; }
+	cpSync(join(pkg, "agent/skills", s), to, { recursive: true });
+	done.push(`.claude/skills/${s}`);
+}
+
+if (principles) skip.push("twoux.theme.json not created (--principles: the app keeps its own theme)");
+else if (!existsSync(join(cwd, "twoux.theme.json"))) {
+	const t = JSON.parse(readFileSync(join(pkg, "theme.json"), "utf8"));
+	writeFileSync(join(cwd, "twoux.theme.json"), `${JSON.stringify(t, null, 2)}\n`);
+	done.push("twoux.theme.json (default: indigo, 4/6/8px)");
+} else skip.push("twoux.theme.json exists");
+
+if (!principles) mkdirSync(join(cwd, "proposals"), { recursive: true });
+if (!principles && existsSync(join(pkg, "agent/proposals-TEMPLATE.md")) && (!existsSync(join(cwd, "proposals/TEMPLATE.md")) || force)) { cpSync(join(pkg, "agent/proposals-TEMPLATE.md"), join(cwd, "proposals/TEMPLATE.md")); done.push("proposals/TEMPLATE.md"); }
+
+console.log("TwoUX is set up for AI agents.\n");
+for (const d of done) console.log(`  + ${d}`);
+for (const s of skip) console.log(`  · ${s}`);
+console.log(principles
+	? "\nNext: ask your agent to /twoux-audit a screen. It reviews it against TwoUX's principles and proposes fixes in your own components."
+	: "\nNext: import '@twoux/ui/styles.css' (then './twoux-theme.css' after running npx twoux theme), and ask your agent to /twoux-audit a screen.");

package/bin/knowledge.mjs

@@ -0,0 +1,87 @@
+// Shared lookups over TwoUX's agent knowledge, used by `twoux docs`, `twoux find` and `twoux mcp`.
+// Reads only files shipped in the package: agent/AGENTS.md, agent/docs-md/*.md and registry/jobs.json.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const pkg = new URL("..", import.meta.url).pathname;
+const docsDir = join(pkg, "agent/docs-md");
+
+export const rules = () => readFileSync(join(pkg, "agent/AGENTS.md"), "utf8");
+
+let docsCache;
+/** Every page: id, name, kind (foundation, component, pattern…), one-line summary. */
+export function listDocs() {
+	if (docsCache) return docsCache;
+	docsCache = readdirSync(docsDir)
+		.filter((f) => f.endsWith(".md"))
+		.map((f) => {
+			const lines = readFileSync(join(docsDir, f), "utf8").split("\n");
+			const name = (lines.find((l) => l.startsWith("# ")) ?? f).replace(/^# /, "");
+			const summary = lines.find((l, i) => i > 0 && l.trim() && !l.startsWith("#")) ?? "";
+			const meta = lines.find((l) => l.startsWith("Kind: ")) ?? "";
+			const kind = meta.match(/^Kind: ([^·]+)/)?.[1].trim() ?? "foundation";
+			const status = meta.match(/Status: ([^·]+)/)?.[1].trim() ?? "";
+			return { id: f.replace(/\.md$/, ""), name, kind, status, summary: summary === meta ? "" : summary };
+		})
+		.sort((a, b) => a.id.localeCompare(b.id));
+	return docsCache;
+}
+
+export function getDoc(id) {
+	const clean = String(id).toLowerCase().trim().replace(/\.md$/, "").replace(/[^a-z0-9-]/g, "-");
+	const file = join(docsDir, `${clean}.md`);
+	if (existsSync(file)) return { id: clean, text: readFileSync(file, "utf8") };
+	// Accept a name such as "Side panel" or "SidePanel".
+	const flat = String(id).toLowerCase().replace(/[^a-z0-9]/g, "");
+	const hit = listDocs().find((d) => d.name.toLowerCase().replace(/[^a-z0-9]/g, "") === flat || d.id.replace(/-/g, "") === flat);
+	return hit ? { id: hit.id, text: readFileSync(join(docsDir, `${hit.id}.md`), "utf8") } : null;
+}
+
+const jobsFile = join(pkg, "registry/jobs.json");
+const STOP = new Set("a an and the of to for in on or with by at as is it its that this from into show let people someone".split(" "));
+const words = (s) => String(s).toLowerCase().replace(/[`"“”]/g, " ").split(/[^a-z0-9]+/).filter((w) => w.length > 1 && !STOP.has(w)).map((w) => w.replace(/(?:ly|ing|ed|es|s)$/, ""));
+
+/** Rank the job table, then page summaries, against a plain-language job such as "confirm a delete". */
+export function findJob(query, limit = 5) {
+	const q = new Set(words(query));
+	if (!q.size) return [];
+	const docs = Object.fromEntries(listDocs().map((d) => [d.id, d]));
+	// Jobs that cover more of the query's words rank first; weights break ties.
+	const hits = (...texts) => new Set(texts.flatMap(words).filter((w) => q.has(w))).size * 10;
+	const score = (text, weight) => words(text).reduce((n, w) => n + (q.has(w) ? weight : 0), 0);
+	const named = (id) => docs[id]?.name ?? id;
+	const jobs = JSON.parse(readFileSync(jobsFile, "utf8")).jobs.map((j) => ({
+		job: j.job,
+		use: j.use,
+		name: docs[j.use]?.name ?? j.use,
+		how: j.how ?? "",
+		notThis: (j.notThis ?? []).map(named),
+		score: hits(j.job, named(j.use), j.how ?? "") + score(j.job, 3) + score(docs[j.use]?.name ?? j.use, 2) + score(j.how ?? "", 1),
+	}));
+	const seen = new Set();
+	const ranked = jobs.filter((j) => j.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
+	for (const j of ranked) seen.add(j.use);
+	// Pages that no job names directly, matched on their name and summary.
+	const pages = listDocs()
+		.filter((d) => !seen.has(d.id))
+		.map((d) => ({ job: d.summary, use: d.id, name: d.name, how: "", notThis: [], score: hits(d.name, d.summary) + score(d.name, 3) + score(d.summary, 1) }))
+		.filter((d) => d.score > 11)
+		.sort((a, b) => b.score - a.score)
+		.slice(0, Math.max(0, limit - ranked.length));
+	return [...ranked, ...pages];
+}
+
+export function formatMatches(matches) {
+	if (!matches.length) return "No job matched. Run `twoux docs` to list every page, or read the job table in AGENTS.md.";
+	return matches
+		.map((m) => [`${m.job}\n  Use: ${m.name} (twoux docs ${m.use})`, m.how && `  How: ${m.how.replace(/`/g, "")}`, m.notThis.length && `  Not this: ${m.notThis.join(", ")}`].filter(Boolean).join("\n"))
+		.join("\n\n");
+}
+
+export function formatList(kind) {
+	const docs = listDocs().filter((d) => !kind || d.kind === kind);
+	const kinds = [...new Set(docs.map((d) => d.kind))];
+	return kinds
+		.map((k) => `## ${k}\n${docs.filter((d) => d.kind === k).map((d) => `- ${d.id}: ${d.name}${d.status && !d.status.startsWith("built") ? ` (${d.status})` : ""}`).join("\n")}`)
+		.join("\n\n");
+}

package/bin/mcp.mjs

@@ -0,0 +1,116 @@
+// twoux mcp: TwoUX's Model Context Protocol server over stdio, with no dependencies.
+// Agents ask it the same questions people ask the docs: which component fits a job, what a page says,
+// what the rules are, and whether code passes `twoux check`. Messages are newline-delimited JSON-RPC 2.0.
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { findJob, formatList, formatMatches, getDoc, pkg, rules } from "./knowledge.mjs";
+
+const VERSION = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8")).version;
+const PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+
+const INSTRUCTIONS = `TwoUX is the design system for this app's UI. Before writing UI: call find_component with the job in plain words, then get_doc for the page it names (read "When not to use"). Call get_rules once per task for the full rule set. Before finishing, call check on the files you changed and fix every error.`;
+
+const TOOLS = [
+	{
+		name: "find_component",
+		title: "Find the component for a job",
+		description: "Given a UI job in plain words (\"confirm a permanent delete\", \"filter a list by a few fields\"), return the one TwoUX component or pattern to use, how to use it and what not to use instead.",
+		inputSchema: { type: "object", properties: { job: { type: "string", description: "What the UI must do, in plain words." } }, required: ["job"] },
+		annotations: { readOnlyHint: true },
+		run: ({ job }) => formatMatches(findJob(job)),
+	},
+	{
+		name: "get_doc",
+		title: "Read a TwoUX page",
+		description: "Return one foundation, component or pattern page as Markdown: when to use, when not to use, behaviour, accessibility, keyboard, API, example code and sources. Accepts an id (side-panel) or a name (Side panel).",
+		inputSchema: { type: "object", properties: { id: { type: "string", description: "Page id or name, such as button, side-panel or filtering-search." } }, required: ["id"] },
+		annotations: { readOnlyHint: true },
+		run: ({ id }) => {
+			const doc = getDoc(id);
+			if (doc) return doc.text;
+			throw new Error(`No page called "${id}". Call list_docs for every id, or find_component with the job.`);
+		},
+	},
+	{
+		name: "list_docs",
+		title: "List TwoUX pages",
+		description: "List every page id and name, grouped by kind. Filter with kind: component, pattern or foundation.",
+		inputSchema: { type: "object", properties: { kind: { type: "string", enum: ["component", "pattern", "foundation"] } } },
+		annotations: { readOnlyHint: true },
+		run: ({ kind }) => formatList(kind),
+	},
+	{
+		name: "get_rules",
+		title: "Read the TwoUX rules",
+		description: "Return AGENTS.md: the steps before writing UI, every rule with its reason, and the full job-to-component table.",
+		inputSchema: { type: "object", properties: {} },
+		annotations: { readOnlyHint: true },
+		run: () => rules(),
+	},
+	{
+		name: "check",
+		title: "Run twoux check",
+		description: "Lint app code against TwoUX's rules (raw colours, arbitrary values, inline styles, local copies, bypassed imports, copy tone). Returns the report; errors must be fixed before finishing.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				paths: { type: "array", items: { type: "string" }, description: "Files or folders relative to the project root. Default: src." },
+				principles: { type: "boolean", description: "The app is not built with TwoUX: run only the checks that hold outside it." },
+			},
+		},
+		annotations: { readOnlyHint: true },
+		run: ({ paths = [], principles = false }) => {
+			const safe = paths.filter((p) => typeof p === "string" && !p.startsWith("-"));
+			const r = spawnSync(process.execPath, [join(pkg, "bin/twoux.mjs"), "check", ...(principles ? ["--principles"] : []), ...safe], { cwd: process.cwd(), encoding: "utf8", timeout: 120_000 });
+			const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() || "No output.";
+			return r.status === 0 ? out : { text: out, isError: true };
+		},
+	},
+];
+
+const send = (msg) => process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", ...msg })}\n`);
+
+function handle(req) {
+	const { id, method, params = {} } = req;
+	switch (method) {
+		case "initialize":
+			return {
+				protocolVersion: PROTOCOLS.includes(params.protocolVersion) ? params.protocolVersion : PROTOCOLS[0],
+				capabilities: { tools: {} },
+				serverInfo: { name: "twoux", title: "TwoUX", version: VERSION },
+				instructions: INSTRUCTIONS,
+			};
+		case "ping":
+			return {};
+		case "tools/list":
+			return { tools: TOOLS.map(({ run, ...t }) => t) };
+		case "tools/call": {
+			const tool = TOOLS.find((t) => t.name === params.name);
+			if (!tool) throw Object.assign(new Error(`Unknown tool: ${params.name}`), { code: -32602 });
+			try {
+				const out = tool.run(params.arguments ?? {});
+				const { text, isError } = typeof out === "string" ? { text: out, isError: false } : out;
+				return { content: [{ type: "text", text }], isError };
+			} catch (e) {
+				return { content: [{ type: "text", text: e.message }], isError: true };
+			}
+		}
+		default:
+			if (id === undefined) return undefined; // notifications such as notifications/initialized need no reply
+			throw Object.assign(new Error(`Method not found: ${method}`), { code: -32601 });
+	}
+}
+
+createInterface({ input: process.stdin }).on("line", (line) => {
+	if (!line.trim()) return;
+	let req;
+	try { req = JSON.parse(line); } catch { return send({ id: null, error: { code: -32700, message: "Parse error" } }); }
+	try {
+		const result = handle(req);
+		if (req.id !== undefined && result !== undefined) send({ id: req.id, result });
+	} catch (e) {
+		if (req.id !== undefined) send({ id: req.id, error: { code: e.code ?? -32603, message: e.message } });
+	}
+});

package/bin/theme.mjs

@@ -0,0 +1,168 @@
+// twoux theme: builds the brand layer (brand colour, corner radii, button shape, font).
+// In an app: reads ./twoux.theme.json, writes ./twoux-theme.css (import it after @twoux/ui/styles.css).
+// In the TwoUX repo: reads packages/ui/theme.json, writes packages/ui/src/styles/theme.css.
+// Fails, and writes nothing, if the colour would break WCAG contrast.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const pkg = new URL("..", import.meta.url).pathname;
+const projectTheme = join(process.cwd(), "twoux.theme.json");
+const inApp = existsSync(projectTheme) && !existsSync(join(process.cwd(), "packages/ui/bin/theme.mjs"));
+const THEME = inApp ? projectTheme : join(pkg, "theme.json");
+const OUT = inApp ? join(process.cwd(), "twoux-theme.css") : join(pkg, "src/styles/theme.css");
+const PALETTE = join(pkg, "src/styles/palette.css");
+
+/* ---------- colour maths (same as scripts/palette.mjs) ---------- */
+const toLin = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const toGam = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+function hexToOklch(hex) {
+	const [r, g, b] = [1, 3, 5].map((i) => toLin(Number.parseInt(hex.slice(i, i + 2), 16) / 255));
+	const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+	const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+	const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+	const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+	const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+	const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+	return { L, C: Math.hypot(A, B), H: ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360 };
+}
+function oklchToRgb({ L, C, H }) {
+	const a = C * Math.cos((H * Math.PI) / 180), b = C * Math.sin((H * Math.PI) / 180);
+	const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+	const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+	const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+	return [4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s, -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s, -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s];
+}
+const inGamut = (rgb) => rgb.every((v) => v >= -1e-4 && v <= 1 + 1e-4);
+function oklchToHex(c) {
+	let lo = 0, hi = c.C;
+	if (!inGamut(oklchToRgb(c))) { for (let i = 0; i < 24; i++) { const mid = (lo + hi) / 2; inGamut(oklchToRgb({ ...c, C: mid })) ? (lo = mid) : (hi = mid); } c = { ...c, C: lo }; }
+	return `#${oklchToRgb(c).map((v) => Math.round(Math.min(1, Math.max(0, toGam(v))) * 255).toString(16).padStart(2, "0")).join("").toUpperCase()}`;
+}
+const lum = (hex) => { const [r, g, b] = [1, 3, 5].map((i) => toLin(Number.parseInt(hex.slice(i, i + 2), 16) / 255)); return 0.2126 * r + 0.7152 * g + 0.0722 * b; };
+const contrast = (a, b) => { const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p); return (x + 0.05) / (y + 0.05); };
+
+const STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+const LIGHT = { 50: 0.975, 100: 0.945, 200: 0.89, 300: 0.81, 400: 0.71, 500: 0.62, 600: 0.545, 700: 0.475, 800: 0.405, 900: 0.335, 950: 0.255 };
+const CHROMA = { 50: 0.14, 100: 0.25, 200: 0.45, 300: 0.7, 400: 0.9, 500: 1, 600: 1, 700: 0.92, 800: 0.8, 900: 0.66, 950: 0.5 };
+
+/* ---------- read theme ---------- */
+const theme = JSON.parse(readFileSync(THEME, "utf8"));
+const fail = (msg) => { console.error(`${inApp ? "twoux.theme.json" : "theme.json"}: ${msg}\nNothing was written.`); process.exit(1); };
+
+// The primary colour is either a TwoUX palette family ("indigo", "blue", "teal"...) or a brand hex.
+let ramp;
+let source;
+if (/^#[0-9a-f]{6}$/i.test(theme.primary)) {
+	const hex = theme.primary.toUpperCase();
+	const c = hexToOklch(hex);
+	const at = STEPS.reduce((best, s) => (Math.abs(LIGHT[s] - c.L) < Math.abs(LIGHT[best] - c.L) ? s : best), 600);
+	const peak = c.C / CHROMA[at];
+	ramp = Object.fromEntries(STEPS.map((s) => [s, s === at ? hex : oklchToHex({ L: LIGHT[s], C: peak * CHROMA[s], H: c.H })]));
+	source = `brand ${hex} (anchored at step ${at})`;
+} else {
+	const palette = readFileSync(PALETTE, "utf8");
+	ramp = Object.fromEntries(STEPS.map((s) => {
+		const m = palette.match(new RegExp(`--color-${theme.primary}-${s}:\\s*(#[0-9A-F]{6})`, "i"));
+		if (!m) fail(`"${theme.primary}" is not a palette family or a #RRGGBB colour.`);
+		return [s, m[1].toUpperCase()];
+	}));
+	source = `palette family "${theme.primary}"`;
+}
+
+/* ---------- pick roles from the ramp, by contrast ---------- */
+const WHITE = "#FFFFFF";
+const darkerFrom = (start) => STEPS.filter((s) => s >= start);
+const primaryStep = darkerFrom(500).find((s) => contrast(ramp[s], WHITE) >= 4.5);
+if (!primaryStep) fail(`no step of ${source} reaches 4.5:1 with white text. Pick a darker or more saturated colour.`);
+const hoverStep = STEPS[Math.min(STEPS.indexOf(primaryStep) + 1, STEPS.length - 1)];
+const inkStep = darkerFrom(hoverStep).find((s) => contrast(ramp[s], WHITE) >= 7) ?? 950;
+const soft = ramp[50];
+const checks = [
+	["White text on primary", contrast(WHITE, ramp[primaryStep]), 4.5],
+	["Accent text on white", contrast(ramp[inkStep], WHITE), 4.5],
+	["Accent text on the selection tint", contrast(ramp[inkStep], soft), 4.5],
+	["Focus ring on white", contrast(ramp[primaryStep], WHITE), 3],
+];
+/* Dark theme: the same brand, re-chosen against the dark surfaces in twoux.css (not a flip). */
+const twouxCss = readFileSync(join(pkg, "src/styles/twoux.css"), "utf8");
+const darkOf = (role) => twouxCss.match(new RegExp(`--color-${role}: light-dark\\([^,]+,\\s*(#[0-9A-F]{6})\\)`, "i"))[1];
+const [DS, DHOVER] = [darkOf("surface"), darkOf("hover")];
+const mix = (a, b, t) => { // oklab mix, as color-mix(in oklab, a t, b)
+	const [p, q] = [hexToOklch(a), hexToOklch(b)].map(({ L, C, H }) => [L, C * Math.cos((H * Math.PI) / 180), C * Math.sin((H * Math.PI) / 180)]);
+	const [L, x, y] = p.map((v, i) => v * t + q[i] * (1 - t));
+	return oklchToHex({ L, C: Math.hypot(x, y), H: (Math.atan2(y, x) * 180) / Math.PI });
+};
+const darkSoft = mix(ramp[500], DS, 0.18);
+const lighterFrom = (start) => STEPS.filter((s) => s <= start).reverse();
+const darkInkStep = lighterFrom(400).find((s) => contrast(ramp[s], DS) >= 7 && contrast(ramp[s], darkSoft) >= 4.5) ?? 50;
+const focusStep = contrast(ramp[primaryStep], DHOVER) >= 3 ? primaryStep : lighterFrom(primaryStep).find((s) => contrast(ramp[s], DHOVER) >= 3) ?? 300;
+checks.push(
+	["Dark: accent text on the surface", contrast(ramp[darkInkStep], DS), 4.5],
+	["Dark: accent text on the selection tint", contrast(ramp[darkInkStep], darkSoft), 4.5],
+	["Dark: focus ring on a hover fill", contrast(ramp[focusStep], DHOVER), 3],
+);
+const failed = checks.filter(([, r, min]) => r < min);
+if (failed.length) fail(failed.map(([n, r, min]) => `${n} is ${r.toFixed(2)}:1, needs ${min}:1`).join("; "));
+
+/* ---------- radii and font ---------- */
+const { button: buttonRadius, ...tiers } = theme.radius ?? {};
+const radius = { xs: 4, sm: 6, md: 8, ...tiers };
+if (buttonRadius !== undefined && buttonRadius !== "pill" && (typeof buttonRadius !== "number" || buttonRadius < 0 || buttonRadius > 16)) fail('radius.button must be a number from 0 to 16, or "pill".');
+const buttonCss = buttonRadius === "pill" ? "9999px" : buttonRadius === undefined ? "var(--radius-sm)" : `${buttonRadius}px`;
+for (const [k, v] of Object.entries(radius)) if (typeof v !== "number" || v < 0 || v > 16) fail(`radius.${k} must be a number from 0 to 16.`);
+if (!(radius.xs <= radius.sm && radius.sm <= radius.md)) fail("radius must grow: xs ≤ sm ≤ md (inside, controls, floating).");
+const font = theme.font ?? "Geist";
+
+/* ---------- motion: tempo scales durations, character sets how much a pop overshoots ---------- */
+const { tempo = 1, character = "standard" } = theme.motion ?? {};
+if (typeof tempo !== "number" || tempo < 0.75 || tempo > 1.25) fail("motion.tempo must be a number from 0.75 (quicker) to 1.25 (calmer). TwoUX stays short because people trigger the same motion all day.");
+const CHARACTERS = {
+	crisp: { ease: "cubic-bezier(0.22, 1, 0.36, 1)", pop: 1.1 },
+	standard: { ease: "cubic-bezier(0.34, 1.56, 0.64, 1)", pop: 1.25 },
+};
+if (!CHARACTERS[character]) fail(`motion.character must be "crisp" or "standard". TwoUX has no expressive character: overshoot on entrances and layout slows down work.`);
+
+/* ---------- write ---------- */
+const css = `/* Generated by twoux theme from ${inApp ? "twoux.theme.json" : "packages/ui/theme.json"} (${source}). Do not edit: change the theme file and run twoux theme. */
+@theme static {
+${STEPS.map((s) => `  --color-brand-${s}: ${ramp[s]};`).join("\n")}
+
+  /* Primary roles, chosen by contrast */
+  --color-primary: var(--color-brand-${primaryStep});        /* ${contrast(WHITE, ramp[primaryStep]).toFixed(2)}:1 with white text */
+  --color-primary-hover: var(--color-brand-${hoverStep});
+  --color-primary-soft: light-dark(var(--color-brand-50), color-mix(in oklab, var(--color-brand-500) 18%, ${DS})); /* selected rows, AI cell tint */
+  --color-primary-ink: light-dark(var(--color-brand-${inkStep}), var(--color-brand-${darkInkStep})); /* accent text, ${contrast(ramp[inkStep], WHITE).toFixed(2)}:1 on white, ${contrast(ramp[darkInkStep], DS).toFixed(2)}:1 on dark */
+  --color-focus: light-dark(var(--color-primary), var(--color-brand-${focusStep})); /* focus ring: ${contrast(ramp[focusStep], DHOVER).toFixed(2)}:1 on a dark hover fill */
+  --color-primary-foreground: var(--color-white);
+
+  /* Corners: inside a control, controls and cards, what floats */
+  --radius-xs: ${radius.xs}px;
+  --radius-sm: ${radius.sm}px;
+  --radius-md: ${radius.md}px;
+  --radius-button: ${buttonCss}; /* buttons only; defaults to sm */
+
+  --font-sans: "${font}", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+
+  /* Motion: tempo scales every --duration-* token; character sets the pop */
+  --motion-tempo: ${tempo};
+  --motion-pop-scale: ${CHARACTERS[character].pop};
+  --ease-pop: ${CHARACTERS[character].ease}; /* ${character} */
+}
+`;
+// Warn when the brand sits close to a status hue: a green brand next to green "Open" badges reads as status.
+const paletteCss = readFileSync(PALETTE, "utf8");
+const hueOf = (name) => hexToOklch(paletteCss.match(new RegExp(`--color-${name}:\\s*(#[0-9A-F]{6})`, "i"))[1]).H;
+const STATUS = { ok: hueOf("green-700"), warn: hueOf("amber-600"), bad: hueOf("red-600") };
+const brandHue = hexToOklch(ramp[primaryStep]).H;
+for (const [name, h] of Object.entries(STATUS)) {
+	const d = Math.min(Math.abs(brandHue - h), 360 - Math.abs(brandHue - h));
+	if (d < 30) console.warn(`  Note: the brand hue is ${Math.round(d)}° from the "${name}" status colour. Primary buttons and ${name} badges may read as the same thing; status always carries a word, but check key screens.`);
+}
+writeFileSync(OUT, css);
+if (inApp) console.log(`Wrote twoux-theme.css. Import it after @twoux/ui/styles.css.`);
+console.log(`Theme: ${source}. Primary step ${primaryStep} (${ramp[primaryStep]}), ink ${inkStep}.`);
+if (/^#/.test(theme.primary) && ramp[primaryStep] !== theme.primary.toUpperCase())
+	console.warn(`  Note: ${theme.primary.toUpperCase()} is too light for white button text (${contrast(theme.primary, WHITE).toFixed(2)}:1), so buttons use the darker ${ramp[primaryStep]}. Your exact colour stays available as --color-brand-* for marks and illustrations.`);
+if (contrast(ramp[primaryStep], DS) < 3) console.warn(`  Note: in dark, primary buttons are ${contrast(ramp[primaryStep], DS).toFixed(2)}:1 against the surface. Their white label carries them (WCAG 1.4.11 exempts labelled buttons), but they will look quieter than in light.`);
+for (const [n, r, min] of checks) console.log(`  ${n}: ${r.toFixed(2)}:1 (needs ${min}:1)`);
+console.log(`  Radius ${radius.xs}/${radius.sm}/${radius.md}px, buttons ${buttonRadius ?? "sm"} · font ${font} · motion tempo ${tempo}, ${character}`);

package/bin/twoux.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// twoux: TwoUX's command line. Run from your project root.
+//   twoux init                              set up this project for AI agents (AGENTS.md, CLAUDE.md, guard, skills, MCP, theme, proposals)
+//   twoux find "<job>"                      which component or pattern fits a job
+//   twoux docs [id]                         list every page, or print one
+//   twoux check [paths…] [--check-links]   lint app code and proposals against TwoUX's rules
+//   twoux theme                             build twoux-theme.css from twoux.theme.json
+//   twoux mcp                               MCP server over stdio, for agents that speak MCP
+//   twoux guard                             Claude Code PreToolUse hook (reads the tool call on stdin)
+const [cmd, ...rest] = process.argv.slice(2);
+const run = { check: "./check.mjs", theme: "./theme.mjs", guard: "./guard.mjs", init: "./init.mjs", docs: "./docs.mjs", find: "./docs.mjs", mcp: "./mcp.mjs" }[cmd];
+if (!run) {
+	console.log(`Usage: twoux <command> [options]
+
+  init [--force] [--principles]      set up this project for AI agents
+  find "<job>"                       which component or pattern fits a job
+  docs [id] [--kind <kind>]          list every page, or print one (docs rules: every rule)
+  check [paths…] [--check-links]     lint app code against TwoUX's rules
+  theme                              build twoux-theme.css from twoux.theme.json
+  mcp                                MCP server over stdio
+  guard                              Claude Code hook, run by init`);
+	process.exit(cmd ? 1 : 0);
+}
+process.argv = [process.argv[0], run, ...(run === "./docs.mjs" ? [cmd] : []), ...rest];
+await import(run);

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@twoux/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Engineering-first design system for complex apps. Makes UI and UX decisions explicit for engineers and AI agents.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles.css": "./src/styles/twoux.css",
+    "./theme.json": "./theme.json",
+    "./agent/*": "./agent/*",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "@radix-ui/react-checkbox": "1.3.2",
+    "@radix-ui/react-dialog": "1.1.14",
+    "@radix-ui/react-dropdown-menu": "2.1.15",
+    "@radix-ui/react-label": "2.1.7",
+    "@radix-ui/react-radio-group": "1.3.7",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@radix-ui/react-switch": "1.2.5",
+    "@radix-ui/react-tabs": "1.1.12",
+    "@radix-ui/react-toggle-group": "1.1.10",
+    "@radix-ui/react-tooltip": "1.2.7",
+    "@xyflow/react": "12.12.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "1.1.1",
+    "d3-geo": "3.1.1",
+    "date-fns": "4.1.0",
+    "lucide-react": "0.525.0",
+    "radix-ui": "1.4.2",
+    "react-day-picker": "9.11.1",
+    "sonner": "2.0.7",
+    "tailwind-merge": "^3.3.1",
+    "topojson-client": "3.1.0",
+    "tw-animate-css": "1.3.5"
+  },
+  "devDependencies": {
+    "@types/d3-geo": "3.1.0",
+    "@types/geojson": "7946.0.16",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@types/topojson-client": "3.1.5",
+    "@types/topojson-specification": "1.0.5",
+    "typescript": "^5.8.3"
+  },
+  "bin": {
+    "twoux": "./bin/twoux.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "agent",
+    "registry",
+    "theme.json",
+    "SHADCN-DIFF.md",
+    "LICENSE.md",
+    "NOTICE.md",
+    "LICENSES"
+  ],
+  "author": "Giulia Pizzignacco <hi@axdexpert.ai>",
+  "homepage": "https://twoux.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axdexpert/twoux.git",
+    "directory": "packages/ui"
+  },
+  "bugs": {
+    "url": "https://github.com/axdexpert/twoux/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
 }