rastack 0.0.24 → 0.0.26

package/dist/tokens/studio.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * The design studio page — a self-contained, dependency-free HTML app that
+ * `rastack design` serves. It **showcases** the design system (colour swatches,
+ * type ramp, spacing, radii, shadows, and live component previews built from the
+ * tokens themselves) and lets you **edit** token values in place — with a live
+ * preview — then save them back to the source, or export the DTCG JSON / CSS.
+ *
+ * Pure: given a themed doc it returns an HTML string, so it renders identically
+ * whether served by the CLI or snapshotted in a test. The page talks to the CLI
+ * server over two tiny endpoints: `POST /save` (persist) and it embeds
+ * everything else it needs inline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderStudio = renderStudio;
+const css_1 = require("./css");
+const resolve_1 = require("./resolve");
+function toView(prefix, tok) {
+    return {
+        path: tok.path,
+        cssVar: (0, resolve_1.cssVarName)(tok.path, prefix),
+        type: tok.type,
+        decl: tok.aliasOf ? `var(${(0, resolve_1.cssVarName)(tok.aliasOf, prefix)})` : (0, css_1.formatCssValue)(tok),
+        literal: (0, css_1.formatCssValue)(tok),
+        aliasOf: tok.aliasOf,
+        description: tok.$description,
+    };
+}
+/** Render the full design-studio HTML document for a themed token set. */
+function renderStudio(themed, options = {}) {
+    const prefix = options.prefix ?? "";
+    const editable = options.editable !== false;
+    const title = options.title ?? "Design System";
+    const resolved = (0, resolve_1.resolveTheme)(themed);
+    const layers = {
+        base: resolved.base.map((t) => toView(prefix, t)),
+    };
+    for (const [name, toks] of Object.entries(resolved.modes)) {
+        layers[name] = toks.map((t) => toView(prefix, t));
+    }
+    const modeNames = Object.keys(resolved.modes);
+    const css = (0, css_1.emitCss)(themed, { prefix });
+    const payload = {
+        title,
+        prefix,
+        editable,
+        defaultMode: resolved.defaultMode ?? null,
+        modeNames,
+        layers,
+        raw: themed,
+    };
+    return page(title, css, payload);
+}
+function page(title, css, payload) {
+    const data = JSON.stringify(payload).replace(/</g, "\\u003c");
+    return `<!doctype html>
+<html lang="en" data-theme="${payload.defaultMode ?? ""}">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(title)} · rastack design</title>
+<style id="tokens-css">${css}</style>
+<style>${STUDIO_CSS}</style>
+</head>
+<body>
+<div id="app"></div>
+<script id="studio-data" type="application/json">${data}</script>
+<script>${STUDIO_JS}</script>
+</body>
+</html>
+`;
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+}
+/* -- The studio's own chrome. Deliberately neutral so it frames, not fights,
+      the design system it is displaying. --------------------------------- */
+const STUDIO_CSS = `
+* { box-sizing: border-box; }
+body { margin: 0; font-family: var(--font-sans, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif);
+  background: #0d1117; color: #e6edf3; -webkit-font-smoothing: antialiased; }
+.studio-header { position: sticky; top: 0; z-index: 10; display: flex; align-items: center; gap: 16px;
+  padding: 14px 24px; background: #161b22ee; backdrop-filter: blur(8px); border-bottom: 1px solid #30363d; }
+.studio-header h1 { font-size: 15px; font-weight: 650; margin: 0; letter-spacing: .2px; }
+.studio-header .spacer { flex: 1; }
+.pill { font: inherit; font-size: 12px; padding: 6px 12px; border-radius: 999px; border: 1px solid #30363d;
+  background: #21262d; color: #e6edf3; cursor: pointer; }
+.pill.active { background: #388bfd33; border-color: #388bfd; color: #cae3ff; }
+.pill:hover { border-color: #58a6ff; }
+.btn { font: inherit; font-size: 12px; font-weight: 600; padding: 6px 14px; border-radius: 6px; border: 1px solid #30363d;
+  background: #21262d; color: #e6edf3; cursor: pointer; }
+.btn.primary { background: #238636; border-color: #2ea043; }
+.btn:disabled { opacity: .5; cursor: default; }
+.layout { max-width: 1180px; margin: 0 auto; padding: 28px 24px 96px; }
+section { margin: 40px 0 0; }
+section > h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .12em; color: #8b949e; margin: 0 0 16px;
+  padding-bottom: 8px; border-bottom: 1px solid #21262d; }
+.grid { display: grid; gap: 14px; grid-template-columns: repeat(auto-fill, minmax(210px, 1fr)); }
+.card { background: #161b22; border: 1px solid #21262d; border-radius: 12px; padding: 14px; }
+.swatch { height: 56px; border-radius: 8px; border: 1px solid #ffffff1a; margin-bottom: 10px; }
+.tok-name { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11.5px; color: #7ee787; word-break: break-all; }
+.tok-meta { font-size: 11px; color: #8b949e; margin-top: 2px; }
+.tok-alias { color: #d2a8ff; }
+.row { display: flex; align-items: center; gap: 8px; margin-top: 10px; }
+.row input[type=text] { flex: 1; min-width: 0; font: inherit; font-family: ui-monospace, monospace; font-size: 12px;
+  padding: 6px 8px; border-radius: 6px; border: 1px solid #30363d; background: #0d1117; color: #e6edf3; }
+.row input[type=color] { width: 34px; height: 30px; padding: 0; border: 1px solid #30363d; border-radius: 6px; background: none; }
+.bar { height: 12px; max-width: 100%; background: var(--_v); border-radius: 4px; }
+.radius-box { height: 56px; background: #388bfd33; border: 1px solid #58a6ff88; }
+.shadow-box { height: 56px; background: #ffffff; border-radius: 8px; margin: 6px 4px 12px; }
+.type-sample { font-size: 20px; margin: 6px 0; color: #e6edf3; }
+.preview { display: flex; flex-wrap: wrap; gap: 16px; align-items: flex-start; }
+.saved-toast { position: fixed; bottom: 20px; left: 50%; transform: translateX(-50%); background: #238636;
+  padding: 10px 18px; border-radius: 8px; font-size: 13px; opacity: 0; transition: opacity .25s; pointer-events: none; }
+.saved-toast.show { opacity: 1; }
+.dim-note { font-size: 11px; color: #6e7681; margin-top: 16px; }
+`;
+/* -- The studio client. Renders sections from the embedded payload, applies
+      edits live to :root, and posts the mutated doc back to the server. ---- */
+const STUDIO_JS = `
+(function () {
+  var data = JSON.parse(document.getElementById("studio-data").textContent);
+  var root = document.documentElement;
+  var activeLayer = data.defaultMode || "base";
+  var app = document.getElementById("app");
+
+  // Deep clone the raw doc so edits are collected without touching the payload.
+  var draft = JSON.parse(JSON.stringify(data.raw));
+  var dirty = false;
+
+  function tokenType(views, path) {
+    for (var i = 0; i < views.length; i++) if (views[i].path === path) return views[i].type;
+  }
+  function setPath(tree, path, value, type) {
+    var segs = path.split(".");
+    var node = tree;
+    for (var i = 0; i < segs.length - 1; i++) { node[segs[i]] = node[segs[i]] || {}; node = node[segs[i]]; }
+    var leaf = node[segs[segs.length - 1]] || {};
+    leaf.$value = value; if (type && !leaf.$type) leaf.$type = type;
+    node[segs[segs.length - 1]] = leaf;
+  }
+  function layerTree(layer) {
+    if (layer === "base") return draft.tokens;
+    draft.modes = draft.modes || {};
+    draft.modes[layer] = draft.modes[layer] || {};
+    return draft.modes[layer];
+  }
+
+  // Apply a layer's declarations to :root so the preview reflects it exactly.
+  function applyLayer(layer) {
+    var views = data.layers[layer] || data.layers.base;
+    views.forEach(function (v) { root.style.setProperty(v.cssVar, v.decl); });
+    root.setAttribute("data-theme", layer === "base" ? "" : layer);
+  }
+
+  function onEdit(view, raw) {
+    root.style.setProperty(view.cssVar, raw);
+    setPath(layerTree(activeLayer), view.path, raw, view.type);
+    dirty = true;
+    var btn = document.getElementById("save-btn");
+    if (btn) btn.disabled = false;
+  }
+
+  function group(views, pred) { return views.filter(pred); }
+
+  function sectionEl(title, nodes) {
+    if (!nodes.length) return null;
+    var s = document.createElement("section");
+    var h = document.createElement("h2"); h.textContent = title; s.appendChild(h);
+    var g = document.createElement("div"); g.className = "grid";
+    nodes.forEach(function (n) { g.appendChild(n); }); s.appendChild(g);
+    return s;
+  }
+
+  function cardShell(view, preview) {
+    var c = document.createElement("div"); c.className = "card";
+    if (preview) c.appendChild(preview);
+    var name = document.createElement("div"); name.className = "tok-name"; name.textContent = view.path;
+    c.appendChild(name);
+    var meta = document.createElement("div"); meta.className = "tok-meta";
+    meta.innerHTML = view.aliasOf ? '→ <span class="tok-alias">' + view.aliasOf + "</span>" : escapeHtml(view.literal);
+    c.appendChild(meta);
+    if (view.description) { var d = document.createElement("div"); d.className = "tok-meta"; d.textContent = view.description; c.appendChild(d); }
+    return c;
+  }
+
+  function editorRow(view, isColor) {
+    if (!data.editable || view.aliasOf) return null;
+    var row = document.createElement("div"); row.className = "row";
+    var text = document.createElement("input"); text.type = "text"; text.value = view.literal;
+    if (isColor) {
+      var color = document.createElement("input"); color.type = "color";
+      try { color.value = toHex(view.literal); } catch (e) {}
+      color.oninput = function () { text.value = color.value; onEdit(view, color.value); };
+      row.appendChild(color);
+    }
+    text.oninput = function () { onEdit(view, text.value); };
+    row.appendChild(text);
+    return row;
+  }
+
+  function render() {
+    var views = data.layers[activeLayer] || data.layers.base;
+    app.innerHTML = "";
+    app.appendChild(header());
+    var wrap = document.createElement("div"); wrap.className = "layout";
+
+    var colors = group(views, function (v) { return v.type === "color"; }).map(function (v) {
+      var sw = document.createElement("div"); sw.className = "swatch"; sw.style.background = "var(" + v.cssVar + ")";
+      var c = cardShell(v, sw); var ed = editorRow(v, true); if (ed) c.appendChild(ed); return c;
+    });
+    add(wrap, sectionEl("Colours", colors));
+
+    var isRadius = function (v) { return /radius|radii|round/i.test(v.path); };
+    var dims = group(views, function (v) { return v.type === "dimension" && !isRadius(v); }).map(function (v) {
+      var bar = document.createElement("div"); bar.className = "bar"; bar.style.width = "var(" + v.cssVar + ")"; bar.style.setProperty("--_v", "var(" + v.cssVar + ")");
+      bar.style.background = "#58a6ff";
+      var c = cardShell(v, bar); var ed = editorRow(v, false); if (ed) c.appendChild(ed); return c;
+    });
+    add(wrap, sectionEl("Spacing & dimensions", dims));
+
+    var radii = group(views, function (v) { return isRadius(v) && v.type !== "color"; });
+    // radii tokens are dimensions too; show a rounded-box preview for the named ones
+    var radiiCards = radii.map(function (v) {
+      var box = document.createElement("div"); box.className = "radius-box"; box.style.borderRadius = "var(" + v.cssVar + ")";
+      return cardShell(v, box);
+    });
+    add(wrap, sectionEl("Radii", radiiCards));
+
+    var shadows = group(views, function (v) { return v.type === "shadow"; }).map(function (v) {
+      var box = document.createElement("div"); box.className = "shadow-box"; box.style.boxShadow = "var(" + v.cssVar + ")";
+      return cardShell(v, box);
+    });
+    add(wrap, sectionEl("Shadows", shadows));
+
+    var fonts = group(views, function (v) { return v.type === "fontFamily" || v.type === "fontWeight"; }).map(function (v) {
+      var s = document.createElement("div"); s.className = "type-sample";
+      if (v.type === "fontFamily") s.style.fontFamily = "var(" + v.cssVar + ")"; else s.style.fontWeight = "var(" + v.cssVar + ")";
+      s.textContent = "The quick brown fox";
+      var c = cardShell(v, s); var ed = editorRow(v, false); if (ed) c.appendChild(ed); return c;
+    });
+    add(wrap, sectionEl("Typography", fonts));
+
+    var known = { color: 1, dimension: 1, shadow: 1, fontFamily: 1, fontWeight: 1 };
+    var other = group(views, function (v) { return !known[v.type]; }).map(function (v) {
+      var c = cardShell(v, null); var ed = editorRow(v, false); if (ed) c.appendChild(ed); return c;
+    });
+    add(wrap, sectionEl("Other tokens", other));
+
+    add(wrap, componentPreview());
+
+    var note = document.createElement("div"); note.className = "dim-note";
+    note.textContent = data.editable
+      ? "Edits apply live. Aliased tokens (→) follow their source; edit the source to change them. Save writes back to the token source."
+      : "Read-only: this source is a module, not JSON. Export to capture edits.";
+    wrap.appendChild(note);
+    app.appendChild(wrap);
+    applyLayer(activeLayer);
+  }
+
+  function componentPreview() {
+    var s = document.createElement("section");
+    var h = document.createElement("h2"); h.textContent = "Components"; s.appendChild(h);
+    var box = document.createElement("div"); box.className = "preview";
+    box.innerHTML =
+      '<button style="font:inherit;font-weight:600;padding:10px 18px;border:none;border-radius:var(--radius-md,8px);' +
+        'background:var(--color-accent,#4F6BFF);color:var(--color-on-accent,#fff);cursor:pointer">Primary action</button>' +
+      '<button style="font:inherit;font-weight:600;padding:10px 18px;border:1px solid var(--color-border,#30363d);' +
+        'border-radius:var(--radius-md,8px);background:transparent;color:var(--color-text,#e6edf3);cursor:pointer">Secondary</button>' +
+      '<div style="padding:16px;border-radius:var(--radius-lg,12px);background:var(--color-surface,#161b22);' +
+        'border:1px solid var(--color-border,#30363d);box-shadow:var(--shadow-md,none);min-width:200px">' +
+        '<div style="font-weight:650;color:var(--color-text,#e6edf3)">Card title</div>' +
+        '<div style="color:var(--color-text-muted,#8b949e);font-size:13px;margin-top:4px">Body copy in the muted text tone.</div></div>';
+    s.appendChild(box);
+    return s;
+  }
+
+  function header() {
+    var h = document.createElement("div"); h.className = "studio-header";
+    var title = document.createElement("h1"); title.textContent = data.title; h.appendChild(title);
+    var layers = ["base"].concat(data.modeNames);
+    layers.forEach(function (layer) {
+      var b = document.createElement("button"); b.className = "pill" + (layer === activeLayer ? " active" : "");
+      b.textContent = layer; b.onclick = function () { activeLayer = layer; render(); };
+      h.appendChild(b);
+    });
+    var sp = document.createElement("div"); sp.className = "spacer"; h.appendChild(sp);
+    var exp = document.createElement("button"); exp.className = "btn"; exp.textContent = "Export JSON";
+    exp.onclick = exportJson; h.appendChild(exp);
+    if (data.editable) {
+      var save = document.createElement("button"); save.className = "btn primary"; save.id = "save-btn";
+      save.textContent = "Save"; save.disabled = !dirty; save.onclick = saveDoc; h.appendChild(save);
+    }
+    return h;
+  }
+
+  function saveDoc() {
+    var btn = document.getElementById("save-btn"); btn.disabled = true; btn.textContent = "Saving…";
+    fetch("/save", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(draft) })
+      .then(function (r) { if (!r.ok) throw new Error(); return r.json(); })
+      .then(function () { dirty = false; btn.textContent = "Save"; toast("Saved & recompiled"); })
+      .catch(function () { btn.disabled = false; btn.textContent = "Save"; toast("Save failed"); });
+  }
+
+  function exportJson() {
+    var blob = new Blob([JSON.stringify(draft, null, 2)], { type: "application/json" });
+    var a = document.createElement("a"); a.href = URL.createObjectURL(blob); a.download = "tokens.json"; a.click();
+  }
+
+  function toast(msg) {
+    var el = document.createElement("div"); el.className = "saved-toast show"; el.textContent = msg; document.body.appendChild(el);
+    setTimeout(function () { el.classList.remove("show"); setTimeout(function () { el.remove(); }, 300); }, 1600);
+  }
+
+  function add(parent, el) { if (el) parent.appendChild(el); }
+  function escapeHtml(s) { return String(s).replace(/[&<>"]/g, function (c) { return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]; }); }
+  function toHex(v) {
+    v = (v || "").trim();
+    if (/^#([0-9a-f]{6})$/i.test(v)) return v;
+    if (/^#([0-9a-f]{3})$/i.test(v)) return "#" + v.slice(1).split("").map(function (c) { return c + c; }).join("");
+    var m = v.match(/rgba?\\(([^)]+)\\)/i);
+    if (m) { var p = m[1].split(",").map(function (x) { return parseInt(x, 10); }); return "#" + p.slice(0, 3).map(function (n) { return ("0" + n.toString(16)).slice(-2); }).join(""); }
+    return "#000000";
+  }
+
+  render();
+})();
+`;

package/dist/tokens/theme.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `defineTheme` — the simple, non-designer entry point.
+ *
+ * State a handful of decisions in plain values — your brand colour, how round
+ * the corners are, which font — and get a **complete** design system back:
+ * colour scales, semantic tokens (background, surface, text, border, accent…),
+ * and both **light and dark** modes, with readable on-colours chosen for you.
+ *
+ * ```ts
+ * import { defineTheme } from "rastack/tokens";
+ *
+ * export default defineTheme({
+ *   brand: "#4F6BFF",     // one colour is enough — we build the 50–950 scale
+ *   radius: "rounded",    // "sharp" | "rounded" | "pill" | a px number
+ *   font: "Inter",
+ * });
+ * ```
+ *
+ * It returns the same {@link ThemedTokens} that `defineTokens` produces, so it
+ * plugs straight into `rastack tokens`, `rastack design`, and `rastack/theme`.
+ * `defineTheme` is sugar over `defineTokens`; reach for the raw DSL only when you
+ * want per-token control. Everything is overridable — pass `colors`, `radius`,
+ * `space`, or `extend` to adjust or add anything.
+ */
+import { ThemedTokens } from "./types";
+export interface ThemeConfig {
+    /** Your main brand colour, as a hex string. The rest is derived from it. */
+    brand: string;
+    /** A secondary accent colour. Defaults to `brand`. */
+    accent?: string;
+    /** The neutral/grey seed used for backgrounds, surfaces, text and borders. */
+    neutral?: string;
+    /** Corner roundness: a keyword or a base radius in px. Default `"rounded"`. */
+    radius?: "sharp" | "rounded" | "pill" | number;
+    /** Body font family (name or stack). Default Inter/system-ui. */
+    font?: string | string[];
+    /** Which modes to generate. Default `"both"`. */
+    appearance?: "light" | "dark" | "both";
+    /** Status colours (sensible defaults provided). */
+    success?: string;
+    danger?: string;
+    warning?: string;
+    /**
+     * Override or add any semantic colour, e.g. `{ accent: "#e11d48" }` or
+     * `{ "text-muted": "#888" }`. Applied on top of the generated palette.
+     */
+    colors?: Record<string, string>;
+    /**
+     * Escape hatch: raw DTCG tokens deep-merged over everything (per mode via
+     * `{ modes: { dark: { … } } }`), for anything the simple config can't express.
+     */
+    extend?: Partial<ThemedTokens>;
+}
+/** Turn a plain intent config into a full themed token document. */
+export declare function defineTheme(config: ThemeConfig): ThemedTokens;

package/dist/tokens/theme.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * `defineTheme` — the simple, non-designer entry point.
+ *
+ * State a handful of decisions in plain values — your brand colour, how round
+ * the corners are, which font — and get a **complete** design system back:
+ * colour scales, semantic tokens (background, surface, text, border, accent…),
+ * and both **light and dark** modes, with readable on-colours chosen for you.
+ *
+ * ```ts
+ * import { defineTheme } from "rastack/tokens";
+ *
+ * export default defineTheme({
+ *   brand: "#4F6BFF",     // one colour is enough — we build the 50–950 scale
+ *   radius: "rounded",    // "sharp" | "rounded" | "pill" | a px number
+ *   font: "Inter",
+ * });
+ * ```
+ *
+ * It returns the same {@link ThemedTokens} that `defineTokens` produces, so it
+ * plugs straight into `rastack tokens`, `rastack design`, and `rastack/theme`.
+ * `defineTheme` is sugar over `defineTokens`; reach for the raw DSL only when you
+ * want per-token control. Everything is overridable — pass `colors`, `radius`,
+ * `space`, or `extend` to adjust or add anything.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTheme = defineTheme;
+const color_1 = require("./color");
+const define_1 = require("./define");
+const resolve_1 = require("./resolve");
+const RADIUS_KEYWORDS = { sharp: 3, rounded: 10, pill: 18 };
+const DEFAULT_FONT = ["Inter", "system-ui", "-apple-system", "Segoe UI", "Roboto", "sans-serif"];
+/** Turn a plain intent config into a full themed token document. */
+function defineTheme(config) {
+    const brand = (0, color_1.scale)(config.brand);
+    const accentSeed = config.accent ?? config.brand;
+    const accent = (0, color_1.scale)(accentSeed);
+    const neutral = (0, color_1.scale)(config.neutral ?? "#64748B");
+    const onAccent = (0, color_1.readableOn)(accentSeed);
+    const baseRadius = typeof config.radius === "number"
+        ? config.radius
+        : RADIUS_KEYWORDS[config.radius ?? "rounded"];
+    const colorScale = (name, s) => Object.fromEntries(Object.entries(s).map(([step, hex]) => [step, { $value: hex }]));
+    // --- base tree (also the light appearance) ------------------------------
+    const base = {
+        color: {
+            $type: "color",
+            brand: colorScale("brand", brand),
+            ...(config.accent ? { "accent-scale": colorScale("accent", accent) } : {}),
+            // Semantic tokens alias the scales, so overriding a scale flows through.
+            accent: { $value: config.accent ? "{color.accent-scale.500}" : "{color.brand.500}" },
+            "accent-strong": { $value: config.accent ? "{color.accent-scale.600}" : "{color.brand.600}" },
+            "on-accent": { $value: onAccent },
+            bg: { $value: "#FFFFFF" },
+            surface: { $value: "#FFFFFF" },
+            "surface-alt": { $value: neutral["100"] },
+            border: { $value: neutral["200"] },
+            text: { $value: neutral["900"] },
+            "text-muted": { $value: neutral["500"] },
+            success: { $value: config.success ?? "#1FA971" },
+            danger: { $value: config.danger ?? "#E5484D" },
+            warning: { $value: config.warning ?? "#F5A623" },
+        },
+        space: {
+            $type: "dimension",
+            xs: { $value: "4px" },
+            sm: { $value: "8px" },
+            md: { $value: "16px" },
+            lg: { $value: "24px" },
+            xl: { $value: "40px" },
+        },
+        radius: {
+            $type: "dimension",
+            sm: { $value: `${Math.round(baseRadius * 0.6)}px` },
+            md: { $value: `${baseRadius}px` },
+            lg: { $value: `${Math.round(baseRadius * 1.6)}px` },
+            xl: { $value: `${Math.round(baseRadius * 2.4)}px` },
+            pill: { $value: "999px" },
+        },
+        font: {
+            family: {
+                $type: "fontFamily",
+                sans: { $value: config.font ?? DEFAULT_FONT },
+            },
+            weight: {
+                $type: "fontWeight",
+                regular: { $value: 400 },
+                medium: { $value: 500 },
+                bold: { $value: 700 },
+            },
+        },
+    };
+    // Apply user colour overrides onto the semantic layer.
+    if (config.colors) {
+        for (const [name, hex] of Object.entries(config.colors)) {
+            base.color[name] = { $value: hex };
+        }
+    }
+    // --- dark appearance: only the tokens that differ ------------------------
+    const dark = {
+        color: {
+            // In dark, the accent reads better a step lighter.
+            accent: { $value: config.accent ? "{color.accent-scale.400}" : "{color.brand.400}" },
+            "accent-strong": { $value: config.accent ? "{color.accent-scale.300}" : "{color.brand.300}" },
+            bg: { $value: neutral["950"] },
+            surface: { $value: neutral["900"] },
+            "surface-alt": { $value: neutral["800"] },
+            border: { $value: neutral["700"] },
+            text: { $value: neutral["50"] },
+            "text-muted": { $value: neutral["400"] },
+        },
+    };
+    const appearance = config.appearance ?? "both";
+    const modes = {};
+    if (appearance !== "light")
+        modes.dark = dark;
+    let themed = {
+        tokens: base,
+        modes,
+        defaultMode: appearance === "dark" ? "dark" : "light",
+    };
+    // dark-only: fold the dark overrides into the base so :root is dark.
+    if (appearance === "dark") {
+        themed = { tokens: (0, resolve_1.mergeTokens)(base, dark), modes: {}, defaultMode: "dark" };
+    }
+    // Escape hatch merges last.
+    if (config.extend) {
+        if (config.extend.tokens)
+            themed.tokens = (0, resolve_1.mergeTokens)(themed.tokens, config.extend.tokens);
+        if (config.extend.modes) {
+            for (const [name, doc] of Object.entries(config.extend.modes)) {
+                themed.modes = themed.modes ?? {};
+                themed.modes[name] = themed.modes[name] ? (0, resolve_1.mergeTokens)(themed.modes[name], doc) : doc;
+            }
+        }
+    }
+    // Normalise through defineTokens so the result is identical in shape.
+    return (0, define_1.defineTokens)(themed);
+}

package/dist/tokens/ts.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Typed-theme emitter — the ergonomic, autocompleted output.
+ *
+ * Emits a `.ts` module exporting a nested `theme` object that mirrors the token
+ * tree, whose leaves are `var(--…)` strings, plus a `TokenPath` union of every
+ * token name. Application code reads `theme.color.brand[500]` (a real CSS
+ * variable reference) with full type-safety and rename-refactoring, while the
+ * actual values live in the emitted CSS and stay swappable per mode.
+ */
+import { ResolvedToken } from "./types";
+export interface TsOptions {
+    prefix?: string;
+}
+/** Emit the typed-theme `.ts` source for a resolved base token list. */
+export declare function emitTs(tokens: ResolvedToken[], options?: TsOptions): string;

package/dist/tokens/ts.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Typed-theme emitter — the ergonomic, autocompleted output.
+ *
+ * Emits a `.ts` module exporting a nested `theme` object that mirrors the token
+ * tree, whose leaves are `var(--…)` strings, plus a `TokenPath` union of every
+ * token name. Application code reads `theme.color.brand[500]` (a real CSS
+ * variable reference) with full type-safety and rename-refactoring, while the
+ * actual values live in the emitted CSS and stay swappable per mode.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitTs = emitTs;
+const resolve_1 = require("./resolve");
+/** A key that is a safe JS identifier can be written bare; otherwise quote it. */
+function keyLiteral(key) {
+    return /^[A-Za-z_$][\w$]*$/.test(key) ? key : JSON.stringify(key);
+}
+/** Build a nested plain object from dotted paths → `var(--…)` leaf strings. */
+function nest(tokens, prefix) {
+    const root = {};
+    for (const tok of tokens) {
+        const segments = tok.path.split(".");
+        let node = root;
+        segments.forEach((seg, i) => {
+            if (i === segments.length - 1) {
+                node[seg] = `var(${(0, resolve_1.cssVarName)(tok.path, prefix)})`;
+            }
+            else {
+                node[seg] = node[seg] ?? {};
+                node = node[seg];
+            }
+        });
+    }
+    return root;
+}
+function serialize(node, indent) {
+    const inner = indent + "  ";
+    const entries = Object.entries(node).map(([key, val]) => {
+        const k = keyLiteral(key);
+        if (typeof val === "string")
+            return `${inner}${k}: ${JSON.stringify(val)},`;
+        return `${inner}${k}: ${serialize(val, inner)},`;
+    });
+    return `{\n${entries.join("\n")}\n${indent}}`;
+}
+/** Emit the typed-theme `.ts` source for a resolved base token list. */
+function emitTs(tokens, options = {}) {
+    const prefix = options.prefix ?? "";
+    const tree = nest(tokens, prefix);
+    const union = tokens.map((t) => `  | ${JSON.stringify(t.path)}`).join("\n") || "  never";
+    return `/* Generated by \`rastack tokens\` — do not edit by hand. */
+
+/** Every design-token path, for type-safe lookups. */
+export type TokenPath =
+${union};
+
+/**
+ * The design system as a typed tree of CSS-variable references.
+ * \`theme.color.brand[500]\` → \`"var(--color-brand-500)"\`.
+ */
+export const theme = ${serialize(tree, "")} as const;
+
+/** The CSS custom-property name for a token path. */
+export function cssVar(path: TokenPath): string {
+  const body = path
+    .split(".")
+    .map((s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase())
+    .join("-")
+    .replace(/[^a-z0-9-]+/g, "-");
+  return ${JSON.stringify(prefix ? `--${prefix}-` : "--")} + body;
+}
+`;
+}