@rojaostudio/ds-core 1.1.0-next.7 → 1.1.0-next.9

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/dist/{chunk-Y25PXY26.js → chunk-N3HPD3U5.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") {
@@ -706,18 +808,19 @@ function ramp(c, custom) {
 }
 var on = (bg) => onColor(bg);
 var AA = 4.5;
-var readsOn = (fg, bgs) => bgs.every((bg) => contrastRatio(fg, bg) >= AA);
-function readableFrom(base, scale, bgs, toward, fallback) {
+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)) return base;
+  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));
+  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)) return c;
+    if (readsOn(c, bgs, min)) return c;
   }
   return fallback;
 }
@@ -828,14 +931,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, 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);
@@ -930,8 +1038,7 @@ function generateRdsTheme(def, opts = {}) {
     "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],
@@ -959,6 +1066,8 @@ function generateRdsTheme(def, opts = {}) {
     ["colors/primary/dark", "text/on/primary-strong"],
     ["surface/tint/default", "text/on/tint"]
   ]) l[text] = on(l[fill]);
+  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"];
@@ -1023,7 +1132,6 @@ function generateRdsTheme(def, opts = {}) {
     "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],
@@ -1046,12 +1154,15 @@ function generateRdsTheme(def, opts = {}) {
     ["surface/tint/default", "text/on/tint"],
     ["surface/lift/action", "text/on/lift-action"]
   ]) d[text] = on(d[fill]);
+  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 plateCard = (_b = SCALE_STEPS.map((st) => P.scale[st]).filter((c) => !!c && isHex(c) && c.toLowerCase() !== plate.toLowerCase()).sort((a, b2) => Math.abs(relativeLuminance(a) - lp) - Math.abs(relativeLuminance(b2) - lp)).find((c) => contrastRatio(ink, c) >= AA)) != null ? _b : 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],
@@ -1096,6 +1207,7 @@ function generateRdsTheme(def, opts = {}) {
     "border/strong-hover": inkA(80),
     "text/on/primary-subtle": inkA(30)
   };
+  const brandError = readableFrom(red[300], red, [plateCard], awayFrom(plateCard), ink, NON_TEXT);
   const out = { light: {}, dark: {}, brand: {} };
   const pick = (src, role) => {
     var _a2;
@@ -1109,6 +1221,8 @@ function generateRdsTheme(def, opts = {}) {
     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 = [
@@ -1134,6 +1248,12 @@ var covered = (sel) => {
 };
 function emitRdsCss(theme, opts = {}) {
   var _a, _b, _c;
+  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]");
@@ -1200,10 +1320,34 @@ function rdsContrastReport(theme) {
   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;
+  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) {
@@ -1211,7 +1355,12 @@ function rdsThemeFromTable(table, opts = {}) {
       continue;
     }
     for (const [role] of ROLES) {
-      const ref2 = roles[role];
+      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];
@@ -1220,10 +1369,10 @@ function rdsThemeFromTable(table, opts = {}) {
       } else out[mode][roleVar(role)] = ref2;
     }
   }
-  const valueOf = (where, ref2) => {
+  const valueOf = (field, ref2) => {
     if (!isColourRef(ref2)) return ref2;
     const value = table.primitives[ref2];
-    if (value === void 0) problems.push(`${where} points to unknown primitive "${ref2}"`);
+    if (value === void 0) problems.push(`${field} points to unknown primitive "${ref2}"`);
     return value == null ? void 0 : value.toLowerCase();
   };
   if (table.vars) {
@@ -1233,12 +1382,18 @@ function rdsThemeFromTable(table, opts = {}) {
       if (value !== void 0) out.vars[roleVar(name)] = value;
     }
   }
-  if (problems.length) throw new Error(`rdsThemeFromTable(${table.name}):
+  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)
-    ((_b = opts.warn) != null ? _b : defaultWarn)(
-      `rdsThemeFromTable(${table.name}): ${fails.length} text pair(s) below 4.5:1
+    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;
@@ -1315,6 +1470,11 @@ ${lightBlock}${darkBlock}
 }
 
 // generate/emitClaudeMd.ts
+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" },
@@ -1374,8 +1534,9 @@ var CLAUDE_MD_FOUNDATION = {
 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 roleTable(theme) {
   const rows = ROLE_DOCS.filter((r) => roleVar(r.role) in theme.light).map((r) => {
@@ -1386,19 +1547,29 @@ function roleTable(theme) {
   return ["| Token | Use for | Light | Dark |", "|---|---|---|---|", ...rows].join("\n");
 }
 function emitClaudeMd(source, opts = {}) {
-  var _a, _b, _c;
+  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 description = !isTable(source) && source.description ? ` \u2014 ${source.description}` : "";
+  const desc = !isTable(source) ? oneLine(source.description) : "";
+  const description = desc ? ` \u2014 ${desc}` : "";
   const cssFile = (_b = opts.cssFile) != null ? _b : "rds-theme.css";
-  const target = (_c = opts.target) != null ? _c : "claude";
+  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 */`;
-  return `# Design System \u2014 ${Name}
+  const text = `# Design System \u2014 ${Name}
 
 > 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
@@ -1406,7 +1577,7 @@ function emitClaudeMd(source, opts = {}) {
 
 ## Setup (once per app)
 \`\`\`bash
-pnpm add @rojaostudio/ds
+${install}
 \`\`\`
 \`\`\`css
 /* root stylesheet */
@@ -1466,6 +1637,8 @@ Brand's own variables (same value in every mode): ${own.map((v) => `\`${v}\``).j
 
 <!-- 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 { RDS_CONTRAST_PAIRS, RDS_SCOPE_SELECTORS, RDS_TOKEN_SCOPE, ROLES, SCALE_STEPS, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, generateTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, 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/generate.d.ts

@@ -84,12 +84,33 @@ type RdsBrandTable = {
     vars?: Record<string, string>;
 };
 /**
- * The theme of a brand table. Fails on a missing role or an unknown primitive, listing them all. 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.
+ * 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.
  * Header + bloco light (.theme-<name>) + bloco dark (seletor duplo), agrupado
@@ -123,6 +144,11 @@ interface ClaudeMdOptions {
     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(source: BrandDef | RdsBrandTable, opts?: ClaudeMdOptions): string;
 
@@ -192,4 +218,4 @@ declare function isNeutralBrand(def: {
     palettes?: PaletteDefs;
 }): boolean;
 
-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, SCALE_STEPS, type Scale, type ScaleStep, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, 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 { RDS_CONTRAST_PAIRS, ROLES as RDS_ROLES, RDS_SCOPE_SELECTORS, RDS_TOKEN_SCOPE, SCALE_STEPS, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, generateTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, refToHex, relativeLuminance, resolveTheme, roleVar } from './chunk-Y25PXY26.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-N3HPD3U5.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_CONTRAST_PAIRS, RDS_ROLES, RDS_SCOPE_SELECTORS, RDS_TOKEN_SCOPE, RdsBrandTable, RdsContrastFailure, RdsCssOptions, RdsMode, RdsTheme, RdsThemeOptions, SCALE_STEPS, Scale, ScaleStep, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, 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-PV6GFEAM.js';
-export { RDS_CONTRAST_PAIRS, ROLES as RDS_ROLES, RDS_SCOPE_SELECTORS, RDS_TOKEN_SCOPE, SCALE_STEPS, brandTones, buildScale, contrastRatio, emitClaudeMd, emitCss, emitRdsCss, generateRdsTheme, generateTheme, hexToHsl, hslToHex, isHex, isNeutralBrand, onColor, rdsContrast, rdsContrastReport, rdsThemeFromTable, refToHex, relativeLuminance, resolveTheme, roleVar } from './chunk-Y25PXY26.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-N3HPD3U5.js';
 export { primitives, tokens } from './chunk-FRWRLCYM.js';
 import './chunk-ORMEWXMH.js';

package/dist/themes.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rojaostudio/ds-core",
-  "version": "1.1.0-next.7",
+  "version": "1.1.0-next.9",
   "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)",