orbital-ds 0.12.0 → 0.13.0

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 (57) hide show
  1. package/AGENTS.md +32 -4
  2. package/README.md +93 -93
  3. package/components.manifest.json +66 -14
  4. package/dist/motion.css +139 -0
  5. package/dist/styles.css +15 -2
  6. package/dist/themes/fractalia.css +473 -464
  7. package/dist/themes/fractalia.fonts.css +3 -3
  8. package/dist/themes/fractalia.guide.md +79 -77
  9. package/dist/themes/fractalia.meta.json +99 -96
  10. package/dist/themes/fractalia.scoped.css +473 -464
  11. package/dist/themes/friendly.css +7 -1
  12. package/dist/themes/friendly.meta.json +7 -0
  13. package/dist/themes/friendly.scoped.css +7 -1
  14. package/dist/themes/qratia.css +13 -8
  15. package/dist/themes/qratia.meta.json +8 -1
  16. package/dist/themes/qratia.scoped.css +13 -8
  17. package/dist/themes/tactile.css +7 -1
  18. package/dist/themes/tactile.meta.json +7 -0
  19. package/dist/themes/tactile.scoped.css +7 -1
  20. package/dist/themes/twitter.css +7 -1
  21. package/dist/themes/twitter.meta.json +7 -0
  22. package/dist/themes/twitter.scoped.css +7 -1
  23. package/dist/themes/zyro.css +7 -1
  24. package/dist/themes/zyro.meta.json +7 -0
  25. package/dist/themes/zyro.scoped.css +7 -1
  26. package/dist/ui/alert.js +6 -5
  27. package/dist/ui/attachment.d.ts +1 -1
  28. package/dist/ui/badge.js +6 -6
  29. package/dist/ui/banner.js +4 -4
  30. package/dist/ui/button.d.ts +1 -1
  31. package/dist/ui/combobox.js +1 -1
  32. package/dist/ui/context-menu.js +4 -4
  33. package/dist/ui/dropdown-menu.js +4 -4
  34. package/dist/ui/input-group.d.ts +1 -1
  35. package/dist/ui/item.d.ts +3 -3
  36. package/dist/ui/item.js +14 -4
  37. package/dist/ui/marker.d.ts +1 -1
  38. package/dist/ui/menubar.js +4 -4
  39. package/dist/ui/native-select.js +2 -2
  40. package/dist/ui/select.js +7 -8
  41. package/dist/ui/stat.d.ts +11 -1
  42. package/dist/ui/stat.js +13 -3
  43. package/dist/ui/status-badge.js +6 -6
  44. package/docs/adr/0002-sistemas-corporativos-al-modelo.md +176 -176
  45. package/docs/designer/flujo.md +79 -0
  46. package/docs/designer/patrones.md +116 -0
  47. package/docs/designer/revision.md +60 -0
  48. package/docs/designer/ux.md +71 -0
  49. package/package.json +9 -2
  50. package/scripts/brand-core.mjs +51 -13
  51. package/scripts/cli.mjs +370 -0
  52. package/scripts/doctor.mjs +578 -509
  53. package/scripts/init.mjs +187 -125
  54. package/scripts/manifest.mjs +85 -79
  55. package/scripts/setup.mjs +2 -1
  56. package/scripts/skill.mjs +67 -0
  57. package/skill/SKILL.md +47 -0
package/AGENTS.md CHANGED
@@ -43,6 +43,14 @@ adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
43
43
 
44
44
  ## Movimiento (animación)
45
45
 
46
+ - **Animaciones de fábrica sin código: `@import 'orbital-ds/motion.css'`** (después del tema; el asistente lo añade si
47
+ lo activas). Entradas en cascada de tarjetas, paneles, KPI, filas-tarjeta, avisos, cabeceras y filas de tabla, y
48
+ superficies pulsables. Cada grupo tiene su interruptor con un tipo del CATÁLOGO: `--ds-enter-surfaces`,
49
+ `--ds-enter-notices`, `--ds-enter-headers`, `--ds-enter-rows` = `ds-auto-enter` (sube) · `ds-auto-fade` ·
50
+ `ds-auto-pop` (crece) · `ds-auto-slide` (de lado, RTL) · `ds-auto-focus` (se enfoca) · `none`. Cada tema elige
51
+ según su personalidad y lo declara en su ficha (`motion.auto`); el doctor comprueba que sea del catálogo y que
52
+ ficha y CSS coincidan. La app lo cambia en `brand.css`. Sin el import, no anima nada.
53
+
46
54
  - **El tema gobierna el «cómo»**: ritmo (`--ds-motion-*`), curvas (`--ds-ease-*`) y coreografía
47
55
  (`--ds-motion-distance`, `-scale`, `-blur`, `--ds-spring-bounce`, `--ds-motion-stagger`,
48
56
  `--ds-motion-press-scale`). Cada tema trae el suyo de fábrica; la app lo ajusta en `brand.css`.
@@ -97,7 +105,11 @@ adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
97
105
 
98
106
  ## Instalar en una app
99
107
 
100
- `pnpm exec orbital-ds-init`: elige tema (enseña su ficha: esencia, paleta, gesto, excepciones de
108
+ **Orden única: `pnpm exec orbital-ds`** (menú) · `orbital-ds init` (configuración inicial) · `orbital-ds theme [tema]`
109
+ (cambiar de tema conservando marca y extras) · `orbital-ds doctor` · `orbital-ds i18n` · `orbital-ds help [orden]`.
110
+ Las órdenes sueltas (`orbital-ds-init`, `-doctor`, `-i18n`) siguen valiendo como atajos.
111
+
112
+ `orbital-ds init` (= `pnpm exec orbital-ds-init`): elige tema (enseña su ficha: esencia, paleta, gesto, excepciones de
101
113
  contraste), elige **cómo aplicar la marca** y, si lo aceptas, escribe `brand.css`, conecta el CSS de
102
114
  la app (bloque de imports en orden), anota DESIGN.md, instala Motion y pasa el doctor.
103
115
 
@@ -109,6 +121,20 @@ la app (bloque de imports en orden), anota DESIGN.md, instala Motion y pasa el d
109
121
  - Sin preguntas: `--theme fractalia --connect` (fiel) · `--primary <color> --mode primary --theme <tema>` ·
110
122
  `--primary <color> --theme <tema> --connect --motion` (completa).
111
123
 
124
+ ## Diseñar con orbital-ds (diseñador para agentes)
125
+
126
+ Para crear o revisar pantallas y flujos, sigue `docs/designer/`: **flujo.md** (contexto real, modo, mapa del flujo y
127
+ modelo mental de la persona, orden de autoridad), **patrones.md** (P1–P12: página, lista de entidades, detalle, tabla,
128
+ formulario, asistente, panel de datos, destructiva, estados, avisos, búsqueda, ajustes), **ux.md** (heurísticas,
129
+ carga cognitiva, formularios, textos, WCAG 2.2 AA, responsivo) y **revision.md** (lista observable y anti-patrones).
130
+ Regla de oro: **nunca te sales del sistema**; si algo no se puede hacer con componentes y variables, se anota como hueco.
131
+
132
+ - `orbital-ds context` (o `--json`): el estado real de la app para un agente (tema, marca, extras, componentes con
133
+ sus notas, patrones). Las notas de uso de cada componente se escriben en el propio fichero con `@note`.
134
+ - `orbital-ds skill`: instala en la app el skill de Claude Code **orbital-ds-designer** (`.claude/skills/`). Es fino:
135
+ lee esta documentación del paquete instalado, así que se actualiza con cada versión; `orbital-ds skill --check` en
136
+ el verify avisa si quedó de otra versión. El asistente lo ofrece en sus extras.
137
+
112
138
  ## Cómo comprobar tu trabajo
113
139
 
114
140
  ```bash
@@ -180,9 +206,11 @@ Para que una app (o un agente que la edite) use orbital-ds sin romper nada:
180
206
  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`).
181
207
  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.
182
208
  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.
183
- 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.
184
- 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.
185
- 7. **Comprueba antes de dar algo por bueno:** `pnpm exec orbital-ds-doctor --css src/brand.css` y el `verify` de la app.
209
+ 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.
210
+ 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.
211
+ 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`).
212
+ 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.
213
+ 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.
186
214
 
187
215
  ### Accesibilidad (WCAG 2.2)
188
216
 
package/README.md CHANGED
@@ -1,93 +1,93 @@
1
- # orbital-ds
2
-
3
- Sistema de diseño genérico: **estructura común + temas intercambiables + ~60 componentes**
4
- sobre [Base UI](https://base-ui.com) y Tailwind v4 (los de shadcn en su versión Base UI).
5
-
6
- - `styles.css` — la ESTRUCTURA: mapea variables de tema a utilidades de Tailwind y define los
7
- tokens semánticos (radios, alturas, sombras, espaciado, capas, movimiento, foco, materiales)
8
- y la capa base. No lleva colores ni fuentes.
9
- - `themes/<tema>.css` — un TEMA: paleta (claro/oscuro), radio base y tipografía.
10
- Hoy: `qratia`, `zyro` (cristal), `friendly`, `twitter`, `tactile` y `fractalia` (sistema corporativo de
11
- Fractalia, para usarlo fiel). Añadir otro = añadir otro fichero.
12
- - `themes/<tema>.fonts.css` — las fuentes del tema (un `@import url()`; va el primero).
13
- - `ui/*` — componentes, uno por fichero (`orbital-ds/ui/button`, …): quien no usa gráficos
14
- no necesita `recharts`, quien no usa el calendario no necesita `react-day-picker`.
15
- - `contract.json` + `pnpm check:ds` — el contrato de tema y su comprobación.
16
-
17
- ## Uso en una app (Tailwind v4)
18
-
19
- ```css
20
- @import 'orbital-ds/themes/qratia.fonts.css'; /* fuentes: lo primero */
21
- @import 'tailwindcss';
22
- @plugin '@tailwindcss/typography';
23
- @import 'tw-animate-css';
24
- @import 'orbital-ds/styles.css'; /* estructura */
25
- @import 'orbital-ds/themes/qratia.css'; /* tema (después de la estructura) */
26
- @source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
27
- ```
28
-
29
- ```tsx
30
- import { Button } from 'orbital-ds/ui/button';
31
- ```
32
-
33
- Cambiar de identidad = cambiar `qratia` por `zyro` en esas dos líneas de tema/fuentes.
34
- Detalle del contrato, tokens y reglas de nombres en [`docs/CONTRACT.md`](docs/CONTRACT.md).
35
-
36
- ## Generar la marca desde un color (asistente)
37
-
38
- ```
39
- pnpm exec orbital-ds-init # asistente interactivo
40
- pnpm exec orbital-ds-init --primary "#1D63D8" # sin preguntas (CI, scripts)
41
- ```
42
-
43
- A partir del **color primario** (hex, `rgb()`, `hsl()` u `oklch()`) deriva en OKLCH los neutros teñidos
44
- (papel, tinta, tarjeta, bordes, lateral), el texto sobre el primario, el enlace y el foco, en piel clara y
45
- oscura, y **comprueba el contraste** (AA 4,5:1). Si un color no llega, lo ajusta lo mínimo y te lo dice.
46
- Escribe solo un bloque delimitado en `brand.css`; con `--update` lo reescribe y lo tuyo de fuera no se
47
- toca. Opciones: `--theme`, `--accent`, `--no-marker` (apaga el rotulador de `tactile`), `--dry-run`,
48
- `--yes`, `--out`. Sin dependencias.
49
-
50
- **Modos de marca** (`--mode`; el asistente los ofrece con el recomendado por la ficha del tema):
51
- `faithful` deja el tema tal cual (lo que piden los temas de un sistema corporativo, como `fractalia`:
52
- `--theme fractalia --connect`), `primary` cambia solo el primario sobre la paleta del tema y `full`
53
- deriva la paleta entera.
54
-
55
- ## Guía de cada tema
56
-
57
- Cada tema lleva su documentación, que viaja con el paquete:
58
-
59
- - `orbital-ds/themes/<tema>.guide.md` — guía de diseño: esencia, gesto firma, principios, referencias (qué se tomó de cada una), paleta, tipografía, formas, accesibilidad y estado de los valores (confirmados, aproximados o de diseño propio).
60
- - `orbital-ds/themes/<tema>.meta.json` — la misma ficha legible por máquina.
61
-
62
- `pnpm check:ds` falla si a un tema le falta alguna de las dos. Un tema nuevo debe nacer con ambas.
63
-
64
- ## Marca de una app
65
-
66
- Lo propio de cada app (color principal, acento, radio, fuentes) va en **su** `src/brand.css`,
67
- importado después del tema. Ninguna actualización de orbital-ds lo toca. `pnpm exec orbital-ds-init`
68
- lo crea la primera vez. Detalle en [`docs/CONTRACT.md`](docs/CONTRACT.md).
69
-
70
- ## Regla
71
-
72
- Ningún componente lleva valores propios (colores, medidas, sombras, z-index, duraciones):
73
- pide un hueco a una variable. Para cambiar el aspecto se cambia el tema, no el componente.
74
- Si un componente necesita un hueco nuevo, se AÑADE el token con un valor que deje el aspecto
75
- como estaba. `pnpm check:ds` lo comprueba.
76
-
77
- ## Desarrollo
78
-
79
- ```bash
80
- pnpm install
81
- pnpm verify # doctor + typecheck + build
82
- pnpm check:ds # solo el contrato de tema y los valores fijos
83
- ```
84
-
85
- Peers obligatorios: `react`, `react-dom`, `@base-ui/react`, `tailwindcss`, `tailwind-merge`,
86
- `class-variance-authority`, `clsx`, `lucide-react`, `tw-animate-css`.
87
- Opcionales (solo si usas ese componente): `recharts`, `sonner`, `next-themes`, `cmdk`,
88
- `date-fns` + `react-day-picker`, `embla-carousel-react`, `input-otp`,
89
- `react-resizable-panels`, `@shadcn/react`.
90
-
91
- ## Licencia
92
-
93
- MIT © Fractalia Systems
1
+ # orbital-ds
2
+
3
+ Sistema de diseño genérico: **estructura común + temas intercambiables + ~60 componentes**
4
+ sobre [Base UI](https://base-ui.com) y Tailwind v4 (los de shadcn en su versión Base UI).
5
+
6
+ - `styles.css` — la ESTRUCTURA: mapea variables de tema a utilidades de Tailwind y define los
7
+ tokens semánticos (radios, alturas, sombras, espaciado, capas, movimiento, foco, materiales)
8
+ y la capa base. No lleva colores ni fuentes.
9
+ - `themes/<tema>.css` — un TEMA: paleta (claro/oscuro), radio base y tipografía.
10
+ Hoy: `qratia`, `zyro` (cristal), `friendly`, `twitter`, `tactile` y `fractalia` (sistema corporativo de
11
+ Fractalia, para usarlo fiel). Añadir otro = añadir otro fichero.
12
+ - `themes/<tema>.fonts.css` — las fuentes del tema (un `@import url()`; va el primero).
13
+ - `ui/*` — componentes, uno por fichero (`orbital-ds/ui/button`, …): quien no usa gráficos
14
+ no necesita `recharts`, quien no usa el calendario no necesita `react-day-picker`.
15
+ - `contract.json` + `pnpm check:ds` — el contrato de tema y su comprobación.
16
+
17
+ ## Uso en una app (Tailwind v4)
18
+
19
+ ```css
20
+ @import 'orbital-ds/themes/qratia.fonts.css'; /* fuentes: lo primero */
21
+ @import 'tailwindcss';
22
+ @plugin '@tailwindcss/typography';
23
+ @import 'tw-animate-css';
24
+ @import 'orbital-ds/styles.css'; /* estructura */
25
+ @import 'orbital-ds/themes/qratia.css'; /* tema (después de la estructura) */
26
+ @source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
27
+ ```
28
+
29
+ ```tsx
30
+ import { Button } from 'orbital-ds/ui/button';
31
+ ```
32
+
33
+ Cambiar de identidad = cambiar `qratia` por `zyro` en esas dos líneas de tema/fuentes.
34
+ Detalle del contrato, tokens y reglas de nombres en [`docs/CONTRACT.md`](docs/CONTRACT.md).
35
+
36
+ ## Generar la marca desde un color (asistente)
37
+
38
+ ```
39
+ pnpm exec orbital-ds-init # asistente interactivo
40
+ pnpm exec orbital-ds-init --primary "#1D63D8" # sin preguntas (CI, scripts)
41
+ ```
42
+
43
+ A partir del **color primario** (hex, `rgb()`, `hsl()` u `oklch()`) deriva en OKLCH los neutros teñidos
44
+ (papel, tinta, tarjeta, bordes, lateral), el texto sobre el primario, el enlace y el foco, en piel clara y
45
+ oscura, y **comprueba el contraste** (AA 4,5:1). Si un color no llega, lo ajusta lo mínimo y te lo dice.
46
+ Escribe solo un bloque delimitado en `brand.css`; con `--update` lo reescribe y lo tuyo de fuera no se
47
+ toca. Opciones: `--theme`, `--accent`, `--no-marker` (apaga el rotulador de `tactile`), `--dry-run`,
48
+ `--yes`, `--out`. Sin dependencias.
49
+
50
+ **Modos de marca** (`--mode`; el asistente los ofrece con el recomendado por la ficha del tema):
51
+ `faithful` deja el tema tal cual (lo que piden los temas de un sistema corporativo, como `fractalia`:
52
+ `--theme fractalia --connect`), `primary` cambia solo el primario sobre la paleta del tema y `full`
53
+ deriva la paleta entera.
54
+
55
+ ## Guía de cada tema
56
+
57
+ Cada tema lleva su documentación, que viaja con el paquete:
58
+
59
+ - `orbital-ds/themes/<tema>.guide.md` — guía de diseño: esencia, gesto firma, principios, referencias (qué se tomó de cada una), paleta, tipografía, formas, accesibilidad y estado de los valores (confirmados, aproximados o de diseño propio).
60
+ - `orbital-ds/themes/<tema>.meta.json` — la misma ficha legible por máquina.
61
+
62
+ `pnpm check:ds` falla si a un tema le falta alguna de las dos. Un tema nuevo debe nacer con ambas.
63
+
64
+ ## Marca de una app
65
+
66
+ Lo propio de cada app (color principal, acento, radio, fuentes) va en **su** `src/brand.css`,
67
+ importado después del tema. Ninguna actualización de orbital-ds lo toca. `pnpm exec orbital-ds-init`
68
+ lo crea la primera vez. Detalle en [`docs/CONTRACT.md`](docs/CONTRACT.md).
69
+
70
+ ## Regla
71
+
72
+ Ningún componente lleva valores propios (colores, medidas, sombras, z-index, duraciones):
73
+ pide un hueco a una variable. Para cambiar el aspecto se cambia el tema, no el componente.
74
+ Si un componente necesita un hueco nuevo, se AÑADE el token con un valor que deje el aspecto
75
+ como estaba. `pnpm check:ds` lo comprueba.
76
+
77
+ ## Desarrollo
78
+
79
+ ```bash
80
+ pnpm install
81
+ pnpm verify # doctor + typecheck + build
82
+ pnpm check:ds # solo el contrato de tema y los valores fijos
83
+ ```
84
+
85
+ Peers obligatorios: `react`, `react-dom`, `@base-ui/react`, `tailwindcss`, `tailwind-merge`,
86
+ `class-variance-authority`, `clsx`, `lucide-react`, `tw-animate-css`.
87
+ Opcionales (solo si usas ese componente): `recharts`, `sonner`, `next-themes`, `cmdk`,
88
+ `date-fns` + `react-day-picker`, `embla-carousel-react`, `input-otp`,
89
+ `react-resizable-panels`, `@shadcn/react`.
90
+
91
+ ## Licencia
92
+
93
+ MIT © Fractalia Systems
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "package": "orbital-ds",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "engine": "@base-ui/react",
5
5
  "docs": [
6
6
  "README.md",
@@ -57,7 +57,10 @@
57
57
  "alert-dialog-title",
58
58
  "alert-dialog-trigger"
59
59
  ],
60
- "optionalPeers": []
60
+ "optionalPeers": [],
61
+ "notes": [
62
+ "Acción destructiva: título con la pregunta concreta («¿Eliminar el cliente Acme?»), descripción de la consecuencia y AlertDialogAction con el verbo («Eliminar cliente»)."
63
+ ]
61
64
  },
62
65
  "alert": {
63
66
  "import": "orbital-ds/ui/alert",
@@ -226,7 +229,12 @@
226
229
  "buttonVariants"
227
230
  ],
228
231
  "slots": [],
229
- "optionalPeers": []
232
+ "optionalPeers": [],
233
+ "notes": [
234
+ "Una sola acción principal (variant default) por vista; las demás outline/ghost o en un menú.",
235
+ "Texto con verbo + objeto («Crear cliente»), nunca «Aceptar» o «Enviar»; botón de solo icono con aria-label.",
236
+ "Destructivo: variant destructive y siempre con confirmación (AlertDialog) o deshacer."
237
+ ]
230
238
  },
231
239
  "calendar": {
232
240
  "import": "orbital-ds/ui/calendar",
@@ -498,6 +506,10 @@
498
506
  ],
499
507
  "optionalPeers": [
500
508
  "@tanstack/react-table"
509
+ ],
510
+ "notes": [
511
+ "Para muchas filas, comparar y ordenar; para 3–5 elementos usa Item variant=\"card\". Estado en la URL con dataTableStateToSearch.",
512
+ "Cifras con DataTableNumber (alineadas, tabular-nums); acciones por fila en un menú; sin resultados con Empty y «Limpiar filtros»."
501
513
  ]
502
514
  },
503
515
  "date-picker": {
@@ -662,7 +674,10 @@
662
674
  "echart-canvas",
663
675
  "echart-empty"
664
676
  ],
665
- "optionalPeers": []
677
+ "optionalPeers": [],
678
+ "notes": [
679
+ "Nunca pongas colores en el option: los da el tema (paleta --chart-1…5). Para informes en servidor: renderEChartToSvg."
680
+ ]
666
681
  },
667
682
  "empty": {
668
683
  "import": "orbital-ds/ui/empty",
@@ -682,7 +697,10 @@
682
697
  "empty-icon",
683
698
  "empty-title"
684
699
  ],
685
- "optionalPeers": []
700
+ "optionalPeers": [],
701
+ "notes": [
702
+ "Estado vacío: qué es esto, por qué está vacío y la acción para empezar; sin resultados: los filtros aplicados y «Limpiar filtros»."
703
+ ]
686
704
  },
687
705
  "eyebrow": {
688
706
  "import": "orbital-ds/ui/eyebrow",
@@ -719,7 +737,11 @@
719
737
  "field-separator-content",
720
738
  "field-set"
721
739
  ],
722
- "optionalPeers": []
740
+ "optionalPeers": [],
741
+ "notes": [
742
+ "Formularios: FieldGroup + Field con FieldLabel (siempre visible; el placeholder no es etiqueta), FieldDescription y FieldError junto al campo.",
743
+ "Una columna; agrupa con FieldSet/FieldLegend; lo opcional, marcado o plegado."
744
+ ]
723
745
  },
724
746
  "filter-bar": {
725
747
  "import": "orbital-ds/ui/filter-bar",
@@ -763,7 +785,10 @@
763
785
  "gauge-value",
764
786
  "gauge-value-suffix"
765
787
  ],
766
- "optionalPeers": []
788
+ "optionalPeers": [],
789
+ "notes": [
790
+ "Tono del vocabulario común (DsDataTone): la app traduce su dominio (riesgo bajo → success, medio → warning, alto → danger, analizando → neutral). Siempre con label."
791
+ ]
767
792
  },
768
793
  "heatmap-grid": {
769
794
  "import": "orbital-ds/ui/heatmap-grid",
@@ -887,11 +912,16 @@
887
912
  "item-footer",
888
913
  "item-group",
889
914
  "item-header",
915
+ "item-listitem",
890
916
  "item-media",
891
917
  "item-separator",
892
918
  "item-title"
893
919
  ],
894
- "optionalPeers": []
920
+ "optionalPeers": [],
921
+ "notes": [
922
+ "Listas de entidades: variant=\"card\" (fila-tarjeta). Sin acciones: render={<a href=… />} y la fila entera navega. Con acciones: el Item queda como div, el enlace va en ItemTitle estirado (after:absolute after:inset-0, Item relative) e ItemActions con relative z-(--ds-z-raised): nunca un botón dentro de un enlace. Dentro de ItemGroup cada Item ya va en su role=\"listitem\" (no lo envuelvas a mano).",
923
+ "No compongas Card + Item a mano ni metas tarjetas dentro de tarjetas."
924
+ ]
895
925
  },
896
926
  "kbd": {
897
927
  "import": "orbital-ds/ui/kbd",
@@ -1167,7 +1197,10 @@
1167
1197
  "section-header-icon",
1168
1198
  "section-header-title"
1169
1199
  ],
1170
- "optionalPeers": []
1200
+ "optionalPeers": [],
1201
+ "notes": [
1202
+ "Cabecera de vista: PageHeaderTitle + PageHeaderDescription y la acción principal en PageHeaderActions; centrada en --ds-page-max-w."
1203
+ ]
1171
1204
  },
1172
1205
  "pagination": {
1173
1206
  "import": "orbital-ds/ui/pagination",
@@ -1381,7 +1414,13 @@
1381
1414
  "select-trigger",
1382
1415
  "select-value"
1383
1416
  ],
1384
- "optionalPeers": []
1417
+ "optionalPeers": [],
1418
+ "notes": [
1419
+ "Pasa `items` al Select (lista de { value, label }) para que el disparador muestre la ETIQUETA y no el valor antes de abrir el menú (también en el HTML del servidor): <Select items={OPCIONES} defaultValue=\"warning\">.",
1420
+ "Por defecto position=\"popper\" y align=\"start\": debajo del campo, sin taparlo. position=\"item-aligned\" sigue disponible.",
1421
+ "La lista mide al menos el ancho del disparador y como máximo --ds-select-max-h (≈ 8 filas); ajústalo en brand.css.",
1422
+ "Resaltado de opciones con data-highlighted (ratón y teclado), como en los menús."
1423
+ ]
1385
1424
  },
1386
1425
  "separator": {
1387
1426
  "import": "orbital-ds/ui/separator",
@@ -1438,7 +1477,10 @@
1438
1477
  "shield-ring",
1439
1478
  "shield-value"
1440
1479
  ],
1441
- "optionalPeers": []
1480
+ "optionalPeers": [],
1481
+ "notes": [
1482
+ "Nivel de protección 0–1; con decorative si solo adorna. ShieldRadar para protegido/alerta con latido del tema."
1483
+ ]
1442
1484
  },
1443
1485
  "sidebar": {
1444
1486
  "import": "orbital-ds/ui/sidebar",
@@ -1501,7 +1543,10 @@
1501
1543
  "slots": [
1502
1544
  "skeleton"
1503
1545
  ],
1504
- "optionalPeers": []
1546
+ "optionalPeers": [],
1547
+ "notes": [
1548
+ "Cargando: Skeleton con la forma del contenido, no un spinner a pantalla completa."
1549
+ ]
1505
1550
  },
1506
1551
  "slider": {
1507
1552
  "import": "orbital-ds/ui/slider",
@@ -1575,7 +1620,11 @@
1575
1620
  "stat-value-reason",
1576
1621
  "stat-value-unit"
1577
1622
  ],
1578
- "optionalPeers": []
1623
+ "optionalPeers": [],
1624
+ "notes": [
1625
+ "KPI que filtra: render={<button type=\"button\" />}, pressed cuando el filtro está aplicado y onClick para alternarlo; el texto de la tarjeta dice qué pasa al pulsar.",
1626
+ "Un dato nulo no es cero: value={null} pinta «—» con «Sin dato» (y reason en un tooltip)."
1627
+ ]
1579
1628
  },
1580
1629
  "status-badge": {
1581
1630
  "import": "orbital-ds/ui/status-badge",
@@ -1598,7 +1647,10 @@
1598
1647
  "status-explanation-detail",
1599
1648
  "status-explanation-term"
1600
1649
  ],
1601
- "optionalPeers": []
1650
+ "optionalPeers": [],
1651
+ "notes": [
1652
+ "El estado SIEMPRE con texto: el color refuerza, nunca es el único portador; level=\"none\" es «sin dato», distinto de ok."
1653
+ ]
1602
1654
  },
1603
1655
  "status-hero": {
1604
1656
  "import": "orbital-ds/ui/status-hero",
@@ -0,0 +1,139 @@
1
+ /*
2
+ * orbital-ds · MOVIMIENTO AUTOMÁTICO (opcional): animaciones de fábrica sin escribir código.
3
+ *
4
+ * @import 'orbital-ds/motion.css'; (después del tema, en el CSS de la app)
5
+ *
6
+ * Qué hace, con el ritmo y la coreografía del TEMA activo (--ds-motion-*, --ds-ease-*,
7
+ * --ds-motion-distance, -scale, -blur, -stagger, -press-scale, --ds-hover-lift):
8
+ * - ENTRADA: tarjetas, paneles, KPI, filas-tarjeta, avisos, cabeceras de página y filas de
9
+ * tabla aparecen subiendo y fundiéndose, en CASCADA entre hermanas.
10
+ * - SUPERFICIES PULSABLES (tarjeta o fila-tarjeta que es enlace o botón): al pasar, la sombra
11
+ * de hover del tema y su elevación; al pulsar, se hunden un poco.
12
+ * - Movimiento reducido: no anima nada (y la regla global de la estructura lo refuerza).
13
+ *
14
+ * Interruptores por grupo (variables de la estructura; el tema los fija y la app los cambia en
15
+ * brand.css): --ds-enter-surfaces (tarjetas, paneles, KPI, filas-tarjeta), --ds-enter-notices
16
+ * (avisos, banners, vacíos), --ds-enter-headers (cabeceras) y --ds-enter-rows (filas de tabla y
17
+ * línea de tiempo). Valor: ds-auto-enter (anima) o none (apagado). La ficha del tema lo describe
18
+ * en motion.auto.
19
+ *
20
+ * Todo con :where() (especificidad cero): un tema o una app lo ajustan sin pelear. Para quitarlo
21
+ * en una pieza concreta: class="animate-none" o style="animation: none".
22
+ * Motion (motion.dev) sigue siendo la vía para coreografías a medida (DsMotionProvider + useDsMotion).
23
+ */
24
+
25
+ @media (prefers-reduced-motion: no-preference) {
26
+ /* ── Entrada (cada grupo, con su interruptor: none lo apaga) ───────────── */
27
+ :where([data-slot='card'], [data-slot='panel'], [data-slot='stat'], [data-slot='item'][data-variant='card']) {
28
+ animation: var(--ds-enter-surfaces) var(--ds-motion-base) var(--ds-ease-enter) both;
29
+ }
30
+ :where([data-slot='alert'], [data-slot='banner'], [data-slot='empty']) {
31
+ animation: var(--ds-enter-notices) var(--ds-motion-base) var(--ds-ease-enter) both;
32
+ }
33
+ :where([data-slot='page-header'], [data-slot='section-header']) {
34
+ animation: var(--ds-enter-headers) var(--ds-motion-base) var(--ds-ease-enter) both;
35
+ }
36
+ :where([data-slot='timeline-item'], [data-slot='table-body'] > [data-slot='table-row']) {
37
+ animation: var(--ds-enter-rows) var(--ds-motion-base) var(--ds-ease-enter) both;
38
+ }
39
+
40
+ /* Cascada entre hermanas: cada una, un paso de --ds-motion-stagger más tarde (hasta 10). */
41
+ :where(
42
+ [data-slot='card'],
43
+ [data-slot='panel'],
44
+ [data-slot='stat'],
45
+ [data-slot='item'][data-variant='card'],
46
+ [data-slot='timeline-item'],
47
+ [data-slot='table-body'] > [data-slot='table-row']
48
+ ) {
49
+ &:nth-child(2) { animation-delay: calc(var(--ds-motion-stagger) * 1); }
50
+ &:nth-child(3) { animation-delay: calc(var(--ds-motion-stagger) * 2); }
51
+ &:nth-child(4) { animation-delay: calc(var(--ds-motion-stagger) * 3); }
52
+ &:nth-child(5) { animation-delay: calc(var(--ds-motion-stagger) * 4); }
53
+ &:nth-child(6) { animation-delay: calc(var(--ds-motion-stagger) * 5); }
54
+ &:nth-child(7) { animation-delay: calc(var(--ds-motion-stagger) * 6); }
55
+ &:nth-child(8) { animation-delay: calc(var(--ds-motion-stagger) * 7); }
56
+ &:nth-child(9) { animation-delay: calc(var(--ds-motion-stagger) * 8); }
57
+ &:nth-child(n + 10) { animation-delay: calc(var(--ds-motion-stagger) * 9); }
58
+ }
59
+
60
+ /* Filas-tarjeta dentro de un ItemGroup: cada una va en su envoltorio role="listitem", así que la
61
+ cascada cuenta los envoltorios. */
62
+ :where([data-slot='item-listitem']) {
63
+ &:nth-child(2) > [data-slot='item'][data-variant='card'] { animation-delay: calc(var(--ds-motion-stagger) * 1); }
64
+ &:nth-child(3) > [data-slot='item'][data-variant='card'] { animation-delay: calc(var(--ds-motion-stagger) * 2); }
65
+ &:nth-child(4) > [data-slot='item'][data-variant='card'] { animation-delay: calc(var(--ds-motion-stagger) * 3); }
66
+ &:nth-child(5) > [data-slot='item'][data-variant='card'] { animation-delay: calc(var(--ds-motion-stagger) * 4); }
67
+ &:nth-child(6) > [data-slot='item'][data-variant='card'] { animation-delay: calc(var(--ds-motion-stagger) * 5); }
68
+ &:nth-child(7) > [data-slot='item'][data-variant='card'] { animation-delay: calc(var(--ds-motion-stagger) * 6); }
69
+ &:nth-child(8) > [data-slot='item'][data-variant='card'] { animation-delay: calc(var(--ds-motion-stagger) * 7); }
70
+ &:nth-child(9) > [data-slot='item'][data-variant='card'] { animation-delay: calc(var(--ds-motion-stagger) * 8); }
71
+ &:nth-child(n + 10) > [data-slot='item'][data-variant='card'] { animation-delay: calc(var(--ds-motion-stagger) * 9); }
72
+ }
73
+
74
+ /* ── Superficies pulsables ───────────────────────────────────────────────── */
75
+ :where(
76
+ a[data-slot='card'],
77
+ button[data-slot='card'],
78
+ a[data-slot='item'][data-variant='card'],
79
+ button[data-slot='item'][data-variant='card']
80
+ ) {
81
+ transition:
82
+ box-shadow var(--ds-motion-fast) var(--ds-ease-standard),
83
+ translate var(--ds-motion-fast) var(--ds-ease-standard),
84
+ scale var(--ds-motion-fast) var(--ds-ease-standard);
85
+
86
+ &:hover {
87
+ box-shadow: var(--ds-shadow-card-hover);
88
+ translate: 0 calc(var(--ds-hover-lift) * -1);
89
+ }
90
+ &:active {
91
+ scale: var(--ds-motion-press-scale);
92
+ }
93
+ }
94
+ }
95
+
96
+ /* ── CATÁLOGO de entradas (nombres fijos: el tema elige una por grupo; el doctor lo comprueba) ──
97
+ * Todas toman recorrido, escala y desenfoque del tema; la curva (con o sin rebote), de --ds-ease-enter. */
98
+ :root {
99
+ --ds-dir: 1;
100
+ }
101
+ [dir='rtl'] {
102
+ --ds-dir: -1;
103
+ }
104
+ /* sube y aparece (por defecto) */
105
+ @keyframes ds-auto-enter {
106
+ from {
107
+ opacity: 0;
108
+ translate: 0 var(--ds-motion-distance);
109
+ scale: var(--ds-motion-scale);
110
+ filter: blur(var(--ds-motion-blur));
111
+ }
112
+ }
113
+ /* solo aparece */
114
+ @keyframes ds-auto-fade {
115
+ from {
116
+ opacity: 0;
117
+ }
118
+ }
119
+ /* crece desde un poco más pequeño (con rebote si la curva del tema lo tiene) */
120
+ @keyframes ds-auto-pop {
121
+ from {
122
+ opacity: 0;
123
+ scale: var(--ds-motion-scale);
124
+ }
125
+ }
126
+ /* entra de lado, desde el inicio de la línea (respeta RTL) */
127
+ @keyframes ds-auto-slide {
128
+ from {
129
+ opacity: 0;
130
+ translate: calc(var(--ds-motion-distance) * -1 * var(--ds-dir)) 0;
131
+ }
132
+ }
133
+ /* se enfoca desde desenfocado (cristal) */
134
+ @keyframes ds-auto-focus {
135
+ from {
136
+ opacity: 0;
137
+ filter: blur(max(var(--ds-motion-blur), var(--ds-motion-focus-blur)));
138
+ }
139
+ }
package/dist/styles.css CHANGED
@@ -208,6 +208,13 @@
208
208
  --ds-spring-bounce: 0.15;
209
209
  --ds-motion-stagger: 40ms;
210
210
  --ds-motion-press-scale: 0.97;
211
+ /* Movimiento automático (orbital-ds/motion.css): interruptor por grupo. ds-auto-enter = anima; none = apagado */
212
+ --ds-enter-surfaces: ds-auto-enter; /* tarjetas, paneles, KPI, filas-tarjeta */
213
+ --ds-enter-notices: ds-auto-enter; /* avisos, banners, vacíos */
214
+ --ds-enter-headers: ds-auto-enter; /* cabeceras de página y de sección */
215
+ --ds-enter-rows: ds-auto-enter; /* filas de tabla y línea de tiempo */
216
+ /* Catálogo: ds-auto-enter (sube) · ds-auto-fade · ds-auto-pop (crece) · ds-auto-slide (de lado) · ds-auto-focus (se enfoca) · none */
217
+ --ds-motion-focus-blur: 6px; /* desenfoque mínimo de ds-auto-focus */
211
218
 
212
219
  --ds-z-stack: 1000; /* base del apilado interno (toasts unos sobre otros) */
213
220
 
@@ -275,7 +282,7 @@
275
282
  --ds-button-case: none;
276
283
  --ds-button-tracking: normal;
277
284
  --ds-button-outline-w: 1px;
278
- /* Colores por variante del botón (0.11.0): por defecto, el aspecto de siempre */
285
+ /* Colores por variante del botón (0.12.0): por defecto, el aspecto de siempre */
279
286
  --ds-button-primary-hover: color-mix(in oklab, var(--primary) 80%, transparent); /* fondo del primario al pasar */
280
287
  --ds-button-primary-hover-fg: var(--primary-foreground);
281
288
  --ds-button-outline-bg: var(--ds-field-bg); /* botón outline */
@@ -283,6 +290,9 @@
283
290
  --ds-button-outline-border: var(--border);
284
291
  --ds-button-secondary-border: transparent; /* borde del botón secundario */
285
292
  --ds-badge-weight: var(--ds-label-weight); /* peso de la insignia */
293
+ /* --ds-on-soft (OPCIONAL): texto sobre el fondo suave de un estado (Alert, Banner, Badge y StatusBadge suaves).
294
+ * Sin definir, cada tono usa su color. Un tema cuyos tonos no llegan a AA sobre su fondo suave la pone en
295
+ * tinta (var(--foreground)); el color del estado queda en el icono y el borde. El doctor la mide. */
286
296
  --ds-button-disabled-opacity: var(--ds-disabled-opacity); /* botón desactivado: 1 si el tema lo pinta con color */
287
297
  /* Desactivado CON COLOR (opcional): sin definir, cada variante conserva su color y se atenúa con la
288
298
  * opacidad. Un tema que lo quiera define las tres y pone --ds-button-disabled-opacity: 1.
@@ -418,6 +428,9 @@
418
428
  --ds-menu-p: 0.25rem;
419
429
  --ds-menu-item-px: 0.75rem;
420
430
  --ds-menu-item-py: 0.5rem;
431
+ --ds-select-max-h: 18rem; /* alto máximo de la lista de Select y Combobox (≈ 8 filas; luego, scroll) */
432
+ --ds-select-min-w: 9rem; /* ancho mínimo de la lista (y nunca menos que el disparador) */
433
+ --ds-select-max-w: min(32rem, calc(100vw - 2rem)); /* ancho máximo: el texto largo se recorta */
421
434
  --ds-button-px-sm: 0.75rem;
422
435
  --ds-button-px-md: 1rem;
423
436
  --ds-button-px-lg: 1rem;
@@ -453,7 +466,7 @@
453
466
  --ds-banner-px: 1rem; /* aviso de página (Banner) */
454
467
  --ds-banner-py: 0.625rem;
455
468
  --ds-tabs-gap: 0.25rem; /* separación entre pestañas cuando el tema las separa */
456
- /* Piezas de estado y progreso (0.11.0): medidas y efectos propios, ajustables por tema y app */
469
+ /* Piezas de estado y progreso (0.12.0): medidas y efectos propios, ajustables por tema y app */
457
470
  --ds-track-bg: var(--muted); /* pista de barras, anillos y segmentos sin rellenar */
458
471
  --ds-status-dot-sm: var(--ds-status-dot); /* StatusDot suelto: size="sm" (sin size, el punto en línea) */
459
472
  --ds-status-dot-md: 0.75rem; /* size="md" */