orbital-ds 0.12.0 → 0.13.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 (55) hide show
  1. package/AGENTS.md +33 -5
  2. package/README.md +93 -93
  3. package/components.manifest.json +1906 -1854
  4. package/contract.json +1 -1
  5. package/dist/motion.css +139 -0
  6. package/dist/styles.css +17 -2
  7. package/dist/themes/fractalia.css +473 -464
  8. package/dist/themes/fractalia.fonts.css +3 -3
  9. package/dist/themes/fractalia.guide.md +79 -77
  10. package/dist/themes/fractalia.meta.json +99 -96
  11. package/dist/themes/fractalia.scoped.css +473 -464
  12. package/dist/themes/friendly.css +16 -13
  13. package/dist/themes/friendly.meta.json +7 -0
  14. package/dist/themes/friendly.scoped.css +16 -13
  15. package/dist/themes/qratia.css +13 -8
  16. package/dist/themes/qratia.meta.json +8 -1
  17. package/dist/themes/qratia.scoped.css +13 -8
  18. package/dist/themes/tactile.css +17 -6
  19. package/dist/themes/tactile.meta.json +7 -0
  20. package/dist/themes/tactile.scoped.css +17 -6
  21. package/dist/themes/twitter.css +13 -12
  22. package/dist/themes/twitter.meta.json +7 -0
  23. package/dist/themes/twitter.scoped.css +13 -12
  24. package/dist/themes/zyro.css +15 -26
  25. package/dist/themes/zyro.meta.json +7 -0
  26. package/dist/themes/zyro.scoped.css +15 -26
  27. package/dist/ui/alert.js +6 -5
  28. package/dist/ui/badge.js +6 -6
  29. package/dist/ui/banner.js +4 -4
  30. package/dist/ui/button.js +4 -4
  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/item.d.ts +2 -2
  35. package/dist/ui/item.js +14 -4
  36. package/dist/ui/menubar.js +4 -4
  37. package/dist/ui/native-select.js +2 -2
  38. package/dist/ui/select.js +7 -8
  39. package/dist/ui/stat.d.ts +11 -1
  40. package/dist/ui/stat.js +13 -3
  41. package/dist/ui/status-badge.js +6 -6
  42. package/docs/adr/0002-sistemas-corporativos-al-modelo.md +176 -176
  43. package/docs/designer/flujo.md +79 -0
  44. package/docs/designer/patrones.md +116 -0
  45. package/docs/designer/revision.md +60 -0
  46. package/docs/designer/ux.md +71 -0
  47. package/package.json +9 -2
  48. package/scripts/brand-core.mjs +51 -13
  49. package/scripts/cli.mjs +370 -0
  50. package/scripts/doctor.mjs +76 -7
  51. package/scripts/init.mjs +187 -125
  52. package/scripts/manifest.mjs +85 -79
  53. package/scripts/setup.mjs +2 -1
  54. package/scripts/skill.mjs +67 -0
  55. 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
@@ -158,7 +184,7 @@ Se adapta el sistema al modelo, nunca al revés (decisión y plan: `docs/adr/000
158
184
 
159
185
  1. **Valores a los huecos.** Cada valor de su DS va a la variable pública que ya lo cubre (`--ds-radius-button`,
160
186
  `--ds-field-bg`, `--ds-switch-track-off`, `--ds-*-weight`…). La personalidad solo para lo que ningún hueco
161
- cubre. El doctor avisa si una regla pinta una propiedad que tiene hueco (`slotTokens` del contrato).
187
+ cubre. El doctor rechaza (aviso si el tema no es estricto) una regla que pinta una propiedad que tiene hueco (`slotTokens` del contrato).
162
188
  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
163
189
  desactivado con color: `--ds-button-disabled-bg/-fg/-border`, opcionales con respaldo por variante).
164
190
  3. **Pesos cargados = pesos usados**: el doctor avisa si una `--ds-*-weight` pide un peso que `<tema>.fonts.css`
@@ -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