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

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,107 @@ 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]>;
+/**
+ * What is not text but has to be seen (WCAG 1.4.11, 3:1): the border of a field and of a field in error, the focus
+ * ring, the brand's logo and its chart series, on the surfaces they are placed on.
+ */
+declare const RDS_NON_TEXT_PAIRS: ReadonlyArray<readonly [string, string]>;
+/** A pair below its minimum: 4.5:1 for text (RDS_CONTRAST_PAIRS), 3:1 for the rest (RDS_NON_TEXT_PAIRS). */
+type RdsContrastFailure = {
+    mode: RdsMode;
+    fg: string;
+    bg: string;
+    ratio: number;
+    min: number;
+};
+/**
+ * The pairs of RDS_CONTRAST_PAIRS below WCAG AA (4.5:1) and of RDS_NON_TEXT_PAIRS below 3:1, mode by mode. Empty
+ * means every pair passes. A pair with an alpha colour is skipped (rdsContrast).
+ */
+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 +129,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 +228,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, RDS_NON_TEXT_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, RDS_NON_TEXT_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-D6HJEVJK.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_NON_TEXT_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, RDS_NON_TEXT_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-D6HJEVJK.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-D6HJEVJK.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.11",
   "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",