orbital-ds 0.7.0 → 0.9.0

package/dist/ui/toggle.js

@@ -3,7 +3,7 @@ import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
 import { cva } from "class-variance-authority";
 import { cn } from "../lib/utils";
 const toggleVariants = cva(
-  "group/toggle inline-flex items-center justify-center gap-1 rounded-control text-sm font-medium whitespace-nowrap transition-colors outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-(length:--ds-ring-width) focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-muted dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  "group/toggle inline-flex items-center justify-center gap-1 rounded-control text-sm font-medium whitespace-nowrap transition-colors duration-(--ds-motion-snap) outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-(length:--ds-ring-width) focus-visible:ring-(--ds-ring-color) disabled:pointer-events-none disabled:opacity-(--ds-disabled-opacity) aria-invalid:border-(--ds-invalid-border) aria-invalid:ring-(--ds-invalid-ring) aria-pressed:bg-muted [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
   {
     variants: {
       variant: {
@@ -11,9 +11,9 @@ const toggleVariants = cva(
         outline: "border border-input bg-transparent hover:bg-muted"
       },
       size: {
-        default: "h-9 min-w-9 px-3 has-data-[icon=inline-end]:pr-2.5 has-data-[icon=inline-start]:pl-2.5",
-        sm: "h-8 min-w-8 px-3 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
-        lg: "h-10 min-w-10 px-4 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3"
+        default: "h-(--ds-control-h-md) min-w-(--ds-control-h-md) px-3 has-data-[icon=inline-end]:pr-2.5 has-data-[icon=inline-start]:pl-2.5",
+        sm: "h-(--ds-control-h-sm) min-w-(--ds-control-h-sm) px-3 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        lg: "h-(--ds-control-h-lg) min-w-(--ds-control-h-lg) px-4 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3"
       }
     },
     defaultVariants: {
@@ -32,6 +32,8 @@ function Toggle({
     TogglePrimitive,
     {
       "data-slot": "toggle",
+      "data-variant": variant,
+      "data-size": size,
       className: cn(toggleVariants({ variant, size, className })),
       ...props
     }

package/dist/ui/tooltip.js

@@ -42,13 +42,13 @@ function TooltipContent({
         {
           "data-slot": "tooltip-content",
           className: cn(
-            "z-(--ds-z-overlay) inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-2xl bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-(--ds-z-overlay) **:data-[slot=kbd]:rounded-control data-starting-style:animate-in data-starting-style:fade-in-0 data-starting-style:zoom-in-95 data-ending-style:animate-out data-ending-style:fade-out-0 data-ending-style:zoom-out-95",
+            "z-(--ds-z-overlay) inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-tooltip bg-(--ds-tooltip-bg) px-3 py-1.5 text-xs text-(--ds-tooltip-fg) has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-(--ds-z-overlay) **:data-[slot=kbd]:rounded-control data-starting-style:animate-in data-starting-style:fade-in-0 data-starting-style:zoom-in-95 data-ending-style:animate-out data-ending-style:fade-out-0 data-ending-style:zoom-out-95",
             className
           ),
           ...props,
           children: [
             children,
-            /* @__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]" })
+            /* @__PURE__ */ jsx(TooltipPrimitive.Arrow, { "data-slot": "tooltip-arrow", className: "z-(--ds-z-overlay) size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-xs bg-(--ds-tooltip-bg) fill-(--ds-tooltip-bg) data-[side=left]:translate-x-[-1.5px] data-[side=right]:translate-x-[1.5px]" })
           ]
         }
       )

package/docs/CONTRACT.md

@@ -1,153 +1,183 @@
-# Contrato de tema de orbital-ds
-
-Un **tema** es un fichero CSS (`themes/<nombre>.css`) que da valores a un conjunto
-cerrado de variables. Los componentes **solo** leen esas variables: ninguno lleva
-colores, medidas, sombras, capas ni duraciones escritos a mano. Por eso cambiar de
-tema cambia todo el aspecto sin tocar un componente.
-
-El contrato vive en [`contract.json`](../contract.json) y lo comprueba
-`pnpm check:ds` (que forma parte de `pnpm verify`): si a un tema le falta un token
-obligatorio, el build falla.
-
-## Cómo se usa
-
-```css
-@import 'orbital-ds/themes/qratia.fonts.css'; /* 0. las FUENTES del tema: lo PRIMERO del fichero */
-@import 'tailwindcss';
-@plugin '@tailwindcss/typography';
-@import 'tw-animate-css';
-
-@import 'orbital-ds/styles.css';        /* 1. la ESTRUCTURA común */
-@import 'orbital-ds/themes/qratia.css'; /* 2. un TEMA (después, para poder sobrescribir) */
-
-@source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
-```
-
-El tema se importa **después** de la estructura: así puede sobrescribir también la
-escala de radios y las sombras, que viven en `@theme`.
-
-Las **fuentes** van en un fichero aparte por tema (`themes/<tema>.fonts.css`, solo un
-`@import url(...)` de Google Fonts) porque un `@import` remoto solo vale al principio
-de la hoja. Importado el primero, el empaquetador lo sube al inicio y se cargan. Dentro
-del propio `<tema>.css` no se pueden poner.
-
-Los títulos usan `--font-display` (por defecto, la misma fuente que el cuerpo; un tema
-con fuente de titulares, como zyro, la sobrescribe).
-
-Para ajustar un valor sin crear un tema, se sobrescribe la variable al final:
-
-```css
-:root { --primary: oklch(0.55 0.2 260); }
-```
-
-## Tokens obligatorios (todo tema, en `:root`)
-
-| Grupo | Tokens |
-|---|---|
-| Forma | `--radius` |
-| Superficies y texto | `--background`, `--foreground`, `--card`, `--card-foreground`, `--popover`, `--popover-foreground` |
-| Acción | `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--accent`, `--accent-foreground` |
-| Atenuado | `--muted`, `--muted-foreground` |
-| Destructivo | `--destructive`, `--destructive-foreground` |
-| Líneas y foco | `--border`, `--input`, `--ring` |
-| Gráficos | `--chart-1` … `--chart-5` |
-| Sidebar | `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` |
-| Estados | `--danger`, `--warning`, `--success`, `--info`, `--neutral` y cada uno con su `-soft` |
-| Texto acentuado | `--link`, `--link-hover` |
-| Superficie hundida | `--inset`, `--inset-foreground` |
-| Marca | `--brand`, `--brand-bright` |
-| Tipografía | `--font-sans` (en `:root` o en `@theme`); opcional `--font-display` para titulares |
-
-En `.dark` se redefine lo que cambie; `check:ds` avisa (no falla) de los tokens
-principales que se hereden de la piel clara.
-
-`--destructive` es el rojo de **acciones** (botón de borrar); `--danger` es el rojo
-de **estado** (etiqueta de nivel crítico). Pueden coincidir, pero son huecos distintos.
-
-## Tokens con valor por defecto (el tema los puede cambiar)
-
-Los define la estructura con un valor neutro; un tema los sobrescribe si quiere.
-
-| Hueco | Variables |
-|---|---|
-| Radios semánticos | `--radius-control`, `--radius-overlay` (y la rampa `--radius-sm … 2xl`, derivada de `--radius`) |
-| Sombras | `--shadow-card`, `--shadow-card-hover`, `--shadow-control`, `--shadow-raised`, `--shadow-overlay`, `--shadow-popover` |
-| Altura de controles | `--ds-control-h-sm`, `-md`, `-lg` |
-| Espaciado interno | `--ds-card-spacing`, `--ds-card-spacing-sm`, `--ds-field-px`, `--ds-cell-p`, `--ds-overlay-p`, `--ds-overlay-gap`, `--ds-popover-p`, `--ds-menu-p`, `--ds-menu-item-px`, `--ds-menu-item-py`, `--ds-button-px-sm/md/lg`, `--ds-badge-px` |
-| 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` |
-| 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`) |
-
-Los **materiales** son lo que hace posible un tema de cristal como `zyro`: con valores
-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.
-- Los nombres que Tailwind convierte en utilidades (`--color-*`, `--radius-*`,
-  `--shadow-*`) siguen su convención y **no llevan prefijo**. El resto de variables
-  propias llevan el prefijo **`--ds-`** para no chocar con las de una app.
-- Un componente que necesite un hueco nuevo **añade el token** con un valor que deje
-  el aspecto como estaba; nunca escribe el valor en el componente.
-
-## Qué comprueba `pnpm check:ds`
-
-1. **Contrato**: cada tema define todos los tokens obligatorios.
-2. **Repetidos**: ninguna variable se define dos veces en el mismo bloque.
-3. **Valores fijos** en `src/ui/*.tsx`: colores literales (hex, `rgb()`, `oklch()`
-   salvo derivados de un token), `z-<n>`, `duration-<n>`, `bg-black`/`bg-white`,
-   sombras de la escala de Tailwind, `text-[<n>px]`, radios fuera de la rampa y
-   colores de la paleta de Tailwind.
-
-También se puede pasar el CSS de una app: `orbital-ds-doctor --css src/styles.css`
-(detecta variables repetidas).
-
-## Crear un tema nuevo
-
-1. Copia `themes/qratia.css` (o `zyro.css`) a `themes/<nombre>.css`.
-2. Cambia los valores; no quites ninguno.
-3. `pnpm check:ds`: te dice qué falta.
-4. Opcional: usa los materiales para dar cristal, relieve o un fondo propio.
-
-Se puede partir de un tema de shadcn (por ejemplo exportado desde tweakcn): usa los
-mismos nombres estándar (`--background`, `--primary`…). Habrá que añadir los tokens
-propios (`danger`, `warning`, `success`, `info`, `neutral`, `link`, `inset`, `brand`).
-
-## Cosas que un tema NO puede cambiar
-
-La **anatomía** de un componente (otro diseño de sidebar o de tarjeta) no es un valor,
-es estructura: se resuelve con variantes del componente. Un fondo animado (como la
-malla WebGL de zyro) es código, no una variable: se ofrece como componente opcional.
+# Contrato de tema de orbital-ds
+
+Un **tema** es un fichero CSS (`themes/<nombre>.css`) que da valores a un conjunto
+cerrado de variables. Los componentes **solo** leen esas variables: ninguno lleva
+colores, medidas, sombras, capas ni duraciones escritos a mano. Por eso cambiar de
+tema cambia todo el aspecto sin tocar un componente.
+
+El contrato vive en [`contract.json`](../contract.json) y lo comprueba
+`pnpm check:ds` (que forma parte de `pnpm verify`): si a un tema le falta un token
+obligatorio, el build falla.
+
+## Cómo se usa
+
+```css
+@import 'orbital-ds/themes/qratia.fonts.css'; /* 0. las FUENTES del tema: lo PRIMERO del fichero */
+@import 'tailwindcss';
+@plugin '@tailwindcss/typography';
+@import 'tw-animate-css';
+
+@import 'orbital-ds/styles.css';        /* 1. la ESTRUCTURA común */
+@import 'orbital-ds/themes/qratia.css'; /* 2. un TEMA (después, para poder sobrescribir) */
+
+@source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
+```
+
+El tema se importa **después** de la estructura: así puede sobrescribir también la
+escala de radios y las sombras, que viven en `@theme`.
+
+Las **fuentes** van en un fichero aparte por tema (`themes/<tema>.fonts.css`, solo un
+`@import url(...)` de Google Fonts) porque un `@import` remoto solo vale al principio
+de la hoja. Importado el primero, el empaquetador lo sube al inicio y se cargan. Dentro
+del propio `<tema>.css` no se pueden poner.
+
+Los títulos usan `--font-display` (por defecto, la misma fuente que el cuerpo; un tema
+con fuente de titulares, como zyro o tactile, la sobrescribe). Vale para h1–h4 y para
+**todos** los títulos de componente (card, dialog, sheet, alert, alert-dialog, drawer,
+empty, popover), con los ejes de `--ds-display-variation`.
+
+Para ajustar un valor sin crear un tema, se sobrescribe la variable al final:
+
+```css
+:root { --primary: oklch(0.55 0.2 260); }
+```
+
+## Tokens obligatorios (todo tema, en `:root`)
+
+| Grupo | Tokens |
+|---|---|
+| Forma | `--radius` |
+| Superficies y texto | `--background`, `--foreground`, `--card`, `--card-foreground`, `--popover`, `--popover-foreground` |
+| Acción | `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--accent`, `--accent-foreground` |
+| Atenuado | `--muted`, `--muted-foreground` |
+| Destructivo | `--destructive`, `--destructive-foreground` |
+| Líneas y foco | `--border`, `--input`, `--ring` |
+| Gráficos | `--chart-1` … `--chart-5` |
+| Sidebar | `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` |
+| Estados | `--danger`, `--warning`, `--success`, `--info`, `--neutral` y cada uno con su `-soft` |
+| Texto acentuado | `--link`, `--link-hover` |
+| Superficie hundida | `--inset`, `--inset-foreground` |
+| Marca | `--brand`, `--brand-bright` |
+| Tipografía | `--font-sans` (en `:root` o en `@theme`); opcional `--font-display` para titulares |
+
+En `.dark` se redefine lo que cambie; `check:ds` avisa (no falla) de los tokens
+principales que se hereden de la piel clara.
+
+`--destructive` es el rojo de **acciones** (botón de borrar); `--danger` es el rojo
+de **estado** (etiqueta de nivel crítico). Pueden coincidir, pero son huecos distintos.
+
+## Tokens con valor por defecto (el tema los puede cambiar)
+
+Los define la estructura con un valor neutro; un tema los sobrescribe si quiere.
+
+| Hueco | Variables |
+|---|---|
+| Radios semánticos | `--radius-control`, `--radius-overlay` (y la rampa `--radius-sm … 2xl`, derivada de `--radius`) |
+| Sombras | `--shadow-card`, `--shadow-card-hover`, `--shadow-control`, `--shadow-raised`, `--shadow-overlay`, `--shadow-popover` |
+| Altura de controles | `--ds-control-h-sm`, `-md`, `-lg` |
+| Espaciado interno | `--ds-card-spacing`, `--ds-card-spacing-sm`, `--ds-field-px`, `--ds-cell-p`, `--ds-overlay-p`, `--ds-overlay-gap`, `--ds-popover-p`, `--ds-menu-p`, `--ds-menu-item-px`, `--ds-menu-item-py`, `--ds-button-px-sm/md/lg`, `--ds-badge-px` |
+| 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` |
+| 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) |
+| **Gesto de tecla** | `--ds-key-outline`, `--ds-key-edge` (colores), `--ds-key-border` (contorno), `--ds-key-edge-w` / `-sm` / `-pressed` (arista en reposo, en controles pequeños y al pulsar), `--ds-key-press` / `-sm` (cuánto se hunde), `--ds-key-radius` / `-sm`, `--ds-key-weight`, `--ds-key-disabled-opacity`, `--ds-rule-w` (filete de superficies), `--ds-overlay-edge-w` (arista de diálogos). Valores neutros en la estructura; los usa la personalidad de un tema como `tactile` |
+| **Rotulador** | `--ds-marker` (color; `transparent` lo apaga), `--ds-marker-thickness` (grosor de la franja), `--ds-marker-offset` (cuánto sube); gesto **común**: lo dibuja la estructura en los títulos de cualquier tema |
+| **Títulos y etiquetas** | `--ds-display-variation` (ejes de la fuente de titulares, p. ej. `"SOFT" 50, "WONK" 1`), `--ds-heading-weight` (h1–h3), `--ds-title-weight`, `--ds-title-leading` (títulos de componente), `--ds-heading-tracking`, `--ds-label-tracking` (versalitas), `--ds-strong-weight`, `--ds-nav-weight`, `--ds-tabs-gap` |
+| **Personalidad común** | `--ds-radius-pill`, `--ds-button-case`, `--ds-button-tracking`, `--ds-button-outline-w`, `--ds-shadow-button` / `-hover`, `--ds-hover-lift`, `--ds-hover-opacity`, `--ds-tab-weight` / `-active-weight`, `--ds-tab-indicator-w`, `--ds-label-weight`, `--ds-nav-active-weight`. Huecos que **cualquier** tema usa en su personalidad (píldoras, botones en mayúsculas, brillo, subrayado de pestañas…) |
+| 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`) |
+
+Los **materiales** son lo que hace posible un tema de cristal como `zyro`: con valores
+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.
+- Los nombres que Tailwind convierte en utilidades (`--color-*`, `--radius-*`,
+  `--shadow-*`) siguen su convención y **no llevan prefijo**. El resto de variables
+  propias llevan el prefijo **`--ds-`** para no chocar con las de una app.
+- Un componente que necesite un hueco nuevo **añade el token** con un valor que deje
+  el aspecto como estaba; nunca escribe el valor en el componente.
+
+## Qué comprueba `pnpm check:ds`
+
+1. **Contrato**: cada tema define todos los tokens obligatorios.
+2. **Repetidos**: ninguna variable se define dos veces en el mismo bloque.
+3. **Valores fijos** en `src/ui/*.tsx`: colores literales (hex, `rgb()`, `oklch()`
+   salvo derivados de un token), `z-<n>`, `duration-<n>`, `bg-black`/`bg-white`,
+   sombras de la escala de Tailwind, `text-[<n>px]`, radios fuera de la rampa y
+   colores de la paleta de Tailwind.
+
+4. **Personalidad solo con variables**: una regla de personalidad (cualquier propiedad
+   que no sea `--x`) no escribe medidas, colores, pesos, opacidades, interlineados ni
+   duraciones; pide el hueco a una variable.
+5. **Familias completas** (`slotFamilies` en `contract.json`): si la personalidad
+   estiliza una pieza (`checkbox`), estiliza sus hermanas (`radio-group-item`). Familias:
+   choice, field, modal, floating, title, toggle, track.
+6. **Contraste AA** de los pares de texto principales y de los textos de estado; resuelve
+   `var(--x)`, así que un color derivado (`--sidebar-primary: var(--primary)`) también se mide.
+
+Las reglas 4 y 5 son **error** en un tema con `"conformance": "strict"` en su ficha
+(`<tema>.meta.json`) y **aviso** en los demás. **Todos los temas del paquete son estrictos**,
+y un tema nuevo debe nacer así.
+
+### Un solo sitio para cada cosa
+
+| Quién | Dónde cambia el aspecto | Qué toca |
+|---|---|---|
+| Autor de un tema | bloque «VARIABLES» del tema (`:root` y `.dark`) | valores; las reglas de PERSONALIDAD solo los leen |
+| App (o su agente) | `src/brand.css` | cualquier variable pública: color, forma, fuentes, gesto (`--ds-key-*`, `--ds-marker`, `--ds-radius-pill`…) |
+
+Ninguna regla escribe un valor, así que cambiar una variable cambia **todas** las piezas que
+la usan, en cualquier tema. Si una variable que lee la personalidad deriva de otra que cambia
+de piel (p. ej. una sombra con el color de marca), el tema la repite en `.dark`.
+
+También se puede pasar el CSS de una app: `orbital-ds-doctor --css src/styles.css`
+(detecta variables repetidas).
+
+## Crear un tema nuevo
+
+1. Copia `themes/qratia.css` (o `zyro.css`) a `themes/<nombre>.css`.
+2. Cambia los valores; no quites ninguno.
+3. `pnpm check:ds`: te dice qué falta.
+4. Opcional: usa los materiales para dar cristal, relieve o un fondo propio.
+
+Se puede partir de un tema de shadcn (por ejemplo exportado desde tweakcn): usa los
+mismos nombres estándar (`--background`, `--primary`…). Habrá que añadir los tokens
+propios (`danger`, `warning`, `success`, `info`, `neutral`, `link`, `inset`, `brand`).
+
+## Cosas que un tema NO puede cambiar
+
+La **anatomía** de un componente (otro diseño de sidebar o de tarjeta) no es un valor,
+es estructura: se resuelve con variantes del componente. Un fondo animado (como la
+malla WebGL de zyro) es código, no una variable: se ofrece como componente opcional.