orbital-ds 0.6.2 → 0.8.0

package/dist/ui/sidebar.js

@@ -421,7 +421,7 @@ function SidebarMenuItem({ className, ...props }) {
   );
 }
 const sidebarMenuButtonVariants = cva(
-  "peer/menu-button group/menu-button flex w-full items-center gap-2 overflow-hidden rounded-(--ds-sidebar-item-radius) px-3 py-2 text-left text-sm ring-sidebar-ring outline-hidden transition-[width,height,padding] group-has-data-[sidebar=menu-action]/menu-item:pr-8 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground data-[active=true]:bg-sidebar-accent data-[active=true]:font-medium data-[active=true]:text-sidebar-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0 [&>span:last-child]:truncate",
+  "peer/menu-button group/menu-button flex w-full items-center gap-2 overflow-hidden rounded-(--ds-sidebar-item-radius) px-3 py-2 text-left text-sm ring-sidebar-ring outline-hidden transition-[width,height,padding] group-has-data-[sidebar=menu-action]/menu-item:pr-8 group-data-[collapsible=icon]:mx-auto group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground data-[active=true]:bg-sidebar-accent data-[active=true]:font-medium data-[active=true]:text-sidebar-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0 [&>span:last-child]:truncate",
   {
     variants: {
       variant: {

package/dist/ui/tooltip.js

@@ -48,7 +48,7 @@ function TooltipContent({
           ...props,
           children: [
             children,
-            /* @__PURE__ */ jsx(TooltipPrimitive.Arrow, { className: "z-(--ds-z-overlay) size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=left]:translate-x-[-1.5px] data-[side=right]:translate-x-[1.5px]" })
+            /* @__PURE__ */ jsx(TooltipPrimitive.Arrow, { "data-slot": "tooltip-arrow", className: "z-(--ds-z-overlay) size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=left]:translate-x-[-1.5px] data-[side=right]:translate-x-[1.5px]" })
           ]
         }
       )

package/docs/CONTRACT.md

@@ -77,7 +77,7 @@ Los define la estructura con un valor neutro; un tema los sobrescribe si quiere.
 | Capas | `--ds-z-raised`, `--ds-z-sticky`, `--ds-z-sidebar` (sobre la cabecera sticky), `--ds-z-overlay` |
 | Movimiento | `--ds-motion-fast`, `--ds-motion-base`, `--ds-motion-slow`, `--ds-motion-blink` |
 | Foco | `--ds-ring-width` |
-| Sidebar | `--ds-sidebar-rail-w` (ancho del lateral contraído; por defecto `4rem`) |
+| Lateral | `--ds-sidebar-icon`, `--ds-sidebar-icon-stroke` (iconos), `--ds-sidebar-rail-w` (ancho contraído), `--ds-sidebar-rail-item` (tecla del raíl), `--ds-sidebar-logo` (logo y avatar), `--ds-sidebar-sep-inset` (separadores; negativo = de borde a borde). **Todo tema los define** (contrato) |
 | Velo | `--color-scrim` |
 | **Materiales** | `--ds-card-backdrop`, `--ds-overlay-backdrop`, `--ds-field-backdrop`, `--ds-sidebar-backdrop` (un `backdrop-filter` completo; por defecto `none`) y `--ds-page-backdrop` (un `background-image` para el fondo de la página; por defecto `none`) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orbital-ds",
-  "version": "0.6.2",
+  "version": "0.8.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",

package/scripts/doctor.mjs

@@ -207,6 +207,35 @@ for (const f of themeFiles) {
         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)`);
       }
+
+      // Pares principales de texto sobre su superficie. AA (4.5:1) es el mínimo exigible; las
+      // excepciones deben estar declaradas en `<tema>.meta.json` → `a11y.exceptions` ("fg/bg").
+      // AAA (7:1) es el objetivo del texto del cuerpo: solo avisa, y solo con `--aaa`.
+      const PARES = [
+        ['foreground', 'background'], ['card-foreground', 'card'], ['popover-foreground', 'popover'],
+        ['primary-foreground', 'primary'], ['secondary-foreground', 'secondary'],
+        ['muted-foreground', 'background'], ['muted-foreground', 'card'],
+        ['sidebar-foreground', 'sidebar'], ['sidebar-primary-foreground', 'sidebar-primary'],
+        ['destructive-foreground', 'destructive'],
+      ];
+      let excepciones = [];
+      try { excepciones = JSON.parse(read(join(themesDir, `${tema}.meta.json`))).a11y?.exceptions ?? []; } catch { /* sin ficha: lo avisa 1b */ }
+      const blanco = { r: 255, g: 255, b: 255, a: 1 };
+      for (const [fgName, bgName] of PARES) {
+        const fgRaw = vars[fgName] && parseColor(vars[fgName]);
+        const bgRaw = vars[bgName] && parseColor(vars[bgName]);
+        if (!fgRaw || !bgRaw) continue;
+        const bg = over(bgRaw, over(lienzo, blanco));
+        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)`;
+          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)`);
+        }
+      }
     }
   }
 }

package/scripts/init.mjs

@@ -1,89 +1,351 @@
-#!/usr/bin/env node
-/**
- * orbital-ds-init — crea el fichero de MARCA de una app.
- *
- *   pnpm exec orbital-ds-init            # crea src/brand.css si no existe
- *   pnpm exec orbital-ds-init --out app/brand.css
- *
- * NUNCA sobrescribe un fichero existente. Ese fichero es de la app: ninguna
- * actualización de orbital-ds lo toca, y se importa DESPUÉS del tema para que gane.
- *
- * DESIGN.md: orbital-ds NO lo crea. Si la app ya tiene uno (`./DESIGN.md` o
- * `--design ruta`), añade —o actualiza— solo un bloque delimitado por marcas
- * `<!-- orbital-ds:start -->` … `<!-- orbital-ds:end -->`; el resto no se toca.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const contract = JSON.parse(readFileSync(resolve(ROOT, 'contract.json'), 'utf8'));
-
-const outIdx = process.argv.indexOf('--out');
-const out = resolve(outIdx > -1 && process.argv[outIdx + 1] ? process.argv[outIdx + 1] : 'src/brand.css');
-
-const brandExiste = existsSync(out);
-if (brandExiste) console.log(`Ya existe ${out}: no se toca (es de tu app).`);
-
-if (!brandExiste) {
-const lines = contract.brand.tokens.map(
-  (t) => `  /* --${t.name}: ${t.example}; */  /* ${t.about} */`,
-);
-
-const css = `/*
- * MARCA de la app — fichero TUYO.
- *
- * Ninguna actualización de orbital-ds lo toca. Se importa DESPUÉS del tema, así que
- * lo que pongas aquí gana. Si no defines nada, se aplica el valor estándar del tema.
- *
- * Estas variables son el grupo estable de «lo que una marca suele cambiar»: renombrar
- * o quitar una de ellas es una versión MAYOR de orbital-ds, con aviso previo.
- * Descomenta solo lo que necesites y cambia el valor.
- *
- * Cambia el color principal TODO junto: primary, ring, link, brand, sidebar-primary y
- * chart-1 deben ir a la par (y comprueba el contraste del texto sobre ellos).
- */
-:root {
-${lines.join('\n')}
-}
-
-/* Piel oscura: solo si tu marca necesita valores distintos en oscuro. */
-.dark {
-  /* --primary: ...; */
-}
-`;
-
-mkdirSync(dirname(out), { recursive: true });
-writeFileSync(out, css);
-console.log(`Creado ${out}.\n\nImpórtalo DESPUÉS del tema, en el CSS de tu app:\n\n  @import 'orbital-ds/themes/<tema>.css';\n  @import './brand.css';\n`);
-}
-
-// ── DESIGN.md de la app: bloque adicional, nunca el fichero entero ───────────────
-const designIdx = process.argv.indexOf('--design');
-const design = resolve(designIdx > -1 && process.argv[designIdx + 1] ? process.argv[designIdx + 1] : 'DESIGN.md');
-if (existsSync(design)) {
-  const INI = '<!-- orbital-ds:start -->';
-  const FIN = '<!-- orbital-ds:end -->';
-  const bloque = `${INI}
-## Sistema de diseño (orbital-ds)
-
-Bloque gestionado por \`orbital-ds-init\`; lo de fuera de las marcas es de la app y no se toca.
-
-- Reglas de uso: \`node_modules/orbital-ds/AGENTS.md\`
-- Contrato de tokens: \`orbital-ds/contract.json\` · componentes: \`orbital-ds/components.manifest.json\`
-- Cada tema trae su guía (\`orbital-ds/themes/<tema>.guide.md\`) y su ficha (\`<tema>.meta.json\`).
-- La marca de la app va en \`brand.css\` (importado después del tema), nunca editando el paquete.
-- Comprobación: \`pnpm exec orbital-ds-doctor\`
-${FIN}`;
-  const actual = readFileSync(design, 'utf8');
-  let nuevo;
-  if (actual.includes(INI) && actual.includes(FIN)) {
-    nuevo = actual.slice(0, actual.indexOf(INI)) + bloque + actual.slice(actual.indexOf(FIN) + FIN.length);
-  } else {
-    nuevo = `${actual.replace(/\s*$/, '')}\n\n${bloque}\n`;
-  }
-  if (nuevo !== actual) {
-    writeFileSync(design, nuevo);
-    console.log(`Actualizado el bloque de orbital-ds en ${design} (el resto no se toca).`);
-  } else console.log(`${design}: el bloque de orbital-ds ya está al día.`);
-}
+#!/usr/bin/env node
+/**
+ * orbital-ds-init — asistente de MARCA de una app.
+ *
+ *   pnpm exec orbital-ds-init                       # asistente interactivo (terminal)
+ *   pnpm exec orbital-ds-init --primary "#1D63D8"   # sin preguntas (scripts / CI)
+ *
+ * Opciones:
+ *   --theme <tema>    tema para el que se genera (por defecto: el que importa tu CSS, o qratia)
+ *   --primary <color> color primario: hex, rgb(), hsl() u oklch()
+ *   --accent <color>  color de acento/gesto (si no, el complementario del primario)
+ *   --no-marker       apaga el rotulador del tema (si el tema lo tiene)
+ *   --out <fichero>   fichero de marca (por defecto src/brand.css)
+ *   --update          reescribe el bloque generado si ya existe
+ *   --dry-run         muestra el resultado sin escribir nada
+ *   --wizard          fuerza el asistente aunque no haya terminal interactiva
+ *   --yes             no pregunta (usa los valores dados)
+ *   --design <ruta>   DESIGN.md donde añadir el bloque de orbital-ds
+ *
+ * Qué hace: a partir del primario deriva —en OKLCH— los neutros teñidos (papel, tinta,
+ * tarjeta, bordes, lateral), el texto sobre el primario, el enlace, el foco, las dos
+ * pieles (clara y oscura) y comprueba el contraste (WCAG AA 4,5:1). Escribe SOLO un
+ * bloque delimitado en el fichero de marca; lo que la app tenga fuera no se toca.
+ *
+ * NUNCA sobrescribe lo que es de la app. Sin opciones y sin terminal interactiva (CI),
+ * se comporta como siempre: crea la plantilla de marca si falta y añade el bloque de
+ * DESIGN.md.
+ *
+ * Sin dependencias: el color se calcula aquí (matrices OKLab estándar).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const contract = JSON.parse(readFileSync(resolve(ROOT, 'contract.json'), 'utf8'));
+const args = process.argv.slice(2);
+const flag = (n) => args.includes(`--${n}`);
+const opt = (n) => { const i = args.indexOf(`--${n}`); return i > -1 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : undefined; };
+
+/* ═══════════════════════════════ 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. */
+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 };
+}
+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})`;
+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); }
+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(). */
+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.
+ */
+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 } };
+}
+
+/* ═══════════════════════════════ SALIDA ══════════════════════════════════════ */
+const TTY_COLOR = process.stdout.isTTY && (process.env.COLORTERM === 'truecolor' || process.env.COLORTERM === '24bit' || process.env.WT_SESSION);
+const muestra = (c) => (TTY_COLOR ? `\x1b[48;2;${c.r};${c.g};${c.b}m    \x1b[0m ` : '');
+const INI = '/* orbital-ds:brand:start */';
+const FIN = '/* orbital-ds:brand:end */';
+
+function bloqueCss(res, { tema, primario }) {
+  const fmt = (tokens) => Object.entries(tokens).map(([k, v]) => `  --${k}: ${v};`).join('\n');
+  return `${INI}
+/* Generado por \`orbital-ds-init\` (tema ${tema}, primario ${primario}). Si vuelves a ejecutarlo con
+ * --update, solo se reescribe este bloque; lo que tengas fuera no se toca. */
+:root {
+${fmt(res.claro)}
+}
+.dark {
+${fmt(res.oscuro)}
+}
+${FIN}
+`;
+}
+
+function escribirBloque(file, bloque) {
+  const actual = existsSync(file) ? readFileSync(file, 'utf8') : null;
+  if (actual === null) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `/*\n * MARCA de la app — fichero TUYO. Se importa DESPUÉS del tema, así que lo que pongas aquí gana.\n */\n\n${bloque}`);
+    return 'creado';
+  }
+  if (actual.includes(INI) && actual.includes(FIN)) {
+    const nuevo = actual.slice(0, actual.indexOf(INI)) + bloque.trimEnd() + actual.slice(actual.indexOf(FIN) + FIN.length);
+    if (nuevo === actual) return 'igual';
+    writeFileSync(file, nuevo);
+    return 'actualizado';
+  }
+  writeFileSync(file, `${actual.replace(/\s*$/, '')}\n\n${bloque}`);
+  return 'añadido';
+}
+
+/* ═══════════════════════════════ TEMAS ═══════════════════════════════════════ */
+const temasDir = existsSync(join(ROOT, 'src/themes')) ? join(ROOT, 'src/themes') : join(ROOT, 'dist/themes');
+const temas = readdirSync(temasDir).filter((f) => f.endsWith('.meta.json')).map((f) => JSON.parse(readFileSync(join(temasDir, f), 'utf8')));
+const TEMA_CSS = (() => {
+  for (const f of ['src/styles.css', 'app/styles.css', 'src/index.css']) {
+    if (existsSync(f)) { const m = readFileSync(f, 'utf8').match(/orbital-ds\/themes\/([\w-]+)\.css/); if (m) return m[1]; }
+  }
+  return 'qratia';
+})();
+/** Un tema tiene gestos si su ficha (`<tema>.meta.json`) los declara con variables públicas. */
+const tieneGestos = (tema) => (temas.find((t) => t.name === tema)?.gestures ?? []).length > 0;
+
+/* ═══════════════════════════════ FLUJO ═══════════════════════════════════════ */
+function plantillaClasica() {
+  const out = resolve(opt('out') ?? 'src/brand.css');
+  if (existsSync(out)) console.log(`Ya existe ${out}: no se toca (es de tu app).`);
+  else {
+    const lines = contract.brand.tokens.map((t) => `  /* --${t.name}: ${t.example}; */  /* ${t.about} */`);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, `/*\n * MARCA de la app — fichero TUYO.\n *\n * Ninguna actualización de orbital-ds lo toca. Se importa DESPUÉS del tema, así que\n * lo que pongas aquí gana. Si no defines nada, se aplica el valor estándar del tema.\n *\n * Para generar la marca completa desde un color:  pnpm exec orbital-ds-init --primary "#1D63D8"\n */\n:root {\n${lines.join('\n')}\n}\n\n/* Piel oscura: solo si tu marca necesita valores distintos en oscuro. */\n.dark {\n  /* --primary: ...; */\n}\n`);
+    console.log(`Creado ${out}.\n\nImpórtalo DESPUÉS del tema, en el CSS de tu app:\n\n  @import 'orbital-ds/themes/<tema>.css';\n  @import './brand.css';\n`);
+  }
+}
+
+function actualizarDesign() {
+  const design = resolve(opt('design') ?? 'DESIGN.md');
+  if (!existsSync(design)) return;
+  const I = '<!-- orbital-ds:start -->', F = '<!-- orbital-ds:end -->';
+  const bloque = `${I}
+## Sistema de diseño (orbital-ds)
+
+Bloque gestionado por \`orbital-ds-init\`; lo de fuera de las marcas es de la app y no se toca.
+
+- Reglas de uso y estándar de integración: \`node_modules/orbital-ds/AGENTS.md\`
+- Contrato de tokens: \`orbital-ds/contract.json\` · componentes: \`orbital-ds/components.manifest.json\`
+- Cada tema trae su guía (\`orbital-ds/themes/<tema>.guide.md\`) y su ficha (\`<tema>.meta.json\`).
+- La marca de la app va en \`brand.css\` (importado después del tema), nunca editando el paquete.
+- Comprobación: \`pnpm exec orbital-ds-doctor --css src/brand.css\` (contraste AA incluido)
+${F}`;
+  const actual = readFileSync(design, 'utf8');
+  const nuevo = actual.includes(I) && actual.includes(F)
+    ? actual.slice(0, actual.indexOf(I)) + bloque + actual.slice(actual.indexOf(F) + F.length)
+    : `${actual.replace(/\s*$/, '')}\n\n${bloque}\n`;
+  if (nuevo !== actual) { writeFileSync(design, nuevo); console.log(`Actualizado el bloque de orbital-ds en ${design} (el resto no se toca).`); }
+}
+
+function mostrar(res, tema, primario) {
+  const m = res.muestras;
+  console.log(`\nMarca derivada de ${primario} para el tema «${tema}»\n`);
+  console.log(`  Claro   ${muestra(m.papel)}papel ${hex(m.papel)}   ${muestra(m.tinta)}tinta ${hex(m.tinta)}   ${muestra(m.prim)}primario ${hex(m.prim)}   ${muestra(m.acentoC)}acento ${hex(m.acentoC)}`);
+  console.log(`  Oscuro  ${muestra(m.fondoO)}fondo ${hex(m.fondoO)}   ${muestra(m.textoO)}texto ${hex(m.textoO)}   ${muestra(m.primO)}primario ${hex(m.primO)}\n`);
+  console.log('  Contraste (mínimo AA 4.5:1):');
+  for (const p of res.pares) console.log(`    ${p.r >= 7 ? '✓ AAA' : p.r >= 4.5 ? '✓ AA ' : '✗    '}  ${p.r.toFixed(2).padStart(5)}:1  ${p.piel.padEnd(6)} ${p.nombre}`);
+  for (const a of res.avisos) console.log(`  ! ${a}`);
+  console.log('');
+}
+
+async function asistente() {
+  const rl = createInterface({ input: process.stdin, terminal: false });
+  const lineas = rl[Symbol.asyncIterator]();
+  const preguntar = async (q, def) => {
+    process.stdout.write(def ? `${q} [${def}] ` : `${q} `);
+    const { value, done } = await lineas.next();
+    const r = (done ? '' : value).trim();
+    if (!process.stdin.isTTY) process.stdout.write(`${r}
+`); // eco cuando las respuestas llegan por tubería
+    return r || def || '';
+  };
+  console.log('\norbital-ds · asistente de marca\n');
+  console.log('Temas disponibles:');
+  temas.forEach((t, i) => console.log(`  ${i + 1}. ${t.name.padEnd(9)} ${t.essence}`));
+  const nt = await preguntar('\n¿Para qué tema? (número o nombre)', TEMA_CSS);
+  const tema = (temas[+nt - 1] ?? temas.find((t) => t.name === nt) ?? temas.find((t) => t.name === TEMA_CSS)).name;
+  let primario;
+  for (;;) {
+    const raw = await preguntar('Color primario (hex, rgb(), hsl() u oklch()):', '');
+    primario = raw && parseColor(raw);
+    if (primario) { console.log(`  ${muestra(primario)}${hex(primario)}`); break; }
+    console.log('  No entiendo ese color. Ejemplos: #1D63D8 · rgb(29 99 216) · hsl(219 76% 48%) · oklch(0.55 0.2 260)');
+  }
+  const gestos = tieneGestos(tema);
+  let marcador = true, acento;
+  if (gestos) {
+    const P = rgbToOklch(primario);
+    const prop = [['complementario', 180], ['análogo', 30], ['triádico', 120]].map(([n, d]) => [n, ok(0.82, 0.16, (P.h + d) % 360)]);
+    console.log('\nAcento / color del rotulador (opcional). Propuestas:');
+    prop.forEach(([n, c], i) => console.log(`  ${i + 1}. ${muestra(c)}${n.padEnd(15)} ${hex(c)}`));
+    const a = await preguntar('Elige 1-3, escribe otro color, o Enter para el complementario:', '1');
+    acento = prop[+a - 1]?.[1] ?? parseColor(a) ?? prop[0][1];
+    const r = await preguntar('¿Rotulador bajo los títulos? (s/n)', 's');
+    marcador = !/^n/i.test(r);
+  }
+  const res = derivar(primario, { acento, marcador, gestos });
+  mostrar(res, tema, hex(primario));
+  const out = resolve(opt('out') ?? 'src/brand.css');
+  const ok2 = await preguntar(`¿Escribo el bloque en ${out}? (s/n)`, 's');
+  rl.close();
+  if (/^n/i.test(ok2)) { console.log('No se ha escrito nada.'); return; }
+  const estado = escribirBloque(out, bloqueCss(res, { tema, primario: hex(primario) }));
+  console.log(`\nBloque ${estado} en ${out}. Lo que tengas fuera de las marcas no se ha tocado.`);
+  actualizarDesign();
+}
+
+async function directo() {
+  const primario = parseColor(opt('primary'));
+  if (!primario) { console.error('Color primario no válido. Usa hex, rgb(), hsl() u oklch().'); process.exit(1); }
+  const tema = opt('theme') ?? TEMA_CSS;
+  if (!temas.some((t) => t.name === tema)) { console.error(`El tema «${tema}» no existe. Disponibles: ${temas.map((t) => t.name).join(', ')}`); process.exit(1); }
+  const acento = opt('accent') ? parseColor(opt('accent')) : undefined;
+  const res = derivar(primario, { acento, marcador: !flag('no-marker'), gestos: tieneGestos(tema) });
+  mostrar(res, tema, hex(primario));
+  const bloque = bloqueCss(res, { tema, primario: hex(primario) });
+  const out = resolve(opt('out') ?? 'src/brand.css');
+  if (flag('dry-run')) { console.log(bloque); return; }
+  if (existsSync(out) && readFileSync(out, 'utf8').includes(INI) && !flag('update')) {
+    console.log(`Ya hay un bloque generado en ${out}. Usa --update para reescribirlo.`); return;
+  }
+  const estado = escribirBloque(out, bloque);
+  console.log(`Bloque ${estado} en ${out}.`);
+  actualizarDesign();
+}
+
+if (opt('primary')) await directo();
+else if (flag('wizard') || (process.stdin.isTTY && process.stdout.isTTY && !flag('classic'))) await asistente();
+else { plantillaClasica(); actualizarDesign(); }