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

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

@@ -675,27 +675,209 @@ 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");
-function palette(name) {
+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") {
+    if (!isHex(own)) throw new Error(`rdsTheme: palette "${name}" is not a hex colour`);
+    return buildScale(own);
+  }
+  if (own) return own;
   const p = palettes[name];
   if (!p || typeof p === "string") throw new Error(`rdsTheme: unknown palette "${name}"`);
   return p;
 }
-function ramp(c) {
+function ramp(c, custom) {
   var _a;
   if (isHex(c)) return { base: c, scale: buildScale(c) };
-  const m = c.match(/^([a-zA-Z]+)-(\d{2,3})$/);
-  if (m) return { base: (_a = refToHex(c)) != null ? _a : palette(m[1])[Number(m[2])], scale: palette(m[1]) };
+  const m = c.match(/^([a-zA-Z][a-zA-Z0-9]*)-(\d{2,3})$/);
+  if (m) {
+    const scale = palette(m[1], custom);
+    return { base: (_a = scale[Number(m[2])]) != null ? _a : refToHex(c), scale };
+  }
   const hex = refToHex(c);
   if (!hex) throw new Error(`rdsTheme: cannot resolve colour "${c}"`);
   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"],
@@ -799,22 +981,38 @@ 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 P = ramp(b.primary);
-  const S = b.secondary ? ramp(b.secondary) : P;
-  const A = b.accent ? ramp(b.accent) : P;
-  const N = palette(def.text && palettes[def.text] && typeof palettes[def.text] !== "string" ? def.text : "zinc");
+  const own = def.palettes;
+  const P = ramp(b.primary, own);
+  const S = b.secondary ? ramp(b.secondary, own) : P;
+  const A = b.accent ? ramp(b.accent, own) : P;
+  const N = def.text && ((own == null ? void 0 : own[def.text]) || palettes[def.text] && typeof palettes[def.text] !== "string") ? palette(def.text, own) : palette("zinc");
   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).base : P.base;
-  const invert = b.invert ? ramp(b.invert).base : WHITE;
+  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],
     "colors/primary/default": P.base,
@@ -850,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],
@@ -891,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],
@@ -917,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"];
@@ -935,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],
@@ -962,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],
@@ -985,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],
@@ -1004,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,
@@ -1023,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),
@@ -1045,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),
@@ -1053,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;
   };
@@ -1066,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) {
@@ -1092,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 = [
@@ -1164,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 };