orbital-ds 0.2.0 → 0.4.0

package/AGENTS.md

@@ -0,0 +1,60 @@
+# orbital-ds — guía para agentes de IA
+
+Sistema de diseño: **estructura común + temas + componentes** sobre Base UI y Tailwind v4.
+Todo está pensado para que un agente pueda usarlo, ampliarlo y comprobar su trabajo sin
+adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
+`components.manifest.json` (qué componentes hay, cómo se importan y qué `data-slot` exponen).
+
+## Reglas (obligatorias)
+
+1. **Solo variables.** Un componente no escribe colores, medidas, sombras, z-index ni
+   duraciones: pide un hueco a una variable (`--ds-*` o las de color de shadcn). Si falta el
+   hueco, **añade el token** con un valor que deje el aspecto como estaba y úsalo.
+2. **Añadir, nunca sustituir.** Un componente nuevo es un fichero nuevo en `src/ui/`. No se
+   reescribe ni se renombra uno existente para otro fin. No uses `--overwrite` de la CLI de
+   shadcn sin aprobación expresa. Quitar o renombrar algo público = versión **mayor**.
+3. **Nombres en inglés.** Tokens, props y valores de variantes. Variables propias con el
+   prefijo `--ds-`; las que Tailwind convierte en utilidades (`--color-*`, `--radius-*`,
+   `--shadow-*`) siguen su convención. Las privadas de un tema llevan el prefijo del tema
+   (`--zy-*`).
+4. **Un solo motor: Base UI.** Nada de Radix. `asChild` no existe: se usa `render`.
+5. **«Sin sombra» es `0 0 #0000`**, nunca `none` (invalida todo el `box-shadow`, anillo de
+   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
+
+- **Valores** (color, forma, fuentes, escala, sombras, espaciado, materiales, sidebar):
+  variables del tema en `src/themes/<tema>.css`.
+- **Personalidad de un elemento** (por ejemplo, botones en píldora con degradado): reglas en
+  la sección «PERSONALIDAD» del tema, dirigidas a los ganchos del DOM —`data-slot`,
+  `data-variant`, `data-size`, `data-active`, `data-state`— y escritas solo con variables. Van
+  **sin capa** para ganar a las utilidades; define también hover y active.
+- **Estructura** distinta de un componente (otro layout): variante del componente, no tema.
+
+## Cómo comprobar tu trabajo
+
+```bash
+pnpm check:ds    # contrato de tema, repetidos, sombras, fugas, valores fijos y API pública
+pnpm verify    # doctor + typecheck + build
+pnpm manifest  # regenera components.manifest.json tras añadir componentes
+```
+
+Si `pnpm check:ds` falla, **corrige la causa**; no lo desactives ni lo rodees.
+
+## Añadir un componente
+
+1. Fichero en `src/ui/<nombre>.tsx` (un componente = un fichero; sin barril).
+2. `data-slot="<nombre>"` en su raíz y en las partes relevantes.
+3. Solo tokens. Importa `cn` de `../lib/utils`; los demás componentes, de `./<otro>`.
+4. Dependencias de terceros: opcionales (`peerDependenciesMeta`), nunca obligatorias.
+5. `pnpm manifest`, `pnpm verify`; versión **menor** (añadido compatible).
+
+## Crear un tema
+
+Copia `themes/qratia.css` (o `zyro.css`), cambia valores, no quites ninguno, añade
+`<tema>.fonts.css` con el `@import url()` de sus fuentes y ejecuta `pnpm check:ds`.

package/README.md

@@ -1,49 +1,63 @@
 # orbital-ds
 
-Sistema de diseño genérico. **Estructura común + temas intercambiables + primitivos**
-sobre [Base UI](https://base-ui.com) y Tailwind v4.
+Sistema de diseño genérico: **estructura común + temas intercambiables + ~60 componentes**
+sobre [Base UI](https://base-ui.com) y Tailwind v4 (los de shadcn en su versión Base UI).
 
 - `styles.css` — la ESTRUCTURA: mapea variables de tema a utilidades de Tailwind y define los
-  tokens semánticos (radios, alturas de control, sombras, capas, movimiento, foco) y la capa base.
-  No lleva colores ni fuentes.
+  tokens semánticos (radios, alturas, sombras, espaciado, capas, movimiento, foco, materiales)
+  y la capa base. No lleva colores ni fuentes.
 - `themes/<tema>.css` — un TEMA: paleta (claro/oscuro), radio base y tipografía.
-  Hoy: `qratia`. Añadir otro = añadir otro fichero.
-- `ui/*` — primitivos (`orbital-ds/ui/button`, …), uno por fichero: quien no usa gráficos no
-  necesita `recharts`, quien no usa toasts no necesita `sonner`.
+  Hoy: `qratia` y `zyro` (cristal). Añadir otro = añadir otro fichero.
+- `themes/<tema>.fonts.css` — las fuentes del tema (un `@import url()`; va el primero).
+- `ui/*` — componentes, uno por fichero (`orbital-ds/ui/button`, …): quien no usa gráficos
+  no necesita `recharts`, quien no usa el calendario no necesita `react-day-picker`.
+- `contract.json` + `pnpm check:ds` — el contrato de tema y su comprobación.
 
 ## Uso en una app (Tailwind v4)
 
 ```css
+@import 'orbital-ds/themes/qratia.fonts.css'; /* fuentes: lo primero */
 @import 'tailwindcss';
 @plugin '@tailwindcss/typography';
 @import 'tw-animate-css';
-@import 'orbital-ds/themes/qratia.css';    /* un tema */
-@import 'orbital-ds/styles.css';           /* la estructura */
-@source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
+@import 'orbital-ds/styles.css';              /* estructura */
+@import 'orbital-ds/themes/qratia.css';       /* tema (después de la estructura) */
+@source '../node_modules/orbital-ds/dist';    /* que Tailwind vea las clases del paquete */
 ```
 
 ```tsx
 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):
 pide un hueco a una variable. Para cambiar el aspecto se cambia el tema, no el componente.
 Si un componente necesita un hueco nuevo, se AÑADE el token con un valor que deje el aspecto
-como estaba.
+como estaba. `pnpm check:ds` lo comprueba.
 
 ## Desarrollo
 
 ```bash
 pnpm install
-pnpm verify    # typecheck + build
-pnpm dev       # recompila al guardar (para consumirlo con `link:` desde una app)
+pnpm verify    # doctor + typecheck + build
+pnpm check:ds    # solo el contrato de tema y los valores fijos
 ```
 
 Peers obligatorios: `react`, `react-dom`, `@base-ui/react`, `tailwindcss`, `tailwind-merge`,
 `class-variance-authority`, `clsx`, `lucide-react`, `tw-animate-css`.
-Opcionales (solo si usas ese primitivo): `recharts` (chart), `sonner` (sonner), `next-themes` (sonner).
+Opcionales (solo si usas ese componente): `recharts`, `sonner`, `next-themes`, `cmdk`,
+`date-fns` + `react-day-picker`, `embla-carousel-react`, `input-otp`,
+`react-resizable-panels`, `@shadcn/react`.
 
 ## Licencia