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