orbital-ds 0.3.0 → 0.4.0

package/AGENTS.md

@@ -22,6 +22,9 @@ adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
    foco incluido).
 6. **Un tema cumple el contrato completo** (`contract.json`) y define en `:root` todo
    `--ds-*` que defina el tema base.
+7. **La marca de una app vive en SU `brand.css`**, no en el tema del paquete. Para
+   personalizar una app (color, radio, fuentes) edita ese fichero; nunca `node_modules` ni
+   los temas. `pnpm exec orbital-ds-init` lo crea sin sobrescribir.
 
 ## Cómo cambiar el aspecto
 

package/README.md

@@ -32,6 +32,12 @@ import { Button } from 'orbital-ds/ui/button';
 Cambiar de identidad = cambiar `qratia` por `zyro` en esas dos líneas de tema/fuentes.
 Detalle del contrato, tokens y reglas de nombres en [`docs/CONTRACT.md`](docs/CONTRACT.md).
 
+## Marca de una app
+
+Lo propio de cada app (color principal, acento, radio, fuentes) va en **su** `src/brand.css`,
+importado después del tema. Ninguna actualización de orbital-ds lo toca. `pnpm exec orbital-ds-init`
+lo crea la primera vez. Detalle en [`docs/CONTRACT.md`](docs/CONTRACT.md).
+
 ## Regla
 
 Ningún componente lleva valores propios (colores, medidas, sombras, z-index, duraciones):

package/contract.json

@@ -1,5 +1,5 @@
 {
-  "version": 2,
+  "version": 3,
   "descripcion": "Contrato de tema de orbital-ds: todo tema (themes/*.css) debe definir estos tokens en :root. Nombres en inglés estándar; los de shadcn sin prefijo; los propios con --ds-. baseTheme es el tema aplicado siempre (los demás se aplican encima, con ámbito).",
   "root": [
     "radius",
@@ -78,5 +78,85 @@
       "link"
     ]
   },
-  "baseTheme": "qratia"
+  "baseTheme": "qratia",
+  "brand": {
+    "descripcion": "Grupo ESTABLE de variables que una app suele personalizar en su fichero de marca (brand.css). Renombrar o quitar una es versión MAYOR. Todas están también en `root` salvo las --ds-*.",
+    "tokens": [
+      {
+        "name": "primary",
+        "example": "oklch(0.55 0.2 260)",
+        "about": "color de acción principal (botones, foco)"
+      },
+      {
+        "name": "primary-foreground",
+        "example": "#ffffff",
+        "about": "texto sobre el color principal (comprueba el contraste)"
+      },
+      {
+        "name": "ring",
+        "example": "oklch(0.55 0.2 260)",
+        "about": "anillo de foco; suele ir igual que primary"
+      },
+      {
+        "name": "link",
+        "example": "oklch(0.5 0.15 260)",
+        "about": "texto de enlace: más oscuro que primary para tener contraste"
+      },
+      {
+        "name": "link-hover",
+        "example": "oklch(0.42 0.13 260)",
+        "about": "enlace al pasar el ratón"
+      },
+      {
+        "name": "brand",
+        "example": "oklch(0.7 0.13 220)",
+        "about": "acento de marca (detalles, selección)"
+      },
+      {
+        "name": "brand-bright",
+        "example": "oklch(0.8 0.13 220)",
+        "about": "acento de marca sobre fondos oscuros"
+      },
+      {
+        "name": "sidebar-primary",
+        "example": "oklch(0.8 0.13 220)",
+        "about": "acento dentro del sidebar"
+      },
+      {
+        "name": "sidebar-primary-foreground",
+        "example": "#04121c",
+        "about": "texto sobre el acento del sidebar"
+      },
+      {
+        "name": "sidebar-accent-foreground",
+        "example": "oklch(0.85 0.1 220)",
+        "about": "texto del destino activo del sidebar"
+      },
+      {
+        "name": "accent-foreground",
+        "example": "oklch(0.5 0.15 260)",
+        "about": "texto sobre superficies de acento suave"
+      },
+      {
+        "name": "chart-1",
+        "example": "oklch(0.55 0.2 260)",
+        "about": "primera serie de las gráficas: la marca"
+      },
+      {
+        "name": "radius",
+        "example": "12px",
+        "about": "redondez base (en temas cuya rampa deriva de ella)"
+      },
+      {
+        "name": "ds-font-sans",
+        "example": "'Inter', system-ui, sans-serif",
+        "about": "fuente del cuerpo (carga la fuente en tu app)"
+      },
+      {
+        "name": "ds-font-display",
+        "example": "'Sora', system-ui, sans-serif",
+        "about": "fuente de los titulares"
+      }
+    ]
+  }
 }

package/dist/themes/twitter.css

@@ -0,0 +1,290 @@
+/*
+ * TEMA twitter — la interfaz de Twitter anterior a X (rediseño de 2021).
+ *
+ * Personalidad: PLANO y de alto contraste. Sin sombras ni cristal en el contenido;
+ * separación por filetes de 1px; botones en píldora con peso 700; tarjetas de 16px
+ * sin elevación; sidebar a ras de borde, sin fondo, con filas en píldora y la activa
+ * en negrita; pestañas con subrayado de acento. Azul de marca #1D9BF0 (confirmado) con
+ * «menos azul»: la acción más importante puede ir en tinta (negro/blanco).
+ *
+ * VALORES APROXIMADOS: el azul de marca y la fuente (Chirp, propietaria) están
+ * documentados; los grises, bordes y los fondos de «Dim» son de memoria y NO se han
+ * contrastado con la hoja de estilos real — ajústalos con una captura de referencia.
+ * Chirp no se puede distribuir: se usa la pila del sistema como respaldo.
+ *
+ * Importar DESPUÉS de la estructura. Variables `--zt-*`: privadas de este tema.
+ */
+
+/* ── VARIABLES · PIEL CLARA ──────────────────────────────────────────────── */
+:root {
+  --radius: 16px;
+
+  --ds-font-sans: 'Chirp', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+  --ds-font-display: var(--ds-font-sans);
+  --ds-font-mono: ui-monospace, 'SF Mono', Menlo, monospace;
+  --ds-heading-tracking: normal;
+
+  /* Color */
+  --background: #ffffff;
+  --foreground: #0f1419;
+
+  --card: #ffffff;
+  --card-foreground: #0f1419;
+  --popover: #ffffff;
+  --popover-foreground: #0f1419;
+
+  --primary: #1d9bf0;
+  --primary-foreground: #ffffff;
+  --secondary: #eff3f4;
+  --secondary-foreground: #0f1419;
+  --muted: #f7f9f9;
+  --muted-foreground: #536471;
+  --accent: rgba(29, 155, 240, 0.1);
+  --accent-foreground: #1a8cd8;
+  --destructive: #f4212e;
+  --destructive-foreground: #ffffff;
+
+  --border: #eff3f4;
+  --input: #cfd9de;
+  --ring: #1d9bf0;
+
+  --chart-1: #1d9bf0;
+  --chart-2: #00ba7c;
+  --chart-3: #ffd400;
+  --chart-4: #f91880;
+  --chart-5: #7856ff;
+
+  --sidebar: transparent;
+  --sidebar-foreground: #0f1419;
+  --sidebar-primary: #1d9bf0;
+  --sidebar-primary-foreground: #ffffff;
+  --sidebar-accent: rgba(15, 20, 25, 0.1);
+  --sidebar-accent-foreground: #0f1419;
+  --sidebar-border: #eff3f4;
+  --sidebar-ring: #1d9bf0;
+
+  --danger: #d4141f;
+  --danger-soft: rgba(244, 33, 46, 0.1);
+  --warning: #8a6d00;
+  --warning-soft: rgba(255, 212, 0, 0.2);
+  --success: #00875a;
+  --success-soft: rgba(0, 186, 124, 0.12);
+  --info: #1a8cd8;
+  --info-soft: rgba(29, 155, 240, 0.1);
+  --neutral: #536471;
+  --neutral-soft: #eff3f4;
+
+  --link: #1d9bf0;
+  --link-hover: #1a8cd8;
+  --inset: #f7f9f9;
+  --inset-foreground: #0f1419;
+  --brand: #1d9bf0;
+  --brand-bright: #1d9bf0;
+
+  /* Formas: píldoras para acciones, 16px para superficies */
+  --ds-radius-sm: 8px;
+  --ds-radius-md: 12px;
+  --ds-radius-lg: 16px;
+  --ds-radius-xl: 16px;
+  --ds-radius-2xl: 20px;
+  --ds-radius-control: 9999px;
+  --ds-radius-overlay: 16px;
+
+  /* Sin elevación: solo los menús flotantes llevan sombra, muy suave */
+  --ds-shadow-card: 0 0 #0000;
+  --ds-shadow-card-hover: 0 0 #0000;
+  --ds-shadow-control: 0 0 #0000;
+  --ds-shadow-raised: 0 0 #0000;
+  --ds-shadow-overlay: 0 0 15px rgba(101, 119, 134, 0.2), 0 0 3px 1px rgba(101, 119, 134, 0.15);
+  --ds-shadow-popover: 0 0 15px rgba(101, 119, 134, 0.2), 0 0 3px 1px rgba(101, 119, 134, 0.15);
+
+  /* Medidas */
+  --ds-control-h-sm: 2rem;
+  --ds-control-h-md: 2.25rem;
+  --ds-control-h-lg: 3.25rem;
+  --ds-button-px-sm: 1rem;
+  --ds-button-px-md: 1.25rem;
+  --ds-button-px-lg: 2rem;
+  --ds-field-px: 1rem;
+  --ds-card-spacing: 1rem;
+  --ds-card-spacing-sm: 0.75rem;
+
+  /* Materiales: ninguno (plano) */
+  --ds-card-backdrop: none;
+  --ds-overlay-backdrop: none;
+  --ds-field-backdrop: none;
+  --ds-sidebar-backdrop: none;
+  --ds-page-backdrop: none;
+
+  /* Sidebar a ras de borde, sin silueta; filas en píldora grandes */
+  --ds-sidebar-pad: 0px;
+  --ds-sidebar-radius: 0px;
+  --ds-sidebar-shadow: 0 0 #0000;
+  --ds-sidebar-ring: 0px;
+  --ds-sidebar-edge: 1px solid var(--sidebar-border);
+  --ds-sidebar-item-radius: 9999px;
+  --ds-sidebar-item-h: 3.25rem;
+
+  /* Privadas de twitter */
+  --zt-hover: rgba(15, 20, 25, 0.1);
+  --zt-hover-soft: rgba(15, 20, 25, 0.03);
+  --zt-line-strong: #cfd9de;
+  --zt-ink: #0f1419;
+  --zt-ink-foreground: #ffffff;
+}
+
+/* ── VARIABLES · PIEL OSCURA («Dim») ─────────────────────────────────────── */
+.dark {
+  --background: #15202b;
+  --foreground: #f7f9f9;
+
+  --card: #15202b;
+  --card-foreground: #f7f9f9;
+  --popover: #1e2732;
+  --popover-foreground: #f7f9f9;
+
+  --primary: #1d9bf0;
+  --primary-foreground: #ffffff;
+  --secondary: #1e2732;
+  --secondary-foreground: #f7f9f9;
+  --muted: #1e2732;
+  --muted-foreground: #8b98a5;
+  --accent: rgba(29, 155, 240, 0.15);
+  --accent-foreground: #4db3f5;
+  --destructive: #f4212e;
+  --destructive-foreground: #ffffff;
+
+  --border: #38444d;
+  --input: #536471;
+  --ring: #1d9bf0;
+
+  --sidebar: transparent;
+  --sidebar-foreground: #f7f9f9;
+  --sidebar-primary: #1d9bf0;
+  --sidebar-primary-foreground: #ffffff;
+  --sidebar-accent: rgba(247, 249, 249, 0.1);
+  --sidebar-accent-foreground: #f7f9f9;
+  --sidebar-border: #38444d;
+  --sidebar-ring: #1d9bf0;
+
+  --danger: #ff5a64;
+  --danger-soft: rgba(244, 33, 46, 0.18);
+  --warning: #ffd400;
+  --warning-soft: rgba(255, 212, 0, 0.16);
+  --success: #00ba7c;
+  --success-soft: rgba(0, 186, 124, 0.16);
+  --info: #4db3f5;
+  --info-soft: rgba(29, 155, 240, 0.18);
+  --neutral: #8b98a5;
+  --neutral-soft: #1e2732;
+
+  --link: #4db3f5;
+  --link-hover: #8dcdf8;
+  --inset: #1e2732;
+  --inset-foreground: #f7f9f9;
+  --brand: #1d9bf0;
+  --brand-bright: #4db3f5;
+
+  --ds-shadow-overlay: 0 0 15px rgba(255, 255, 255, 0.2), 0 0 3px 1px rgba(255, 255, 255, 0.15);
+  --ds-shadow-popover: 0 0 15px rgba(255, 255, 255, 0.2), 0 0 3px 1px rgba(255, 255, 255, 0.15);
+
+  --zt-hover: rgba(247, 249, 249, 0.1);
+  --zt-hover-soft: rgba(247, 249, 249, 0.03);
+  --zt-line-strong: #536471;
+  --zt-ink: #eff3f4;
+  --zt-ink-foreground: #0f1419;
+}
+
+/* ── PERSONALIDAD ────────────────────────────────────────────────────────────
+ * Sin capa: gana a las utilidades de los componentes. Solo variables.
+ */
+:root {
+  /* Botones: píldora en peso 700; primario en azul; contorno con filete */
+  [data-slot='button'] {
+    border-radius: 9999px;
+    font-weight: 700;
+  }
+  [data-slot='button'][data-variant='default']:hover:not(:disabled) {
+    background-color: var(--link-hover);
+  }
+  [data-slot='button'][data-variant='secondary'] {
+    background: var(--zt-ink);
+    color: var(--zt-ink-foreground);
+  }
+  [data-slot='button'][data-variant='secondary']:hover:not(:disabled) {
+    opacity: 0.88;
+  }
+  [data-slot='button'][data-variant='outline'] {
+    background: transparent;
+    border: 1px solid var(--zt-line-strong);
+    color: var(--foreground);
+  }
+  [data-slot='button'][data-variant='outline']:hover:not(:disabled),
+  [data-slot='button'][data-variant='ghost']:hover:not(:disabled) {
+    background: var(--zt-hover);
+  }
+  [data-slot='button'][data-variant='destructive'] {
+    background: var(--destructive);
+    color: var(--destructive-foreground);
+  }
+
+  /* Tarjetas: planas, con filete, sin elevación */
+  [data-slot='card'] {
+    border: 1px solid var(--border);
+    box-shadow: none;
+  }
+
+  /* Campos: píldora/16px con filete; foco azul lo da el anillo */
+  [data-slot='input'],
+  [data-slot='textarea'],
+  [data-slot='select-trigger'] {
+    background: transparent;
+    border: 1px solid var(--input);
+  }
+  [data-slot='textarea'] {
+    border-radius: var(--ds-radius-lg);
+  }
+
+  /* Etiquetas en píldora */
+  [data-slot='badge'] {
+    border-radius: 9999px;
+  }
+
+  /* Pestañas: sin fondo, subrayado de acento en la activa */
+  [data-slot='tabs-list'] {
+    background: transparent;
+    border-bottom: 1px solid var(--border);
+    border-radius: 0;
+  }
+  [data-slot='tabs-trigger'] {
+    border-radius: 0;
+    background: transparent;
+    font-weight: 500;
+  }
+  [data-slot='tabs-trigger']:hover {
+    background: var(--zt-hover-soft);
+  }
+  [data-slot='tabs-trigger'][data-active] {
+    background: transparent;
+    box-shadow: inset 0 -4px 0 var(--primary);
+    font-weight: 700;
+  }
+
+  /* Sidebar: filas grandes en píldora; la activa en negrita, sin relleno */
+  [data-sidebar='menu-button'] {
+    font-size: 1.125rem;
+    border-radius: 9999px;
+  }
+  [data-sidebar='menu-button']:hover {
+    background: var(--zt-hover);
+  }
+  [data-sidebar='menu-button'][data-active='true'] {
+    background: transparent;
+    font-weight: 700;
+  }
+
+  /* Interruptor y progreso en el azul de marca, planos */
+  [data-slot='progress-indicator'] {
+    background: var(--primary);
+  }
+}

package/dist/themes/twitter.fonts.css

@@ -0,0 +1,6 @@
+/*
+ * Fuentes del tema twitter. Chirp (la fuente de Twitter) es propietaria y no se
+ * puede distribuir: no hay nada que cargar. El tema usa la pila del sistema como
+ * respaldo (`-apple-system, Segoe UI, Roboto…`). Si tienes licencia de Chirp, defínela
+ * con @font-face en tu app y quedará aplicada.
+ */

package/dist/themes/twitter.scoped.css

@@ -0,0 +1,290 @@
+/*
+ * TEMA twitter — la interfaz de Twitter anterior a X (rediseño de 2021).
+ *
+ * Personalidad: PLANO y de alto contraste. Sin sombras ni cristal en el contenido;
+ * separación por filetes de 1px; botones en píldora con peso 700; tarjetas de 16px
+ * sin elevación; sidebar a ras de borde, sin fondo, con filas en píldora y la activa
+ * en negrita; pestañas con subrayado de acento. Azul de marca #1D9BF0 (confirmado) con
+ * «menos azul»: la acción más importante puede ir en tinta (negro/blanco).
+ *
+ * VALORES APROXIMADOS: el azul de marca y la fuente (Chirp, propietaria) están
+ * documentados; los grises, bordes y los fondos de «Dim» son de memoria y NO se han
+ * contrastado con la hoja de estilos real — ajústalos con una captura de referencia.
+ * Chirp no se puede distribuir: se usa la pila del sistema como respaldo.
+ *
+ * Importar DESPUÉS de la estructura. Variables `--zt-*`: privadas de este tema.
+ */
+
+/* ── VARIABLES · PIEL CLARA ──────────────────────────────────────────────── */
+:root[data-theme='twitter'] {
+  --radius: 16px;
+
+  --ds-font-sans: 'Chirp', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+  --ds-font-display: var(--ds-font-sans);
+  --ds-font-mono: ui-monospace, 'SF Mono', Menlo, monospace;
+  --ds-heading-tracking: normal;
+
+  /* Color */
+  --background: #ffffff;
+  --foreground: #0f1419;
+
+  --card: #ffffff;
+  --card-foreground: #0f1419;
+  --popover: #ffffff;
+  --popover-foreground: #0f1419;
+
+  --primary: #1d9bf0;
+  --primary-foreground: #ffffff;
+  --secondary: #eff3f4;
+  --secondary-foreground: #0f1419;
+  --muted: #f7f9f9;
+  --muted-foreground: #536471;
+  --accent: rgba(29, 155, 240, 0.1);
+  --accent-foreground: #1a8cd8;
+  --destructive: #f4212e;
+  --destructive-foreground: #ffffff;
+
+  --border: #eff3f4;
+  --input: #cfd9de;
+  --ring: #1d9bf0;
+
+  --chart-1: #1d9bf0;
+  --chart-2: #00ba7c;
+  --chart-3: #ffd400;
+  --chart-4: #f91880;
+  --chart-5: #7856ff;
+
+  --sidebar: transparent;
+  --sidebar-foreground: #0f1419;
+  --sidebar-primary: #1d9bf0;
+  --sidebar-primary-foreground: #ffffff;
+  --sidebar-accent: rgba(15, 20, 25, 0.1);
+  --sidebar-accent-foreground: #0f1419;
+  --sidebar-border: #eff3f4;
+  --sidebar-ring: #1d9bf0;
+
+  --danger: #d4141f;
+  --danger-soft: rgba(244, 33, 46, 0.1);
+  --warning: #8a6d00;
+  --warning-soft: rgba(255, 212, 0, 0.2);
+  --success: #00875a;
+  --success-soft: rgba(0, 186, 124, 0.12);
+  --info: #1a8cd8;
+  --info-soft: rgba(29, 155, 240, 0.1);
+  --neutral: #536471;
+  --neutral-soft: #eff3f4;
+
+  --link: #1d9bf0;
+  --link-hover: #1a8cd8;
+  --inset: #f7f9f9;
+  --inset-foreground: #0f1419;
+  --brand: #1d9bf0;
+  --brand-bright: #1d9bf0;
+
+  /* Formas: píldoras para acciones, 16px para superficies */
+  --ds-radius-sm: 8px;
+  --ds-radius-md: 12px;
+  --ds-radius-lg: 16px;
+  --ds-radius-xl: 16px;
+  --ds-radius-2xl: 20px;
+  --ds-radius-control: 9999px;
+  --ds-radius-overlay: 16px;
+
+  /* Sin elevación: solo los menús flotantes llevan sombra, muy suave */
+  --ds-shadow-card: 0 0 #0000;
+  --ds-shadow-card-hover: 0 0 #0000;
+  --ds-shadow-control: 0 0 #0000;
+  --ds-shadow-raised: 0 0 #0000;
+  --ds-shadow-overlay: 0 0 15px rgba(101, 119, 134, 0.2), 0 0 3px 1px rgba(101, 119, 134, 0.15);
+  --ds-shadow-popover: 0 0 15px rgba(101, 119, 134, 0.2), 0 0 3px 1px rgba(101, 119, 134, 0.15);
+
+  /* Medidas */
+  --ds-control-h-sm: 2rem;
+  --ds-control-h-md: 2.25rem;
+  --ds-control-h-lg: 3.25rem;
+  --ds-button-px-sm: 1rem;
+  --ds-button-px-md: 1.25rem;
+  --ds-button-px-lg: 2rem;
+  --ds-field-px: 1rem;
+  --ds-card-spacing: 1rem;
+  --ds-card-spacing-sm: 0.75rem;
+
+  /* Materiales: ninguno (plano) */
+  --ds-card-backdrop: none;
+  --ds-overlay-backdrop: none;
+  --ds-field-backdrop: none;
+  --ds-sidebar-backdrop: none;
+  --ds-page-backdrop: none;
+
+  /* Sidebar a ras de borde, sin silueta; filas en píldora grandes */
+  --ds-sidebar-pad: 0px;
+  --ds-sidebar-radius: 0px;
+  --ds-sidebar-shadow: 0 0 #0000;
+  --ds-sidebar-ring: 0px;
+  --ds-sidebar-edge: 1px solid var(--sidebar-border);
+  --ds-sidebar-item-radius: 9999px;
+  --ds-sidebar-item-h: 3.25rem;
+
+  /* Privadas de twitter */
+  --zt-hover: rgba(15, 20, 25, 0.1);
+  --zt-hover-soft: rgba(15, 20, 25, 0.03);
+  --zt-line-strong: #cfd9de;
+  --zt-ink: #0f1419;
+  --zt-ink-foreground: #ffffff;
+}
+
+/* ── VARIABLES · PIEL OSCURA («Dim») ─────────────────────────────────────── */
+:root[data-theme='twitter'].dark {
+  --background: #15202b;
+  --foreground: #f7f9f9;
+
+  --card: #15202b;
+  --card-foreground: #f7f9f9;
+  --popover: #1e2732;
+  --popover-foreground: #f7f9f9;
+
+  --primary: #1d9bf0;
+  --primary-foreground: #ffffff;
+  --secondary: #1e2732;
+  --secondary-foreground: #f7f9f9;
+  --muted: #1e2732;
+  --muted-foreground: #8b98a5;
+  --accent: rgba(29, 155, 240, 0.15);
+  --accent-foreground: #4db3f5;
+  --destructive: #f4212e;
+  --destructive-foreground: #ffffff;
+
+  --border: #38444d;
+  --input: #536471;
+  --ring: #1d9bf0;
+
+  --sidebar: transparent;
+  --sidebar-foreground: #f7f9f9;
+  --sidebar-primary: #1d9bf0;
+  --sidebar-primary-foreground: #ffffff;
+  --sidebar-accent: rgba(247, 249, 249, 0.1);
+  --sidebar-accent-foreground: #f7f9f9;
+  --sidebar-border: #38444d;
+  --sidebar-ring: #1d9bf0;
+
+  --danger: #ff5a64;
+  --danger-soft: rgba(244, 33, 46, 0.18);
+  --warning: #ffd400;
+  --warning-soft: rgba(255, 212, 0, 0.16);
+  --success: #00ba7c;
+  --success-soft: rgba(0, 186, 124, 0.16);
+  --info: #4db3f5;
+  --info-soft: rgba(29, 155, 240, 0.18);
+  --neutral: #8b98a5;
+  --neutral-soft: #1e2732;
+
+  --link: #4db3f5;
+  --link-hover: #8dcdf8;
+  --inset: #1e2732;
+  --inset-foreground: #f7f9f9;
+  --brand: #1d9bf0;
+  --brand-bright: #4db3f5;
+
+  --ds-shadow-overlay: 0 0 15px rgba(255, 255, 255, 0.2), 0 0 3px 1px rgba(255, 255, 255, 0.15);
+  --ds-shadow-popover: 0 0 15px rgba(255, 255, 255, 0.2), 0 0 3px 1px rgba(255, 255, 255, 0.15);
+
+  --zt-hover: rgba(247, 249, 249, 0.1);
+  --zt-hover-soft: rgba(247, 249, 249, 0.03);
+  --zt-line-strong: #536471;
+  --zt-ink: #eff3f4;
+  --zt-ink-foreground: #0f1419;
+}
+
+/* ── PERSONALIDAD ────────────────────────────────────────────────────────────
+ * Sin capa: gana a las utilidades de los componentes. Solo variables.
+ */
+:root[data-theme='twitter'] {
+  /* Botones: píldora en peso 700; primario en azul; contorno con filete */
+  [data-slot='button'] {
+    border-radius: 9999px;
+    font-weight: 700;
+  }
+  [data-slot='button'][data-variant='default']:hover:not(:disabled) {
+    background-color: var(--link-hover);
+  }
+  [data-slot='button'][data-variant='secondary'] {
+    background: var(--zt-ink);
+    color: var(--zt-ink-foreground);
+  }
+  [data-slot='button'][data-variant='secondary']:hover:not(:disabled) {
+    opacity: 0.88;
+  }
+  [data-slot='button'][data-variant='outline'] {
+    background: transparent;
+    border: 1px solid var(--zt-line-strong);
+    color: var(--foreground);
+  }
+  [data-slot='button'][data-variant='outline']:hover:not(:disabled),
+  [data-slot='button'][data-variant='ghost']:hover:not(:disabled) {
+    background: var(--zt-hover);
+  }
+  [data-slot='button'][data-variant='destructive'] {
+    background: var(--destructive);
+    color: var(--destructive-foreground);
+  }
+
+  /* Tarjetas: planas, con filete, sin elevación */
+  [data-slot='card'] {
+    border: 1px solid var(--border);
+    box-shadow: none;
+  }
+
+  /* Campos: píldora/16px con filete; foco azul lo da el anillo */
+  [data-slot='input'],
+  [data-slot='textarea'],
+  [data-slot='select-trigger'] {
+    background: transparent;
+    border: 1px solid var(--input);
+  }
+  [data-slot='textarea'] {
+    border-radius: var(--ds-radius-lg);
+  }
+
+  /* Etiquetas en píldora */
+  [data-slot='badge'] {
+    border-radius: 9999px;
+  }
+
+  /* Pestañas: sin fondo, subrayado de acento en la activa */
+  [data-slot='tabs-list'] {
+    background: transparent;
+    border-bottom: 1px solid var(--border);
+    border-radius: 0;
+  }
+  [data-slot='tabs-trigger'] {
+    border-radius: 0;
+    background: transparent;
+    font-weight: 500;
+  }
+  [data-slot='tabs-trigger']:hover {
+    background: var(--zt-hover-soft);
+  }
+  [data-slot='tabs-trigger'][data-active] {
+    background: transparent;
+    box-shadow: inset 0 -4px 0 var(--primary);
+    font-weight: 700;
+  }
+
+  /* Sidebar: filas grandes en píldora; la activa en negrita, sin relleno */
+  [data-sidebar='menu-button'] {
+    font-size: 1.125rem;
+    border-radius: 9999px;
+  }
+  [data-sidebar='menu-button']:hover {
+    background: var(--zt-hover);
+  }
+  [data-sidebar='menu-button'][data-active='true'] {
+    background: transparent;
+    font-weight: 700;
+  }
+
+  /* Interruptor y progreso en el azul de marca, planos */
+  [data-slot='progress-indicator'] {
+    background: var(--primary);
+  }
+}

package/dist/themes/zyro.css

@@ -341,3 +341,41 @@
     background: var(--zy-conv-h);
   }
 }
+
+/* Ajustes de personalidad (vistos en el banco de pruebas) */
+:root {
+  /* Grupos de botones: píldora solo en los extremos, el interior recto */
+  [data-slot='button-group'] [data-slot='button'] {
+    border-radius: 0;
+  }
+  [data-slot='button-group'] [data-slot='button']:first-child {
+    border-start-start-radius: 9999px;
+    border-end-start-radius: 9999px;
+  }
+  [data-slot='button-group'] [data-slot='button']:last-child {
+    border-start-end-radius: 9999px;
+    border-end-end-radius: 9999px;
+  }
+
+  /* Esqueletos: visibles sobre la tarjeta casi blanca */
+  [data-slot='skeleton'] {
+    background: color-mix(in oklch, var(--foreground) 9%, transparent);
+  }
+}
+
+/* Fondo vivo: los degradados derivan despacio (aproximación ligera, sin WebGL de la
+   malla original). `prefers-reduced-motion` ya detiene la animación en la estructura. */
+:root {
+  body {
+    background-size: 160% 160%;
+    animation: zy-drift 40s ease-in-out infinite alternate;
+  }
+}
+@keyframes zy-drift {
+  from {
+    background-position: 0% 0%;
+  }
+  to {
+    background-position: 100% 100%;
+  }
+}

package/dist/themes/zyro.scoped.css

@@ -341,3 +341,41 @@
     background: var(--zy-conv-h);
   }
 }
+
+/* Ajustes de personalidad (vistos en el banco de pruebas) */
+:root[data-theme='zyro'] {
+  /* Grupos de botones: píldora solo en los extremos, el interior recto */
+  [data-slot='button-group'] [data-slot='button'] {
+    border-radius: 0;
+  }
+  [data-slot='button-group'] [data-slot='button']:first-child {
+    border-start-start-radius: 9999px;
+    border-end-start-radius: 9999px;
+  }
+  [data-slot='button-group'] [data-slot='button']:last-child {
+    border-start-end-radius: 9999px;
+    border-end-end-radius: 9999px;
+  }
+
+  /* Esqueletos: visibles sobre la tarjeta casi blanca */
+  [data-slot='skeleton'] {
+    background: color-mix(in oklch, var(--foreground) 9%, transparent);
+  }
+}
+
+/* Fondo vivo: los degradados derivan despacio (aproximación ligera, sin WebGL de la
+   malla original). `prefers-reduced-motion` ya detiene la animación en la estructura. */
+:root[data-theme='zyro'] {
+  body {
+    background-size: 160% 160%;
+    animation: zy-drift 40s ease-in-out infinite alternate;
+  }
+}
+@keyframes zy-drift {
+  from {
+    background-position: 0% 0%;
+  }
+  to {
+    background-position: 100% 100%;
+  }
+}

package/docs/CONTRACT.md

@@ -84,6 +84,35 @@ Los **materiales** son lo que hace posible un tema de cristal como `zyro`: con v
 neutros no hay efecto ni coste; con `blur(28px) saturate(180%)` las superficies se
 vuelven translúcidas.
 
+## Capa de marca (`brand.css`): lo que cambia una app, y nunca se pisa
+
+Tres capas, de menos a más personal:
+
+1. **Estructura y componentes** (paquete): se actualizan.
+2. **Tema y personalidad** (paquete: `qratia`, `zyro`…): formas, sombras, materiales,
+   anatomía del sidebar. Se actualizan con versión y changelog.
+3. **Marca** (`src/brand.css`, **en la app**): el grupo estable de variables que una marca
+   suele cambiar (`brand.tokens` en `contract.json`: color principal, foco, enlace,
+   acento, radio, fuentes). Se importa **después** del tema, así gana, y **ninguna
+   actualización lo toca**. Sin fichero, o vacío, se aplica el estándar del tema.
+
+```css
+@import 'orbital-ds/themes/qratia.css';
+@import './brand.css';   /* tuyo: gana al tema */
+```
+
+`pnpm exec orbital-ds-init` lo crea la primera vez (con las variables comentadas) y **nunca
+sobrescribe** uno existente.
+
+**Por qué una actualización no lo rompe:** los nombres de ese grupo son estables; quitar o
+renombrar uno es versión **mayor**, con aviso antes. Además,
+`orbital-ds-doctor --css src/brand.css` falla si el fichero usa una `--ds-*` que el paquete
+ya no define, para que una renombrada no se ignore en silencio.
+
+**Cambiar el color principal:** mueve juntas `primary`, `ring`, `link`, `brand`,
+`sidebar-primary` y `chart-1`, y comprueba el contraste del texto sobre ellas. Nunca edites
+el tema dentro de `node_modules` para personalizar una app.
+
 ## Reglas de nombres
 
 - Todo en **inglés**: tokens, props y valores de variantes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orbital-ds",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -19,13 +19,14 @@
   "files": [
     "dist",
     "scripts/doctor.mjs",
-    "scripts/manifest.mjs",
     "contract.json",
     "components.manifest.json",
     "docs",
     "AGENTS.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "scripts/init.mjs",
+    "scripts/manifest.mjs"
   ],
   "exports": {
     "./styles.css": "./dist/styles.css",
@@ -133,6 +134,7 @@
     "react-resizable-panels": "^4.14.4"
   },
   "bin": {
-    "orbital-ds-doctor": "./scripts/doctor.mjs"
+    "orbital-ds-doctor": "./scripts/doctor.mjs",
+    "orbital-ds-init": "./scripts/init.mjs"
   }
 }

package/scripts/doctor.mjs

@@ -65,6 +65,21 @@ function declarations(body) {
   return [...top.matchAll(/(^|[;\s])(--[a-z0-9-]+)\s*:\s*([^;]*);?/gi)].map((m) => ({ name: m[2], value: m[3].trim() }));
 }
 
+/** Variables --ds-* que la estructura del paquete define (las que una app puede usar). */
+function knownDsVars() {
+  const f = existsSync(join(ROOT, 'src/styles.css')) ? join(ROOT, 'src/styles.css') : join(ROOT, 'dist/styles.css');
+  return new Set([...read(f).matchAll(/(--ds-[a-z0-9-]+)\s*:/g)].map((m) => m[1]));
+}
+
+// El grupo de marca debe ser coherente con el contrato: cada variable, o es del contrato, o es --ds-*.
+for (const t of contract.brand?.tokens ?? []) {
+  const inContract =
+    contract.root.includes(t.name) ||
+    contract.fonts.includes(t.name) ||
+    (t.name.startsWith('ds-') && knownDsVars().has(`--${t.name}`));
+  if (!inContract) errors.push(`contrato: la variable de marca --${t.name} ni es del contrato ni la define la estructura`);
+}
+
 const themeInfo = {}; // nombre → { rootVars:Set, darkVars:Set }
 
 function checkTheme(file, name) {
@@ -141,6 +156,13 @@ if (cssArgIdx > -1 && process.argv[cssArgIdx + 1]) {
     const seen = new Map();
     for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
     for (const [v, n] of seen) if (n > 1) errors.push(`app css: ${v} definido ${n} veces en :root (#${idx + 1})`);
+    // Una variable --ds-* que el paquete ya no tiene: la marca la ignoraría en silencio.
+    const known = knownDsVars();
+    for (const d of declarations(body)) {
+      if (d.name.startsWith('--ds-') && !known.has(d.name)) {
+        errors.push(`app css: ${d.name} no existe en orbital-ds (¿renombrada o retirada? mira docs/CONTRACT.md)`);
+      }
+    }
   });
 }
 

package/scripts/init.mjs

@@ -0,0 +1,55 @@
+#!/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.
+ */
+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');
+
+if (existsSync(out)) {
+  console.log(`Ya existe ${out}: no se toca (es de tu app).`);
+  process.exit(0);
+}
+
+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`);