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
@@ -0,0 +1,79 @@
1
+ # Diseñador orbital-ds · 1. Flujo de trabajo
2
+
3
+ Cómo trabaja el diseñador (persona o agente) en una app con orbital-ds. Lo primero siempre es
4
+ **entender a la persona y su recorrido**; después, **elegir patrones**; al final, **componer y revisar**.
5
+ Nunca al revés.
6
+
7
+ ## 0. Contexto real, antes de nada
8
+
9
+ ```bash
10
+ pnpm exec orbital-ds context # (o npx orbital-ds context) versión, tema activo, marca, componentes, patrones
11
+ ```
12
+
13
+ Lee también, según la tarea: la ficha y la guía del tema (`node_modules/orbital-ds/dist/themes/<tema>.meta.json`
14
+ y `.guide.md`), `node_modules/orbital-ds/AGENTS.md` y las notas de cada componente en
15
+ `node_modules/orbital-ds/components.manifest.json` (`notes`). No supongas: lo que diga `context` manda.
16
+
17
+ ## 1. Modo de la petición
18
+
19
+ | Modo | Cuándo | Qué hace | Qué NO hace |
20
+ |---|---|---|---|
21
+ | **Dar forma** | «quiero una pantalla / un flujo para…» | mapa del flujo (§2) y propuesta de patrones, antes del código | no escribe código hasta acordar el flujo si hay dudas de fondo |
22
+ | **Construir** | «créame / añade…» | mapa breve → patrones → componentes → verificación | no inventa estilos ni componentes visuales |
23
+ | **Revisar** | «revisa / audita…» | lista de hallazgos con la regla incumplida y el arreglo (`fichero:línea`) | no edita salvo que se pida |
24
+ | **Robustecer** | «déjalo listo para producción» | estados vacíos, carga, error, textos largos, idiomas, RTL, teclado, móvil | no cambia el diseño aprobado |
25
+
26
+ ## 2. Entender el flujo mental de la persona (obligatorio)
27
+
28
+ Antes de elegir componentes, escribe (en la respuesta o en el PR) un **mapa del flujo** corto:
29
+
30
+ 1. **Quién** y en qué contexto (rol, frecuencia de uso, dispositivo, prisa, nivel de experiencia).
31
+ 2. **Qué intenta conseguir** (su objetivo, en sus palabras: «dar de alta a un cliente», no «crear entidad»).
32
+ 3. **Por dónde entra** (menú, enlace, aviso, búsqueda ⌘K) y **qué espera encontrar** al llegar (modelo mental:
33
+ lo que ya conoce de otras apps y de esta; ley de Jakob).
34
+ 4. **Pasos lógicos** en el orden en que la persona piensa (no en el orden del modelo de datos). En cada paso:
35
+ qué necesita **ver** para decidir, qué **decide**, qué **datos** aporta.
36
+ 5. **Momentos de duda o riesgo**: dónde se puede perder, equivocar o abandonar; qué es irreversible.
37
+ 6. **Éxito y salida**: cómo sabe que ha terminado y adónde va después.
38
+ 7. **Estados**: vacío (primera vez), cargando, parcial, error (y cómo se recupera), sin permiso, sin conexión.
39
+
40
+ Luego **reduce**: quita pasos que no aportan, agrupa decisiones relacionadas, pospón lo opcional (revelación
41
+ progresiva) y deja una sola acción principal por pantalla.
42
+
43
+ ## 3. Del flujo a los patrones
44
+
45
+ Cada paso del mapa se resuelve con un **patrón** de `patrones.md` (página, lista de entidades, detalle,
46
+ formulario, asistente por pasos, panel de datos, tabla, confirmación destructiva, búsqueda, avisos, estados
47
+ vacíos…). Si un paso no encaja en ningún patrón, **no inventes**: combina patrones existentes o reporta el
48
+ hueco (ver §6).
49
+
50
+ ## 4. Componer
51
+
52
+ - Solo componentes de `orbital-ds/ui/*` (consulta el manifiesto; usa sus `notes`). Nada de HTML con estilos
53
+ propios para algo que ya existe (botón, campo, tarjeta, insignia, tabla, diálogo…).
54
+ - Solo variables y utilidades del sistema: ni colores, ni medidas, ni sombras, ni duraciones, ni z-index a mano.
55
+ Ni `!important`, ni selectores propios contra la librería.
56
+ - La marca es de `brand.css`; la personalidad, del tema. El diseñador **no elige** fuentes, colores ni radios:
57
+ los pone el tema. Si la app necesita otro aspecto, se ajusta en `brand.css` (o se elige otro tema).
58
+ - Textos de la app con su i18n; los de orbital-ds ya vienen en en/es/pt-BR.
59
+ - Movimiento: el del tema (`orbital-ds/motion.css` si está activo; Motion con `useDsMotion()` para lo demás).
60
+
61
+ ## 5. Verificar (antes de dar nada por bueno)
62
+
63
+ 1. `pnpm exec orbital-ds doctor --css src/brand.css --ui src` (comprobación mecánica de las vistas) y el verify de la app.
64
+ 2. Recorre **cada estado** del mapa (§2.7) y cada paso con **teclado** (Tab, Enter, Esc, flechas).
65
+ 3. Ancho de **móvil** (≈ 360–400 px) y ancho grande; **claro y oscuro**; **textos largos** y otro idioma.
66
+ 4. Pasa la lista de `revision.md` y responde los hallazgos.
67
+
68
+ ## 6. Orden de autoridad y huecos
69
+
70
+ Si algo choca, gana por este orden:
71
+ 1. Lo que pide la persona usuaria explícitamente (salvo que rompa accesibilidad o el contrato: entonces avisa).
72
+ 2. El contrato de orbital-ds: `AGENTS.md`, `contract.json`, el manifiesto y sus `notes`.
73
+ 3. La ficha y la guía del tema activo, y el `brand.css` de la app.
74
+ 4. Los patrones (`patrones.md`).
75
+ 5. Las heurísticas generales de UX (`ux.md`).
76
+
77
+ **Nunca te sales del sistema.** Si lo que hace falta no se puede hacer con componentes y variables existentes:
78
+ dilo, propone la combinación más cercana y deja anotado el hueco para la librería (issue en orbital-ds con el
79
+ caso, el patrón afectado y la variable o variante que faltaría). No lo resuelvas con estilos a mano.
@@ -0,0 +1,116 @@
1
+ # Diseñador orbital-ds · 2. Patrones
2
+
3
+ Cada paso del flujo de la persona se resuelve con UNO de estos patrones (o una combinación). Todos usan solo
4
+ componentes de `orbital-ds/ui/*` y variables; el aspecto lo pone el tema. Si un caso no encaja, combina
5
+ patrones o reporta el hueco: **no inventes estilos**.
6
+
7
+ Formato: **cuándo** · **piezas** · **reglas** · **evita**.
8
+
9
+ ---
10
+
11
+ ## P1 · Página (marco de cualquier vista)
12
+ - **Cuándo:** toda vista de la app.
13
+ - **Piezas:** `SidebarProvider` + `Sidebar` (navegación) + `SidebarInset`; cabecera con `SidebarTrigger`, título,
14
+ selector de idioma y de tema (y avisos con `NotificationCenter`; opcional, buscador ⌘K con `CommandDialog`).
15
+ Contenido: `PageHeader` (`PageHeaderTitle`, `PageHeaderDescription`, `PageHeaderActions`) centrado en
16
+ `--ds-page-max-w`; secciones con `SectionHeader`.
17
+ - **Reglas:** una sola acción principal (botón `default`) por vista, en `PageHeaderActions`; las secundarias,
18
+ `outline`/`ghost` o en un menú. Breadcrumb solo si hay jerarquía de más de dos niveles. Solo un lienzo
19
+ (mapa, kanban, editor) ocupa todo el ancho.
20
+ - **Evita:** acciones de la vista en la cabecera global; dos botones primarios; títulos que repiten el menú.
21
+
22
+ ## P2 · Lista de entidades
23
+ - **Cuándo:** agentes, clientes, dispositivos, proyectos… (pocas columnas, se escanea por nombre).
24
+ - **Piezas:** `ItemGroup` + `Item variant="card"` (`ItemMedia`/`IconTile`, `ItemContent` con `ItemTitle` y
25
+ `ItemDescription`, `ItemActions` con `StatusBadge` y menú `DropdownMenu`). Filtros con `FilterBar`. Vacío con `Empty`.
26
+ - **Reglas:** la fila entera navega al detalle. Sin acciones en la fila: `Item render={<a href=… />}`. **Con acciones**
27
+ (menú «⋯», botón): un botón dentro de un enlace no es HTML válido, así que el `Item` queda como `div` y el ENLACE va
28
+ en el título, estirado a toda la fila (`<ItemTitle><a href=… className="after:absolute after:inset-0">…</a></ItemTitle>`,
29
+ con `relative` en el `Item`), y `ItemActions` lleva `relative z-(--ds-z-raised)` para quedar encima. `ItemGroup` ya es
30
+ una lista accesible: envuelve cada `Item` en su `role="listitem"` (no lo hagas a mano). Estado siempre con texto
31
+ (`StatusBadge`), nunca solo color.
32
+ - **Evita:** `Card` + `Item` compuestos a mano; tarjetas dentro de tarjetas; más de 3 acciones visibles por fila.
33
+ - **Si hay muchas columnas o hay que comparar/ordenar:** P4.
34
+
35
+ ## P3 · Detalle de una entidad
36
+ - **Piezas:** `PageHeader` (nombre, estado, acciones) + `Tabs` para secciones si hay más de 3 bloques; datos
37
+ con `Panel`/`Card` y pares etiqueta-valor; historial con `Timeline`; KPIs con `Stat`.
38
+ - **Reglas:** lo que la persona vino a ver, arriba; la edición, en el sitio (P5) o en `Sheet` lateral si es corta.
39
+ - **Detalle en panel lateral** (`Sheet`, sin salir de la lista): la entidad abierta va en la URL (`?id=…`) para que se
40
+ pueda compartir, recargar y cerrar con Atrás; conserva el último dato mientras el panel se cierra (que la animación
41
+ de salida no quede vacía). En móvil, el `Sheet` ocupa la pantalla.
42
+
43
+ ## P4 · Tabla de datos
44
+ - **Cuándo:** muchas filas, comparar, ordenar, filtrar, paginar.
45
+ - **Piezas:** `DataTable` (TanStack Table; estado en la URL con `dataTableStateToSearch`), `FilterBar`,
46
+ `DataTableNumber` para cifras, `Pagination`, `Empty` sin resultados (con «Limpiar filtros»).
47
+ - **Reglas:** números alineados a la derecha y con `tabular-nums`; la acción por fila en un menú; selección
48
+ múltiple solo si hay acciones en lote. Más de 50 filas visibles: paginar o virtualizar.
49
+ - **Evita:** tablas para 3–5 elementos (usa P2); colores para el estado sin texto.
50
+
51
+ ## P5 · Formulario
52
+ - **Piezas:** `FieldGroup` + `Field` (`FieldLabel`, control, `FieldDescription`, `FieldError`); controles: `Input`,
53
+ `Textarea`, `Select` (con `items`), `Combobox` (búsqueda en listas largas), `RadioGroup` (2–5 opciones visibles),
54
+ `Checkbox`, `Switch` (efecto inmediato), `DatePicker`/`DateRangePicker`, `Dropzone`, `InputOTP`.
55
+ - **Reglas:** una columna; etiquetas siempre visibles (el placeholder no es etiqueta); agrupa con `FieldSet` y
56
+ `FieldLegend`; lo opcional, marcado o plegado; validación al salir del campo y al enviar, con el error junto
57
+ al campo y foco en el primero; el botón de enviar dice qué hace («Crear cliente», no «Enviar») y queda activo
58
+ hasta que empieza el envío (luego `Spinner`); nunca bloquear pegar; `autocomplete` y `type` correctos.
59
+ - **Elección de control:** 2–5 opciones → `RadioGroup`; 6–15 → `Select`; más o con búsqueda → `Combobox`;
60
+ sí/no con efecto inmediato → `Switch`; sí/no que se envía con el formulario → `Checkbox`.
61
+
62
+ ## P6 · Asistente por pasos
63
+ - **Cuándo:** un proceso largo con pasos con sentido propio (alta, importación, configuración inicial).
64
+ - **Piezas:** `Stepper` (o `StepDots` si son 3–5 pasos cortos), un formulario P5 por paso, `TaskProgress` para lo
65
+ que tarda, resumen final con `Panel`.
66
+ - **Reglas:** 3–7 pasos; cada paso con un objetivo y un título; «Atrás» nunca pierde datos; el último paso
67
+ muestra un **resumen** antes de confirmar; se puede salir y retomar (guarda el borrador).
68
+
69
+ ## P7 · Panel de datos (dashboard)
70
+ - **Piezas:** fila de `Stat` (3–5 KPIs con `StatDelta` y `Sparkline`; si filtran lo de debajo, `render={<button type="button" />}` y
71
+ `pressed`), gráficos con `EChart` y los presets de
72
+ `orbital-ds/lib/echarts-presets`, `Legend`, `ProportionBar`, `HeatmapGrid`, `Gauge`/`LevelMeter` para un valor
73
+ frente a un objetivo, `DateRangePicker` para el periodo.
74
+ - **Reglas:** de lo general a lo particular (KPIs → tendencias → detalle); cada número dice de qué periodo es;
75
+ sin dato ≠ 0 (`unknown`/`null`); los colores de las series los da el tema (nunca en el `option`).
76
+
77
+ ## P8 · Acción destructiva
78
+ - **Piezas:** `AlertDialog` (título «¿Eliminar el cliente Acme?», descripción de la consecuencia,
79
+ `AlertDialogAction` con `variant="destructive"` y el verbo concreto: «Eliminar cliente»).
80
+ - **Reglas:** confirmación o «deshacer» (`toast` con acción) — nunca ejecutar sin una de las dos; para lo muy
81
+ grave, escribir el nombre para confirmar. El foco empieza en «Cancelar».
82
+
83
+ ## P9 · Estados de una vista
84
+ - **Vacío (primera vez):** `Empty` con qué es esto, por qué está vacío y la acción para empezar.
85
+ - **Sin resultados:** `Empty` con la búsqueda/filtros aplicados y «Limpiar filtros».
86
+ - **Cargando:** `Skeleton` con la forma del contenido (no un spinner a pantalla completa); `Spinner` en botones.
87
+ - **Error:** `Alert` (o `Banner` si afecta a toda la página) que dice qué pasó y qué hacer, con «Reintentar».
88
+ - **Tarea larga:** `TaskProgress` o `TaskLoader`; para estados de protección/seguridad, `Shield`/`StatusHero`.
89
+
90
+ ## P10 · Avisos y respuesta del sistema
91
+ - **Piezas:** `toast` (sonner) para confirmar algo hecho («Cliente creado») con «Deshacer» si aplica; `Alert` en
92
+ el contexto del problema; `Banner` para algo de toda la página (mantenimiento, prueba gratuita);
93
+ `NotificationCenter` para lo que llega sin que la persona lo pida.
94
+ - **Reglas:** el aviso dice qué pasó en voz activa; los errores dicen cómo arreglarlo; nada de avisos para lo
95
+ que ya se ve en pantalla.
96
+
97
+ ## P11 · Búsqueda y navegación rápida
98
+ - **Piezas:** `CommandDialog` (⌘K) con grupos (`CommandGroup`), atajos (`CommandShortcut`, `Kbd`) y vacío
99
+ (`CommandEmpty`). En la cabecera, un `InputGroup` compacto que lo abre (en móvil, solo el icono).
100
+
101
+ ## P12 · Ajustes
102
+ - **Piezas:** `Tabs` o navegación lateral por secciones; cada sección un `FieldGroup`; `Switch` para lo que se
103
+ aplica al momento y botón «Guardar cambios» para lo que no (nunca mezclados en la misma sección).
104
+
105
+ ---
106
+
107
+ ## Patrones de movimiento
108
+ - Entradas y superficies pulsables: `orbital-ds/motion.css` (cada tema las suyas; interruptores
109
+ `--ds-enter-*`). Coreografías a medida: Motion con `useDsMotion()` (`fadeUp`, `scaleIn`, `list`, `press`).
110
+ - El movimiento explica (de dónde viene algo, qué ha cambiado); no decora. Siempre interrumpible y quieto con
111
+ movimiento reducido. Nunca duraciones ni curvas a mano.
112
+
113
+ ## En un artifact o prototipo HTML (sin React)
114
+ Mismos patrones y mismos valores: toma las variables del tema de `node_modules/orbital-ds/dist/themes/<tema>.css`
115
+ (y de la estructura `dist/styles.css`), reproduce el DOM con los mismos `data-slot` y no añadas colores, radios ni
116
+ fuentes que el tema no tenga.
@@ -0,0 +1,60 @@
1
+ # Diseñador orbital-ds · 4. Revisión
2
+
3
+ Lista para revisar una pantalla o un flujo. Cada punto es **observable** (se puede comprobar mirando el código o
4
+ la pantalla). Un hallazgo se reporta así: `fichero:línea · regla · qué pasa · arreglo`.
5
+
6
+ ## A. Fidelidad al sistema (bloqueante)
7
+ - [ ] Solo componentes de `orbital-ds/ui/*` para lo que ya existe (botón, campo, tarjeta, insignia, tabla, diálogo,
8
+ menú, aviso…). Nada de `<button className="bg-…">` ni de componentes visuales propios que los dupliquen.
9
+ - [ ] Ningún color, medida, sombra, radio, peso, duración, curva ni z-index escrito a mano (ni en valores
10
+ arbitrarios de Tailwind: `bg-[#…]`, `rounded-[10px]`, `duration-[250ms]`, `text-[13px]`).
11
+ - [ ] Ninguna clase de paleta de Tailwind (`bg-blue-500`, `text-gray-600`): solo tokens (`bg-primary`,
12
+ `text-muted-foreground`, `bg-(--ds-…)`).
13
+ - [ ] Sin `!important` ni selectores propios contra la librería; ajustes de aspecto solo en `brand.css`.
14
+ - [ ] Fuentes, colores y radios: los del tema. El diseñador no los cambia.
15
+ - [ ] Cada componente usado según sus `notes` del manifiesto (p. ej. `Select` con `items`).
16
+ - [ ] `pnpm exec orbital-ds doctor --css src/brand.css --ui src` sin errores (comprueba lo mecánico de esta lista).
17
+
18
+ ## B. Flujo y comprensión
19
+ - [ ] Hay mapa del flujo (quién, objetivo, pasos, estados) y la pantalla responde a un paso concreto.
20
+ - [ ] Una sola acción principal por vista, con verbo + objeto.
21
+ - [ ] La persona sabe dónde está, qué puede hacer y qué pasará al pulsar (título, estado activo, textos claros).
22
+ - [ ] Lo irreversible pide confirmación o permite deshacer (P8).
23
+ - [ ] Al acabar, confirmación del éxito y siguiente paso lógico.
24
+ - [ ] Nada obliga a recordar datos de un paso a otro.
25
+
26
+ ## C. Estados (P9)
27
+ - [ ] Vacío (primera vez) con explicación y acción para empezar.
28
+ - [ ] Sin resultados con «Limpiar filtros».
29
+ - [ ] Cargando con `Skeleton` con la forma del contenido; botones con `Spinner` mientras envían.
30
+ - [ ] Error con qué pasó y qué hacer (+ «Reintentar»); el formulario conserva lo escrito.
31
+ - [ ] Textos muy largos, cifras grandes y listas largas no rompen el diseño.
32
+
33
+ ## D. Accesibilidad e interacción
34
+ - [ ] Todo con teclado (Tab, Enter, Esc, flechas); foco visible y no tapado.
35
+ - [ ] Etiquetas en todos los campos; errores junto al campo y anunciados; foco al primer error al enviar.
36
+ - [ ] `<a>` para navegar, `<button>` para acciones; iconos solos con nombre accesible.
37
+ - [ ] Estado nunca solo con color.
38
+ - [ ] Contraste del tema intacto (sin colores propios encima de superficies del tema).
39
+
40
+ ## E. Idioma, formato y responsivo
41
+ - [ ] Textos de la app por i18n (ni uno escrito a mano en la vista); los de orbital-ds, del espacio «orbital».
42
+ - [ ] Fechas y números con `Intl` en el idioma activo; nada de formatos fijos.
43
+ - [ ] Clases lógicas (`ms-`/`ps-`/`start-`/`text-start`) para que funcione en RTL.
44
+ - [ ] Móvil (≈ 360 px): una columna, sin desplazamiento horizontal, objetivos táctiles cómodos.
45
+ - [ ] Claro y oscuro revisados.
46
+
47
+ ## F. Movimiento
48
+ - [ ] Solo el del tema (`motion.css` y sus interruptores, o `useDsMotion()`); nada de duraciones o curvas propias.
49
+ - [ ] El movimiento explica algo (origen, cambio de estado), no decora; quieto con movimiento reducido.
50
+
51
+ ## Anti-patrones (rechazar)
52
+ - Tarjetas dentro de tarjetas; todo metido en tarjetas.
53
+ - Texto gris sobre fondos de color; texto sobre imágenes sin garantía de contraste.
54
+ - Iconos en cuadradito encima de cada título «porque queda bien».
55
+ - Degradados, sombras o brillos que el tema no trae.
56
+ - Botones genéricos («Aceptar», «Continuar», «Enviar») y mensajes de error que culpan o no dicen cómo arreglarlo.
57
+ - Spinners a pantalla completa para cargas parciales; modales para lo que cabe en la página.
58
+ - Placeholders como etiqueta; validar mientras se escribe la primera vez.
59
+ - Más de una acción principal; acciones importantes escondidas en menús.
60
+ - Formatos de fecha/número escritos a mano; textos de interfaz fuera del i18n.
@@ -0,0 +1,71 @@
1
+ # Diseñador orbital-ds · 3. Estándares de UX/UI
2
+
3
+ Principios para decidir el flujo y cada pantalla. Son la base de la revisión (`revision.md`). Cuando un
4
+ principio choca con el sistema (tema, contrato, patrones), gana el sistema; el principio sirve para elegir
5
+ **dentro** de él.
6
+
7
+ ## Heurísticas de usabilidad (Nielsen), aplicadas
8
+ 1. **Visibilidad del estado:** toda acción tiene respuesta en < 100 ms (estado de pulsado, `Spinner`,
9
+ `Skeleton`, `TaskProgress`); la persona sabe dónde está (título, menú activo, `Stepper`).
10
+ 2. **Lenguaje de la persona:** palabras de su trabajo, no del sistema («Clientes», no «Entidades»; «Enviar
11
+ factura», no «Ejecutar acción»).
12
+ 3. **Control y libertad:** «Atrás», «Cancelar», «Deshacer»; los diálogos se cierran con Esc; nada atrapa.
13
+ 4. **Consistencia:** el mismo patrón para el mismo problema en toda la app; verbos iguales para acciones iguales.
14
+ 5. **Prevenir errores:** el control adecuado (P5), valores por defecto sensatos, límites visibles, confirmación
15
+ en lo irreversible (P8).
16
+ 6. **Reconocer mejor que recordar:** opciones a la vista, datos previos visibles en el siguiente paso,
17
+ búsqueda con sugerencias.
18
+ 7. **Flexibilidad:** atajos de teclado (⌘K) y acciones en lote para quien usa mucho la app, sin estorbar a quien empieza.
19
+ 8. **Minimalismo:** cada elemento justifica su sitio; lo secundario, plegado o en un menú.
20
+ 9. **Ayuda a recuperarse:** el error dice qué pasó, por qué y cómo arreglarlo, junto a donde ocurrió.
21
+ 10. **Ayuda y documentación:** `FieldDescription`, `Tooltip` en iconos, `Empty` que explica; ayuda en contexto.
22
+
23
+ ## Carga cognitiva y leyes de interacción
24
+ - **Ley de Hick:** más opciones = más tiempo para decidir. Reduce, agrupa y destaca la recomendada.
25
+ - **Revelación progresiva:** primero lo esencial; lo avanzado, en «Opciones avanzadas» (`Collapsible`/`Accordion`).
26
+ - **Ley de Fitts:** los objetivos importantes, grandes y cerca de donde está la atención; mínimo 24×24 px
27
+ (WCAG 2.5.8), en táctil cómodo 44×44 (`--ds-touch-target`).
28
+ - **Ley de Jakob:** la gente usa otras apps la mayor parte del tiempo; respeta convenciones (logo a la
29
+ izquierda en LTR, búsqueda arriba, «⋯» para más acciones, X para cerrar).
30
+ - **Memoria de trabajo (≈ 4 ± 1 elementos):** no obligues a recordar datos de un paso a otro; muéstralos.
31
+ - **Proximidad y jerarquía:** lo relacionado, junto; un solo foco de atención por pantalla (la acción principal).
32
+
33
+ ## Flujo
34
+ - Ordena los pasos como piensa la persona; pide los datos cuando tiene sentido pedirlos (no todo al principio).
35
+ - Una pantalla = un objetivo. Si hay dos objetivos, son dos pasos o dos vistas.
36
+ - El camino feliz, corto; los casos raros, posibles (pero no en medio del camino feliz).
37
+ - Al acabar: confirma el éxito y ofrece el siguiente paso lógico («Cliente creado · Ver cliente · Crear otro»).
38
+
39
+ ## Formularios
40
+ Ver P5. Además: el tipo de teclado correcto en móvil (`inputMode`), `autocomplete`, ejemplos en el placeholder
41
+ terminados en «…», sin validar mientras se escribe la primera vez, mensajes de error que no culpan.
42
+
43
+ ## Contenido y textos
44
+ - Voz activa y segunda persona («Guarda los cambios», «Has creado…»).
45
+ - Botones con verbo + objeto («Crear cliente»); nada de «Aceptar», «Enviar», «Continuar» genéricos.
46
+ - Puntos suspensivos tipográficos «…»; los estados de carga terminan en «…» («Guardando…»).
47
+ - Cifras con `Intl.NumberFormat` y fechas con `Intl.DateTimeFormat` en el idioma activo; unidades con espacio
48
+ duro (`10 MB`).
49
+ - Prevé textos cortos, normales y muy largos (truncado con `title` o salto de línea; nunca desbordar).
50
+
51
+ ## Accesibilidad (WCAG 2.2 AA, mínimo)
52
+ - Contraste 4,5:1 en texto, 3:1 en controles, foco y gráficos (el tema ya cumple; no lo rompas con colores propios).
53
+ - Todo se usa con teclado; foco siempre visible y no tapado por cabeceras fijas; orden de tabulación lógico.
54
+ - HTML semántico antes que ARIA: `<button>` para acciones, `<a>` para navegar, encabezados en orden.
55
+ - Botones de solo icono con `aria-label` (los de orbital-ds ya lo traen); iconos decorativos `aria-hidden`.
56
+ - Cambios asíncronos (avisos, validación) anunciados (`aria-live`, ya en `toast` y `FieldError`).
57
+ - El color nunca es el único portador del significado: texto o icono además del color.
58
+ - Movimiento reducido respetado (el sistema ya lo hace; no añadas animaciones fuera de él).
59
+
60
+ ## Interacción (de las Web Interface Guidelines de Vercel, en lo que aplica)
61
+ - Estados `hover`, `active` y `focus-visible` más marcados que el reposo (los da el tema).
62
+ - Enlaces que funcionan con Ctrl/Cmd+clic y clic central (usa `<a>`/`Link`, nunca `div` con `onClick`).
63
+ - Avisa antes de salir con cambios sin guardar.
64
+ - Arrastrar, deslizar o pellizcar siempre tienen alternativa con clic y teclado.
65
+ - Animaciones interrumpibles; solo `transform` y `opacity` cuando se anima a mano.
66
+ - Listas de más de 50 elementos: paginar o virtualizar.
67
+
68
+ ## Responsivo
69
+ - Primero móvil: una columna, acciones al alcance, nada de tablas anchas sin desplazamiento propio.
70
+ - Sin desplazamiento horizontal de la página; los hijos flex que llevan texto con `min-w-0`.
71
+ - `Sheet`/`Drawer` en móvil para lo que en escritorio es un panel lateral o un popover grande.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "orbital-ds",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "description": "Sistema de diseño genérico: estructura común + temas con personalidad (qratia, zyro) + ~60 componentes sobre Base UI y Tailwind v4, con contrato verificable y legible por agentes.",
5
5
  "keywords": [
6
6
  "design-system",
@@ -27,6 +27,9 @@
27
27
  "README.md",
28
28
  "LICENSE",
29
29
  "scripts/init.mjs",
30
+ "scripts/cli.mjs",
31
+ "scripts/skill.mjs",
32
+ "skill",
30
33
  "scripts/manifest.mjs",
31
34
  "scripts/brand-core.mjs",
32
35
  "scripts/setup.mjs",
@@ -34,6 +37,7 @@
34
37
  ],
35
38
  "exports": {
36
39
  "./styles.css": "./dist/styles.css",
40
+ "./motion.css": "./dist/motion.css",
37
41
  "./themes/*.css": "./dist/themes/*.css",
38
42
  "./themes/*.md": "./dist/themes/*.md",
39
43
  "./themes/*.meta.json": "./dist/themes/*.meta.json",
@@ -58,10 +62,12 @@
58
62
  "build": "tsup && node scripts/build-css.mjs",
59
63
  "dev": "tsup --watch --onSuccess \"node scripts/copy-css.mjs\"",
60
64
  "typecheck": "tsc --noEmit",
61
- "verify": "pnpm check:ds && pnpm typecheck && pnpm showcase:typecheck && pnpm build && pnpm check:bundle",
65
+ "verify": "pnpm check:ds && pnpm typecheck && pnpm showcase:typecheck && pnpm build && pnpm check:bundle && pnpm check:pack",
62
66
  "manifest": "node scripts/manifest.mjs",
63
67
  "check:ds": "node scripts/doctor.mjs",
64
68
  "check:bundle": "node scripts/check-bundle.mjs",
69
+ "check:pack": "node scripts/check-pack.mjs",
70
+ "prepublishOnly": "pnpm verify",
65
71
  "showcase": "vite --config showcase/vite.config.ts",
66
72
  "showcase:build": "vite build --config showcase/vite.config.ts",
67
73
  "showcase:typecheck": "tsc --noEmit -p showcase"
@@ -163,6 +169,7 @@
163
169
  "vite": "^8.3.4"
164
170
  },
165
171
  "bin": {
172
+ "orbital-ds": "./scripts/cli.mjs",
166
173
  "orbital-ds-doctor": "./scripts/doctor.mjs",
167
174
  "orbital-ds-init": "./scripts/init.mjs",
168
175
  "orbital-ds-i18n": "./scripts/i18n.mjs"
@@ -81,13 +81,39 @@ function ajustar(color, dir, bien) {
81
81
  return null;
82
82
  }
83
83
 
84
+ /**
85
+ * Series de gráfico (5) en armonía con la marca: 1 = primario, 2 = secundario (o un tono
86
+ * complementario suave), 3–5 = tonos intermedios repartidos por el círculo, separados al menos
87
+ * 40° entre sí. Cada una se ajusta hasta 3:1 sobre el lienzo (WCAG 1.4.11: elementos gráficos)
88
+ * y se distinguen por luminosidad además de por tono (alterna claro/oscuro).
89
+ */
90
+ export function derivarSeries(primario, secundario, lienzo, { oscura = false } = {}) {
91
+ const P = rgbToOklch(primario);
92
+ const H = P.c < 0.02 ? 255 : P.h;
93
+ const S = secundario ? rgbToOklch(secundario) : null;
94
+ const tonos = [H, S && S.c >= 0.02 ? S.h : (H + 150) % 360];
95
+ for (const d of [60, 210, 290, 100, 330, 30]) {
96
+ if (tonos.length === 5) break;
97
+ const h = (H + d) % 360;
98
+ if (tonos.every((t) => Math.min(Math.abs(t - h), 360 - Math.abs(t - h)) >= 40)) tonos.push(h);
99
+ }
100
+ const croma = Math.max(0.11, Math.min(P.c, 0.18));
101
+ const dir = oscura ? +1 : -1;
102
+ return tonos.map((h, i) => {
103
+ let c = i === 0 ? primario : i === 1 && secundario ? secundario : ok(oscura ? (i % 2 ? 0.74 : 0.66) : i % 2 ? 0.52 : 0.62, croma, h);
104
+ if (oscura && i === 0) c = oklchToRgb({ ...P, l: Math.max(P.l, 0.7), c: Math.min(P.c, 0.2) });
105
+ return ratio(c, lienzo) >= 3 ? c : ajustar(c, dir, (x) => ratio(x, lienzo) >= 3) ?? c;
106
+ });
107
+ }
108
+
84
109
  /**
85
110
  * Deriva la marca. Devuelve { claro, oscuro, avisos } con los tokens (sin el prefijo --).
111
+ * `secundario` (opcional): serie 2 de los gráficos y, si el tema tiene gestos, el acento del gesto.
86
112
  * `acento` y `marcador` solo si el tema tiene gestos.
87
113
  * `base` ({ papel, tinta, fondoO, textoO }): neutros REALES del tema. Con ellos, el texto sobre el
88
114
  * primario, el enlace y el contraste se calculan contra la paleta del tema (modo «solo primario»).
89
115
  */
90
- export function derivar(primario, { acento, marcador = true, gestos = false, base = {} }) {
116
+ export function derivar(primario, { acento, secundario = null, marcador = true, gestos = false, base = {} }) {
91
117
  const avisos = [];
92
118
  const P = rgbToOklch(primario);
93
119
  const H = P.c < 0.02 ? 255 : P.h; // primario casi gris: neutros azulados por defecto
@@ -104,14 +130,16 @@ export function derivar(primario, { acento, marcador = true, gestos = false, bas
104
130
  }
105
131
  const primFg = textoSobre(prim);
106
132
  const enlace = ajustar(prim, -1, (c) => ratio(c, papel) >= 4.5 && ratio(c, blanco) >= 4.5) ?? prim;
133
+ // Foco: el primario si se ve (3:1 sobre papel y tarjeta); si no (p. ej. un amarillo), oscurecido hasta verse.
134
+ const foco = ratio(prim, papel) >= 3 && ratio(prim, blanco) >= 3 ? prim : ajustar(prim, -1, (c) => ratio(c, papel) >= 3 && ratio(c, blanco) >= 3) ?? enlace;
107
135
  const enlaceHover = ajustar(enlace, -1, (c) => rgbToOklch(c).l <= rgbToOklch(enlace).l - 0.07) ?? enlace;
108
136
  const brillo = oklchToRgb({ ...rgbToOklch(prim), l: Math.min(0.95, rgbToOklch(prim).l + 0.08) });
109
137
 
110
- const acentoC = acento ?? ok(0.82, 0.16, (H + 180) % 360);
138
+ const acentoC = acento ?? secundario ?? ok(0.82, 0.16, (H + 180) % 360);
111
139
  const claro = {
112
- primary: hex(prim), 'primary-foreground': hex(primFg), ring: hex(prim), link: hex(enlace), 'link-hover': hex(enlaceHover),
113
- brand: hex(prim), 'brand-bright': hex(brillo), 'sidebar-primary': hex(prim), 'sidebar-primary-foreground': hex(primFg), 'sidebar-ring': hex(prim),
114
- 'chart-1': hex(prim), 'accent-foreground': hex(tinta),
140
+ primary: hex(prim), 'primary-foreground': hex(primFg), ring: hex(foco), link: hex(enlace), 'link-hover': hex(enlaceHover),
141
+ brand: hex(prim), 'brand-bright': hex(brillo), 'sidebar-primary': hex(prim), 'sidebar-primary-foreground': hex(primFg), 'sidebar-ring': hex(foco),
142
+ 'accent-foreground': hex(tinta),
115
143
  background: hex(papel), foreground: hex(tinta), card: '#ffffff', 'card-foreground': hex(tinta), popover: '#ffffff', 'popover-foreground': hex(tinta),
116
144
  secondary: hex(suave), 'secondary-foreground': hex(tinta), muted: hex(suave), 'muted-foreground': rgba(tinta, 0.72),
117
145
  border: rgba(tinta, 0.14), input: hex(tinta),
@@ -129,11 +157,12 @@ export function derivar(primario, { acento, marcador = true, gestos = false, bas
129
157
  const primOFg = fondoO;
130
158
  if (ratio(primOFg, primO) < 4.5) primO = ajustar(primO, +1, (c) => ratio(primOFg, c) >= 4.5) ?? primO;
131
159
  const enlaceO = ajustar(primO, +1, (c) => ratio(c, fondoO) >= 4.5) ?? primO;
160
+ const focoO = ratio(primO, fondoO) >= 3 ? primO : ajustar(primO, +1, (c) => ratio(c, fondoO) >= 3) ?? enlaceO;
132
161
  const enlaceHoverO = oklchToRgb({ ...rgbToOklch(enlaceO), l: Math.min(0.95, rgbToOklch(enlaceO).l + 0.07) });
133
162
  const oscuro = {
134
- primary: hex(primO), 'primary-foreground': hex(primOFg), ring: hex(primO), link: hex(enlaceO), 'link-hover': hex(enlaceHoverO),
135
- brand: hex(primO), 'brand-bright': hex(enlaceO), 'sidebar-primary': hex(primO), 'sidebar-primary-foreground': hex(primOFg), 'sidebar-ring': hex(primO),
136
- 'chart-1': hex(primO), 'accent-foreground': hex(textoO),
163
+ primary: hex(primO), 'primary-foreground': hex(primOFg), ring: hex(focoO), link: hex(enlaceO), 'link-hover': hex(enlaceHoverO),
164
+ brand: hex(primO), 'brand-bright': hex(enlaceO), 'sidebar-primary': hex(primO), 'sidebar-primary-foreground': hex(primOFg), 'sidebar-ring': hex(focoO),
165
+ 'accent-foreground': hex(textoO),
137
166
  background: hex(fondoO), foreground: hex(textoO), card: hex(tarjetaO), 'card-foreground': hex(textoO), popover: hex(tarjetaO), 'popover-foreground': hex(textoO),
138
167
  secondary: hex(suaveO), 'secondary-foreground': hex(textoO), muted: hex(suaveO), 'muted-foreground': rgba(textoO, 0.72),
139
168
  border: rgba(textoO, 0.14), input: rgba(textoO, 0.92),
@@ -145,11 +174,20 @@ export function derivar(primario, { acento, marcador = true, gestos = false, bas
145
174
  oscuro['ds-marker'] = marcador ? rgba(acentoC, 0.45) : 'transparent';
146
175
  }
147
176
 
148
- /* ── comprobación ── */
177
+ /* ── series de gráfico: 5, en armonía, 3:1 sobre el lienzo de cada piel ── */
178
+ const seriesC = derivarSeries(prim, secundario, papel);
179
+ const seriesO = derivarSeries(primO, secundario ? oklchToRgb({ ...rgbToOklch(secundario), l: Math.max(rgbToOklch(secundario).l, 0.7) }) : null, fondoO, { oscura: true });
180
+ seriesC.forEach((c, i) => { claro[`chart-${i + 1}`] = hex(c); });
181
+ seriesO.forEach((c, i) => { oscuro[`chart-${i + 1}`] = hex(c); });
182
+
183
+ /* ── comprobación: texto 4.5:1 (AA); foco y series de gráfico 3:1 (WCAG 1.4.11) ── */
149
184
  const pares = [
150
- ['claro', 'texto/papel', tinta, papel], ['claro', 'texto/tarjeta', tinta, blanco], ['claro', 'texto sobre primario', primFg, prim],
151
- ['claro', 'enlace/papel', enlace, papel], ['oscuro', 'texto/fondo', textoO, fondoO], ['oscuro', 'texto sobre primario', primOFg, primO], ['oscuro', 'enlace/fondo', enlaceO, fondoO],
152
- ].map(([piel, nombre, f, b]) => ({ piel, nombre, r: ratio(f, b) }));
153
- return { claro, oscuro, avisos, pares, muestras: { papel, tinta, prim, suave, acentoC, fondoO, textoO, primO } };
185
+ ['claro', 'texto/papel', tinta, papel, 4.5], ['claro', 'texto/tarjeta', tinta, blanco, 4.5], ['claro', 'texto sobre primario', primFg, prim, 4.5],
186
+ ['claro', 'enlace/papel', enlace, papel, 4.5], ['claro', 'foco/papel', foco, papel, 3],
187
+ ['oscuro', 'texto/fondo', textoO, fondoO, 4.5], ['oscuro', 'texto sobre primario', primOFg, primO, 4.5], ['oscuro', 'enlace/fondo', enlaceO, fondoO, 4.5], ['oscuro', 'foco/fondo', focoO, fondoO, 3],
188
+ ...seriesC.map((c, i) => ['claro', `serie ${i + 1}/papel`, c, papel, 3]),
189
+ ...seriesO.map((c, i) => ['oscuro', `serie ${i + 1}/fondo`, c, fondoO, 3]),
190
+ ].map(([piel, nombre, f, b, min]) => ({ piel, nombre, r: ratio(f, b), min }));
191
+ return { claro, oscuro, avisos, pares, muestras: { papel, tinta, prim, suave, acentoC, fondoO, textoO, primO, seriesC, seriesO, secundario } };
154
192
  }
155
193