orbital-ds 0.28.0 → 0.29.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/AGENTS.md +289 -273
  2. package/components.manifest.json +410 -7
  3. package/dist/hooks/use-ds-messages.d.ts +196 -0
  4. package/dist/lib/auth-better-auth.d.ts +29 -0
  5. package/dist/lib/auth-better-auth.js +60 -0
  6. package/dist/lib/auth-flow.d.ts +59 -0
  7. package/dist/lib/auth-flow.js +135 -0
  8. package/dist/lib/auth-providers.d.ts +194 -0
  9. package/dist/lib/auth-providers.js +64 -0
  10. package/dist/lib/auth.d.ts +68 -0
  11. package/dist/lib/auth.js +110 -0
  12. package/dist/lib/i18n.d.ts +196 -0
  13. package/dist/lib/i18n.js +597 -3
  14. package/dist/styles.css +419 -3
  15. package/dist/themes/lagoon.css +8 -8
  16. package/dist/themes/lagoon.meta.json +3 -2
  17. package/dist/themes/lagoon.scoped.css +8 -8
  18. package/dist/ui/auth-backdrop.d.ts +20 -0
  19. package/dist/ui/auth-backdrop.js +137 -0
  20. package/dist/ui/auth-form.d.ts +107 -0
  21. package/dist/ui/auth-form.js +526 -0
  22. package/dist/ui/auth-layout.d.ts +70 -0
  23. package/dist/ui/auth-layout.js +283 -0
  24. package/dist/ui/auth-parts.d.ts +43 -0
  25. package/dist/ui/auth-parts.js +159 -0
  26. package/dist/ui/auth-status.d.ts +23 -0
  27. package/dist/ui/auth-status.js +99 -0
  28. package/dist/ui/connected-accounts.d.ts +25 -0
  29. package/dist/ui/connected-accounts.js +89 -0
  30. package/dist/ui/empty-state.d.ts +10 -1
  31. package/dist/ui/empty-state.js +28 -7
  32. package/dist/ui/error-page.d.ts +10 -1
  33. package/dist/ui/error-page.js +74 -28
  34. package/dist/ui/icon-tile.d.ts +1 -1
  35. package/dist/ui/input-otp.js +2 -1
  36. package/dist/ui/mfa-challenge.d.ts +33 -0
  37. package/dist/ui/mfa-challenge.js +214 -0
  38. package/dist/ui/mfa-setup.d.ts +29 -0
  39. package/dist/ui/mfa-setup.js +196 -0
  40. package/dist/ui/oauth-consent.d.ts +54 -0
  41. package/dist/ui/oauth-consent.js +208 -0
  42. package/dist/ui/passkey-list.d.ts +17 -0
  43. package/dist/ui/passkey-list.js +112 -0
  44. package/dist/ui/password-input.d.ts +5 -0
  45. package/dist/ui/password-input.js +77 -0
  46. package/dist/ui/session-list.d.ts +19 -0
  47. package/dist/ui/session-list.js +70 -0
  48. package/dist/ui/session-timeout.d.ts +13 -0
  49. package/dist/ui/session-timeout.js +87 -0
  50. package/dist/ui/sidebar.d.ts +12 -4
  51. package/dist/ui/sidebar.js +35 -5
  52. package/dist/ui/sign-out-dialog.d.ts +17 -0
  53. package/dist/ui/sign-out-dialog.js +82 -0
  54. package/dist/ui/stat-group.d.ts +1 -1
  55. package/dist/ui/stat-group.js +6 -2
  56. package/dist/ui/stat.d.ts +24 -5
  57. package/dist/ui/stat.js +124 -19
  58. package/dist/ui/status-badge.d.ts +1 -1
  59. package/docs/designer/patrones.md +21 -0
  60. package/docs/designer/revision.md +8 -0
  61. package/package.json +187 -187
  62. package/scripts/brand-core.d.mts +2 -0
  63. package/scripts/brand-core.mjs +21 -1
  64. package/scripts/doctor.mjs +3 -0
  65. package/scripts/init.mjs +7 -3
package/AGENTS.md CHANGED
@@ -1,273 +1,289 @@
1
- # orbital-ds — guía para agentes de IA
2
-
3
- Sistema de diseño: **estructura común + temas + componentes** sobre Base UI y Tailwind v4.
4
- Todo está pensado para que un agente pueda usarlo, ampliarlo y comprobar su trabajo sin
5
- adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
6
- `components.manifest.json` (qué componentes hay, cómo se importan y qué `data-slot` exponen).
7
-
8
- ## Reglas (obligatorias)
9
-
10
- 1. **Solo variables.** Un componente no escribe colores, medidas, sombras, z-index ni
11
- duraciones: pide un hueco a una variable (`--ds-*` o las de color de shadcn). Si falta el
12
- hueco, **añade el token** con un valor que deje el aspecto como estaba y úsalo.
13
- 2. **Añadir, nunca sustituir.** Un componente nuevo es un fichero nuevo en `src/ui/`. No se
14
- reescribe ni se renombra uno existente para otro fin. No uses `--overwrite` de la CLI de
15
- shadcn sin aprobación expresa. Quitar o renombrar algo público = versión **mayor**.
16
- 3. **Nombres en inglés.** Tokens, props y valores de variantes. Variables propias con el
17
- prefijo `--ds-`; las que Tailwind convierte en utilidades (`--color-*`, `--radius-*`,
18
- `--shadow-*`) siguen su convención. Las privadas de un tema llevan el prefijo del tema
19
- (`--zy-*`).
20
- 4. **Un solo motor: Base UI.** Nada de Radix. `asChild` no existe: se usa `render`.
21
- 5. **«Sin sombra» es `0 0 #0000`**, nunca `none` (invalida todo el `box-shadow`, anillo de
22
- foco incluido).
23
- 6. **Un tema cumple el contrato completo** (`contract.json`) y define en `:root` todo
24
- `--ds-*` que defina el tema base.
25
- 7. **Unidades: rem, no px.** Tamaños, alturas y container queries (`@[32rem]`) van en `rem` para respetar el
26
- tamaño de letra de la persona (WCAG 1.4.4); `em` solo si algo debe escalar con el texto de su propio
27
- componente; `px` solo en filetes y bordes finos, a través de tokens. El doctor rechaza `@[Npx]`.
28
- 8. **La marca de una app vive en SU `brand.css`**, no en el tema del paquete. Para
29
- personalizar una app (color, radio, fuentes) edita ese fichero; nunca `node_modules` ni
30
- los temas. `pnpm exec orbital-ds-init` lo crea sin sobrescribir.
31
-
32
- ## Cómo cambiar el aspecto
33
-
34
- - **Valores** (color, forma, fuentes, escala, sombras, espaciado, materiales, sidebar):
35
- variables del tema en `src/themes/<tema>.css`.
36
- - **Personalidad de un elemento** (por ejemplo, botones en píldora con degradado): reglas en
37
- la sección «PERSONALIDAD» del tema, dirigidas a los ganchos del DOM —`data-slot`,
38
- `data-variant`, `data-size`, `data-active`, `data-state`— y escritas solo con variables. Van
39
- **sin capa** para ganar a las utilidades; define también hover y active.
40
- - **Estructura** distinta de un componente (otro layout): variante del componente, no tema.
41
- - **Un solo sitio.** Todos los temas son `conformance: strict`: sus reglas de personalidad solo
42
- leen variables, y estilizan familias completas de piezas. Para adaptar el aspecto de una app
43
- basta con su `brand.css`; para cambiar un tema, su bloque de VARIABLES. Si una regla necesita
44
- un valor que no existe, añade la variable a la estructura (`src/styles.css`) con un valor
45
- neutro y dásela en el tema.
46
-
47
- ## Movimiento (animación)
48
-
49
- - **Animaciones de fábrica sin código: `@import 'orbital-ds/motion.css'`** (después del tema; el asistente lo añade si
50
- lo activas). Entradas en cascada de tarjetas, paneles, KPI, filas-tarjeta, avisos, cabeceras y filas de tabla, y
51
- superficies pulsables. Cada grupo tiene su interruptor con un tipo del CATÁLOGO: `--ds-enter-surfaces`,
52
- `--ds-enter-notices`, `--ds-enter-headers`, `--ds-enter-rows` = `ds-auto-enter` (sube) · `ds-auto-fade` ·
53
- `ds-auto-pop` (crece) · `ds-auto-slide` (de lado, RTL) · `ds-auto-focus` (se enfoca) · `none`. Cada tema elige
54
- según su personalidad y lo declara en su ficha (`motion.auto`); el doctor comprueba que sea del catálogo y que
55
- ficha y CSS coincidan. La app lo cambia en `brand.css`. Sin el import, no anima nada.
56
-
57
- - **El tema gobierna el «cómo»**: ritmo (`--ds-motion-*`), curvas (`--ds-ease-*`) y coreografía
58
- (`--ds-motion-distance`, `-scale`, `-blur`, `--ds-spring-bounce`, `--ds-motion-stagger`,
59
- `--ds-motion-press-scale`). Cada tema trae el suyo de fábrica; la app lo ajusta en `brand.css`.
60
- - **La app decide el «qué» y el «cuándo»** con **Motion** (librería oficial, opcional): una vez
61
- `<DsMotionProvider>` en la raíz y los presets del tema con `useDsMotion()` (`fadeUp`,
62
- `scaleIn`, `list`, `press`, `spring`). Para animar un componente existente:
63
- `render={<motion.div {...m.fadeUp} />}`.
64
- - Los componentes del paquete animan con CSS y nunca dependen de Motion. Ninguna duración, curva
65
- ni capa se escribe a mano (el doctor lo comprueba también dentro de valores arbitrarios).
66
- - Otras librerías: `readDsTransition()` (`orbital-ds/lib/motion`) da duración y curva CSS.
67
-
68
- ## Gráficos e informes (Apache ECharts)
69
-
70
- - **Librería oficial: ECharts** (dependencia opcional). `chart.tsx` (Recharts) se mantiene por compatibilidad,
71
- sin nuevas funciones.
72
- - **El tema gobierna el gráfico**: `<EChart option={…} />` (`orbital-ds/ui/echart`) monta un tema de ECharts
73
- desde las variables del tema activo y de la marca (paleta `--chart-1…5` + estados, textos, ejes, tooltip,
74
- fuentes, ritmo) y se repinta al cambiar de tema o de piel. SVG por defecto; `exportable` descarga SVG/PNG.
75
- Nunca pongas colores en el `option`: los da el tema (si una serie necesita un tono, usa la paleta del tema).
76
- - **Tarjeta**: `<ChartCard preset="standard|glance|focus|dense" option={…} loading error empty />` (`orbital-ds/ui/chart-card`) pone título, estados, descarga y motor de pintado; el `option` sigue sin colores.
77
- - **Opciones listas**: `orbital-ds/lib/echarts-presets` (línea/área, barras, combo, mapa de calor, sankey,
78
- gauge, donut, dispersión, radar, embudo, treemap, sunburst, velas, boxplot, líneas y áreas de referencia). Sirven igual en pantalla y en informes.
79
- - **Informes automáticos (servidor / Workers, sin DOM)**: `renderEChartToSvg(option, { width, height, tokens })`
80
- (`orbital-ds/lib/echarts-server`) con `tokens` = `orbital-ds/themes/<tema>.tokens.json` → `.light` o
81
- `.dark` (colores ya resueltos; mezcla ahí los de la marca si la app tiene). Para PNG (plantillas de
82
- documento), la app convierte el SVG (p. ej. resvg) con las fuentes del tema.
83
- - **Validación**: `pnpm check:charts` (dentro de `verify`) ejecuta cada constructor de `echarts-presets`, comprueba
84
- que su `option` no lleva colores y que se dibuja como SVG en el servidor. Un constructor nuevo necesita su caso en
85
- `scripts/check-charts.mjs`, o la comprobación falla.
86
- - Registro común de tipos y componentes: `orbital-ds/lib/echarts-setup`. Otro tipo → `echarts.use([...])` en la app. Si la app
87
- usa `echarts` directamente (sin `<EChart>` ni `renderEChartToSvg`), llama antes a `dsEcharts()` (registra y lo devuelve):
88
- así ningún empaquetador quita el registro. `pnpm check:bundle` lo comprueba empaquetando un consumidor.
89
- - **Recetas completas** (pantalla, informe SVG→PNG, función de servidor de TanStack Start, endpoint en un Worker, marca en los informes): `docs/GRAFICOS.md`.
90
-
91
- ## Idioma (i18n)
92
-
93
- - Los textos PROPIOS de los componentes (cerrar, cargando, paginación, carrusel, lateral,
94
- cuestionario…) salen de `useDsMessages()` y sus catálogos (`orbital-ds/lib/i18n`: en, es,
95
- pt-BR). **Ningún componente escribe un texto visible o accesible a mano**: el doctor lo rechaza
96
- (`aria-label="…"`, `sr-only`, `?? "…"`, `title="…"`).
97
- - Un texto nuevo = una clave nueva en los TRES catálogos (el tipo obliga a tenerla en todos).
98
- - La app pasa su idioma una vez: `<DsI18nProvider locale={i18n.language}>` (con i18next,
99
- `useTranslation().i18n.language`). Un texto concreto se sobrescribe con `messages`. Sin
100
- provider, inglés. Otro idioma cae a su base (`es-CO` → `es`) o al inglés.
101
- - El texto de la APP (títulos, botones con contenido) lo pone la app con su i18n, no orbital-ds.
102
- - **En una app con i18next** (la plantilla TanStack es la referencia): los textos de orbital-ds viven
103
- en el espacio **«orbital»** de sus JSON (`src/i18n/locales/<idioma>.json`), añadido a `ns`, y se
104
- pasan con `messages={i18n.getResourceBundle(i18n.language, "orbital")}`. `pnpm exec orbital-ds-i18n`
105
- rellena lo que falte sin pisar lo personalizado; `--check` va en el verify.
106
- - **Añadir un idioma** (p. ej. `ru`): crea `ru.json` con las mismas claves que `es.json`, añádelo a
107
- los idiomas de la app y ejecuta `pnpm exec orbital-ds-i18n`. Si orbital-ds no trae ese idioma, deja
108
- el inglés y LISTA las claves pendientes: tradúcelas en el JSON hasta que `--check` pase.
109
- - **RTL**: `dsDirection(idioma)` (`orbital-ds/lib/i18n`) da `ltr`/`rtl`; la app lo pone en `<html dir>` y
110
- `DsI18nProvider` lo pasa a Base UI. La conversión de los componentes a clases lógicas
111
- (`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`.
112
-
113
- ## Instalar en una app
114
-
115
- **Orden única: `pnpm exec orbital-ds`** (menú) · `orbital-ds init` (configuración inicial) · `orbital-ds theme [tema]`
116
- (cambiar de tema conservando marca y extras) · `orbital-ds doctor` · `orbital-ds i18n` · `orbital-ds help [orden]`.
117
- Las órdenes sueltas (`orbital-ds-init`, `-doctor`, `-i18n`) siguen valiendo como atajos.
118
-
119
- `orbital-ds init` (= `pnpm exec orbital-ds-init`): elige tema (enseña su ficha: esencia, paleta, gesto, excepciones de
120
- contraste), elige **cómo aplicar la marca** y, si lo aceptas, escribe `brand.css`, conecta el CSS de
121
- la app (bloque de imports en orden), anota DESIGN.md, instala Motion y pasa el doctor.
122
-
123
- - **Modos de marca** (`--mode`): `faithful` (el tema tal cual, sin derivar nada; quita un bloque
124
- generado con `--update`), `primary` (solo el primario —foco, enlace, lateral activo, serie 1— sobre
125
- la paleta del tema, con el contraste medido contra SU lienzo) y `full` (paleta entera derivada).
126
- - La ficha del tema recomienda el modo con `"branding"`. Un tema de un **sistema corporativo**
127
- (p. ej. `fractalia`) declara `"branding": "faithful"`: no le derives la paleta.
128
- - Sin preguntas: `--theme fractalia --connect` (fiel) · `--primary <color> --mode primary --theme <tema>` ·
129
- `--primary <color> --theme <tema> --connect --motion` (completa).
130
- - **Cambiar de tema**: `orbital-ds theme <tema> [--brand adapt|clean|clean-all|keep]`. `adapt` recalcula la marca
131
- para el tema nuevo y desactiva los colores escritos a mano para el anterior; `clean` solo desactiva esos colores;
132
- `clean-all`, toda la marca; `keep` la deja (por defecto sin terminal, con aviso). Lo desactivado queda comentado,
133
- con copia `.bak`; quita también los imports de tema sueltos y pone `@base-theme` al tema nuevo. Al pasar por un
134
- tema fiel, la marca queda recordada y vuelve al salir de él.
135
-
136
- ## Diseñar con orbital-ds (diseñador para agentes)
137
-
138
- Para crear o revisar pantallas y flujos, sigue `docs/designer/`: **flujo.md** (contexto real, modo, mapa del flujo y
139
- modelo mental de la persona, orden de autoridad), **patrones.md** (P1–P12: página, lista de entidades, detalle, tabla,
140
- formulario, asistente, panel de datos, destructiva, estados, avisos, búsqueda, ajustes), **ux.md** (heurísticas,
141
- carga cognitiva, formularios, textos, WCAG 2.2 AA, responsivo) y **revision.md** (lista observable y anti-patrones).
142
- Regla de oro: **nunca te sales del sistema**; si algo no se puede hacer con componentes y variables, se anota como hueco.
143
-
144
- - `orbital-ds context` (o `--json`): el estado real de la app para un agente (tema, marca, extras, componentes con
145
- sus notas, patrones). Las notas de uso de cada componente se escriben en el propio fichero con `@note`.
146
- - `orbital-ds skill`: instala en la app el skill de Claude Code **orbital-ds-designer** (`.claude/skills/`). Es fino:
147
- lee esta documentación del paquete instalado, así que se actualiza con cada versión; `orbital-ds skill --check` en
148
- el verify avisa si quedó de otra versión. El asistente lo ofrece en sus extras.
149
-
150
- ## Componentes con presets (patrones de configuración)
151
-
152
- Un componente de **flujo o maqueta** (StepFlow, FormLayout, EmptyState, StatGroup, ConfirmAction) se configura con un
153
- `preset`: una intención en inglés que **solo fija valores por defecto**; cualquier prop explícita lo sobrescribe, así sirve
154
- en cualquier proyecto. Vocabulario común en `src/lib/presets.ts` (`DsDensity`, `DsPresentation`, `dsWarn`).
155
-
156
- 1. **Configuración en inglés** (props, valores, tokens, `data-*`); **texto visible o accesible** por `useDsMessages()` en
157
- los tres catálogos; comentarios y `@note` en español.
158
- 2. **Nombre del preset = intención** (`quick`, `first-use`, `settings`), nunca el aspecto (`small-modal`).
159
- 3. **Ejes independientes**: presentación (`dialog | page | inline | sheet`) y densidad (`compact | default | comfortable`)
160
- son props distintas; los presets las combinan, no las fusionan.
161
- 4. **El diseño sigue el ancho del contenedor** (container query), no el dispositivo ni la presentación.
162
- 5. **Aviso en desarrollo** (`dsWarn`, mensaje en inglés) si la combinación no cuadra.
163
- 6. **Ganchos del DOM**: `data-slot` y `data-preset` (más `data-presentation`/`data-density` si aplica).
164
- 7. **Un `@note`** que diga cuándo usar cada preset. Catálogo hoy: `ChartCard` (glance · standard · focus · dense), `ContentCard` (basic · feature · media · horizontal, con `emphasis` elevated · outlined · filled · ghost), `Mosaic` (even · bento · trio), `PageShell` (content · detail · canvas), `PageHeader` (page · compact · canvas), `FilterBar` (inline · compact · stacked), `DataTable` (browse · manage · compact), `LoadingState` (list · card · table · detail), `PageLoader` (splash · route · section · overlay), `CommandPalette` (go · actions · search), `FileUpload` (drop · button), `ErrorPage` (not-found · forbidden · server-error · offline · maintenance, con `tone` neutral · playful), `DetailPanel` (side · bottom · full), `EntityList` (list · grid · compact), `StepFlow` (quick · activation · long), `FormLayout`
165
- (inline · sectioned · settings), `NoticeReview` (read · acknowledge · resolve · respond), `EmptyState` (first-use · no-results · error · forbidden), `StatGroup` (overview ·
166
- compact · comparison) y `ConfirmAction` (simple · typed).
167
-
168
- **Densidad global.** `--ds-density` (1 por defecto; 0.8 más denso, 1.2 más aireado) escala el relleno de celdas y la separación de secciones y listas; la app lo ajusta en `brand.css`.
169
-
170
- ## Avisos y comunicaciones in-app (qué canal usar)
171
-
172
- Se elige el canal por **urgencia** y **persistencia**; cada app no lo decide a mano:
173
-
174
- | Intención | Canal | Persiste | Interrumpe |
175
- |---|---|---|---|
176
- | Confirmar una acción de la persona | toast (`Toaster`/`Toast`) | no | no |
177
- | Aviso de una sección | `Alert` | sí | no |
178
- | Aviso que afecta a toda la página | `Banner` | hasta resolver | no |
179
- | Asunto con seguimiento o decisión | campana (`NotificationCenter`) + `NoticeReview` | sí, con estado | solo si es crítico |
180
- | Bloqueo que exige respuesta ya | `ConfirmAction` / `AlertDialog` | no | sí |
181
-
182
- Mismo vocabulario en todos: tono `info | success | warning | danger` y estado `new → acknowledged → resolved`.
183
- `NotificationItem onSelect` abre la revisión; `NoticeReview` tiene presets `read | acknowledge | resolve | respond`
184
- (modal o `presentation="sheet"`).
185
-
186
- ## Cómo comprobar tu trabajo
187
-
188
- ```bash
189
- pnpm check:ds # contrato, repetidos, sombras, fugas, valores fijos, personalidad, familias, contraste y demos
190
- pnpm verify # doctor + typecheck + build + check:bundle
191
- pnpm check:charts # cada constructor de gráfico: sin colores y dibuja SVG en servidor
192
- pnpm check:bundle # empaqueta un consumidor de EChart (navegador y servidor) y comprueba que dibuja
193
- pnpm manifest # regenera components.manifest.json tras añadir componentes
194
- pnpm showcase # escaparate: todos los componentes × todos los temas × claro/oscuro × marca
195
- pnpm showcase:typecheck # tipos de las demos
196
- pnpm showcase:build # compila el escaparate (comprobación sin servidor)
197
- ```
198
-
199
- **Escaparate.** Descubre solo los temas (`src/themes`), las demos (`showcase/src/demos/<componente>.tsx`,
200
- una por componente: el doctor falla si falta) y las variantes (`showcase/variants/*.css`).
201
-
202
- **Variante de un tema** (p. ej. «dame variantes de tactile»): un fichero en `showcase/variants/<nombre>.css`
203
- con `@base-theme <tema>` y `@about <frase>` en su comentario de cabecera y **solo variables** (como un
204
- `brand.css`). Valídala con `pnpm check:ds -- --css showcase/variants/<nombre>.css`: comprueba que las
205
- variables existan y el **contraste AA** de la variante sobre su tema. Para llevarla a una app, su contenido
206
- va al `brand.css`.
207
-
208
- Si `pnpm check:ds` falla, **corrige la causa**; no lo desactives ni lo rodees.
209
-
210
- ## Añadir un componente
211
-
212
- 1. Fichero en `src/ui/<nombre>.tsx` (un componente = un fichero; sin barril).
213
- 2. `data-slot="<nombre>"` en su raíz y en las partes relevantes.
214
- 3. Solo tokens. Importa `cn` de `../lib/utils.js`; los demás componentes, de `./<otro>.js`. **Los imports relativos llevan
215
- siempre `.js`**: el paquete es `"type": "module"` y Node (tests, SSR sin bundler) no completa la ruta; `check:pack`
216
- importa cada export con Node puro.
217
- 4. Dependencias de terceros de un COMPONENTE: opcionales (`peerDependenciesMeta`), nunca
218
- obligatorias. Las herramientas de terminal del paquete (`orbital-ds-init`) sí pueden
219
- tener las suyas (`@clack/prompts`), porque no llegan al bundle de la app.
220
- 5. Su demo en `showcase/src/demos/<nombre>.tsx` (variantes, tamaños y estados).
221
- 6. `pnpm manifest`, `pnpm verify`; versión **menor** (añadido compatible).
222
-
223
- ## Crear un tema
224
-
225
- Copia `themes/qratia.css` (o `tactile.css`, el ejemplo estricto), cambia valores, no quites
226
- ninguno, añade `<tema>.fonts.css` con el `@import url()` de sus fuentes, marca la ficha con
227
- `"conformance": "strict"` y ejecuta `pnpm check:ds`. En modo estricto el doctor exige que la
228
- personalidad use **solo variables** (ni medidas, ni colores, ni pesos) y que estilice
229
- **familias completas** de piezas (`slotFamilies` en `contract.json`: si das tinta al
230
- `checkbox`, también al `radio-group-item`).
231
-
232
- ## Adaptar un sistema corporativo (p. ej. Fractalia)
233
-
234
- Se adapta el sistema al modelo, nunca al revés (decisión y plan: `docs/adr/0002-sistemas-corporativos-al-modelo.md`):
235
-
236
- 1. **Valores a los huecos.** Cada valor de su DS va a la variable pública que ya lo cubre (`--ds-radius-button`,
237
- `--ds-field-bg`, `--ds-switch-track-off`, `--ds-*-weight`…). La personalidad solo para lo que ningún hueco
238
- cubre. El doctor rechaza (aviso si el tema no es estricto) una regla que pinta una propiedad que tiene hueco (`slotTokens` del contrato).
239
- 2. **Si falta el hueco, se añade** al núcleo con un valor que deje igual a los demás temas (p. ej. el
240
- desactivado con color: `--ds-button-disabled-bg/-fg/-border`, opcionales con respaldo por variante).
241
- 3. **Pesos cargados = pesos usados**: el doctor avisa si una `--ds-*-weight` pide un peso que `<tema>.fonts.css`
242
- no carga.
243
- 4. **Sus componentes van al núcleo, genéricos** (nunca CSS de componentes dentro de un tema): antes de crear,
244
- busca en el manifiesto y amplía (solo añadir). Tono con el vocabulario común (`DsDataTone`); el significado
245
- de dominio (riesgo bajo/medio/alto) lo traduce la app. Medidas y efectos en `--ds-<pieza>-*`; animación con
246
- CSS y el ritmo del tema (`--ds-motion-pulse`, `--ds-ease-pulse`), quieta con movimiento reducido.
247
- Piezas de estado y progreso: `Shield`/`ShieldRadar`, `Gauge`, `PasswordStrength`, `StepDots`, `StepRing`,
248
- `TaskProgress`, `LevelMeter`, `StatusHero`, `TaskLoader` y `StatusDot size`. Pista común: `--ds-track-bg`.
249
- 5. **Fidelidad comprobada**: compara el valor efectivo de cada propiedad antes y después de traducir (claro y
250
- oscuro); solo deben cambiar los valores de su DS que antes no se aplicaban.
251
-
252
- ## Estándar de integración (cómo debe ajustarse una app)
253
-
254
- Para que una app (o un agente que la edite) use orbital-ds sin romper nada:
255
-
256
- 1. **La marca vive solo en `brand.css`.** Ninguna regla de color propia fuera de ese fichero; jamás se edita el paquete.
257
- 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`).
258
- 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.
259
- 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.
260
- 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). **Opcional: un buscador o paleta de comandos** («Ir a…», ⌘K) cuando es la navegación principal de la app: en escritorio, un `InputGroup` compacto que abre `Command`; en móvil, solo el botón con el icono de búsqueda. 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.
261
- 6. **Listas de entidades** (agentes, herramientas, dispositivos): `Item variant="card"` con su `ItemMedia` (o `IconTile`), `ItemContent` y `ItemActions`. Toma el gesto de la tarjeta de cada tema (filete y arista en tactile, sin borde en fractalia…); no compongas `Card` + `Item` a mano.
262
- 7. **`Select` con `items`.** Pasa la lista `{ value, label }` al `Select` para que el disparador muestre la etiqueta y no el valor antes de abrirse (también en el HTML del servidor). La lista se abre debajo del campo, al menos tan ancha como él y con ≈ 8 filas (`--ds-select-max-h`).
263
- 8. **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.
264
- 9. **Comprueba antes de dar algo por bueno:** `pnpm exec orbital-ds doctor --css src/brand.css --ui src` (marca y vistas: nada fuera del sistema) y el `verify` de la app.
265
-
266
- ### Accesibilidad (WCAG 2.2)
267
-
268
- - **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.
269
- - **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.
270
- - **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. Vale también para el texto de estado sobre su fondo suave (`"warning/warning-soft"`), p. ej. cuando el par viene del sistema corporativo que el tema reproduce (fractalia).
271
- - **Tamaños mínimos** (WCAG 2.5.8 y legibilidad): objetivo táctil ≥ 1,5rem (24 px; los `--ds-control-h-*` van de 1,5 a 2,5rem), texto ≥ 0,75rem (`text-xs`) y cuerpo en 0,875–1rem. El doctor falla si un `--ds-control-h-*` baja de 1,5rem o hay `text-[…rem]` menor de 0,75rem.
272
- - **Foco siempre visible** (anillo de 3:1 como mínimo) y sin que otro elemento lo tape.
273
- - **Una marca nueva debe volver a pasar el doctor.** Cambiar `--primary` obliga a revisar `--primary-foreground`, `--link` y `--ring`.
1
+ # orbital-ds — guía para agentes de IA
2
+
3
+ Sistema de diseño: **estructura común + temas + componentes** sobre Base UI y Tailwind v4.
4
+ Todo está pensado para que un agente pueda usarlo, ampliarlo y comprobar su trabajo sin
5
+ adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
6
+ `components.manifest.json` (qué componentes hay, cómo se importan y qué `data-slot` exponen).
7
+
8
+ ## Reglas (obligatorias)
9
+
10
+ 1. **Solo variables.** Un componente no escribe colores, medidas, sombras, z-index ni
11
+ duraciones: pide un hueco a una variable (`--ds-*` o las de color de shadcn). Si falta el
12
+ hueco, **añade el token** con un valor que deje el aspecto como estaba y úsalo.
13
+ 2. **Añadir, nunca sustituir.** Un componente nuevo es un fichero nuevo en `src/ui/`. No se
14
+ reescribe ni se renombra uno existente para otro fin. No uses `--overwrite` de la CLI de
15
+ shadcn sin aprobación expresa. Quitar o renombrar algo público = versión **mayor**.
16
+ 3. **Nombres en inglés.** Tokens, props y valores de variantes. Variables propias con el
17
+ prefijo `--ds-`; las que Tailwind convierte en utilidades (`--color-*`, `--radius-*`,
18
+ `--shadow-*`) siguen su convención. Las privadas de un tema llevan el prefijo del tema
19
+ (`--zy-*`).
20
+ 4. **Un solo motor: Base UI.** Nada de Radix. `asChild` no existe: se usa `render`.
21
+ 5. **«Sin sombra» es `0 0 #0000`**, nunca `none` (invalida todo el `box-shadow`, anillo de
22
+ foco incluido).
23
+ 6. **Un tema cumple el contrato completo** (`contract.json`) y define en `:root` todo
24
+ `--ds-*` que defina el tema base.
25
+ 7. **Unidades: rem, no px.** Tamaños, alturas y container queries (`@[32rem]`) van en `rem` para respetar el
26
+ tamaño de letra de la persona (WCAG 1.4.4); `em` solo si algo debe escalar con el texto de su propio
27
+ componente; `px` solo en filetes y bordes finos, a través de tokens. El doctor rechaza `@[Npx]`.
28
+ 8. **La marca de una app vive en SU `brand.css`**, no en el tema del paquete. Para
29
+ personalizar una app (color, radio, fuentes) edita ese fichero; nunca `node_modules` ni
30
+ los temas. `pnpm exec orbital-ds-init` lo crea sin sobrescribir.
31
+
32
+ ## Cómo cambiar el aspecto
33
+
34
+ - **Valores** (color, forma, fuentes, escala, sombras, espaciado, materiales, sidebar):
35
+ variables del tema en `src/themes/<tema>.css`.
36
+ - **Personalidad de un elemento** (por ejemplo, botones en píldora con degradado): reglas en
37
+ la sección «PERSONALIDAD» del tema, dirigidas a los ganchos del DOM —`data-slot`,
38
+ `data-variant`, `data-size`, `data-active`, `data-state`— y escritas solo con variables. Van
39
+ **sin capa** para ganar a las utilidades; define también hover y active.
40
+ - **Estructura** distinta de un componente (otro layout): variante del componente, no tema.
41
+ - **Un solo sitio.** Todos los temas son `conformance: strict`: sus reglas de personalidad solo
42
+ leen variables, y estilizan familias completas de piezas. Para adaptar el aspecto de una app
43
+ basta con su `brand.css`; para cambiar un tema, su bloque de VARIABLES. Si una regla necesita
44
+ un valor que no existe, añade la variable a la estructura (`src/styles.css`) con un valor
45
+ neutro y dásela en el tema.
46
+
47
+ ## Movimiento (animación)
48
+
49
+ - **Animaciones de fábrica sin código: `@import 'orbital-ds/motion.css'`** (después del tema; el asistente lo añade si
50
+ lo activas). Entradas en cascada de tarjetas, paneles, KPI, filas-tarjeta, avisos, cabeceras y filas de tabla, y
51
+ superficies pulsables. Cada grupo tiene su interruptor con un tipo del CATÁLOGO: `--ds-enter-surfaces`,
52
+ `--ds-enter-notices`, `--ds-enter-headers`, `--ds-enter-rows` = `ds-auto-enter` (sube) · `ds-auto-fade` ·
53
+ `ds-auto-pop` (crece) · `ds-auto-slide` (de lado, RTL) · `ds-auto-focus` (se enfoca) · `none`. Cada tema elige
54
+ según su personalidad y lo declara en su ficha (`motion.auto`); el doctor comprueba que sea del catálogo y que
55
+ ficha y CSS coincidan. La app lo cambia en `brand.css`. Sin el import, no anima nada.
56
+
57
+ - **El tema gobierna el «cómo»**: ritmo (`--ds-motion-*`), curvas (`--ds-ease-*`) y coreografía
58
+ (`--ds-motion-distance`, `-scale`, `-blur`, `--ds-spring-bounce`, `--ds-motion-stagger`,
59
+ `--ds-motion-press-scale`). Cada tema trae el suyo de fábrica; la app lo ajusta en `brand.css`.
60
+ - **La app decide el «qué» y el «cuándo»** con **Motion** (librería oficial, opcional): una vez
61
+ `<DsMotionProvider>` en la raíz y los presets del tema con `useDsMotion()` (`fadeUp`,
62
+ `scaleIn`, `list`, `press`, `spring`). Para animar un componente existente:
63
+ `render={<motion.div {...m.fadeUp} />}`.
64
+ - Los componentes del paquete animan con CSS y nunca dependen de Motion. Ninguna duración, curva
65
+ ni capa se escribe a mano (el doctor lo comprueba también dentro de valores arbitrarios).
66
+ - Otras librerías: `readDsTransition()` (`orbital-ds/lib/motion`) da duración y curva CSS.
67
+
68
+ ## Gráficos e informes (Apache ECharts)
69
+
70
+ - **Librería oficial: ECharts** (dependencia opcional). `chart.tsx` (Recharts) se mantiene por compatibilidad,
71
+ sin nuevas funciones.
72
+ - **El tema gobierna el gráfico**: `<EChart option={…} />` (`orbital-ds/ui/echart`) monta un tema de ECharts
73
+ desde las variables del tema activo y de la marca (paleta `--chart-1…5` + estados, textos, ejes, tooltip,
74
+ fuentes, ritmo) y se repinta al cambiar de tema o de piel. SVG por defecto; `exportable` descarga SVG/PNG.
75
+ Nunca pongas colores en el `option`: los da el tema (si una serie necesita un tono, usa la paleta del tema).
76
+ - **Tarjeta**: `<ChartCard preset="standard|glance|focus|dense" option={…} loading error empty />` (`orbital-ds/ui/chart-card`) pone título, estados, descarga y motor de pintado; el `option` sigue sin colores.
77
+ - **Opciones listas**: `orbital-ds/lib/echarts-presets` (línea/área, barras, combo, mapa de calor, sankey,
78
+ gauge, donut, dispersión, radar, embudo, treemap, sunburst, velas, boxplot, líneas y áreas de referencia). Sirven igual en pantalla y en informes.
79
+ - **Informes automáticos (servidor / Workers, sin DOM)**: `renderEChartToSvg(option, { width, height, tokens })`
80
+ (`orbital-ds/lib/echarts-server`) con `tokens` = `orbital-ds/themes/<tema>.tokens.json` → `.light` o
81
+ `.dark` (colores ya resueltos; mezcla ahí los de la marca si la app tiene). Para PNG (plantillas de
82
+ documento), la app convierte el SVG (p. ej. resvg) con las fuentes del tema.
83
+ - **Validación**: `pnpm check:charts` (dentro de `verify`) ejecuta cada constructor de `echarts-presets`, comprueba
84
+ que su `option` no lleva colores y que se dibuja como SVG en el servidor. Un constructor nuevo necesita su caso en
85
+ `scripts/check-charts.mjs`, o la comprobación falla.
86
+ - Registro común de tipos y componentes: `orbital-ds/lib/echarts-setup`. Otro tipo → `echarts.use([...])` en la app. Si la app
87
+ usa `echarts` directamente (sin `<EChart>` ni `renderEChartToSvg`), llama antes a `dsEcharts()` (registra y lo devuelve):
88
+ así ningún empaquetador quita el registro. `pnpm check:bundle` lo comprueba empaquetando un consumidor.
89
+ - **Recetas completas** (pantalla, informe SVG→PNG, función de servidor de TanStack Start, endpoint en un Worker, marca en los informes): `docs/GRAFICOS.md`.
90
+
91
+ ## Idioma (i18n)
92
+
93
+ - Los textos PROPIOS de los componentes (cerrar, cargando, paginación, carrusel, lateral,
94
+ cuestionario…) salen de `useDsMessages()` y sus catálogos (`orbital-ds/lib/i18n`: en, es,
95
+ pt-BR). **Ningún componente escribe un texto visible o accesible a mano**: el doctor lo rechaza
96
+ (`aria-label="…"`, `sr-only`, `?? "…"`, `title="…"`).
97
+ - Un texto nuevo = una clave nueva en los TRES catálogos (el tipo obliga a tenerla en todos).
98
+ - La app pasa su idioma una vez: `<DsI18nProvider locale={i18n.language}>` (con i18next,
99
+ `useTranslation().i18n.language`). Un texto concreto se sobrescribe con `messages`. Sin
100
+ provider, inglés. Otro idioma cae a su base (`es-CO` → `es`) o al inglés.
101
+ - El texto de la APP (títulos, botones con contenido) lo pone la app con su i18n, no orbital-ds.
102
+ - **En una app con i18next** (la plantilla TanStack es la referencia): los textos de orbital-ds viven
103
+ en el espacio **«orbital»** de sus JSON (`src/i18n/locales/<idioma>.json`), añadido a `ns`, y se
104
+ pasan con `messages={i18n.getResourceBundle(i18n.language, "orbital")}`. `pnpm exec orbital-ds-i18n`
105
+ rellena lo que falte sin pisar lo personalizado; `--check` va en el verify.
106
+ - **Añadir un idioma** (p. ej. `ru`): crea `ru.json` con las mismas claves que `es.json`, añádelo a
107
+ los idiomas de la app y ejecuta `pnpm exec orbital-ds-i18n`. Si orbital-ds no trae ese idioma, deja
108
+ el inglés y LISTA las claves pendientes: tradúcelas en el JSON hasta que `--check` pase.
109
+ - **RTL**: `dsDirection(idioma)` (`orbital-ds/lib/i18n`) da `ltr`/`rtl`; la app lo pone en `<html dir>` y
110
+ `DsI18nProvider` lo pasa a Base UI. La conversión de los componentes a clases lógicas
111
+ (`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`.
112
+
113
+ ## Instalar en una app
114
+
115
+ **Orden única: `pnpm exec orbital-ds`** (menú) · `orbital-ds init` (configuración inicial) · `orbital-ds theme [tema]`
116
+ (cambiar de tema conservando marca y extras) · `orbital-ds doctor` · `orbital-ds i18n` · `orbital-ds help [orden]`.
117
+ Las órdenes sueltas (`orbital-ds-init`, `-doctor`, `-i18n`) siguen valiendo como atajos.
118
+
119
+ `orbital-ds init` (= `pnpm exec orbital-ds-init`): elige tema (enseña su ficha: esencia, paleta, gesto, excepciones de
120
+ contraste), elige **cómo aplicar la marca** y, si lo aceptas, escribe `brand.css`, conecta el CSS de
121
+ la app (bloque de imports en orden), anota DESIGN.md, instala Motion y pasa el doctor.
122
+
123
+ - **Modos de marca** (`--mode`): `faithful` (el tema tal cual, sin derivar nada; quita un bloque
124
+ generado con `--update`), `primary` (solo el primario —foco, enlace, lateral activo, serie 1— sobre
125
+ la paleta del tema, con el contraste medido contra SU lienzo) y `full` (paleta entera derivada).
126
+ - La ficha del tema recomienda el modo con `"branding"`. Un tema de un **sistema corporativo**
127
+ (p. ej. `fractalia`) declara `"branding": "faithful"`: no le derives la paleta.
128
+ - Sin preguntas: `--theme fractalia --connect` (fiel) · `--primary <color> --mode primary --theme <tema>` ·
129
+ `--primary <color> --theme <tema> --connect --motion` (completa).
130
+ - **Cambiar de tema**: `orbital-ds theme <tema> [--brand adapt|clean|clean-all|keep]`. `adapt` recalcula la marca
131
+ para el tema nuevo y desactiva los colores escritos a mano para el anterior; `clean` solo desactiva esos colores;
132
+ `clean-all`, toda la marca; `keep` la deja (por defecto sin terminal, con aviso). Lo desactivado queda comentado,
133
+ con copia `.bak`; quita también los imports de tema sueltos y pone `@base-theme` al tema nuevo. Al pasar por un
134
+ tema fiel, la marca queda recordada y vuelve al salir de él.
135
+
136
+ ## Diseñar con orbital-ds (diseñador para agentes)
137
+
138
+ Para crear o revisar pantallas y flujos, sigue `docs/designer/`: **flujo.md** (contexto real, modo, mapa del flujo y
139
+ modelo mental de la persona, orden de autoridad), **patrones.md** (P1–P12: página, lista de entidades, detalle, tabla,
140
+ formulario, asistente, panel de datos, destructiva, estados, avisos, búsqueda, ajustes), **ux.md** (heurísticas,
141
+ carga cognitiva, formularios, textos, WCAG 2.2 AA, responsivo) y **revision.md** (lista observable y anti-patrones).
142
+ Regla de oro: **nunca te sales del sistema**; si algo no se puede hacer con componentes y variables, se anota como hueco.
143
+
144
+ - `orbital-ds context` (o `--json`): el estado real de la app para un agente (tema, marca, extras, componentes con
145
+ sus notas, patrones). Las notas de uso de cada componente se escriben en el propio fichero con `@note`.
146
+ - `orbital-ds skill`: instala en la app el skill de Claude Code **orbital-ds-designer** (`.claude/skills/`). Es fino:
147
+ lee esta documentación del paquete instalado, así que se actualiza con cada versión; `orbital-ds skill --check` en
148
+ el verify avisa si quedó de otra versión. El asistente lo ofrece en sus extras.
149
+
150
+ ## Componentes con presets (patrones de configuración)
151
+
152
+ Un componente de **flujo o maqueta** (StepFlow, FormLayout, EmptyState, StatGroup, ConfirmAction) se configura con un
153
+ `preset`: una intención en inglés que **solo fija valores por defecto**; cualquier prop explícita lo sobrescribe, así sirve
154
+ en cualquier proyecto. Vocabulario común en `src/lib/presets.ts` (`DsDensity`, `DsPresentation`, `dsWarn`).
155
+
156
+ 1. **Configuración en inglés** (props, valores, tokens, `data-*`); **texto visible o accesible** por `useDsMessages()` en
157
+ los tres catálogos; comentarios y `@note` en español.
158
+ 2. **Nombre del preset = intención** (`quick`, `first-use`, `settings`), nunca el aspecto (`small-modal`).
159
+ 3. **Ejes independientes**: presentación (`dialog | page | inline | sheet`) y densidad (`compact | default | comfortable`)
160
+ son props distintas; los presets las combinan, no las fusionan.
161
+ 4. **El diseño sigue el ancho del contenedor** (container query), no el dispositivo ni la presentación.
162
+ 5. **Aviso en desarrollo** (`dsWarn`, mensaje en inglés) si la combinación no cuadra.
163
+ 6. **Ganchos del DOM**: `data-slot` y `data-preset` (más `data-presentation`/`data-density` si aplica).
164
+ 7. **Un `@note`** que diga cuándo usar cada preset. Catálogo hoy: `Sidebar` (app · workspace · admin · focus, con `density`), `ChartCard` (glance · standard · focus · dense), `ContentCard` (basic · feature · media · horizontal, con `emphasis` elevated · outlined · filled · ghost), `Mosaic` (even · bento · trio), `PageShell` (content · detail · canvas), `PageHeader` (page · compact · canvas), `FilterBar` (inline · compact · stacked), `DataTable` (browse · manage · compact), `LoadingState` (list · card · table · detail), `PageLoader` (splash · route · section · overlay), `CommandPalette` (go · actions · search), `FileUpload` (drop · button), `ErrorPage` (not-found · forbidden · server-error · offline · maintenance, con `tone` neutral · playful), `DetailPanel` (side · bottom · full), `EntityList` (list · grid · compact), `StepFlow` (quick · activation · long), `FormLayout`
165
+ (inline · sectioned · settings), `NoticeReview` (read · acknowledge · resolve · respond), `EmptyState` (first-use · no-results · error · forbidden), `StatGroup` (overview ·
166
+ compact · comparison · strip) `ConfirmAction` (simple · typed) y, en el acceso (P13), `AuthLayout` (centered · split · cover · banner · minimal),
167
+ `AuthForm` (sign-in · social · sign-up · magic-link · email-code · sso · forgot-password · reset-password),
168
+ `MfaChallenge` (totp · sms · email · backup-code · passkey), `MfaSetup` (totp · sms · backup-codes), `OAuthConsent`
169
+ (authorize · mcp · device), `ConnectedAccounts` (social · integrations) y el flujo entero con `defineAuthFlow`
170
+ (standard · social · passwordless · partner · enterprise · hybrid · sso-only).
171
+ `ErrorPage` y `EmptyState` aceptan además `backdrop` (+ `backdropMedia`, `backdropGlass`) y `animated`.
172
+
173
+ **Densidad global.** `--ds-density` (1 por defecto; 0.8 más denso, 1.2 más aireado) escala el relleno de celdas y la separación de secciones y listas; la app lo ajusta en `brand.css`.
174
+
175
+ ## Acceso y autenticación
176
+
177
+ - **Agnóstico del proveedor; Better Auth como referencia.** orbital-ds pinta, valida y anuncia; la app conecta su
178
+ backend con callbacks (`onSubmit`, `onProvider`, `onPasskey`…) que devuelven un `AuthResult`. Con Better Auth,
179
+ `fromBetterAuth(await authClient.…)` (`orbital-ds/lib/auth-better-auth`) traduce la respuesta.
180
+ - **El flujo primero:** `defineAuthFlow` (`orbital-ds/lib/auth-flow`) fija audiencia, métodos, registro, MFA y
181
+ aspecto; `validateAuthFlow` lo comprueba. Receta y piezas en `docs/designer/patrones.md` (P13).
182
+ - **Errores por código** (`AuthErrorCode`, textos en los tres catálogos); nunca reveles si una cuenta existe.
183
+ - **Fondos** (`AuthBackdrop`, también detrás de `ErrorPage` y `EmptyState`): los colores, el cristal y el ritmo
184
+ los pone el tema; quietos con movimiento reducido o con `--ds-auth-fx-play: paused`.
185
+
186
+ ## Avisos y comunicaciones in-app (qué canal usar)
187
+
188
+ Se elige el canal por **urgencia** y **persistencia**; cada app no lo decide a mano:
189
+
190
+ | Intención | Canal | Persiste | Interrumpe |
191
+ |---|---|---|---|
192
+ | Confirmar una acción de la persona | toast (`Toaster`/`Toast`) | no | no |
193
+ | Aviso de una sección | `Alert` | sí | no |
194
+ | Aviso que afecta a toda la página | `Banner` | hasta resolver | no |
195
+ | Asunto con seguimiento o decisión | campana (`NotificationCenter`) + `NoticeReview` | sí, con estado | solo si es crítico |
196
+ | Bloqueo que exige respuesta ya | `ConfirmAction` / `AlertDialog` | no | sí |
197
+
198
+ Mismo vocabulario en todos: tono `info | success | warning | danger` y estado `new → acknowledged → resolved`.
199
+ `NotificationItem onSelect` abre la revisión; `NoticeReview` tiene presets `read | acknowledge | resolve | respond`
200
+ (modal o `presentation="sheet"`).
201
+
202
+ ## Cómo comprobar tu trabajo
203
+
204
+ ```bash
205
+ pnpm check:ds # contrato, repetidos, sombras, fugas, valores fijos, personalidad, familias, contraste y demos
206
+ pnpm verify # doctor + typecheck + build + check:bundle
207
+ pnpm check:charts # cada constructor de gráfico: sin colores y dibuja SVG en servidor
208
+ pnpm check:bundle # empaqueta un consumidor de EChart (navegador y servidor) y comprueba que dibuja
209
+ pnpm manifest # regenera components.manifest.json tras añadir componentes
210
+ pnpm showcase # escaparate: todos los componentes × todos los temas × claro/oscuro × marca
211
+ pnpm showcase:typecheck # tipos de las demos
212
+ pnpm showcase:build # compila el escaparate (comprobación sin servidor)
213
+ ```
214
+
215
+ **Escaparate.** Descubre solo los temas (`src/themes`), las demos (`showcase/src/demos/<componente>.tsx`,
216
+ una por componente: el doctor falla si falta) y las variantes (`showcase/variants/*.css`).
217
+
218
+ **Variante de un tema** (p. ej. «dame variantes de tactile»): un fichero en `showcase/variants/<nombre>.css`
219
+ con `@base-theme <tema>` y `@about <frase>` en su comentario de cabecera y **solo variables** (como un
220
+ `brand.css`). Valídala con `pnpm check:ds -- --css showcase/variants/<nombre>.css`: comprueba que las
221
+ variables existan y el **contraste AA** de la variante sobre su tema. Para llevarla a una app, su contenido
222
+ va al `brand.css`.
223
+
224
+ Si `pnpm check:ds` falla, **corrige la causa**; no lo desactives ni lo rodees.
225
+
226
+ ## Añadir un componente
227
+
228
+ 1. Fichero en `src/ui/<nombre>.tsx` (un componente = un fichero; sin barril).
229
+ 2. `data-slot="<nombre>"` en su raíz y en las partes relevantes.
230
+ 3. Solo tokens. Importa `cn` de `../lib/utils.js`; los demás componentes, de `./<otro>.js`. **Los imports relativos llevan
231
+ siempre `.js`**: el paquete es `"type": "module"` y Node (tests, SSR sin bundler) no completa la ruta; `check:pack`
232
+ importa cada export con Node puro.
233
+ 4. Dependencias de terceros de un COMPONENTE: opcionales (`peerDependenciesMeta`), nunca
234
+ obligatorias. Las herramientas de terminal del paquete (`orbital-ds-init`) sí pueden
235
+ tener las suyas (`@clack/prompts`), porque no llegan al bundle de la app.
236
+ 5. Su demo en `showcase/src/demos/<nombre>.tsx` (variantes, tamaños y estados).
237
+ 6. `pnpm manifest`, `pnpm verify`; versión **menor** (añadido compatible).
238
+
239
+ ## Crear un tema
240
+
241
+ Copia `themes/qratia.css` (o `tactile.css`, el ejemplo estricto), cambia valores, no quites
242
+ ninguno, añade `<tema>.fonts.css` con el `@import url()` de sus fuentes, marca la ficha con
243
+ `"conformance": "strict"` y ejecuta `pnpm check:ds`. En modo estricto el doctor exige que la
244
+ personalidad use **solo variables** (ni medidas, ni colores, ni pesos) y que estilice
245
+ **familias completas** de piezas (`slotFamilies` en `contract.json`: si das tinta al
246
+ `checkbox`, también al `radio-group-item`).
247
+
248
+ ## Adaptar un sistema corporativo (p. ej. Fractalia)
249
+
250
+ Se adapta el sistema al modelo, nunca al revés (decisión y plan: `docs/adr/0002-sistemas-corporativos-al-modelo.md`):
251
+
252
+ 1. **Valores a los huecos.** Cada valor de su DS va a la variable pública que ya lo cubre (`--ds-radius-button`,
253
+ `--ds-field-bg`, `--ds-switch-track-off`, `--ds-*-weight`…). La personalidad solo para lo que ningún hueco
254
+ cubre. El doctor rechaza (aviso si el tema no es estricto) una regla que pinta una propiedad que tiene hueco (`slotTokens` del contrato).
255
+ 2. **Si falta el hueco, se añade** al núcleo con un valor que deje igual a los demás temas (p. ej. el
256
+ desactivado con color: `--ds-button-disabled-bg/-fg/-border`, opcionales con respaldo por variante).
257
+ 3. **Pesos cargados = pesos usados**: el doctor avisa si una `--ds-*-weight` pide un peso que `<tema>.fonts.css`
258
+ no carga.
259
+ 4. **Sus componentes van al núcleo, genéricos** (nunca CSS de componentes dentro de un tema): antes de crear,
260
+ busca en el manifiesto y amplía (solo añadir). Tono con el vocabulario común (`DsDataTone`); el significado
261
+ de dominio (riesgo bajo/medio/alto) lo traduce la app. Medidas y efectos en `--ds-<pieza>-*`; animación con
262
+ CSS y el ritmo del tema (`--ds-motion-pulse`, `--ds-ease-pulse`), quieta con movimiento reducido.
263
+ Piezas de estado y progreso: `Shield`/`ShieldRadar`, `Gauge`, `PasswordStrength`, `StepDots`, `StepRing`,
264
+ `TaskProgress`, `LevelMeter`, `StatusHero`, `TaskLoader` y `StatusDot size`. Pista común: `--ds-track-bg`.
265
+ 5. **Fidelidad comprobada**: compara el valor efectivo de cada propiedad antes y después de traducir (claro y
266
+ oscuro); solo deben cambiar los valores de su DS que antes no se aplicaban.
267
+
268
+ ## Estándar de integración (cómo debe ajustarse una app)
269
+
270
+ Para que una app (o un agente que la edite) use orbital-ds sin romper nada:
271
+
272
+ 1. **La marca vive solo en `brand.css`.** Ninguna regla de color propia fuera de ese fichero; jamás se edita el paquete.
273
+ 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`).
274
+ 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.
275
+ 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.
276
+ 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). **Opcional: un buscador o paleta de comandos** («Ir a…», ⌘K) cuando es la navegación principal de la app: en escritorio, un `InputGroup` compacto que abre `Command`; en móvil, solo el botón con el icono de búsqueda. 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.
277
+ 6. **Listas de entidades** (agentes, herramientas, dispositivos): `Item variant="card"` con su `ItemMedia` (o `IconTile`), `ItemContent` y `ItemActions`. Toma el gesto de la tarjeta de cada tema (filete y arista en tactile, sin borde en fractalia…); no compongas `Card` + `Item` a mano.
278
+ 7. **`Select` con `items`.** Pasa la lista `{ value, label }` al `Select` para que el disparador muestre la etiqueta y no el valor antes de abrirse (también en el HTML del servidor). La lista se abre debajo del campo, al menos tan ancha como él y con ≈ 8 filas (`--ds-select-max-h`).
279
+ 8. **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.
280
+ 9. **Comprueba antes de dar algo por bueno:** `pnpm exec orbital-ds doctor --css src/brand.css --ui src` (marca y vistas: nada fuera del sistema) y el `verify` de la app.
281
+
282
+ ### Accesibilidad (WCAG 2.2)
283
+
284
+ - **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.
285
+ - **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.
286
+ - **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. Vale también para el texto de estado sobre su fondo suave (`"warning/warning-soft"`), p. ej. cuando el par viene del sistema corporativo que el tema reproduce (fractalia).
287
+ - **Tamaños mínimos** (WCAG 2.5.8 y legibilidad): objetivo táctil ≥ 1,5rem (24 px; los `--ds-control-h-*` van de 1,5 a 2,5rem), texto ≥ 0,75rem (`text-xs`) y cuerpo en 0,875–1rem. El doctor falla si un `--ds-control-h-*` baja de 1,5rem o hay `text-[…rem]` menor de 0,75rem.
288
+ - **Foco siempre visible** (anillo de 3:1 como mínimo) y sin que otro elemento lo tape.
289
+ - **Una marca nueva debe volver a pasar el doctor.** Cambiar `--primary` obliga a revisar `--primary-foreground`, `--link` y `--ring`.