orbital-ds 0.8.0 → 0.10.0

package/AGENTS.md

@@ -1,80 +1,162 @@
-# 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`.
-
-## Estándar de integración (cómo debe ajustarse una app)
-
-Para que una app (o un agente que la edite) use orbital-ds sin romper nada:
-
-1. **La marca vive solo en `brand.css`.** Ninguna regla de color propia fuera de ese fichero; jamás se edita el paquete.
-2. **Solo variables públicas.** Nada de variables privadas de un tema: pueden renombrarse. Usa `--ds-*` y los tokens del contrato (`--zw-*` de `tactile` están obsoletas: usa `--ds-key-outline`, `--ds-key-edge` y `--ds-marker`).
-3. **Sin `!important` ni selectores propios** para vencer a la librería (lateral, raíl, botones). Si algo no se puede ajustar con un token, es un hueco de la librería: abre un issue.
-4. **El tema se elige con un solo `@import`** (o `pnpm theme`). Los temas con ámbito (`*.scoped.css`) son solo para un banco de pruebas; la marca (`brand.css`) gana siempre, también sobre ellos.
-5. **Patrón de página.** La cabecera lleva solo botón de menú, título y, siempre visibles, idioma y tema (y avisos si la app los tiene). El subtítulo y las acciones de la vista van al inicio del contenido, centrado en un ancho máximo; solo un lienzo (mapa, kanban, editor) ocupa todo el ancho.
-6. **Cada tema se documenta y se elige informado.** Lee `orbital-ds/themes/<tema>.guide.md` y su ficha `<tema>.meta.json` (esencia, gesto firma, paleta, accesibilidad, qué valores son aproximados) antes de usar o ajustar un tema.
-7. **Comprueba antes de dar algo por bueno:** `pnpm exec orbital-ds-doctor --css src/brand.css` y el `verify` de la app.
-
-### Accesibilidad (WCAG 2.2)
-
-- **Mínimo exigible: AA.** Texto 4,5:1; texto grande y controles 3:1. `pnpm check:ds` falla si un par principal de texto sobre su superficie (texto/fondo, tarjeta, popover, primario, secundario, lateral, destructivo) o un texto de estado (info, danger, warning, success, neutral) baja de 4,5:1.
-- **Objetivo: AAA en el texto del cuerpo** (7:1 para texto/fondo y texto/tarjeta). Se mide con `pnpm check:ds -- --aaa` y avisa, no falla: WCAG no aconseja exigir AAA a todo el sitio. Hoy todos los temas lo cumplen.
-- **Excepciones declaradas, nunca silenciosas.** Si un tema no puede cumplir un par (el azul de marca de Twitter con texto blanco da 3:1), lo declara en su ficha, en `a11y.exceptions`, con su porqué; el doctor lo muestra como aviso.
-- **Foco siempre visible** (anillo de 3:1 como mínimo) y sin que otro elemento lo tape.
-- **Una marca nueva debe volver a pasar el doctor.** Cambiar `--primary` obliga a revisar `--primary-foreground`, `--link` y `--ring`.
+# 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.
+- **Un solo sitio.** Todos los temas son `conformance: strict`: sus reglas de personalidad solo
+  leen variables, y estilizan familias completas de piezas. Para adaptar el aspecto de una app
+  basta con su `brand.css`; para cambiar un tema, su bloque de VARIABLES. Si una regla necesita
+  un valor que no existe, añade la variable a la estructura (`src/styles.css`) con un valor
+  neutro y dásela en el tema.
+
+## Movimiento (animación)
+
+- **El tema gobierna el «cómo»**: ritmo (`--ds-motion-*`), curvas (`--ds-ease-*`) y coreografía
+  (`--ds-motion-distance`, `-scale`, `-blur`, `--ds-spring-bounce`, `--ds-motion-stagger`,
+  `--ds-motion-press-scale`). Cada tema trae el suyo de fábrica; la app lo ajusta en `brand.css`.
+- **La app decide el «qué» y el «cuándo»** con **Motion** (librería oficial, opcional): una vez
+  `<DsMotionProvider>` en la raíz y los presets del tema con `useDsMotion()` (`fadeUp`,
+  `scaleIn`, `list`, `press`, `spring`). Para animar un componente existente:
+  `render={<motion.div {...m.fadeUp} />}`.
+- Los componentes del paquete animan con CSS y nunca dependen de Motion. Ninguna duración, curva
+  ni capa se escribe a mano (el doctor lo comprueba también dentro de valores arbitrarios).
+- Otras librerías: `readDsTransition()` (`orbital-ds/lib/motion`) da duración y curva CSS.
+
+## Gráficos e informes (Apache ECharts)
+
+- **Librería oficial: ECharts** (dependencia opcional). `chart.tsx` (Recharts) se mantiene por compatibilidad,
+  sin nuevas funciones.
+- **El tema gobierna el gráfico**: `<EChart option={…} />` (`orbital-ds/ui/echart`) monta un tema de ECharts
+  desde las variables del tema activo y de la marca (paleta `--chart-1…5` + estados, textos, ejes, tooltip,
+  fuentes, ritmo) y se repinta al cambiar de tema o de piel. SVG por defecto; `exportable` descarga SVG/PNG.
+  Nunca pongas colores en el `option`: los da el tema (si una serie necesita un tono, usa la paleta del tema).
+- **Opciones listas**: `orbital-ds/lib/echarts-presets` (línea/área, barras, combo, mapa de calor, sankey,
+  gauge, donut, líneas y áreas de referencia). Sirven igual en pantalla y en informes.
+- **Informes automáticos (servidor / Workers, sin DOM)**: `renderEChartToSvg(option, { width, height, tokens })`
+  (`orbital-ds/lib/echarts-server`) con `tokens` = `orbital-ds/themes/<tema>.tokens.json` → `.light` o
+  `.dark` (colores ya resueltos; mezcla ahí los de la marca si la app tiene). Para PNG (plantillas de
+  documento), la app convierte el SVG (p. ej. resvg) con las fuentes del tema.
+- Registro común de tipos y componentes: `orbital-ds/lib/echarts-setup`. Otro tipo → `echarts.use([...])` en la app.
+- **Recetas completas** (pantalla, informe SVG→PNG, función de servidor de TanStack Start, endpoint en un Worker, marca en los informes): `docs/GRAFICOS.md`.
+
+## Idioma (i18n)
+
+- Los textos PROPIOS de los componentes (cerrar, cargando, paginación, carrusel, lateral,
+  cuestionario…) salen de `useDsMessages()` y sus catálogos (`orbital-ds/lib/i18n`: en, es,
+  pt-BR). **Ningún componente escribe un texto visible o accesible a mano**: el doctor lo rechaza
+  (`aria-label="…"`, `sr-only`, `?? "…"`, `title="…"`).
+- Un texto nuevo = una clave nueva en los TRES catálogos (el tipo obliga a tenerla en todos).
+- La app pasa su idioma una vez: `<DsI18nProvider locale={i18n.language}>` (con i18next,
+  `useTranslation().i18n.language`). Un texto concreto se sobrescribe con `messages`. Sin
+  provider, inglés. Otro idioma cae a su base (`es-CO` → `es`) o al inglés.
+- El texto de la APP (títulos, botones con contenido) lo pone la app con su i18n, no orbital-ds.
+- **En una app con i18next** (la plantilla TanStack es la referencia): los textos de orbital-ds viven
+  en el espacio **«orbital»** de sus JSON (`src/i18n/locales/<idioma>.json`), añadido a `ns`, y se
+  pasan con `messages={i18n.getResourceBundle(i18n.language, "orbital")}`. `pnpm exec orbital-ds-i18n`
+  rellena lo que falte sin pisar lo personalizado; `--check` va en el verify.
+- **Añadir un idioma** (p. ej. `ru`): crea `ru.json` con las mismas claves que `es.json`, añádelo a
+  los idiomas de la app y ejecuta `pnpm exec orbital-ds-i18n`. Si orbital-ds no trae ese idioma, deja
+  el inglés y LISTA las claves pendientes: tradúcelas en el JSON hasta que `--check` pase.
+- **RTL**: `dsDirection(idioma)` (`orbital-ds/lib/i18n`) da `ltr`/`rtl`; la app lo pone en `<html dir>` y
+  `DsI18nProvider` lo pasa a Base UI. La conversión de los componentes a clases lógicas
+  (`ms-`/`ps-`/`start-`/`text-start` en lugar de `ml-`/`pl-`/`left-`/`text-left`) es una fase pendiente: decisión y plan en `docs/adr/0001-rtl-clases-logicas.md`.
+
+## Instalar en una app
+
+`pnpm exec orbital-ds-init`: elige tema y color, comprueba el contraste y, si lo aceptas,
+escribe `brand.css`, conecta el CSS de la app (bloque de imports en orden), anota DESIGN.md,
+instala Motion y pasa el doctor. Sin preguntas: `--primary <color> --theme <tema> --connect --motion`.
+
+## Cómo comprobar tu trabajo
+
+```bash
+pnpm check:ds           # contrato, repetidos, sombras, fugas, valores fijos, personalidad, familias, contraste y demos
+pnpm verify             # doctor + typecheck + build
+pnpm manifest           # regenera components.manifest.json tras añadir componentes
+pnpm showcase           # escaparate: todos los componentes × todos los temas × claro/oscuro × marca
+pnpm showcase:typecheck # tipos de las demos
+pnpm showcase:build     # compila el escaparate (comprobación sin servidor)
+```
+
+**Escaparate.** Descubre solo los temas (`src/themes`), las demos (`showcase/src/demos/<componente>.tsx`,
+una por componente: el doctor falla si falta) y las variantes (`showcase/variants/*.css`).
+
+**Variante de un tema** (p. ej. «dame variantes de tactile»): un fichero en `showcase/variants/<nombre>.css`
+con `@base-theme <tema>` y `@about <frase>` en su comentario de cabecera y **solo variables** (como un
+`brand.css`). Valídala con `pnpm check:ds -- --css showcase/variants/<nombre>.css`: comprueba que las
+variables existan y el **contraste AA** de la variante sobre su tema. Para llevarla a una app, su contenido
+va al `brand.css`.
+
+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 de un COMPONENTE: opcionales (`peerDependenciesMeta`), nunca
+   obligatorias. Las herramientas de terminal del paquete (`orbital-ds-init`) sí pueden
+   tener las suyas (`@clack/prompts`), porque no llegan al bundle de la app.
+5. Su demo en `showcase/src/demos/<nombre>.tsx` (variantes, tamaños y estados).
+6. `pnpm manifest`, `pnpm verify`; versión **menor** (añadido compatible).
+
+## Crear un tema
+
+Copia `themes/qratia.css` (o `tactile.css`, el ejemplo estricto), cambia valores, no quites
+ninguno, añade `<tema>.fonts.css` con el `@import url()` de sus fuentes, marca la ficha con
+`"conformance": "strict"` y ejecuta `pnpm check:ds`. En modo estricto el doctor exige que la
+personalidad use **solo variables** (ni medidas, ni colores, ni pesos) y que estilice
+**familias completas** de piezas (`slotFamilies` en `contract.json`: si das tinta al
+`checkbox`, también al `radio-group-item`).
+
+## Estándar de integración (cómo debe ajustarse una app)
+
+Para que una app (o un agente que la edite) use orbital-ds sin romper nada:
+
+1. **La marca vive solo en `brand.css`.** Ninguna regla de color propia fuera de ese fichero; jamás se edita el paquete.
+2. **Solo variables públicas.** Nada de variables privadas de un tema: pueden renombrarse. Usa `--ds-*` y los tokens del contrato (`--zw-*` de `tactile` están obsoletas: usa `--ds-key-outline`, `--ds-key-edge` y `--ds-marker`).
+3. **Sin `!important` ni selectores propios** para vencer a la librería (lateral, raíl, botones). Si algo no se puede ajustar con un token, es un hueco de la librería: abre un issue.
+4. **El tema se elige con un solo `@import`** (o `pnpm theme`). Los temas con ámbito (`*.scoped.css`) son solo para un banco de pruebas; la marca (`brand.css`) gana siempre, también sobre ellos.
+5. **Patrón de página.** La cabecera lleva solo botón de menú, título y, siempre visibles, idioma y tema (y avisos si la app los tiene). El subtítulo y las acciones de la vista van al inicio del contenido, centrado en un ancho máximo; solo un lienzo (mapa, kanban, editor) ocupa todo el ancho.
+6. **Cada tema se documenta y se elige informado.** Lee `orbital-ds/themes/<tema>.guide.md` y su ficha `<tema>.meta.json` (esencia, gesto firma, paleta, accesibilidad, qué valores son aproximados) antes de usar o ajustar un tema.
+7. **Comprueba antes de dar algo por bueno:** `pnpm exec orbital-ds-doctor --css src/brand.css` y el `verify` de la app.
+
+### Accesibilidad (WCAG 2.2)
+
+- **Mínimo exigible: AA.** Texto 4,5:1; texto grande y controles 3:1. `pnpm check:ds` falla si un par principal de texto sobre su superficie (texto/fondo, tarjeta, popover, primario, secundario, lateral, destructivo) o un texto de estado (info, danger, warning, success, neutral) baja de 4,5:1.
+- **Objetivo: AAA en el texto del cuerpo** (7:1 para texto/fondo y texto/tarjeta). Se mide con `pnpm check:ds -- --aaa` y avisa, no falla: WCAG no aconseja exigir AAA a todo el sitio. Hoy todos los temas lo cumplen.
+- **Excepciones declaradas, nunca silenciosas.** Si un tema no puede cumplir un par (el azul de marca de Twitter con texto blanco da 3:1), lo declara en su ficha, en `a11y.exceptions`, con su porqué; el doctor lo muestra como aviso.
+- **Foco siempre visible** (anillo de 3:1 como mínimo) y sin que otro elemento lo tape.
+- **Una marca nueva debe volver a pasar el doctor.** Cambiar `--primary` obliga a revisar `--primary-foreground`, `--link` y `--ring`.