@rojaostudio/ds-core 1.1.0-next.1 → 1.1.0-next.10

package/LICENSE

@@ -19,3 +19,14 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+Arquivos gerados
+
+Os arquivos que esta ferramenta escreve no seu projeto (o tema CSS e o bloco
+entre os marcadores <!-- rojao-ds:start --> e <!-- rojao-ds:end --> em
+CLAUDE.md, AGENTS.md ou .cursorrules) são de quem usa a ferramenta. Você pode
+usá-los, alterá-los e distribuí-los como quiser, sem obrigação de manter aviso
+de licença ou atribuição. A licença MIT acima vale para o código da ferramenta,
+não para o que ela gera.

package/README.md

@@ -9,7 +9,7 @@ npm i @rojaostudio/ds-core
 ```
 
 ```ts
-import { generateTheme, emitCss, emitClaudeMd } from '@rojaostudio/ds-core/generate';
+import { generateRdsTheme, emitRdsCss, emitClaudeMd } from '@rojaostudio/ds-core/generate';
 
 const brand = {
   name: 'acme',
@@ -19,10 +19,13 @@ const brand = {
   fonts: { body: 'inter' },
 };
 
-emitCss(brand);       // theme.css — light and dark, derived from one color
-emitClaudeMd(brand);  // the same brand as rules for Claude Code, Cursor or AGENTS.md
+emitRdsCss(generateRdsTheme(brand)); // rds-theme.css — import it AFTER @rojaostudio/ds/styles/rds.css
+emitClaudeMd(brand);                 // the same brand as rules for Claude Code, Cursor or AGENTS.md
 ```
 
+Or, without writing code: `npx rojao-ds init` (the [`rojao-ds`](https://www.npmjs.com/package/rojao-ds) CLI)
+writes both files into your project.
+
 One color goes in. What comes out is an OKLCH scale with an adaptive contrast floor, semantic
 roles for surface, text, border and brand, and the full light/dark pair — verified against
 WCAG AA on all three surfaces, by test, on every build.
@@ -41,7 +44,7 @@ Components, styles and the React Native target live in
 
 | Entry | What's in it |
 |---|---|
-| `@rojaostudio/ds-core/generate` | `generateTheme`, `emitCss`, `emitClaudeMd`, `buildScale`, `contrastRatio` |
+| `@rojaostudio/ds-core/generate` | `generateRdsTheme`, `rdsThemeFromTable`, `emitRdsCss`, `emitClaudeMd`, `generateTheme`/`emitCss` (1.x), `buildScale`, `contrastRatio` |
 | `@rojaostudio/ds-core/tokens` | `primitives` — the raw palettes and scales |
 | `@rojaostudio/ds-core/recipes` | the reference brand definition |
 | `@rojaostudio/ds-core/themes` | the preset catalogue: a starting palette per niche |

package/dist/{chunk-CFOS2RAD.js → chunk-LP6UA4EW.js}

@@ -675,12 +675,114 @@ function resolveTheme(def, opts) {
   return { tokens: isDark ? __spreadValues(__spreadValues({}, light2), dark) : light2, isDark };
 }
 
+// generate/validate.ts
+var HEX = /^#[0-9a-f]{3,8}$/i;
+var CH = String.raw`(?:[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?(?:%|deg)?|none)`;
+var COLOR_FN = new RegExp(String.raw`^(?:rgba?|oklch)\(\s*${CH}(?:\s*[,/]?\s*${CH}){2,3}\s*\)$`, "i");
+var VAR_NAME = /^[a-z0-9]+(?:[/-][a-z0-9]+)*$/;
+var FONT_BAD = /["';{}\\<>\u0000-\u001f\u007f]/;
+var isSafeColor = (v) => typeof v === "string" && (HEX.test(v) || COLOR_FN.test(v));
+var isSafeVarName = (v) => typeof v === "string" && VAR_NAME.test(v);
+var isSafeFont = (v) => typeof v === "string" && v.trim().length > 0 && v.length <= 100 && !FONT_BAD.test(v);
+var isSafeCustomProperty = (k) => k.startsWith("--") && isSafeVarName(k.slice(2));
+var FONT_ROLE_VAR = "--type-font-mono";
+function preview(v) {
+  var _a;
+  const s = typeof v === "string" ? v : (_a = JSON.stringify(v)) != null ? _a : String(v);
+  const one = s.replace(/[\r\n\t]+/g, " ");
+  return JSON.stringify(one.length > 60 ? `${one.slice(0, 60)}\u2026` : one);
+}
+var RdsValidationError = class extends Error {
+  constructor(where, problems) {
+    super(`${where}: invalid input
+  ${problems.join("\n  ")}`);
+    this.problems = problems;
+    this.name = "RdsValidationError";
+  }
+};
+function collector(where) {
+  const problems = [];
+  return {
+    problems,
+    color(field, v) {
+      if (!isSafeColor(v)) problems.push(`${field}: ${preview(v)} is not a colour (hex, rgb(), rgba() or oklch())`);
+    },
+    name(field, v) {
+      if (!isSafeVarName(v)) problems.push(`${field}: ${preview(v)} is not a valid name (lowercase letters, digits, "-" and "/")`);
+    },
+    font(field, v) {
+      if (!isSafeFont(v)) problems.push(`${field}: ${preview(v)} is not a valid font family (no quotes, ";", braces, "\\" or line breaks)`);
+    },
+    done() {
+      if (problems.length) throw new RdsValidationError(where, problems);
+    }
+  };
+}
+function assertSafeTheme(theme, where) {
+  const c = collector(where);
+  if (!theme || typeof theme !== "object") {
+    c.problems.push("the theme is not an object");
+    c.done();
+  }
+  const check = (label, map, fontRole) => {
+    if (!map || typeof map !== "object" || Array.isArray(map)) {
+      c.problems.push(`${label}: not an object`);
+      return;
+    }
+    for (const [k, v] of Object.entries(map)) {
+      if (!isSafeCustomProperty(k)) {
+        c.problems.push(`${label}: ${preview(k)} is not a valid CSS variable name`);
+        continue;
+      }
+      if (fontRole && k === FONT_ROLE_VAR) c.font(`${label}.${k}`, v);
+      else c.color(`${label}.${k}`, v);
+    }
+  };
+  for (const mode of ["light", "dark", "brand"]) check(mode, theme[mode], true);
+  if (theme.vars !== void 0) check("vars", theme.vars, false);
+  c.done();
+}
+var isSafeSelectorList = (v) => (
+  // eslint-disable-next-line no-control-regex -- control characters are exactly what is refused
+  typeof v === "string" && v.trim().length > 0 && !/[{};\\<@\u0000-\u001f\u007f]|\/\*|\*\//.test(v)
+);
+function oneLine(v, max = 200) {
+  if (typeof v !== "string") return "";
+  let s = v.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, " ").replace(/[<>`]/g, "").replace(/rojao-ds:(start|end)/gi, "").replace(/\s+/g, " ").trim();
+  if (s.length > max) s = `${s.slice(0, max - 1).trimEnd()}\u2026`;
+  return s;
+}
+
 // generate/rdsTheme.ts
 var palettes = primitives.color;
 var WHITE = "#ffffff";
 var BLACK = "#000000";
 var black = (pct) => BLACK + Math.round(pct / 100 * 255).toString(16).padStart(2, "0");
 var white = (pct) => WHITE + Math.round(pct / 100 * 255).toString(16).padStart(2, "0");
+var PALETTE_STEPS2 = /* @__PURE__ */ new Set([...SCALE_STEPS.map(String), "950"]);
+function checkPalettes(custom, where) {
+  if (custom === void 0) return;
+  const c = collector(where);
+  if (!custom || typeof custom !== "object" || Array.isArray(custom)) {
+    c.problems.push("palettes: not an object");
+    c.done();
+  }
+  for (const [name, value] of Object.entries(custom)) {
+    if (!/^[a-z][a-z0-9]*$/i.test(name)) {
+      c.problems.push(`palettes: ${preview(name)} is not a valid palette name (letters and digits)`);
+      continue;
+    }
+    if (typeof value === "string") {
+      if (!isHex(value)) c.problems.push(`palettes.${name}: ${preview(value)} is not a hex colour`);
+    } else if (value && typeof value === "object" && !Array.isArray(value)) {
+      for (const [step2, v] of Object.entries(value)) {
+        if (!PALETTE_STEPS2.has(step2)) c.problems.push(`palettes.${name}: ${preview(step2)} is not a scale step (50\u2013900)`);
+        else c.color(`palettes.${name}.${step2}`, v);
+      }
+    } else c.problems.push(`palettes.${name}: expected a hex or a scale of steps 50\u2013900`);
+  }
+  c.done();
+}
 function palette(name, custom) {
   const own = custom == null ? void 0 : custom[name];
   if (typeof own === "string") {
@@ -705,6 +807,77 @@ function ramp(c, custom) {
   return { base: hex, scale: buildScale(hex) };
 }
 var on = (bg) => onColor(bg);
+var AA = 4.5;
+var NON_TEXT = 3;
+var readsOn = (fg, bgs, min = AA) => bgs.every((bg) => contrastRatio(fg, bg) >= min);
+function readableFrom(base, scale, bgs, toward, fallback, min = AA) {
+  var _a;
+  if (readsOn(base, bgs, min)) return base;
+  const lb = relativeLuminance(base);
+  const steps = SCALE_STEPS.map((s2) => scale[s2]).filter((c) => !!c && isHex(c)).filter((c) => toward === "darker" ? relativeLuminance(c) < lb : relativeLuminance(c) > lb).sort((a, b) => Math.abs(relativeLuminance(a) - lb) - Math.abs(relativeLuminance(b) - lb));
+  const step2 = steps.find((c) => readsOn(c, bgs, min));
+  if (step2) return step2;
+  const [h, s, l0] = hexToHsl((_a = steps[steps.length - 1]) != null ? _a : base);
+  for (let l = l0; toward === "darker" ? l >= 0 : l <= 100; l += toward === "darker" ? -2 : 2) {
+    const c = hslToHex(h, s, l);
+    if (readsOn(c, bgs, min)) return c;
+  }
+  return fallback;
+}
+function stateFills(scale, fill, text, preferred) {
+  const lf = relativeLuminance(fill);
+  const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+  const ramp2 = SCALE_STEPS.map((s) => scale[s]).filter((c) => !!c && isHex(c)).map((c) => c.toLowerCase()).sort((a, b) => relativeLuminance(a) - relativeLuminance(b));
+  const beyond = [];
+  if (ramp2.length) {
+    const [hd, sd, ld] = hexToHsl(ramp2[0]);
+    for (let x = ld - 3; x >= 0; x -= 3) beyond.push(hslToHex(hd, sd, x));
+    const [hl, sl, ll] = hexToHsl(ramp2[ramp2.length - 1]);
+    for (let x = ll + 3; x <= 100; x += 3) beyond.push(hslToHex(hl, sl, x));
+  }
+  const steps = [.../* @__PURE__ */ new Set([...ramp2, ...beyond.map((c) => c.toLowerCase())])].filter(
+    (c) => !same(c, fill) && relativeLuminance(c) !== lf
+  );
+  const side = (dir2) => steps.filter((c) => Math.sign(relativeLuminance(c) - lf) === dir2).sort((a, b) => Math.abs(relativeLuminance(a) - lf) - Math.abs(relativeLuminance(b) - lf));
+  const carrying = (list) => {
+    const out = [];
+    for (const c of list) {
+      if (contrastRatio(text, c) < AA) break;
+      out.push(c);
+    }
+    return out;
+  };
+  const awayFromText = relativeLuminance(text) <= lf ? 1 : -1;
+  const lp = relativeLuminance(preferred[0]);
+  const dir = lp === lf ? awayFromText : lp > lf ? 1 : -1;
+  const n = preferred.length;
+  for (const d of [dir, -dir]) {
+    const all = side(d);
+    const ok2 = carrying(all);
+    if (ok2.length < n) continue;
+    const wants = preferred.map((p, i) => {
+      const k = d === dir ? all.findIndex((c) => same(c, p)) : -1;
+      return k >= 0 ? k : i;
+    });
+    const order = wants.map((_, i) => i).sort((x, y) => wants[x] - wants[y] || x - y);
+    const idx = new Array(n);
+    let next = 0;
+    order.forEach((i, rank) => {
+      idx[i] = Math.min(Math.max(wants[i], next), ok2.length - (n - rank));
+      next = idx[i] + 1;
+    });
+    return idx.map((k) => ok2[k]);
+  }
+  const ok = [...carrying(side(dir)), ...carrying(side(-dir))];
+  return preferred.map((p, i) => {
+    var _a;
+    return (_a = ok[i]) != null ? _a : p;
+  });
+}
+var defaultWarn = (m) => {
+  var _a;
+  return (_a = globalThis.console) == null ? void 0 : _a.warn(m);
+};
 var ROLES = [
   ["colors/primary/light", "d", "b"],
   ["colors/primary/default", "d", "b"],
@@ -808,12 +981,19 @@ var ROLES = [
   ["colors/state/info-strong", "d", "d"],
   ["colors/state/neutral-strong", "d", "d"],
   ["text/on/primary-subtle", "d", "b"],
-  ["surface/tint/subtle", "d", "b"]
+  ["surface/tint/subtle", "d", "b"],
+  ["border/error", "d", "d"]
 ];
+var awayFrom = (bg) => contrastRatio(bg, BLACK) >= contrastRatio(bg, WHITE) ? "darker" : "lighter";
 var TINT_DEFAULT = 200;
 var lighterStep = (s) => s - 100 ;
 var roleVar = (role) => `--${role.replaceAll("/", "-")}`;
-function generateRdsTheme(def) {
+function generateRdsTheme(def, opts = {}) {
+  var _a, _b;
+  const warn = (_a = opts.warn) != null ? _a : defaultWarn;
+  const where = `generateRdsTheme(${preview(def == null ? void 0 : def.name)})`;
+  if (!(def == null ? void 0 : def.brand) || typeof def.brand !== "object") throw new Error(`${where}: brand is missing`);
+  checkPalettes(def.palettes, where);
   const b = def.brand;
   const own = def.palettes;
   const P = ramp(b.primary, own);
@@ -823,7 +1003,15 @@ function generateRdsTheme(def) {
   const L = palette("blue");
   const red = palette("red"), green = palette("green"), orange = palette("orange");
   const teal = palette("teal"), purple = palette("purple");
-  const heading = b.heading ? ramp(b.heading, own).base : P.base;
+  const lightBgs = [WHITE, N[100]];
+  let heading;
+  if (b.heading) {
+    heading = ramp(b.heading, own).base;
+    if (!readsOn(heading, lightBgs)) {
+      const worst = Math.min(...lightBgs.map((bg) => contrastRatio(heading, bg)));
+      warn(`generateRdsTheme(${def.name}): heading ${heading} is ${worst.toFixed(2)}:1 on surface/card or surface/page (AA asks 4.5:1). Kept as given.`);
+    }
+  } else heading = readableFrom(P.base, P.scale, lightBgs, "darker", BLACK);
   const invert = b.invert ? ramp(b.invert, own).base : WHITE;
   const l = {
     "colors/primary/light": P.scale[500],
@@ -860,13 +1048,12 @@ function generateRdsTheme(def) {
     "border/strong-hover": N[600],
     "surface/tint/default": A.scale[TINT_DEFAULT],
     "surface/tint/strong": A.scale[300],
-    "text/on/tint": BLACK,
     // Light selection fill (pressed Toggle, choice tile): one step lighter than the default tint
     // (200 → 100, 100 → 50).
     "surface/tint/subtle": A.scale[lighterStep(TINT_DEFAULT)],
     "surface/action/default": L[100],
     "surface/action/strong": L[200],
-    "text/on/action-tonal": P.scale[700],
+    "text/on/action-tonal": readableFrom(P.scale[700], P.scale, [L[100]], "darker", BLACK),
     "surface/lift/action": P.scale[50],
     "surface/lift/action-strong": L[100],
     "surface/band/action": L[100],
@@ -901,8 +1088,7 @@ function generateRdsTheme(def) {
     "text/warning": orange[700],
     "surface/neutral": N[100],
     "text/neutral": N[800],
-    "chart/series/1": P.scale[600],
-    "chart/series/2": orange[500],
+    "chart/series/2": orange[600],
     "chart/series/3": teal[500],
     "chart/series/4": purple[500],
     "chart/series/5": green[500],
@@ -927,8 +1113,19 @@ function generateRdsTheme(def) {
     ["colors/state/neutral", "text/on/neutral"],
     ["surface/cover", "text/on/cover"],
     ["surface/lift/action", "text/on/lift-action"],
-    ["colors/primary/dark", "text/on/primary-strong"]
+    ["colors/primary/dark", "text/on/primary-strong"],
+    ["surface/tint/default", "text/on/tint"]
   ]) l[text] = on(l[fill]);
+  [l["colors/primary/active"]] = stateFills(P.scale, l["colors/primary/default"], l["text/on/primary"], [l["colors/primary/active"]]);
+  [l["colors/secondary/hover"], l["colors/secondary/active"]] = stateFills(
+    S.scale,
+    l["colors/secondary/default"],
+    l["text/on/secondary"],
+    [l["colors/secondary/hover"], l["colors/secondary/active"]]
+  );
+  [l["colors/accent/hover"]] = stateFills(A.scale, l["colors/accent/default"], l["text/on/accent"], [l["colors/accent/hover"]]);
+  l["border/error"] = readableFrom(l["colors/state/error"], red, [l["surface/card"]], awayFrom(l["surface/card"]), BLACK, NON_TEXT);
+  l["chart/series/1"] = readableFrom(P.scale[600], P.scale, [l["surface/card"]], awayFrom(l["surface/card"]), BLACK, NON_TEXT);
   l["logo/primary"] = l["colors/primary/default"];
   l["logo/signature"] = l["colors/primary/default"];
   l["logo/accent"] = l["colors/accent/logo"];
@@ -945,7 +1142,7 @@ function generateRdsTheme(def) {
     "border/default": N[800],
     "border/strong": N[500],
     "border/strong-hover": N[400],
-    "text/heading": N[50],
+    "text/heading": readableFrom(N[50], N, [N[900]], "lighter", WHITE),
     "text/body": N[100],
     "text/muted": N[300],
     "text/subtle": N[400],
@@ -972,15 +1169,13 @@ function generateRdsTheme(def) {
     "colors/accent/mark": A.scale[300],
     "surface/tint/default": A.scale[900],
     "surface/tint/strong": A.scale[800],
-    "text/on/tint": WHITE,
     // No step below 900 in dark: subtle is the default tint.
     "surface/tint/subtle": A.scale[900],
     "surface/action/default": L[900],
     "surface/action/strong": L[800],
-    "text/on/action-tonal": P.scale[200],
+    "text/on/action-tonal": readableFrom(P.scale[200], P.scale, [L[900]], "lighter", WHITE),
     "surface/lift/action": P.scale[800],
     "surface/lift/action-strong": P.scale[700],
-    "text/on/lift-action": WHITE,
     "colors/state/error-strong": red[400],
     "colors/state/success-strong": green[300],
     "colors/state/warning-strong": orange[400],
@@ -995,7 +1190,6 @@ function generateRdsTheme(def) {
     "text/warning": orange[300],
     "surface/neutral": N[800],
     "text/neutral": N[200],
-    "chart/series/1": P.scale[400],
     "chart/series/2": orange[400],
     "chart/series/3": teal[400],
     "chart/series/4": purple[400],
@@ -1014,12 +1208,28 @@ function generateRdsTheme(def) {
     ["colors/secondary/default", "text/on/secondary"],
     ["colors/accent/default", "text/on/accent"],
     ["colors/accent/mark", "text/on/accent-mark"],
-    ["colors/primary/dark", "text/on/primary-strong"]
+    ["colors/primary/dark", "text/on/primary-strong"],
+    ["surface/tint/default", "text/on/tint"],
+    ["surface/lift/action", "text/on/lift-action"]
   ]) d[text] = on(d[fill]);
+  [d["colors/primary/active"]] = stateFills(P.scale, d["colors/primary/default"], d["text/on/primary"], [d["colors/primary/active"]]);
+  [d["colors/secondary/hover"], d["colors/secondary/active"]] = stateFills(
+    S.scale,
+    d["colors/secondary/default"],
+    d["text/on/secondary"],
+    [d["colors/secondary/hover"], d["colors/secondary/active"]]
+  );
+  [d["colors/accent/hover"]] = stateFills(A.scale, d["colors/accent/default"], d["text/on/accent"], [d["colors/accent/hover"]]);
+  d["border/error"] = readableFrom(d["colors/state/error-strong"], red, [d["surface/card"]], awayFrom(d["surface/card"]), WHITE, NON_TEXT);
+  d["chart/series/1"] = readableFrom(P.scale[400], P.scale, [d["surface/card"]], awayFrom(d["surface/card"]), WHITE, NON_TEXT);
   const plate = l["colors/primary/default"];
   const ink = on(plate);
   const inkA = ink === WHITE ? white : black;
   const antiInk = ink === WHITE ? black : white;
+  const lp = relativeLuminance(plate);
+  const isPlate = (c) => c.toLowerCase() === plate.toLowerCase();
+  const plateCard = P.scale[800] && !isPlate(P.scale[800]) && contrastRatio(ink, P.scale[800]) >= AA ? P.scale[800] : (_b = SCALE_STEPS.map((st) => P.scale[st]).filter((c) => !!c && isHex(c) && !isPlate(c)).sort((a, b2) => Math.abs(relativeLuminance(a) - lp) - Math.abs(relativeLuminance(b2) - lp)).find((c) => contrastRatio(ink, c) >= AA)) != null ? _b : plate;
+  const onPrimaryStrong = contrastRatio(plate, P.scale[100]) >= AA ? plate : on(P.scale[100]);
   const br = {
     "colors/primary/light": P.scale[300],
     "colors/primary/default": ink,
@@ -1033,7 +1243,7 @@ function generateRdsTheme(def) {
     "text/body": ink,
     "text/link": contrastRatio(l["colors/accent/invert"], plate) >= 4.5 ? l["colors/accent/invert"] : ink,
     "surface/page": plate,
-    "surface/card": l["colors/primary/light"],
+    "surface/card": plateCard,
     "surface/panel": plate,
     "border/default": inkA(20),
     "surface/tint/default": inkA(10),
@@ -1055,7 +1265,7 @@ function generateRdsTheme(def) {
     "surface/lift/action": inkA(10),
     "text/on/lift-action": ink,
     "surface/lift/action-strong": inkA(20),
-    "text/on/primary-strong": plate,
+    "text/on/primary-strong": onPrimaryStrong,
     "text/subtle": inkA(60),
     "surface/muted": inkA(10),
     "surface/muted-strong": inkA(20),
@@ -1063,11 +1273,19 @@ function generateRdsTheme(def) {
     "border/strong-hover": inkA(80),
     "text/on/primary-subtle": inkA(30)
   };
+  [br["colors/primary/active"]] = stateFills(P.scale, br["colors/primary/default"], br["text/on/primary"], [br["colors/primary/active"]]);
+  [br["colors/secondary/hover"], br["colors/secondary/active"]] = stateFills(
+    S.scale,
+    br["colors/secondary/default"],
+    br["text/on/secondary"],
+    [br["colors/secondary/hover"], br["colors/secondary/active"]]
+  );
+  const brandError = readableFrom(red[300], red, [plateCard], awayFrom(plateCard), ink, NON_TEXT);
   const out = { light: {}, dark: {}, brand: {} };
   const pick = (src, role) => {
-    var _a;
+    var _a2;
     const table = src === "l" ? l : src === "d" ? d : br;
-    const v = (_a = table[role]) != null ? _a : l[role];
+    const v = (_a2 = table[role]) != null ? _a2 : l[role];
     if (v === void 0) throw new Error(`rdsTheme: no value for "${role}"`);
     return v;
   };
@@ -1076,25 +1294,65 @@ function generateRdsTheme(def) {
     out.dark[roleVar(role)] = pick(darkSrc, role);
     out.brand[roleVar(role)] = pick(brandSrc, role);
   }
+  out.brand[roleVar("border/error")] = brandError;
+  assertSafeTheme(out, where);
   return out;
 }
+var RDS_SCOPE_SELECTORS = [
+  ":root",
+  ".ds-scope",
+  "[data-rds-scope]",
+  ".dark",
+  "[data-rds-mode]",
+  ".ds-plate",
+  "[data-rds-plate]"
+];
+var RDS_TOKEN_SCOPE = RDS_SCOPE_SELECTORS.join(", ");
+var split = (list) => list.split(",").map((s) => s.trim()).filter(Boolean);
+var rootAnchored = (sel) => /^(:root|html)(?![\w-])/i.test(sel);
+var subject = (sel) => {
+  var _a;
+  return (_a = sel.trim().split(/\s*[>+~]\s*|\s+/).pop()) != null ? _a : sel;
+};
+var COVERING = /\.(ds-scope|dark|ds-plate)(?![\w-])|\[\s*data-rds-(scope|mode|plate)\s*([~|^$*]?=[^\]]*)?\]/;
+var covered = (sel) => {
+  const s = subject(sel);
+  return /^(:root|html)(?![\w-])/i.test(s) || COVERING.test(s);
+};
 function emitRdsCss(theme, opts = {}) {
   var _a, _b, _c;
-  const scope = (_a = opts.scope) != null ? _a : ":root, .ds-scope";
-  const dark = (_b = opts.dark) != null ? _b : ".dark";
-  const plate = (_c = opts.plate) != null ? _c : ".ds-plate";
-  const block2 = (sel, map, only) => {
+  assertSafeTheme(theme, "emitRdsCss");
+  const badSel = ["scope", "dark", "plate"].filter((k) => opts[k] !== void 0 && !isSafeSelectorList(opts[k]));
+  if (badSel.length)
+    throw new Error(
+      `emitRdsCss: invalid selector in ${badSel.map((k) => `${k} ${preview(opts[k])}`).join(", ")} (no braces, ";", comments, backslash, "@", "<" or line breaks).`
+    );
+  const scopes = split((_a = opts.scope) != null ? _a : ":root, .ds-scope, [data-rds-scope]");
+  const darks = split((_b = opts.dark) != null ? _b : '.dark, [data-rds-mode="dark"]');
+  const plates = split((_c = opts.plate) != null ? _c : ".ds-plate, [data-rds-plate]");
+  const block2 = (sels, map, only) => {
     const lines = Object.entries(map).filter(([k, v]) => !only || only[k] !== v).map(([k, v]) => `  ${k}: ${k === "--type-font-mono" ? `"${v}", monospace` : v};`);
-    return `${sel} {
+    return `${sels.join(", ")} {
 ${lines.join("\n")}
 }`;
   };
-  const scopes = scope.split(",").map((s) => s.trim());
-  const darkSel = scopes.map((s) => s === ":root" ? `:root${dark}, ${dark}` : `${s}${dark}, ${dark} ${s}`).join(", ");
+  const darkSels = scopes.flatMap(
+    (s) => darks.flatMap((d) => {
+      if (rootAnchored(d)) return s === ":root" ? [d] : [`${d} ${s}`];
+      return s === ":root" ? [`:root${d}`, d] : [`${s}${d}`, `${d} ${s}`];
+    })
+  );
+  if (!opts.allowUncovered) {
+    const bad = [...new Set([...scopes, ...darkSels, ...plates].filter((sel) => !covered(sel)))];
+    if (bad.length)
+      throw new Error(
+        `emitRdsCss: ${bad.map((b) => `"${b}"`).join(", ")} ${bad.length > 1 ? "are" : "is"} not covered by the component tokens of @rojaostudio/ds, redeclared only on ${RDS_TOKEN_SCOPE}. The components inside would keep the colours resolved at :root. Anchor the selector at the root (':root[data-theme="dark"]', as next-themes sets it on <html>), or add the attribute the tokens cover: data-rds-scope on a scope ('.my-scope[data-rds-scope]'), data-rds-mode on a dark element ('[data-rds-mode="dark"]'), data-rds-plate on a plate. Pass allowUncovered: true only for a theme without the components.`
+      );
+  }
   return [
-    block2(scope, theme.light),
-    block2(darkSel, theme.dark, theme.light),
-    block2(plate, theme.brand, theme.light)
+    block2(scopes, __spreadValues(__spreadValues({}, theme.light), theme.vars)),
+    block2(darkSels, theme.dark, theme.light),
+    block2(plates, theme.brand, theme.light)
   ].join("\n\n") + "\n";
 }
 function rdsContrast(theme, mode, fg, bg) {
@@ -1102,6 +1360,121 @@ function rdsContrast(theme, mode, fg, bg) {
   if (!/^#[0-9a-f]{6}$/i.test(a) || !/^#[0-9a-f]{6}$/i.test(c)) return null;
   return contrastRatio(a, c);
 }
+var RDS_CONTRAST_PAIRS = [
+  ["text/heading", "surface/page"],
+  ["text/heading", "surface/card"],
+  ["text/body", "surface/page"],
+  ["text/body", "surface/card"],
+  ["text/muted", "surface/card"],
+  ["text/link", "surface/card"],
+  ["text/on/primary", "colors/primary/default"],
+  ["text/on/primary", "colors/primary/active"],
+  ["text/on/secondary", "colors/secondary/default"],
+  ["text/on/secondary", "colors/secondary/hover"],
+  ["text/on/secondary", "colors/secondary/active"],
+  ["text/on/accent", "colors/accent/default"],
+  ["text/on/accent", "colors/accent/hover"],
+  ["text/on/accent-mark", "colors/accent/mark"],
+  ["text/on/tint", "surface/tint/default"],
+  ["text/on/action-tonal", "surface/action/default"],
+  ["text/on/lift-action", "surface/lift/action"],
+  ["text/on/primary-strong", "colors/primary/dark"],
+  ["text/on/cover", "surface/cover"],
+  ["text/on/error", "colors/state/error"],
+  ["text/on/success", "colors/state/success"],
+  ["text/on/info", "colors/state/info"],
+  ["text/on/warning", "colors/state/warning"],
+  ["text/on/neutral", "colors/state/neutral"],
+  ["text/error", "surface/error"]
+];
+function rdsContrastReport(theme) {
+  const out = [];
+  for (const mode of ["light", "dark", "brand"])
+    for (const [fg, bg] of RDS_CONTRAST_PAIRS) {
+      const ratio = rdsContrast(theme, mode, fg, bg);
+      if (ratio !== null && ratio < AA) out.push({ mode, fg, bg, ratio: Math.round(ratio * 100) / 100 });
+    }
+  return out;
+}
+var isColourRef = (v) => /^[a-z][a-z0-9-]*\/[a-z]?\d+$/i.test(v);
+var ADDED_ROLES = {
+  // Figma: light → base colors/state/error, dark → base dark/colors/state/error-strong, brand → base dark/text/error.
+  "border/error": { light: "colors/state/error", dark: "colors/state/error-strong", brand: "text/error" }
+};
+function rdsThemeFromTable(table, opts = {}) {
+  var _a, _b, _c;
+  const where = `rdsThemeFromTable(${preview(table == null ? void 0 : table.name)})`;
+  if (!table || typeof table !== "object") throw new Error(`${where}: the table is not an object`);
+  const check = collector(where);
+  if (!table.primitives || typeof table.primitives !== "object" || Array.isArray(table.primitives))
+    check.problems.push("primitives: not an object");
+  else
+    for (const [name, value] of Object.entries(table.primitives)) {
+      check.name(`primitives ${preview(name)}`, name);
+      check.color(`primitives.${name}`, value);
+    }
+  if (table.vars !== void 0) {
+    if (!table.vars || typeof table.vars !== "object" || Array.isArray(table.vars)) check.problems.push("vars: not an object");
+    else
+      for (const [name, value] of Object.entries(table.vars)) {
+        check.name(`vars ${preview(name)}`, name);
+        if (typeof value !== "string") check.problems.push(`vars.${name}: not a string`);
+      }
+  }
+  check.done();
+  const out = { light: {}, dark: {}, brand: {} };
+  const problems = [];
+  const derived = /* @__PURE__ */ new Set();
+  for (const mode of ["light", "dark", "brand"]) {
+    const roles = (_a = table.modes) == null ? void 0 : _a[mode];
+    if (!roles) {
+      problems.push(`mode "${mode}" is missing`);
+      continue;
+    }
+    for (const [role] of ROLES) {
+      let ref2 = roles[role];
+      const added = (_b = ADDED_ROLES[role]) == null ? void 0 : _b[mode];
+      if (ref2 === void 0 && added && roles[added] !== void 0) {
+        ref2 = roles[added];
+        derived.add(role);
+      }
+      if (ref2 === void 0) problems.push(`${mode}: role "${role}" is missing`);
+      else if (isColourRef(ref2)) {
+        const value = table.primitives[ref2];
+        if (value === void 0) problems.push(`${mode}: "${role}" points to unknown primitive "${ref2}"`);
+        else out[mode][roleVar(role)] = value.toLowerCase();
+      } else out[mode][roleVar(role)] = ref2;
+    }
+  }
+  const valueOf = (field, ref2) => {
+    if (!isColourRef(ref2)) return ref2;
+    const value = table.primitives[ref2];
+    if (value === void 0) problems.push(`${field} points to unknown primitive "${ref2}"`);
+    return value == null ? void 0 : value.toLowerCase();
+  };
+  if (table.vars) {
+    out.vars = {};
+    for (const [name, ref2] of Object.entries(table.vars)) {
+      const value = valueOf(`var "${name}"`, ref2);
+      if (value !== void 0) out.vars[roleVar(name)] = value;
+    }
+  }
+  if (problems.length) throw new Error(`${where}:
+  ${problems.join("\n  ")}`);
+  assertSafeTheme(out, where);
+  const warn = (_c = opts.warn) != null ? _c : defaultWarn;
+  if (derived.size)
+    warn(
+      `${where}: the table was exported before ${[...derived].map((r) => `"${r}"`).join(", ")} existed in the [RDS] theme. Taken from the tokens Figma aliases it to (` + [...derived].map((r) => Object.entries(ADDED_ROLES[r]).map(([m, src]) => `${m}: ${src}`).join(", ")).join("; ") + `). Export the table again with figma/export-brand.js.`
+    );
+  const fails = rdsContrastReport(out);
+  if (fails.length)
+    warn(
+      `${where}: ${fails.length} text pair(s) below 4.5:1
+  ` + fails.map((f) => `${f.mode}: ${f.fg} on ${f.bg} ${f.ratio}:1`).join("\n  ")
+    );
+  return out;
+}
 
 // generate/emitCss.ts
 var SECTIONS = [
@@ -1174,153 +1547,175 @@ ${lightBlock}${darkBlock}
 }
 
 // generate/emitClaudeMd.ts
-function resolveColor(v) {
-  var _a, _b;
-  if (!v) return v;
-  if (v.startsWith("color-mix")) {
-    const mix = v.match(/var\(--color-([a-zA-Z]+)(?:-(\d+))?\)\s+(\d+)%/);
-    return mix ? `${mix[1]}${mix[2] ? "-" + mix[2] : ""} a ${mix[3]}%` : v;
-  }
-  const scale = v.match(/var\(--color-([a-zA-Z]+)-(\d+)\)/);
-  if (scale) {
-    const pal = primitives.color[scale[1]];
-    return (_a = pal == null ? void 0 : pal[scale[2]]) != null ? _a : v;
-  }
-  const flat = v.match(/var\(--color-(white|black)\)/);
-  if (flat) return (_b = primitives.color[flat[1]]) != null ? _b : v;
-  return v;
-}
-var TOKEN_DOCS = [
-  { key: "--brand-primary", use: "bot\xE3o prim\xE1rio, fills de marca" },
-  { key: "--brand-on-primary", use: "texto/\xEDcone sobre o prim\xE1rio" },
-  { key: "--brand-hover", use: "hover do prim\xE1rio" },
-  { key: "--brand-secondary", use: "2\xAA cor de marca \u2014 S\xD3 como fill (com --brand-on-secondary); nunca borda/texto sobre superf\xEDcie" },
-  { key: "--brand-on-secondary", use: "texto sobre o fill secund\xE1rio" },
-  { key: "--brand-accent", use: "destaque, links, sucesso (use com parcim\xF4nia)" },
-  { key: "--brand-accent-light", use: "fundo tingido do accent" },
-  { key: "--brand-on-accent", use: "texto sobre o accent" },
-  { key: "--surface-page", use: "fundo da p\xE1gina" },
-  { key: "--surface-default", use: "cards, pain\xE9is" },
-  { key: "--surface-raised", use: "superf\xEDcie elevada/hover" },
-  { key: "--border-subtle", use: "divis\xF3rias fracas" },
-  { key: "--border-default", use: "bordas de inputs e cards" },
-  { key: "--border-strong", use: "bordas enfatizadas" },
-  { key: "--border-focus", use: "anel de foco" },
-  { key: "--text-primary", use: "t\xEDtulos, corpo" },
-  { key: "--text-secondary", use: "texto de apoio" },
-  { key: "--text-muted", use: "legendas, metadados" },
-  { key: "--text-inverse", use: "texto sobre superf\xEDcies invertidas" },
-  { key: "--icon-default", use: "cor padr\xE3o de \xEDcone" }
+var MARKERS = /rojao-ds:(start|end)/i;
+var NAME = /^[a-z0-9][a-z0-9 _-]{0,63}$/i;
+var CSS_FILE = /^[a-z0-9_@./-]+\.css$/i;
+var CSS_URL = /^https?:\/\/[^\s"'`<>()\\]+$/i;
+var INSTALL = /^(?:pnpm add|yarn add|bun add|npm install|npm i) @rojaostudio\/ds(?:@[a-z0-9][a-z0-9.+-]*)?$/;
+var ROLE_DOCS = [
+  { role: "colors/primary/default", use: "primary action, brand fills" },
+  { role: "text/on/primary", use: "text/icon on the primary fill" },
+  { role: "colors/primary/active", use: "pressed primary" },
+  { role: "colors/secondary/default", use: "secondary brand fill (with `--text-on-secondary`)" },
+  { role: "colors/accent/default", use: "highlight \u2014 sparingly (with `--text-on-accent`)" },
+  { role: "surface/page", use: "page background" },
+  { role: "surface/card", use: "cards" },
+  { role: "surface/panel", use: "panels, side areas" },
+  { role: "surface/muted", use: "muted areas, wells" },
+  { role: "surface/tint/default", use: "selected / tinted fill (with `--text-on-tint`)" },
+  { role: "border/default", use: "dividers, card borders" },
+  { role: "border/strong", use: "control borders, emphasis" },
+  { role: "focus/ring", use: "focus ring" },
+  { role: "text/heading", use: "headings" },
+  { role: "text/body", use: "body text" },
+  { role: "text/muted", use: "supporting text" },
+  { role: "text/subtle", use: "captions, metadata" },
+  { role: "text/link", use: "links" },
+  { role: "colors/state/error", use: "error fill (with `--text-on-error`)" },
+  { role: "text/error", use: "error message text" },
+  { role: "colors/state/success", use: "success fill (with `--text-on-success`)" },
+  { role: "colors/state/warning", use: "warning fill (with `--text-on-warning`)" }
 ];
-function tokenTable(light2, dark) {
-  const rows = TOKEN_DOCS.filter((t) => t.key in light2).map((t) => {
-    const l = resolveColor(light2[t.key]);
-    const d = t.key in dark ? resolveColor(dark[t.key]) : "\u2014";
-    return `| \`${t.key}\` | ${t.use} | \`${l}\` | \`${d}\` |`;
-  });
-  return [
-    "| Token | Use para | Light | Dark |",
-    "|---|---|---|---|",
-    ...rows
-  ].join("\n");
-}
-function scaleLine(obj, unit = "px") {
-  return Object.entries(obj).map(([k, v]) => `\`${k}\`=${v}${v === 9999 ? "" : unit}`).join(" \xB7 ");
+var CLAUDE_MD_COMPONENTS = [
+  "button",
+  "icon-button",
+  "tooltip",
+  "input",
+  "textarea",
+  "select",
+  "checkbox",
+  "radio-group",
+  "switch",
+  "card",
+  "dialog",
+  "sheet",
+  "tabs",
+  "table",
+  "toast",
+  "badge",
+  "alert",
+  "avatar",
+  "dropdown-menu",
+  "page-header",
+  "sidebar",
+  "empty",
+  "skeleton",
+  "pagination"
+];
+var CLAUDE_MD_FOUNDATION = {
+  space: ["--space-4", "--space-8", "--space-12", "--space-16", "--space-24", "--space-32", "--space-40", "--space-48", "--space-56", "--space-64"],
+  radius: ["--radius-xs", "--radius-control", "--radius-field", "--radius-card", "--radius-container", "--radius-full"],
+  type: ["heading", "lead", "body", "label", "button", "small", "caption"],
+  font: "--type-font-stack"
+};
+function isTable(x) {
+  return typeof x === "object" && x !== null && "modes" in x && "primitives" in x;
 }
+var TARGET_FILES = { claude: "CLAUDE.md", cursor: ".cursorrules", agents: "AGENTS.md" };
 function fileLabel(target) {
-  return target === "cursor" ? ".cursorrules" : target === "agents" ? "AGENTS.md" : "CLAUDE.md";
+  return TARGET_FILES[target];
 }
-function emitClaudeMd(def, opts = {}) {
-  var _a, _b, _c;
-  const { supported, light: light2, dark, note } = generateTheme(def);
-  if (!supported) throw new Error(`emitClaudeMd: ${def.name} n\xE3o suportado \u2014 ${note}`);
-  const Name = def.name[0].toUpperCase() + def.name.slice(1);
-  const cssUrl = (_a = opts.cssUrl) != null ? _a : null;
-  const bodyFont = typeof ((_b = def.fonts) == null ? void 0 : _b.body) === "string" ? def.fonts.body : "inter";
-  const displayFont = typeof ((_c = def.fonts) == null ? void 0 : _c.display) === "string" ? def.fonts.display : bodyFont;
-  const fontTitle = (s) => s.split("-").map((w) => {
-    var _a2;
-    return ((_a2 = w[0]) == null ? void 0 : _a2.toUpperCase()) + w.slice(1);
-  }).join(" ");
-  const neutral = primitives.color.neutral;
-  return `# Design System \u2014 ${Name} (brand: \`${def.name}\`)
-
-> This project uses the **${Name}** design system. When you build any UI \u2014
-> components, pages, screens \u2014 follow the rules below so every screen looks like the
-> same product. Do not invent colors, fonts, spacing, or radii.
+function roleTable(theme) {
+  const rows = ROLE_DOCS.filter((r) => roleVar(r.role) in theme.light).map((r) => {
+    var _a;
+    const v = roleVar(r.role);
+    return `| \`${v}\` | ${r.use} | \`${theme.light[v]}\` | \`${(_a = theme.dark[v]) != null ? _a : theme.light[v]}\` |`;
+  });
+  return ["| Token | Use for | Light | Dark |", "|---|---|---|---|", ...rows].join("\n");
+}
+function emitClaudeMd(source, opts = {}) {
+  var _a, _b, _c, _d;
+  const theme = (_a = opts.theme) != null ? _a : isTable(source) ? rdsThemeFromTable(source) : generateRdsTheme(source);
+  assertSafeTheme(theme, "emitClaudeMd");
+  const name = source.name;
+  if (name !== void 0 && name !== "" && !(typeof name === "string" && NAME.test(name)))
+    throw new Error(`emitClaudeMd: name ${preview(name)} is not valid (letters, digits, space, "-" and "_", up to 64)`);
+  const Name = name ? name[0].toUpperCase() + name.slice(1) : "Brand";
+  const desc = !isTable(source) ? oneLine(source.description) : "";
+  const description = desc ? ` \u2014 ${desc}` : "";
+  const cssFile = (_b = opts.cssFile) != null ? _b : "rds-theme.css";
+  if (!CSS_FILE.test(cssFile)) throw new Error(`emitClaudeMd: cssFile ${preview(cssFile)} is not a valid .css path`);
+  if (opts.cssUrl !== void 0 && !CSS_URL.test(opts.cssUrl))
+    throw new Error(`emitClaudeMd: cssUrl ${preview(opts.cssUrl)} is not a valid http(s) URL`);
+  const install = (_c = opts.install) != null ? _c : "pnpm add @rojaostudio/ds";
+  if (!INSTALL.test(install)) throw new Error(`emitClaudeMd: install ${preview(install)} is not an install command of @rojaostudio/ds`);
+  const target = (_d = opts.target) != null ? _d : "claude";
+  if (!Object.prototype.hasOwnProperty.call(TARGET_FILES, target)) throw new Error(`emitClaudeMd: unknown target ${preview(target)}`);
+  const f = CLAUDE_MD_FOUNDATION;
+  const own = theme.vars ? Object.keys(theme.vars) : [];
+  const themeImport = opts.cssUrl ? `@import "@rojaostudio/ds/styles/rds.css";
+@import url("${opts.cssUrl}"); /* the brand theme, AFTER rds.css */` : `@import "@rojaostudio/ds/styles/rds.css";
+@import "./${cssFile}"; /* the brand theme, AFTER rds.css */`;
+  const text = `# Design System \u2014 ${Name}
 
-## Brand identity
-- **Name:** ${Name}
-- **Look:** ${isNeutralBrand(def) ? "neutral \u2014 black & white lead, the accent does the talking" : "chromatic \u2014 the brand color leads"}${def.description ? ` \u2014 ${def.description}` : ""}
-- **Body font:** ${fontTitle(bodyFont)} \xB7 **Display font:** ${fontTitle(displayFont)} (load from Google Fonts; never substitute)
-- **Default radius:** \`${primitives.radius.md}px\` (\`rounded-lg\`). Pills/avatars fully round.
-- **Light AND dark are first-class** \u2014 every screen must work in both.
+> This project uses **Roj\xE3o DS 2.0** with the **${Name}** brand${description}. When you build any
+> UI \u2014 components, pages, screens \u2014 follow the rules below so every screen looks like the same
+> product. Do not invent colors, fonts, spacing or radii.
 
-## How to apply
-1. ${cssUrl ? `Import the brand stylesheet once at the app root:
-   \`\`\`html
-   <link rel="stylesheet" href="${cssUrl}" />
-   \`\`\`` : `Put \`${def.name}.css\` (downloaded with this file) in your project and import it
-   once at the app root:
-   \`\`\`css
-   @import "./${def.name}.css";
-   \`\`\`
-   The theme is a file **you own** \u2014 commit it. Nothing here depends on an external host.`}
-2. Put the theme class on \`<html>\`:
-   \`\`\`html
-   <html class="theme-${def.name}">       <!-- light -->
-   <html class="theme-${def.name} dark">  <!-- dark -->
-   \`\`\`
-   > One sheet can hold **several themes** \u2014 each as its own \`theme-<name>\` class.
-   > Switch with the class (one product per app, or many on one page).${cssUrl ? `
-   > Edit the theme at the source and this same URL updates **all your apps at once**.` : ""}
-3. Style everything with the semantic tokens below, as CSS variables \u2014 they already
-   flip between light and dark. You never write a hex value in a component.
-   \`\`\`css
-   .card { background: var(--surface-default); color: var(--text-primary);
-           border: 1px solid var(--border-default); border-radius: ${primitives.radius.md}px; }
-   \`\`\`
+## Setup (once per app)
+\`\`\`bash
+${install}
+\`\`\`
+\`\`\`css
+/* root stylesheet */
+${themeImport}
+\`\`\`
+- \`rds.css\` carries the tokens and every component's styles, in cascade layers
+  (\`rds.theme\`, \`rds.tokens\`, \`rds.components\`). No Tailwind, no other stylesheet.
+- ${opts.cssUrl ? `The theme is served from \`${opts.cssUrl}\`.` : `\`${cssFile}\` is the brand theme, generated \u2014 a file **you own**; commit it. Regenerate it
+  with \`npx rojao-ds init\` instead of editing it by hand.`}
+- Dark mode: \`class="dark"\` on \`<html>\` (or any element). Light AND dark are first-class.
+- Brand plate: \`class="ds-plate"\` on a section paints it with the primary color; the roles inside
+  flip so text and components stay legible.
 
-## Semantic color tokens \u2014 ALWAYS use these, NEVER hardcode a color
-${tokenTable(light2, dark)}
+## Components first
+Use the design system components before writing your own markup. Import each from its own path:
+\`\`\`tsx
+import { Button } from "@rojaostudio/ds/components/button";
+import { IconButton } from "@rojaostudio/ds/components/icon-button";
+import { Tooltip } from "@rojaostudio/ds/components/tooltip";
+\`\`\`
+Available, among others: ${CLAUDE_MD_COMPONENTS.map((c) => `\`${c}\``).join(" \xB7 ")}.
+- Components bring their own CSS (inside \`rds.css\`). Don't restyle their internals, don't wrap
+  them in Tailwind classes, don't rebuild them with shadcn/ui.
+- Every \`IconButton\` goes inside a \`Tooltip\` with the same text as its \`label\`.
 
-## Spacing scale (px) \u2014 use ONLY these steps for padding, margin, gap
-${scaleLine(primitives.space)}
+## Theme roles \u2014 ALWAYS use these in your own CSS, NEVER hardcode a color
+They already flip between light, dark and the brand plate.
+${roleTable(theme)}
 
-## Type scale (font-size, px)
-${scaleLine(primitives.fontSize)}
+Every role pairs a fill with its \`--text-on-*\` text. Example:
+\`\`\`css
+.panel { background: var(--surface-card); color: var(--text-body);
+         border: var(--border-width) solid var(--border-default);
+         border-radius: var(--radius-card); padding: var(--space-16); }
+\`\`\`${own.length ? `
 
-**Font weights:** ${scaleLine(primitives.fontWeight, "")}
-**Line heights:** ${Object.entries(primitives.lineHeight).map(([k, v]) => `\`${k}\`=${v}`).join(" \xB7 ")}
+Brand's own variables (same value in every mode): ${own.map((v) => `\`${v}\``).join(" \xB7 ")}.` : ""}
 
-## Radius (px)
-${scaleLine(primitives.radius)}
+## Foundation tokens
+- **Spacing** (padding, margin, gap) \u2014 ONLY: ${f.space.map((v) => `\`${v}\``).join(" \xB7 ")}
+- **Radius:** ${f.radius.map((v) => `\`${v}\``).join(" \xB7 ")}
+- **Type** \u2014 \`--type-<style>-size\` / \`--type-<style>-line\`, styles: ${f.type.map((v) => `\`${v}\``).join(" \xB7 ")}
+- **Font:** \`font-family: var(${f.font})\` \u2014 never substitute.
 
 ## Rules (do / don't)
-- \u2705 Primary button = \`--brand-primary\` bg + \`--brand-on-primary\` text; hover \u2192 \`--brand-hover\`.
-- \u2705 Low-emphasis / secondary action = NEUTRAL outline: \`--border-default\` border + \`--text-secondary\` text (legible by rule, light AND dark). A brand color belongs to the PRIMARY (filled) action, not a secondary outline.
-- \u2705 Page wrapper uses \`--surface-page\`; cards use \`--surface-default\`.
-- \u2705 Body text is \`--text-primary\`; never pure black/white text directly.
-- \u2705 \`--brand-accent\` is the ONLY saturated color \u2014 use it sparingly (links, success, highlights).
-- \u2705 Spacing, font-size and radius come ONLY from the scales above.
-- \u274C Never write a raw hex (\`#000\`, \`bg-black\`) or a Tailwind palette color (\`bg-emerald-500\`, \`text-zinc-700\`) in a component \u2014 map it to a token above.
-- \u274C Never use a brand color (incl. \`--brand-secondary\`) as a border/ring or as text directly on a surface. The engine guarantees contrast ONLY for a fill + its \`--brand-on-*\` text. As a stroke (WCAG 1.4.11, 3:1) or label (1.4.3, 4.5:1) on the surface it can fail \u2014 and in one mode but not the other. Brand colors = fills.
-- \u274C Never introduce a second accent color. Don't hardcode dark-mode colors \u2014 tokens already flip.
-
-## Use with shadcn/ui
-You are NOT replacing shadcn. Use shadcn/ui components and apply THIS brand as the theme:
-map the tokens above onto shadcn's CSS variables (\`--background\` \u2192 \`--surface-page\`,
-\`--foreground\` \u2192 \`--text-primary\`, \`--primary\` \u2192 \`--brand-primary\`, \`--border\` \u2192
-\`--border-default\`, \`--ring\` \u2192 \`--border-focus\`, \`--radius\` \u2192 \`${primitives.radius.md}px\`).
-Build with shadcn's component shapes; paint them with these tokens. Don't restyle components from scratch.
-
-## Primitive palette (reference \u2014 prefer the semantic tokens above)
-\`\`\`
-neutral 50 ${neutral[50]} \xB7 500 ${neutral[500]} \xB7 900 ${neutral[900]}
-\`\`\`
+- \u2705 Primary action = \`Button\` (it already paints \`--colors-primary-default\` + \`--text-on-primary\`).
+- \u2705 Page uses \`--surface-page\`; cards \`--surface-card\`; body text \`--text-body\`.
+- \u2705 \`--colors-accent-default\` is the highlight \u2014 use it sparingly.
+- \u2705 Spacing, radius and type come ONLY from the foundation tokens above.
+- \u2705 Your own CSS is unlayered, so it already wins over the design system \u2014 no \`!important\`.
+- \u274C Never write a raw hex (\`#000\`) or a Tailwind palette class (\`bg-emerald-500\`) in a component.
+- \u274C Never use a brand fill as a border or as text on a surface: contrast is guaranteed only for a
+  fill + its \`--text-on-*\`.
+- \u274C Never hardcode dark-mode colors \u2014 the roles already flip. Don't add a second accent color.
+- \u274C Don't use the 1.x stylesheet (\`styles/base.css\`), its utilities (\`bg-surface-*\`, \`text-fg-*\`) or
+  \`theme-<name>\` classes.
 
-<!-- Generated by Roj\xE3o DS \u2014 file: ${fileLabel("claude")} / ${fileLabel("cursor")} / ${fileLabel("agents")}. Drop it in your project root; Claude Code & Cursor read it automatically. -->
+<!-- Generated by Roj\xE3o DS (npx rojao-ds init) \u2014 file: ${fileLabel(target)}. Claude Code, Cursor and other agents read it from the project root. -->
 `;
+  if (MARKERS.test(text)) throw new Error("emitClaudeMd: the generated text contains a rojao-ds marker");
+  return text;
 }
 
-export { ROLES, SCALE_STEPS, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, generateTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, refToHex, relativeLuminance, resolveTheme, roleVar };
+export { RDS_CONTRAST_PAIRS, RDS_SCOPE_SELECTORS, RDS_TOKEN_SCOPE, ROLES, RdsValidationError, SCALE_STEPS, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, generateTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, isSafeColor, isSafeFont, isSafeVarName, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, refToHex, relativeLuminance, resolveTheme, roleVar };

package/dist/{chunk-3QTDO2HW.js → chunk-PV6GFEAM.js}

@@ -5,8 +5,7 @@ var rojao = {
   brand: {
     primary: "navy-900",
     secondary: "navy-900",
-    accent: "flare-700",
-    heading: "flare-700"
+    accent: "flare-700"
   },
   surface: "zinc",
   text: "zinc",

package/dist/generate.d.ts

@@ -3,7 +3,14 @@ import { a as BrandDef } from './recipe.schema-Cq7e82nx.js';
 export { A as Archetype, B as BrandColors, C as ColorRef, D as DarkStrategy, F as FontDef, P as PaletteRef, S as ScaleToken, T as TextStyle, b as TextStyleName, c as TypeScale } from './recipe.schema-Cq7e82nx.js';
 
 type RdsMode = "light" | "dark" | "brand";
-type RdsTheme = Record<RdsMode, Record<string, string>>;
+type RdsTheme = Record<RdsMode, Record<string, string>> & {
+    /** The brand's own variables (Figma `brand` collection, `<brand>/<name>`), one value for every mode. */
+    vars?: Record<string, string>;
+};
+type RdsThemeOptions = {
+    /** Where the warnings go (an explicit BrandDef.heading that fails AA). Default console.warn. */
+    warn?: (message: string) => void;
+};
 /**
  * Roles of the [RDS] theme collection, in Figma order: [name, dark source, brand source].
  * The light mode always reads the plain base token. In dark and brand, Figma points either to the
@@ -12,22 +19,97 @@ type RdsTheme = Record<RdsMode, Record<string, string>>;
 declare const ROLES: ReadonlyArray<readonly [string, "l" | "d", "l" | "d" | "b"]>;
 /** CSS custom property of a role: the Figma path with hyphens (the [RDS] codeSyntax rule). */
 declare const roleVar: (role: string) => string;
-declare function generateRdsTheme(def: BrandDef): RdsTheme;
+declare function generateRdsTheme(def: BrandDef, opts?: RdsThemeOptions): RdsTheme;
+/**
+ * The selectors on which @rojaostudio/ds redeclares its component tokens (styles/rds/components.css and
+ * foundation.css). A component token holds `var(--theme-role)`, and a custom property is resolved on the element
+ * where it is declared: a theme scope that none of these match would repaint the roles but not the components
+ * inside it, which keep the colours resolved at :root. The attributes are the generic way in: put
+ * `data-rds-scope` on a scope element, `data-rds-mode="dark"` on a dark one, `data-rds-plate` on a plate.
+ */
+declare const RDS_SCOPE_SELECTORS: readonly [":root", ".ds-scope", "[data-rds-scope]", ".dark", "[data-rds-mode]", ".ds-plate", "[data-rds-plate]"];
+/** RDS_SCOPE_SELECTORS as one selector list, as the component token layer is emitted. */
+declare const RDS_TOKEN_SCOPE: string;
 type RdsCssOptions = {
-    /** Scope of the light mode. Default `:root, .ds-scope`. */
+    /** Scope of the light mode. Default `:root, .ds-scope, [data-rds-scope]`. */
     scope?: string;
-    /** Selector of the dark mode, combined with the scope. Default `.dark`. */
+    /**
+     * Selector of the dark mode, combined with each scope. Default `.dark, [data-rds-mode="dark"]`. A selector
+     * anchored at the root (`:root[data-theme="dark"]`, `html.dark`) is used as is: the theme switches on <html>,
+     * as next-themes does.
+     */
     dark?: string;
-    /** Selector of the brand plate (a section painted with the primary). Default `.ds-plate`. */
+    /** Selector of the brand plate (a section painted with the primary). Default `.ds-plate, [data-rds-plate]`. */
     plate?: string;
+    /**
+     * Skip the check that every selector is covered by the component tokens of @rojaostudio/ds (RDS_SCOPE_SELECTORS).
+     * Only for a theme read by your own CSS, without the components.
+     */
+    allowUncovered?: boolean;
 };
 /**
  * The theme as CSS. Dark and plate only carry what differs from light: they inherit the rest
  * through the cascade, like the [RDS] modes that point back to the plain token.
+ *
+ * Throws when a selector would leave the components of @rojaostudio/ds on the root colours (see
+ * RDS_SCOPE_SELECTORS), unless `allowUncovered`.
  */
 declare function emitRdsCss(theme: RdsTheme, opts?: RdsCssOptions): string;
 /** Contrast of a role pair in one mode (alpha colours are not measured: they depend on what is below). */
 declare function rdsContrast(theme: RdsTheme, mode: RdsMode, fg: string, bg: string): number | null;
+/**
+ * The main text pairs of the theme: [text role, the surface it sits on]. Measured in every mode; a pair with an
+ * alpha colour is skipped (its contrast depends on what is below).
+ */
+declare const RDS_CONTRAST_PAIRS: ReadonlyArray<readonly [string, string]>;
+type RdsContrastFailure = {
+    mode: RdsMode;
+    fg: string;
+    bg: string;
+    ratio: number;
+};
+/** The pairs of RDS_CONTRAST_PAIRS that fail WCAG AA (4.5:1), mode by mode. Empty means every pair passes. */
+declare function rdsContrastReport(theme: RdsTheme): RdsContrastFailure[];
+/**
+ * A brand as drawn in the [RDS] Base Tokens file: for each theme mode, every role points to a primitive of the
+ * [RDS] Primitives library by name ("accyan/400"), and `primitives` holds the colour Figma resolves for each.
+ * Exported by `figma/export-brand.js`. The theme comes out one to one with the Figma brand mode.
+ */
+type RdsBrandTable = {
+    $schema?: "rds-brand-table/1";
+    name: string;
+    primitives: Record<string, string>;
+    modes: Record<RdsMode, Record<string, string>>;
+    /** The brand's own variables of the `brand` collection, by Figma path ("marca/ciano") → primitive or value. */
+    vars?: Record<string, string>;
+};
+/**
+ * The theme of a brand table. Fails on a missing role or an unknown primitive, listing them all. A table exported
+ * before a role of ADDED_ROLES existed is the exception: the role is taken from the token Figma aliases it to, and
+ * `opts.warn` asks to export the table again. The contrast of the main text pairs (rdsContrastReport) is only
+ * reported, through `opts.warn`: the table is the brand as drawn in Figma, kept one to one even where a pair fails.
+ */
+declare function rdsThemeFromTable(table: RdsBrandTable, opts?: RdsThemeOptions): RdsTheme;
+
+/**
+ * validate.ts — what the emitters accept from the outside (a recipe, a brand table, a theme object).
+ *
+ * ds-core is a public API, and its output lands in a stylesheet (`emitRdsCss`) and in the rules file an AI agent
+ * reads (`emitClaudeMd`). A value that is not a colour could close the CSS rule and open another one, pull an
+ * `url()`, or carry an instruction into CLAUDE.md. So every value is checked against an allow list before it is
+ * written, and the check runs again in each emitter (defence in depth: a theme object can be built by hand).
+ *
+ * Allow lists, never deny lists: a colour is a hex or a closed `rgb()/rgba()/oklch()`; a variable name is lowercase
+ * words joined by `-` or `/`; a font family has no quote, semicolon, brace, backslash or line break.
+ */
+declare const isSafeColor: (v: unknown) => v is string;
+declare const isSafeVarName: (v: unknown) => v is string;
+declare const isSafeFont: (v: unknown) => v is string;
+/** Thrown when an input fails the allow list. The message lists every field that failed. */
+declare class RdsValidationError extends Error {
+    readonly problems: string[];
+    constructor(where: string, problems: string[]);
+}
 
 /**
  * emitCss.ts — formata o output do generateTheme num theme.css legível.
@@ -37,12 +119,38 @@ declare function rdsContrast(theme: RdsTheme, mode: RdsMode, fg: string, bg: str
 
 declare function emitCss(def: BrandDef): string;
 
+/**
+ * emitClaudeMd.ts — a brand → the rules file (CLAUDE.md / .cursorrules / AGENTS.md) that teaches
+ * the AI (Claude Code, Cursor, any agent) to build with the brand on Rojão DS 2.0.
+ *
+ * 2.0 (issue #5): the file describes the [RDS] setup — components with their own CSS
+ * (`@rojaostudio/ds/styles/rds.css`), the generated theme file imported after it, the theme roles
+ * (`--surface-card`, `--text-on-primary`…) and the foundation tokens (`--space-*`, `--radius-*`,
+ * `--type-*`). The 1.x text (Tailwind utilities, base.css, `theme-<name>`, shadcn mapping) is gone:
+ * no component reads it any more.
+ *
+ * The input is either a recipe (BrandDef, theme derived by `generateRdsTheme`) or a brand table
+ * exported from Figma (`rdsThemeFromTable`). Colours in the table are the theme's own hex values,
+ * so the AI "sees" the brand. Pure (no I/O).
+ */
+
 type ClaudeMdTarget = "claude" | "cursor" | "agents";
 interface ClaudeMdOptions {
-    /** URL de um CSS de tema hospedado, se houver. Sem default: o padrão é arquivo local. */
+    /** URL of a hosted theme stylesheet, if any. No default: the theme is a local file. */
     cssUrl?: string;
+    /** Name of the local theme file the consumer imports. Default `rds-theme.css`. */
+    cssFile?: string;
+    /** The theme, if it was already generated. Default: derived from the input. */
+    theme?: RdsTheme;
+    /** File the text is written to (only the footer changes). Default `claude`. */
+    target?: ClaudeMdTarget;
+    /**
+     * The install command shown in the setup, as the consumer's package manager runs it
+     * (`npm install @rojaostudio/ds@next`). Default `pnpm add @rojaostudio/ds`.
+     */
+    install?: string;
 }
-declare function emitClaudeMd(def: BrandDef, opts?: ClaudeMdOptions): string;
+declare function emitClaudeMd(source: BrandDef | RdsBrandTable, opts?: ClaudeMdOptions): string;
 
 /**
  * scale.ts — deriva uma escala 50–900 a partir de UMA cor custom (1 hex). #28.
@@ -110,4 +218,4 @@ declare function isNeutralBrand(def: {
     palettes?: PaletteDefs;
 }): boolean;
 
-export { BrandDef, type ClaudeMdOptions, type ClaudeMdTarget, ROLES as RDS_ROLES, type RdsCssOptions, type RdsMode, type RdsTheme, SCALE_STEPS, type Scale, type ScaleStep, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, refToHex, relativeLuminance, roleVar };
+export { BrandDef, type ClaudeMdOptions, type ClaudeMdTarget, RDS_CONTRAST_PAIRS, ROLES as RDS_ROLES, RDS_SCOPE_SELECTORS, RDS_TOKEN_SCOPE, type RdsBrandTable, type RdsContrastFailure, type RdsCssOptions, type RdsMode, type RdsTheme, type RdsThemeOptions, RdsValidationError, SCALE_STEPS, type Scale, type ScaleStep, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, isSafeColor, isSafeFont, isSafeVarName, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, refToHex, relativeLuminance, roleVar };

package/dist/generate.js

@@ -1,3 +1,3 @@
-export { ROLES as RDS_ROLES, SCALE_STEPS, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, generateTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, refToHex, relativeLuminance, resolveTheme, roleVar } from './chunk-CFOS2RAD.js';
+export { RDS_CONTRAST_PAIRS, ROLES as RDS_ROLES, RDS_SCOPE_SELECTORS, RDS_TOKEN_SCOPE, RdsValidationError, SCALE_STEPS, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, generateTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, isSafeColor, isSafeFont, isSafeVarName, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, refToHex, relativeLuminance, resolveTheme, roleVar } from './chunk-LP6UA4EW.js';
 import './chunk-FRWRLCYM.js';
 import './chunk-ORMEWXMH.js';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { G as GenResult, R as ResolvedTheme, T as TokenMap, g as generateTheme, r as resolveTheme } from './generateTheme-CUfNpsKs.js';
-export { ClaudeMdOptions, ClaudeMdTarget, RDS_ROLES, RdsCssOptions, RdsMode, RdsTheme, SCALE_STEPS, Scale, ScaleStep, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, refToHex, relativeLuminance, roleVar } from './generate.js';
+export { ClaudeMdOptions, ClaudeMdTarget, RDS_CONTRAST_PAIRS, RDS_ROLES, RDS_SCOPE_SELECTORS, RDS_TOKEN_SCOPE, RdsBrandTable, RdsContrastFailure, RdsCssOptions, RdsMode, RdsTheme, RdsThemeOptions, RdsValidationError, SCALE_STEPS, Scale, ScaleStep, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, isSafeColor, isSafeFont, isSafeVarName, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, refToHex, relativeLuminance, roleVar } from './generate.js';
 export { A as Archetype, B as BrandColors, a as BrandDef, C as ColorRef, D as DarkStrategy, F as FontDef, P as PaletteRef, S as ScaleToken, T as TextStyle, b as TextStyleName, c as TypeScale } from './recipe.schema-Cq7e82nx.js';
 export { primitives, tokens } from './tokens.js';
 export { RecipeName, recipes } from './recipes.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { recipes } from './chunk-3QTDO2HW.js';
-export { ROLES as RDS_ROLES, SCALE_STEPS, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, generateTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, refToHex, relativeLuminance, resolveTheme, roleVar } from './chunk-CFOS2RAD.js';
+export { recipes } from './chunk-PV6GFEAM.js';
+export { RDS_CONTRAST_PAIRS, ROLES as RDS_ROLES, RDS_SCOPE_SELECTORS, RDS_TOKEN_SCOPE, RdsValidationError, SCALE_STEPS, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, generateTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, isSafeColor, isSafeFont, isSafeVarName, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, refToHex, relativeLuminance, resolveTheme, roleVar } from './chunk-LP6UA4EW.js';
 export { primitives, tokens } from './chunk-FRWRLCYM.js';
 import './chunk-ORMEWXMH.js';

package/dist/recipes.d.ts

@@ -15,7 +15,11 @@ import { a as BrandDef } from './recipe.schema-Cq7e82nx.js';
  * ele não descreve marca de ninguém, descreve ponto de partida.
  */
 
-/** rojao — navy + flare accent on zinc, Inter. The `rojao` brand of the Figma [RDS] (2.0). */
+/**
+ * rojao — navy + flare accent on zinc, Inter. The `rojao` brand of the Figma [RDS] (2.0).
+ * text/heading is the primary (navy) on light, as in the [RDS] base collection: the logo pairs are navy and
+ * orange, white and orange. The orange title is the Heading's tone=accent, not the default.
+ */
 declare const rojao: BrandDef;
 declare const recipes: {
     readonly rojao: BrandDef;

package/dist/recipes.js

@@ -1,2 +1,2 @@
-export { recipes, rojao } from './chunk-3QTDO2HW.js';
+export { recipes, rojao } from './chunk-PV6GFEAM.js';
 import './chunk-ORMEWXMH.js';

package/dist/themes.js

@@ -1,4 +1,4 @@
-import { generateTheme } from './chunk-CFOS2RAD.js';
+import { generateTheme } from './chunk-LP6UA4EW.js';
 import './chunk-FRWRLCYM.js';
 import { __spreadValues, __objRest } from './chunk-ORMEWXMH.js';
 

package/figma/export-brand.js

@@ -0,0 +1,58 @@
+/* global figma */
+// Exports one brand of the [RDS] Base Tokens file as a brand table for rdsThemeFromTable().
+// Run inside the Base Tokens file with the Figma Plugin API (a plugin console or an agent with use_figma),
+// after setting BRAND to the mode name of the `base` collection. The return value is the JSON to save.
+//
+// Each theme role is followed through the aliases of the `base` collection (in the brand's mode) down to a
+// primitive of the [RDS] Primitives library, kept by name ("accyan/400") with the colour Figma resolves.
+// The brand's own variables in the `brand` collection (`<brand>/<name>`, as marca/ciano) come along in `vars`.
+const BRAND = "rojao";
+
+const cols = await figma.variables.getLocalVariableCollectionsAsync();
+const base = cols.find((c) => c.name === "base");
+const theme = cols.find((c) => c.name === "theme");
+if (!base || !theme) throw new Error("open the [RDS] Base Tokens file");
+const brandMode = base.modes.find((m) => m.name === BRAND);
+if (!brandMode) throw new Error(`no brand "${BRAND}" in base: ${base.modes.map((m) => m.name).join(", ")}`);
+const local = new Set(cols.map((c) => c.id));
+
+const hex = (c) =>
+  "#" +
+  [c.r, c.g, c.b].map((x) => Math.round(x * 255).toString(16).padStart(2, "0")).join("") +
+  (c.a !== undefined && c.a < 1 ? Math.round(c.a * 255).toString(16).padStart(2, "0") : "");
+const literal = (v, val) => (v.resolvedType === "COLOR" ? hex(val) : String(val));
+const isAlias = (val) => val && typeof val === "object" && val.type === "VARIABLE_ALIAS";
+
+const primitives = {};
+async function resolve(v, themeMode) {
+  if (!local.has(v.variableCollectionId)) {
+    // A Primitives library variable: keep its name, record what it resolves to.
+    const val = Object.values(v.valuesByMode)[0];
+    if (isAlias(val)) return resolve(await figma.variables.getVariableByIdAsync(val.id), themeMode);
+    primitives[v.name] = literal(v, val);
+    return v.name;
+  }
+  const modeId = v.variableCollectionId === base.id ? brandMode.modeId
+    : v.variableCollectionId === theme.id ? themeMode : Object.keys(v.valuesByMode)[0];
+  const val = v.valuesByMode[modeId] ?? Object.values(v.valuesByMode)[0];
+  if (isAlias(val)) return resolve(await figma.variables.getVariableByIdAsync(val.id), themeMode);
+  return literal(v, val);
+}
+
+const modes = {};
+for (const m of theme.modes) {
+  const roles = {};
+  for (const id of theme.variableIds) {
+    const v = await figma.variables.getVariableByIdAsync(id);
+    roles[v.name] = await resolve(v, m.modeId);
+  }
+  modes[m.name] = roles;
+}
+const vars = {};
+const brandCol = cols.find((c) => c.name === "brand");
+for (const id of brandCol?.variableIds ?? []) {
+  const v = await figma.variables.getVariableByIdAsync(id);
+  if (v.name.startsWith(`${BRAND}/`)) vars[v.name] = await resolve(v, theme.modes[0].modeId);
+}
+const sorted = Object.fromEntries(Object.entries(primitives).sort(([a], [b]) => a.localeCompare(b)));
+return { $schema: "rds-brand-table/1", name: BRAND, primitives: sorted, modes, vars };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rojaostudio/ds-core",
-  "version": "1.1.0-next.1",
+  "version": "1.1.0-next.10",
   "description": "O motor do Rojão DS — tokens, derivação de tema e emissores. Sem React, sem Tailwind, sem CSS.",
   "license": "MIT",
   "author": "Rojão Studio (https://rojao.studio)",
@@ -54,7 +54,8 @@
   "files": [
     "LICENSE",
     "README.md",
-    "dist"
+    "dist",
+    "figma/export-brand.js"
   ],
   "devDependencies": {
     "eslint": "^9.18.0",