orbital-ds 0.7.0 → 0.9.0

package/package.json

@@ -1,142 +1,160 @@
-{
-  "name": "orbital-ds",
-  "version": "0.7.0",
-  "description": "Sistema de diseño genérico: estructura común + temas con personalidad (qratia, zyro) + ~60 componentes sobre Base UI y Tailwind v4, con contrato verificable y legible por agentes.",
-  "keywords": [
-    "design-system",
-    "design-tokens",
-    "theme",
-    "tailwindcss",
-    "base-ui",
-    "shadcn",
-    "react"
-  ],
-  "license": "MIT",
-  "type": "module",
-  "sideEffects": [
-    "*.css"
-  ],
-  "files": [
-    "dist",
-    "scripts/doctor.mjs",
-    "contract.json",
-    "components.manifest.json",
-    "docs",
-    "AGENTS.md",
-    "README.md",
-    "LICENSE",
-    "scripts/init.mjs",
-    "scripts/manifest.mjs"
-  ],
-  "exports": {
-    "./styles.css": "./dist/styles.css",
-    "./themes/*.css": "./dist/themes/*.css",
-    "./themes/*.md": "./dist/themes/*.md",
-    "./themes/*.meta.json": "./dist/themes/*.meta.json",
-    "./ui/*": {
-      "types": "./dist/ui/*.d.ts",
-      "import": "./dist/ui/*.js"
-    },
-    "./lib/*": {
-      "types": "./dist/lib/*.d.ts",
-      "import": "./dist/lib/*.js"
-    },
-    "./hooks/*": {
-      "types": "./dist/hooks/*.d.ts",
-      "import": "./dist/hooks/*.js"
-    },
-    "./package.json": "./package.json",
-    "./contract.json": "./contract.json",
-    "./components.manifest.json": "./components.manifest.json"
-  },
-  "peerDependencies": {
-    "@base-ui/react": ">=1.9",
-    "class-variance-authority": ">=0.7",
-    "clsx": ">=2",
-    "lucide-react": ">=0.400",
-    "react": ">=19",
-    "react-dom": ">=19",
-    "tailwind-merge": ">=3",
-    "tailwindcss": ">=4.1",
-    "tw-animate-css": ">=1.3",
-    "next-themes": ">=0.4",
-    "recharts": ">=3",
-    "sonner": ">=2",
-    "@shadcn/react": ">=0.3",
-    "cmdk": ">=1.1",
-    "date-fns": ">=4",
-    "embla-carousel-react": ">=8.6",
-    "input-otp": ">=1.5",
-    "react-day-picker": ">=10",
-    "react-resizable-panels": ">=4"
-  },
-  "peerDependenciesMeta": {
-    "next-themes": {
-      "optional": true
-    },
-    "recharts": {
-      "optional": true
-    },
-    "sonner": {
-      "optional": true
-    },
-    "@shadcn/react": {
-      "optional": true
-    },
-    "cmdk": {
-      "optional": true
-    },
-    "date-fns": {
-      "optional": true
-    },
-    "embla-carousel-react": {
-      "optional": true
-    },
-    "input-otp": {
-      "optional": true
-    },
-    "react-day-picker": {
-      "optional": true
-    },
-    "react-resizable-panels": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@base-ui/react": "^1.9.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^0.577.0",
-    "next-themes": "^0.4.6",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "recharts": "3.8.0",
-    "sonner": "^2.0.8",
-    "tailwind-merge": "^3.0.2",
-    "tailwindcss": "^4.1.18",
-    "tsup": "^8.5.0",
-    "tw-animate-css": "^1.3.6",
-    "typescript": "^5.9.0",
-    "@shadcn/react": "^0.3.1",
-    "cmdk": "^1.1.1",
-    "date-fns": "^4.4.0",
-    "embla-carousel-react": "^8.6.0",
-    "input-otp": "^1.5.0",
-    "react-day-picker": "^10.0.2",
-    "react-resizable-panels": "^4.14.4"
-  },
-  "bin": {
-    "orbital-ds-doctor": "./scripts/doctor.mjs",
-    "orbital-ds-init": "./scripts/init.mjs"
-  },
-  "scripts": {
-    "build": "tsup && node scripts/build-css.mjs",
-    "dev": "tsup --watch --onSuccess \"node scripts/copy-css.mjs\"",
-    "typecheck": "tsc --noEmit",
-    "verify": "pnpm check:ds && pnpm typecheck && pnpm build",
-    "manifest": "node scripts/manifest.mjs",
-    "check:ds": "node scripts/doctor.mjs"
-  }
-}
+{
+  "name": "orbital-ds",
+  "version": "0.9.0",
+  "description": "Sistema de diseño genérico: estructura común + temas con personalidad (qratia, zyro) + ~60 componentes sobre Base UI y Tailwind v4, con contrato verificable y legible por agentes.",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "theme",
+    "tailwindcss",
+    "base-ui",
+    "shadcn",
+    "react"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist",
+    "scripts/doctor.mjs",
+    "contract.json",
+    "components.manifest.json",
+    "docs",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "scripts/init.mjs",
+    "scripts/manifest.mjs",
+    "scripts/brand-core.mjs",
+    "scripts/setup.mjs",
+    "scripts/i18n.mjs"
+  ],
+  "exports": {
+    "./styles.css": "./dist/styles.css",
+    "./themes/*.css": "./dist/themes/*.css",
+    "./themes/*.md": "./dist/themes/*.md",
+    "./themes/*.meta.json": "./dist/themes/*.meta.json",
+    "./ui/*": {
+      "types": "./dist/ui/*.d.ts",
+      "import": "./dist/ui/*.js"
+    },
+    "./lib/*": {
+      "types": "./dist/lib/*.d.ts",
+      "import": "./dist/lib/*.js"
+    },
+    "./hooks/*": {
+      "types": "./dist/hooks/*.d.ts",
+      "import": "./dist/hooks/*.js"
+    },
+    "./package.json": "./package.json",
+    "./contract.json": "./contract.json",
+    "./components.manifest.json": "./components.manifest.json"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/build-css.mjs",
+    "dev": "tsup --watch --onSuccess \"node scripts/copy-css.mjs\"",
+    "typecheck": "tsc --noEmit",
+    "verify": "pnpm check:ds && pnpm typecheck && pnpm showcase:typecheck && pnpm build",
+    "manifest": "node scripts/manifest.mjs",
+    "check:ds": "node scripts/doctor.mjs",
+    "showcase": "vite --config showcase/vite.config.ts",
+    "showcase:build": "vite build --config showcase/vite.config.ts",
+    "showcase:typecheck": "tsc --noEmit -p showcase"
+  },
+  "peerDependencies": {
+    "@base-ui/react": ">=1.9",
+    "@shadcn/react": ">=0.3",
+    "class-variance-authority": ">=0.7",
+    "clsx": ">=2",
+    "cmdk": ">=1.1",
+    "date-fns": ">=4",
+    "embla-carousel-react": ">=8.6",
+    "input-otp": ">=1.5",
+    "lucide-react": ">=0.400",
+    "motion": ">=12",
+    "next-themes": ">=0.4",
+    "react": ">=19",
+    "react-day-picker": ">=10",
+    "react-dom": ">=19",
+    "react-resizable-panels": ">=4",
+    "recharts": ">=3",
+    "sonner": ">=2",
+    "tailwind-merge": ">=3",
+    "tailwindcss": ">=4.1",
+    "tw-animate-css": ">=1.3"
+  },
+  "peerDependenciesMeta": {
+    "next-themes": {
+      "optional": true
+    },
+    "recharts": {
+      "optional": true
+    },
+    "sonner": {
+      "optional": true
+    },
+    "@shadcn/react": {
+      "optional": true
+    },
+    "cmdk": {
+      "optional": true
+    },
+    "date-fns": {
+      "optional": true
+    },
+    "embla-carousel-react": {
+      "optional": true
+    },
+    "input-otp": {
+      "optional": true
+    },
+    "react-day-picker": {
+      "optional": true
+    },
+    "react-resizable-panels": {
+      "optional": true
+    },
+    "motion": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@base-ui/react": "^1.9.0",
+    "@shadcn/react": "^0.3.1",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.4.0",
+    "embla-carousel-react": "^8.6.0",
+    "input-otp": "^1.5.0",
+    "lucide-react": "^0.577.0",
+    "motion": "^14.1.0",
+    "next-themes": "^0.4.6",
+    "react": "^19.2.0",
+    "react-day-picker": "^10.0.2",
+    "react-dom": "^19.2.0",
+    "react-resizable-panels": "^4.14.4",
+    "recharts": "3.8.0",
+    "sonner": "^2.0.8",
+    "tailwind-merge": "^3.0.2",
+    "tailwindcss": "^4.1.18",
+    "tsup": "^8.5.0",
+    "tw-animate-css": "^1.3.6",
+    "typescript": "^5.9.0",
+    "vite": "^8.3.4"
+  },
+  "bin": {
+    "orbital-ds-doctor": "./scripts/doctor.mjs",
+    "orbital-ds-init": "./scripts/init.mjs",
+    "orbital-ds-i18n": "./scripts/i18n.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  }
+}

package/scripts/brand-core.mjs

@@ -0,0 +1,153 @@
+/**
+ * orbital-ds · núcleo de MARCA: color (OKLCH) y derivación de una marca completa a
+ * partir del primario, con comprobación de contraste. Sin dependencias ni APIs de
+ * Node: lo usan `orbital-ds-init` (terminal) y el escaparate (navegador), así que
+ * los dos calculan exactamente lo mismo.
+ */
+/* ═══════════════════════════════ COLOR ═══════════════════════════════════════ */
+const clamp01 = (x) => Math.min(1, Math.max(0, x));
+const toGamma = (x) => (x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055);
+const toLinear = (x) => (x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4);
+
+/** OKLCH → sRGB lineal (sin recortar). */
+function oklchLinear({ l, c, h }) {
+  const a = c * Math.cos((h * Math.PI) / 180), b = c * Math.sin((h * Math.PI) / 180);
+  const l_ = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m_ = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s_ = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_, -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_, -0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_];
+}
+const inGamut = (lin) => lin.every((v) => v >= -1e-4 && v <= 1 + 1e-4);
+
+/** OKLCH → {r,g,b} 0..255, reduciendo el croma hasta caber en sRGB. */
+function oklchToRgb({ l, c, h }) {
+  let cc = c;
+  if (!inGamut(oklchLinear({ l, c: cc, h }))) {
+    let lo = 0, hi = c;
+    for (let i = 0; i < 24; i++) { const mid = (lo + hi) / 2; if (inGamut(oklchLinear({ l, c: mid, h }))) lo = mid; else hi = mid; }
+    cc = lo;
+  }
+  const lin = oklchLinear({ l, c: cc, h }).map(clamp01);
+  const [r, g, b] = lin.map((v) => Math.round(255 * toGamma(v)));
+  return { r, g, b };
+}
+/** {r,g,b} 0..255 → OKLCH. */
+export function rgbToOklch({ r, g, b }) {
+  const [lr, lg, lb] = [r, g, b].map((v) => toLinear(v / 255));
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  const c = Math.hypot(A, B);
+  let h = (Math.atan2(B, A) * 180) / Math.PI; if (h < 0) h += 360;
+  return { l: L, c, h: c < 1e-4 ? 0 : h };
+}
+export const hex = ({ r, g, b }) => '#' + [r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('');
+const rgba = ({ r, g, b }, a) => `rgba(${r}, ${g}, ${b}, ${a})`;
+export const ok = (l, c, h) => oklchToRgb({ l, c, h });
+
+function lumin({ r, g, b }) { const f = (v) => toLinear(v / 255); return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b); }
+export function ratio(a, b) { const [x, y] = [lumin(a), lumin(b)].sort((p, q) => q - p); return (x + 0.05) / (y + 0.05); }
+
+/** Color CSS → {r,g,b}. Acepta #hex, rgb(), hsl() y oklch(). */
+export function parseColor(raw) {
+  const v = raw.trim().toLowerCase();
+  let m = v.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/);
+  if (m) { let h = m[1]; if (h.length === 3) h = [...h].map((c) => c + c).join(''); return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16) }; }
+  m = v.match(/^rgb\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)\s*\)$/);
+  if (m) return { r: +m[1], g: +m[2], b: +m[3] };
+  m = v.match(/^hsl\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%\s*\)$/);
+  if (m) {
+    const h = +m[1] / 360, s = +m[2] / 100, l = +m[3] / 100;
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s, p = 2 * l - q;
+    const f = (t) => { t = (t + 1) % 1; return t < 1 / 6 ? p + (q - p) * 6 * t : t < 1 / 2 ? q : t < 2 / 3 ? p + (q - p) * (2 / 3 - t) * 6 : p; };
+    return { r: Math.round(255 * f(h + 1 / 3)), g: Math.round(255 * f(h)), b: Math.round(255 * f(h - 1 / 3)) };
+  }
+  m = v.match(/^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)\s*\)$/);
+  if (m) return oklchToRgb({ l: m[2] ? +m[1] / 100 : +m[1], c: +m[3], h: +m[4] });
+  return null;
+}
+
+/* ═══════════════════════════════ DERIVACIÓN ══════════════════════════════════ */
+/** Ajusta la luminosidad de `color` (OKLCH) en la dirección dada hasta que `bien(rgb)` sea cierto. */
+function ajustar(color, dir, bien) {
+  const o = rgbToOklch(color);
+  for (let i = 0; i <= 80; i++) {
+    const c = oklchToRgb({ ...o, l: clamp01(o.l + dir * 0.01 * i) });
+    if (bien(c)) return c;
+  }
+  return null;
+}
+
+/**
+ * Deriva la marca. Devuelve { claro, oscuro, avisos } con los tokens (sin el prefijo --).
+ * `acento` y `marcador` solo si el tema tiene gestos.
+ */
+export function derivar(primario, { acento, marcador = true, gestos = false }) {
+  const avisos = [];
+  const P = rgbToOklch(primario);
+  const H = P.c < 0.02 ? 255 : P.h; // primario casi gris: neutros azulados por defecto
+  const tinte = Math.min(0.02, 0.008 + P.c * 0.05);
+
+  /* ── piel clara ── */
+  const papel = ok(0.965, tinte, H), tinta = ok(0.235, 0.05, H), blanco = { r: 255, g: 255, b: 255 };
+  const suave = ok(0.925, tinte + 0.008, H);
+  let prim = primario;
+  const textoSobre = (c) => (ratio(blanco, c) >= ratio(tinta, c) ? blanco : tinta);
+  if (ratio(textoSobre(prim), prim) < 4.5) {
+    const m = ajustar(prim, -1, (c) => ratio(blanco, c) >= 4.5);
+    if (m) { avisos.push(`primario claro ajustado a ${hex(m)} para que el texto sobre él llegue a 4.5:1 (era ${hex(prim)})`); prim = m; }
+  }
+  const primFg = textoSobre(prim);
+  const enlace = ajustar(prim, -1, (c) => ratio(c, papel) >= 4.5 && ratio(c, blanco) >= 4.5) ?? prim;
+  const enlaceHover = ajustar(enlace, -1, (c) => rgbToOklch(c).l <= rgbToOklch(enlace).l - 0.07) ?? enlace;
+  const brillo = oklchToRgb({ ...rgbToOklch(prim), l: Math.min(0.95, rgbToOklch(prim).l + 0.08) });
+
+  const acentoC = acento ?? ok(0.82, 0.16, (H + 180) % 360);
+  const claro = {
+    primary: hex(prim), 'primary-foreground': hex(primFg), ring: hex(prim), link: hex(enlace), 'link-hover': hex(enlaceHover),
+    brand: hex(prim), 'brand-bright': hex(brillo), 'sidebar-primary': hex(prim), 'sidebar-primary-foreground': hex(primFg), 'sidebar-ring': hex(prim),
+    'chart-1': hex(prim), 'accent-foreground': hex(tinta),
+    background: hex(papel), foreground: hex(tinta), card: '#ffffff', 'card-foreground': hex(tinta), popover: '#ffffff', 'popover-foreground': hex(tinta),
+    secondary: hex(suave), 'secondary-foreground': hex(tinta), muted: hex(suave), 'muted-foreground': rgba(tinta, 0.72),
+    border: rgba(tinta, 0.14), input: hex(tinta),
+    sidebar: hex(suave), 'sidebar-foreground': hex(tinta), 'sidebar-accent': '#ffffff', 'sidebar-accent-foreground': hex(tinta), 'sidebar-border': rgba(tinta, 0.26),
+    inset: hex(suave), 'inset-foreground': hex(tinta), neutral: rgba(tinta, 0.72), 'neutral-soft': rgba(tinta, 0.08),
+  };
+  if (gestos) {
+    claro['ds-key-outline'] = hex(tinta); claro['ds-key-edge'] = rgba(tinta, 0.26);
+    claro['ds-marker'] = marcador ? rgba(acentoC, 0.62) : 'transparent';
+  }
+
+  /* ── piel oscura ── */
+  const fondoO = ok(0.19, 0.03, H), tarjetaO = ok(0.25, 0.04, H), suaveO = ok(0.22, 0.035, H), textoO = ok(0.95, 0.012, H);
+  let primO = oklchToRgb({ ...P, l: Math.max(P.l, 0.74), c: Math.min(P.c, 0.2) });
+  const primOFg = fondoO;
+  if (ratio(primOFg, primO) < 4.5) primO = ajustar(primO, +1, (c) => ratio(primOFg, c) >= 4.5) ?? primO;
+  const enlaceO = ajustar(primO, +1, (c) => ratio(c, fondoO) >= 4.5) ?? primO;
+  const enlaceHoverO = oklchToRgb({ ...rgbToOklch(enlaceO), l: Math.min(0.95, rgbToOklch(enlaceO).l + 0.07) });
+  const oscuro = {
+    primary: hex(primO), 'primary-foreground': hex(primOFg), ring: hex(primO), link: hex(enlaceO), 'link-hover': hex(enlaceHoverO),
+    brand: hex(primO), 'brand-bright': hex(enlaceO), 'sidebar-primary': hex(primO), 'sidebar-primary-foreground': hex(primOFg), 'sidebar-ring': hex(primO),
+    'chart-1': hex(primO), 'accent-foreground': hex(textoO),
+    background: hex(fondoO), foreground: hex(textoO), card: hex(tarjetaO), 'card-foreground': hex(textoO), popover: hex(tarjetaO), 'popover-foreground': hex(textoO),
+    secondary: hex(suaveO), 'secondary-foreground': hex(textoO), muted: hex(suaveO), 'muted-foreground': rgba(textoO, 0.72),
+    border: rgba(textoO, 0.14), input: rgba(textoO, 0.92),
+    sidebar: hex(suaveO), 'sidebar-foreground': hex(textoO), 'sidebar-accent': hex(tarjetaO), 'sidebar-accent-foreground': hex(textoO), 'sidebar-border': rgba(textoO, 0.26),
+    inset: hex(suaveO), 'inset-foreground': hex(textoO), neutral: rgba(textoO, 0.72), 'neutral-soft': rgba(textoO, 0.1),
+  };
+  if (gestos) {
+    oscuro['ds-key-outline'] = rgba(textoO, 0.92); oscuro['ds-key-edge'] = rgba(textoO, 0.26);
+    oscuro['ds-marker'] = marcador ? rgba(acentoC, 0.45) : 'transparent';
+  }
+
+  /* ── comprobación ── */
+  const pares = [
+    ['claro', 'texto/papel', tinta, papel], ['claro', 'texto/tarjeta', tinta, blanco], ['claro', 'texto sobre primario', primFg, prim],
+    ['claro', 'enlace/papel', enlace, papel], ['oscuro', 'texto/fondo', textoO, fondoO], ['oscuro', 'texto sobre primario', primOFg, primO], ['oscuro', 'enlace/fondo', enlaceO, fondoO],
+  ].map(([piel, nombre, f, b]) => ({ piel, nombre, r: ratio(f, b) }));
+  return { claro, oscuro, avisos, pares, muestras: { papel, tinta, prim, suave, acentoC, fondoO, textoO, primO } };
+}
+

package/scripts/doctor.mjs

@@ -14,6 +14,9 @@
  *      duraciones ni sombras a mano; todo sale de tokens.
  *   6. API PÚBLICA: no desaparece ningún componente ni export respecto a
  *      components.manifest.json (huella de la última versión). Lo nuevo solo avisa.
+ *   7. PERSONALIDAD: las reglas de un tema solo usan variables y estilizan familias
+ *      completas de piezas (contract.slotFamilies). Error si la ficha del tema dice
+ *      `"conformance": "strict"`; aviso en los demás.
  *
  * Uso:
  *   node scripts/doctor.mjs                 # temas y componentes del paquete
@@ -192,11 +195,48 @@ for (const f of themeFiles) {
     for (const mm of css.slice(i, j - 1).matchAll(/--([\w-]+):\s*([^;]+);/g)) out[mm[1]] = mm[2];
     return out;
   };
-  for (const f of themeFiles) {
-    const tema = f.replace(/\.css$/, '');
+  // Qué se mide: cada tema y, con `--css`, la marca/variante de la app ENCIMA de su tema base
+  // (`--theme <t>` o un comentario `@base-theme <t>` en el fichero).
+  const objetivos = themeFiles.map((f) => {
     const css = stripComments(read(join(themesDir, f)));
-    const claro = varsDe(css, ':root');
-    for (const [piel, vars] of [['claro', claro], ['oscuro', { ...claro, ...varsDe(css, '\\.dark') }]]) {
+    const tema = f.replace(/\.css$/, '');
+    return { tema, etiqueta: `tema ${tema}`, claro: varsDe(css, ':root'), oscuro: varsDe(css, '\\.dark') };
+  });
+  const iCss = process.argv.indexOf('--css');
+  if (iCss > -1 && process.argv[iCss + 1]) {
+    const crudo = read(resolve(process.argv[iCss + 1]));
+    const iTheme = process.argv.indexOf('--theme');
+    const base = (iTheme > -1 && process.argv[iTheme + 1]) || crudo.match(/@base-theme\s+([\w-]+)/)?.[1] || null;
+    const t = base && objetivos.find((o) => o.tema === base);
+    const app = stripComments(crudo);
+    if (t) {
+      objetivos.push({
+        tema: base,
+        etiqueta: `marca ${process.argv[iCss + 1]} (sobre ${base})`,
+        claro: { ...t.claro, ...varsDe(app, ':root') },
+        oscuro: { ...t.oscuro, ...varsDe(app, '\\.dark') },
+      });
+    } else {
+      warnings.push('app css: no sé sobre qué tema medir el contraste; pasa --theme <tema> o pon «@base-theme <tema>» en el fichero');
+    }
+  }
+  for (const { tema, etiqueta, claro, oscuro } of objetivos) {
+    // Resuelve `var(--x)` (y `var(--x, respaldo)`) dentro del mismo tema: un color derivado
+    // de otro (p. ej. `--sidebar-primary: var(--primary)`) también se mide.
+    const resolver = (vars) => {
+      const out = {};
+      for (const [k, v0] of Object.entries(vars)) {
+        let v = v0.trim();
+        for (let n = 0; n < 8; n++) {
+          const m = v.match(/^var\(--([\w-]+)(?:\s*,\s*([\s\S]+))?\)$/);
+          if (!m) break;
+          v = (vars[m[1]] ?? m[2] ?? '').trim();
+        }
+        out[k] = v;
+      }
+      return out;
+    };
+    for (const [piel, vars] of [['claro', resolver(claro)], ['oscuro', resolver({ ...claro, ...oscuro })]]) {
       const lienzo = parseColor(vars.background ?? '#fff');
       if (!lienzo) continue;
       for (const estado of ['info', 'danger', 'warning', 'success', 'neutral']) {
@@ -205,7 +245,7 @@ for (const f of themeFiles) {
         if (!fg || !suave) continue;
         const fondo = over(suave, over(lienzo, { r: 255, g: 255, b: 255, a: 1 }));
         const r = ratio(over(fg, fondo), fondo);
-        if (r < 4.5) errors.push(`tema ${tema} (${piel}): ${estado} sobre ${estado}-soft = ${r.toFixed(2)}:1 (mínimo 4.5:1)`);
+        if (r < 4.5) errors.push(`${etiqueta} (${piel}): ${estado} sobre ${estado}-soft = ${r.toFixed(2)}:1 (mínimo 4.5:1)`);
       }
 
       // Pares principales de texto sobre su superficie. AA (4.5:1) es el mínimo exigible; las
@@ -229,11 +269,11 @@ for (const f of themeFiles) {
         const r = ratio(over(fgRaw, bg), bg);
         const par = `${fgName}/${bgName}`;
         if (r < 4.5) {
-          const msg = `tema ${tema} (${piel}): ${par} = ${r.toFixed(2)}:1 (mínimo AA 4.5:1)`;
+          const msg = `${etiqueta} (${piel}): ${par} = ${r.toFixed(2)}:1 (mínimo AA 4.5:1)`;
           if (excepciones.includes(par)) warnings.push(`${msg} — excepción declarada en la ficha`);
           else errors.push(`${msg}; corrígelo o decláralo en ${tema}.meta.json → a11y.exceptions`);
         } else if (process.argv.includes('--aaa') && r < 7 && (par === 'foreground/background' || par === 'card-foreground/card')) {
-          warnings.push(`tema ${tema} (${piel}): ${par} = ${r.toFixed(2)}:1 (objetivo AAA 7:1 para el texto del cuerpo)`);
+          warnings.push(`${etiqueta} (${piel}): ${par} = ${r.toFixed(2)}:1 (objetivo AAA 7:1 para el texto del cuerpo)`);
         }
       }
     }
@@ -254,6 +294,79 @@ if (base && themeInfo[base]) {
   }
 }
 
+// 7) PERSONALIDAD: solo variables y familias completas.
+//    a) Una regla de personalidad (cualquier propiedad que no sea `--x`) no escribe
+//       medidas, colores, pesos, opacidades ni duraciones: pide un hueco a una variable.
+//    b) Si estiliza una pieza de una familia (contract.slotFamilies), estiliza todas.
+//    Error en los temas con `"conformance": "strict"` en su ficha; aviso en los demás.
+{
+  /** Declaraciones de propiedades normales (no `--x`) de un CSS, con su selector. */
+  const propertyDecls = (css) => {
+    const out = [];
+    const stack = [];
+    let buf = '';
+    for (const ch of css) {
+      if (ch === '{') { stack.push(buf.trim()); buf = ''; }
+      else if (ch === ';' || ch === '}') {
+        const d = buf.trim();
+        const m = d.match(/^([a-z-]+)\s*:\s*([\s\S]+)$/i);
+        if (stack.length && m && !d.startsWith('--')) out.push({ selector: stack.at(-1), prop: m[1], value: m[2].trim() });
+        buf = '';
+        if (ch === '}') stack.pop();
+      } else buf += ch;
+    }
+    return out;
+  };
+  const LITERALES = [
+    { re: /(?<![\w.-])\d*\.?\d+(?:px|rem|em|ch|vh|vw)\b/g, why: 'medida' },
+    { re: /#[0-9a-f]{3,8}\b/gi, why: 'color' },
+    { re: /\b(?:rgba?|hsla?|oklch|oklab)\(/gi, why: 'color' },
+    { re: /(?<![\w.-])\d*\.?\d+m?s\b/g, why: 'duración' },
+  ];
+  const NUMERICAS = { 'font-weight': 'peso', opacity: 'opacidad', 'z-index': 'capa', 'line-height': 'interlineado' };
+  const familias = Object.entries(contract.slotFamilies?.families ?? {});
+  for (const f of themeFiles) {
+    const tema = f.replace(/\.css$/, '');
+    let estricto = false;
+    try { estricto = JSON.parse(read(join(themesDir, `${tema}.meta.json`))).conformance === 'strict'; } catch { /* lo avisa 1b */ }
+    const report = (msg) => (estricto ? errors : warnings).push(`tema ${tema}: ${msg}`);
+    const decls = propertyDecls(stripComments(read(join(themesDir, f))));
+
+    const vistos = new Set();
+    for (const { selector, prop, value } of decls) {
+      const sinVar = value.replace(/var\([^()]*(?:\([^()]*\)[^()]*)*\)/g, '');
+      const hits = LITERALES.flatMap((r) => (sinVar.match(r.re) ?? []).map((h) => `${r.why} ${h}`));
+      if (NUMERICAS[prop] && /^\d*\.?\d+$/.test(value)) hits.push(`${NUMERICAS[prop]} ${value}`);
+      for (const h of hits) {
+        const clave = `${selector}|${prop}|${h}`;
+        if (vistos.has(clave)) continue;
+        vistos.add(clave);
+        report(`personalidad con valor fijo (${h}) en «${prop}» de ${selector.replace(/\s+/g, ' ')} — usa una variable`);
+      }
+    }
+
+    const estilizados = new Set(decls.flatMap((d) => [...d.selector.matchAll(/data-slot=['"]?([\w-]+)/g)].map((m) => m[1])));
+    for (const [familia, slots] of familias) {
+      const tiene = slots.filter((s) => estilizados.has(s));
+      if (!tiene.length || tiene.length === slots.length) continue;
+      const faltan = slots.filter((s) => !estilizados.has(s));
+      report(`familia «${familia}» incompleta: estiliza ${tiene.join(', ')} pero no ${faltan.join(', ')}`);
+    }
+  }
+}
+
+// 8) ESCAPARATE: cada componente tiene su demo (showcase/src/demos/<componente>.tsx), para
+//    que todo se pueda ver con cada tema. Solo en el repo del paquete (no en una app).
+{
+  const demosDir = join(ROOT, 'showcase/src/demos');
+  const uiDir8 = join(ROOT, 'src/ui');
+  if (existsSync(demosDir) && existsSync(uiDir8)) {
+    const demos = new Set(readdirSync(demosDir).filter((n) => n.endsWith('.tsx')).map((n) => n.replace(/\.tsx$/, '')));
+    const faltan = readdirSync(uiDir8).filter((n) => n.endsWith('.tsx')).map((n) => n.replace(/\.tsx$/, '')).filter((n) => !demos.has(n));
+    if (faltan.length) errors.push(`escaparate: componentes sin demo en showcase/src/demos/ (${faltan.join(', ')})`);
+  }
+}
+
 // CSS de una app (opcional)
 const cssArgIdx = process.argv.indexOf('--css');
 if (cssArgIdx > -1 && process.argv[cssArgIdx + 1]) {
@@ -278,6 +391,14 @@ const NO_HARDCODE = [
   { re: /\b(?:rgb|rgba|hsl|hsla|oklch)\((?!from_)/g, why: 'color literal' },
   { re: /(?<![\w-])z-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'z-index numérico (usa --ds-z-*)' },
   { re: /(?<![\w-])duration-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'duración fija (usa --ds-motion-*)' },
+  { re: /(?<![a-zA-Z0-9.-])\d*\.?\d+m?s(?=[\])_,\s])/g, why: 'duración dentro de un valor arbitrario (usa --ds-motion-*)' },
+  { re: /(?<![\w-])ease-\[(?:cubic-bezier|steps)\(/g, why: 'curva de aceleración escrita (usa ease-(--ds-ease-*))' },
+  { re: /(?<![\w-])z-\[[^\]]*\d{2,}/g, why: 'capa numérica dentro de un valor arbitrario (usa --ds-z-*)' },
+  // i18n: los textos que ve o escucha el usuario salen de useDsMessages() (orbital-ds/lib/i18n).
+  { re: /aria-(?:label|roledescription)="[A-Za-z][^"]*"/g, why: 'texto accesible escrito a mano (usa useDsMessages)' },
+  { re: /sr-only">[^<{]*[A-Za-z][^<{]*</g, why: 'texto para lector de pantalla escrito a mano (usa useDsMessages)' },
+  { re: /\?\?\s*"[A-Z][^"]*"/g, why: 'texto por defecto escrito a mano (usa useDsMessages)' },
+  { re: /(?<![\w-])(?:title|description|text|placeholder)\s*=\s*"[A-Z][^"]*"/g, why: 'texto de interfaz escrito a mano (usa useDsMessages)' },
   { re: /(?<![\w-])(?:bg|text|border)-(?:black|white)(?:\/\d+)?(?![\w-])/g, why: 'color fijo (usa un token de color)' },
   { re: /(?<![\w-])shadow-(?:xs|sm|md|lg|xl|2xl)(?![\w-])/g, why: 'sombra de la escala Tailwind (usa shadow-card/control/raised/overlay/popover)' },
   { re: /(?<![\w-])text-\[\d+px\]/g, why: 'tamaño de texto arbitrario (usa la escala estándar)' },