orbital-ds 0.25.0 → 0.28.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/docs/CONTRACT.md CHANGED
@@ -1,224 +1,224 @@
1
- # Contrato de tema de orbital-ds
2
-
3
- Un **tema** es un fichero CSS (`themes/<nombre>.css`) que da valores a un conjunto
4
- cerrado de variables. Los componentes **solo** leen esas variables: ninguno lleva
5
- colores, medidas, sombras, capas ni duraciones escritos a mano. Por eso cambiar de
6
- tema cambia todo el aspecto sin tocar un componente.
7
-
8
- El contrato vive en [`contract.json`](../contract.json) y lo comprueba
9
- `pnpm check:ds` (que forma parte de `pnpm verify`): si a un tema le falta un token
10
- obligatorio, el build falla.
11
-
12
- ## Cómo se usa
13
-
14
- ```css
15
- @import 'orbital-ds/themes/qratia.fonts.css'; /* 0. las FUENTES del tema: lo PRIMERO del fichero */
16
- @import 'tailwindcss';
17
- @plugin '@tailwindcss/typography';
18
- @import 'tw-animate-css';
19
-
20
- @import 'orbital-ds/styles.css'; /* 1. la ESTRUCTURA común */
21
- @import 'orbital-ds/themes/qratia.css'; /* 2. un TEMA (después, para poder sobrescribir) */
22
-
23
- @source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
24
- ```
25
-
26
- El tema se importa **después** de la estructura: así puede sobrescribir también la
27
- escala de radios y las sombras, que viven en `@theme`.
28
-
29
- Las **fuentes** van en un fichero aparte por tema (`themes/<tema>.fonts.css`, solo un
30
- `@import url(...)` de Google Fonts) porque un `@import` remoto solo vale al principio
31
- de la hoja. Importado el primero, el empaquetador lo sube al inicio y se cargan. Dentro
32
- del propio `<tema>.css` no se pueden poner.
33
-
34
- Los títulos usan `--font-display` (por defecto, la misma fuente que el cuerpo; un tema
35
- con fuente de titulares, como zyro o tactile, la sobrescribe). Vale para h1–h4 y para
36
- **todos** los títulos de componente (card, dialog, sheet, alert, alert-dialog, drawer,
37
- empty, popover), con los ejes de `--ds-display-variation`.
38
-
39
- Para ajustar un valor sin crear un tema, se sobrescribe la variable al final:
40
-
41
- ```css
42
- :root { --primary: oklch(0.55 0.2 260); }
43
- ```
44
-
45
- ## Tokens obligatorios (todo tema, en `:root`)
46
-
47
- | Grupo | Tokens |
48
- |---|---|
49
- | Forma | `--radius` |
50
- | Superficies y texto | `--background`, `--foreground`, `--card`, `--card-foreground`, `--popover`, `--popover-foreground` |
51
- | Acción | `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--accent`, `--accent-foreground` |
52
- | Atenuado | `--muted`, `--muted-foreground` |
53
- | Destructivo | `--destructive`, `--destructive-foreground` |
54
- | Líneas y foco | `--border`, `--input`, `--ring` |
55
- | Gráficos | `--chart-1` … `--chart-5` |
56
- | Sidebar | `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` |
57
- | Estados | `--danger`, `--warning`, `--success`, `--info`, `--neutral` y cada uno con su `-soft` |
58
- | Texto acentuado | `--link`, `--link-hover` |
59
- | Superficie hundida | `--inset`, `--inset-foreground` |
60
- | Marca | `--brand`, `--brand-bright` |
61
- | Tipografía | `--font-sans` (en `:root` o en `@theme`); opcional `--font-display` para titulares |
62
-
63
- En `.dark` se redefine lo que cambie; `check:ds` avisa (no falla) de los tokens
64
- principales que se hereden de la piel clara.
65
-
66
- `--destructive` es el rojo de **acciones** (botón de borrar); `--danger` es el rojo
67
- de **estado** (etiqueta de nivel crítico). Pueden coincidir, pero son huecos distintos.
68
-
69
- ## Tokens con valor por defecto (el tema los puede cambiar)
70
-
71
- Los define la estructura con un valor neutro; un tema los sobrescribe si quiere.
72
-
73
- | Hueco | Variables |
74
- |---|---|
75
- | Radios semánticos | `--radius-control`, `--radius-overlay` (y la rampa `--radius-sm … 2xl`, derivada de `--radius`) |
76
- | Sombras | `--shadow-card`, `--shadow-card-hover`, `--shadow-control`, `--shadow-raised`, `--shadow-overlay`, `--shadow-popover` |
77
- | Altura de controles | `--ds-control-h-sm`, `-md`, `-lg` |
78
- | Espaciado interno | `--ds-card-spacing`, `--ds-card-spacing-sm`, `--ds-field-px`, `--ds-cell-p`, `--ds-overlay-p`, `--ds-overlay-gap`, `--ds-popover-p`, `--ds-menu-p`, `--ds-menu-item-px`, `--ds-menu-item-py`, `--ds-button-px-sm/md/lg`, `--ds-badge-px` |
79
- | Capas | `--ds-z-raised`, `--ds-z-sticky`, `--ds-z-sidebar` (sobre la cabecera sticky), `--ds-z-overlay` |
80
- | Movimiento | `--ds-motion-fast`, `--ds-motion-base`, `--ds-motion-slow`, `--ds-motion-blink` |
81
- | Foco | `--ds-ring-width` |
82
- | Lateral | `--ds-sidebar-icon`, `--ds-sidebar-icon-stroke` (iconos), `--ds-sidebar-rail-w` (ancho contraído), `--ds-sidebar-rail-item` (tecla del raíl), `--ds-sidebar-logo` (logo y avatar), `--ds-sidebar-sep-inset` (separadores; negativo = de borde a borde). **Todo tema los define** (contrato) |
83
- | **Gesto de tecla** | `--ds-key-outline`, `--ds-key-edge` (colores), `--ds-key-border` (contorno), `--ds-key-edge-w` / `-sm` / `-pressed` (arista en reposo, en controles pequeños y al pulsar), `--ds-key-press` / `-sm` (cuánto se hunde), `--ds-key-radius` / `-sm`, `--ds-key-weight`, `--ds-key-disabled-opacity`, `--ds-rule-w` (filete de superficies), `--ds-overlay-edge-w` (arista de diálogos). Valores neutros en la estructura; los usa la personalidad de un tema como `tactile` |
84
- | **Rotulador** | `--ds-marker` (color; `transparent` lo apaga), `--ds-marker-thickness` (grosor de la franja), `--ds-marker-offset` (cuánto sube); gesto **común**: lo dibuja la estructura en los títulos de cualquier tema |
85
- | **Títulos y etiquetas** | `--ds-display-variation` (ejes de la fuente de titulares, p. ej. `"SOFT" 50, "WONK" 1`), `--ds-heading-weight` (h1–h3), `--ds-title-weight`, `--ds-title-leading` (títulos de componente), `--ds-heading-tracking`, `--ds-label-tracking` (versalitas), `--ds-strong-weight`, `--ds-nav-weight`, `--ds-tabs-gap` |
86
- | **Personalidad común** | `--ds-radius-pill`, `--ds-button-case`, `--ds-button-tracking`, `--ds-button-outline-w`, `--ds-shadow-button` / `-hover`, `--ds-hover-lift`, `--ds-hover-opacity`, `--ds-tab-weight` / `-active-weight`, `--ds-tab-indicator-w`, `--ds-label-weight`, `--ds-nav-active-weight`. Huecos que **cualquier** tema usa en su personalidad (píldoras, botones en mayúsculas, brillo, subrayado de pestañas…) |
87
- | Velo | `--color-scrim` |
88
- | **Materiales** | `--ds-card-backdrop`, `--ds-overlay-backdrop`, `--ds-field-backdrop`, `--ds-sidebar-backdrop` (un `backdrop-filter` completo; por defecto `none`) y `--ds-page-backdrop` (un `background-image` para el fondo de la página; por defecto `none`) |
89
-
90
- Los **materiales** son lo que hace posible un tema de cristal como `zyro`: con valores
91
- neutros no hay efecto ni coste; con `blur(28px) saturate(180%)` las superficies se
92
- vuelven translúcidas.
93
-
94
- ## Capa de marca (`brand.css`): lo que cambia una app, y nunca se pisa
95
-
96
- Tres capas, de menos a más personal:
97
-
98
- 1. **Estructura y componentes** (paquete): se actualizan.
99
- 2. **Tema y personalidad** (paquete: `qratia`, `zyro`…): formas, sombras, materiales,
100
- anatomía del sidebar. Se actualizan con versión y changelog.
101
- 3. **Marca** (`src/brand.css`, **en la app**): el grupo estable de variables que una marca
102
- suele cambiar (`brand.tokens` en `contract.json`: color principal, foco, enlace,
103
- acento, radio, fuentes). Se importa **después** del tema, así gana, y **ninguna
104
- actualización lo toca**. Sin fichero, o vacío, se aplica el estándar del tema.
105
-
106
- ```css
107
- @import 'orbital-ds/themes/qratia.css';
108
- @import './brand.css'; /* tuyo: gana al tema */
109
- ```
110
-
111
- `pnpm exec orbital-ds-init` lo crea la primera vez (con las variables comentadas) y **nunca
112
- sobrescribe** uno existente.
113
-
114
- **Por qué una actualización no lo rompe:** los nombres de ese grupo son estables; quitar o
115
- renombrar uno es versión **mayor**, con aviso antes. Además,
116
- `orbital-ds-doctor --css src/brand.css` falla si el fichero usa una `--ds-*` que el paquete
117
- ya no define, para que una renombrada no se ignore en silencio.
118
-
119
- **Cambiar el color principal:** mueve juntas `primary`, `ring`, `link`, `brand`,
120
- `sidebar-primary` y `chart-1`, y comprueba el contraste del texto sobre ellas. Nunca edites
121
- el tema dentro de `node_modules` para personalizar una app.
122
-
123
- ## Componentes con presets (patrones de configuración)
124
-
125
- Un componente de **flujo o maqueta** (StepFlow, FormLayout, EmptyState, StatGroup, ConfirmAction) se configura con un
126
- `preset`: una intención en inglés que **solo fija valores por defecto**; cualquier prop explícita lo sobrescribe, así sirve
127
- en cualquier proyecto. Vocabulario común en `src/lib/presets.ts` (`DsDensity`, `DsPresentation`, `dsWarn`).
128
-
129
- 1. **Configuración en inglés** (props, valores, tokens, `data-*`); **texto visible o accesible** por `useDsMessages()` en
130
- los tres catálogos; comentarios y `@note` en español.
131
- 2. **Nombre del preset = intención** (`quick`, `first-use`, `settings`), nunca el aspecto (`small-modal`).
132
- 3. **Ejes independientes**: presentación (`dialog | page | inline | sheet`) y densidad (`compact | default | comfortable`)
133
- son props distintas; los presets las combinan, no las fusionan.
134
- 4. **El diseño sigue el ancho del contenedor** (container query), no el dispositivo ni la presentación.
135
- 5. **Aviso en desarrollo** (`dsWarn`, mensaje en inglés) si la combinación no cuadra.
136
- 6. **Ganchos del DOM**: `data-slot` y `data-preset` (más `data-presentation`/`data-density` si aplica).
137
- 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`
138
- (inline · sectioned · settings), `NoticeReview` (read · acknowledge · resolve · respond), `EmptyState` (first-use · no-results · error · forbidden), `StatGroup` (overview ·
139
- compact · comparison) y `ConfirmAction` (simple · typed).
140
-
141
- **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`.
142
-
143
- ## Avisos y comunicaciones in-app (qué canal usar)
144
-
145
- Se elige el canal por **urgencia** y **persistencia**; cada app no lo decide a mano:
146
-
147
- | Intención | Canal | Persiste | Interrumpe |
148
- |---|---|---|---|
149
- | Confirmar una acción de la persona | toast (`Toaster`/`Toast`) | no | no |
150
- | Aviso de una sección | `Alert` | sí | no |
151
- | Aviso que afecta a toda la página | `Banner` | hasta resolver | no |
152
- | Asunto con seguimiento o decisión | campana (`NotificationCenter`) + `NoticeReview` | sí, con estado | solo si es crítico |
153
- | Bloqueo que exige respuesta ya | `ConfirmAction` / `AlertDialog` | no | sí |
154
-
155
- Mismo vocabulario en todos: tono `info | success | warning | danger` y estado `new → acknowledged → resolved`.
156
- `NotificationItem onSelect` abre la revisión; `NoticeReview` tiene presets `read | acknowledge | resolve | respond`
157
- (modal o `presentation="sheet"`).
158
-
159
- ## Unidades
160
-
161
- Medidas en `rem` (también en container queries); `em` solo relativo al propio componente; `px` solo en filetes y
162
- bordes finos vía token. `pnpm check:ds` rechaza `@[Npx]` y medidas fijas en valores arbitrarios.
163
-
164
- ## Reglas de nombres
165
-
166
- - Todo en **inglés**: tokens, props y valores de variantes.
167
- - Los nombres que Tailwind convierte en utilidades (`--color-*`, `--radius-*`,
168
- `--shadow-*`) siguen su convención y **no llevan prefijo**. El resto de variables
169
- propias llevan el prefijo **`--ds-`** para no chocar con las de una app.
170
- - Un componente que necesite un hueco nuevo **añade el token** con un valor que deje
171
- el aspecto como estaba; nunca escribe el valor en el componente.
172
-
173
- ## Qué comprueba `pnpm check:ds`
174
-
175
- 1. **Contrato**: cada tema define todos los tokens obligatorios.
176
- 2. **Repetidos**: ninguna variable se define dos veces en el mismo bloque.
177
- 3. **Valores fijos** en `src/ui/*.tsx`: colores literales (hex, `rgb()`, `oklch()`
178
- salvo derivados de un token), `z-<n>`, `duration-<n>`, `bg-black`/`bg-white`,
179
- sombras de la escala de Tailwind, `text-[<n>px]`, radios fuera de la rampa y
180
- colores de la paleta de Tailwind.
181
-
182
- 4. **Personalidad solo con variables**: una regla de personalidad (cualquier propiedad
183
- que no sea `--x`) no escribe medidas, colores, pesos, opacidades, interlineados ni
184
- duraciones; pide el hueco a una variable.
185
- 5. **Familias completas** (`slotFamilies` en `contract.json`): si la personalidad
186
- estiliza una pieza (`checkbox`), estiliza sus hermanas (`radio-group-item`). Familias:
187
- choice, field, modal, floating, title, toggle, track.
188
- 6. **Contraste AA** de los pares de texto principales y de los textos de estado; resuelve
189
- `var(--x)`, así que un color derivado (`--sidebar-primary: var(--primary)`) también se mide.
190
-
191
- Las reglas 4 y 5 son **error** en un tema con `"conformance": "strict"` en su ficha
192
- (`<tema>.meta.json`) y **aviso** en los demás. **Todos los temas del paquete son estrictos**,
193
- y un tema nuevo debe nacer así.
194
-
195
- ### Un solo sitio para cada cosa
196
-
197
- | Quién | Dónde cambia el aspecto | Qué toca |
198
- |---|---|---|
199
- | Autor de un tema | bloque «VARIABLES» del tema (`:root` y `.dark`) | valores; las reglas de PERSONALIDAD solo los leen |
200
- | App (o su agente) | `src/brand.css` | cualquier variable pública: color, forma, fuentes, gesto (`--ds-key-*`, `--ds-marker`, `--ds-radius-pill`…) |
201
-
202
- Ninguna regla escribe un valor, así que cambiar una variable cambia **todas** las piezas que
203
- la usan, en cualquier tema. Si una variable que lee la personalidad deriva de otra que cambia
204
- de piel (p. ej. una sombra con el color de marca), el tema la repite en `.dark`.
205
-
206
- También se puede pasar el CSS de una app: `orbital-ds-doctor --css src/styles.css`
207
- (detecta variables repetidas).
208
-
209
- ## Crear un tema nuevo
210
-
211
- 1. Copia `themes/qratia.css` (o `zyro.css`) a `themes/<nombre>.css`.
212
- 2. Cambia los valores; no quites ninguno.
213
- 3. `pnpm check:ds`: te dice qué falta.
214
- 4. Opcional: usa los materiales para dar cristal, relieve o un fondo propio.
215
-
216
- Se puede partir de un tema de shadcn (por ejemplo exportado desde tweakcn): usa los
217
- mismos nombres estándar (`--background`, `--primary`…). Habrá que añadir los tokens
218
- propios (`danger`, `warning`, `success`, `info`, `neutral`, `link`, `inset`, `brand`).
219
-
220
- ## Cosas que un tema NO puede cambiar
221
-
222
- La **anatomía** de un componente (otro diseño de sidebar o de tarjeta) no es un valor,
223
- es estructura: se resuelve con variantes del componente. Un fondo animado (como la
224
- malla WebGL de zyro) es código, no una variable: se ofrece como componente opcional.
1
+ # Contrato de tema de orbital-ds
2
+
3
+ Un **tema** es un fichero CSS (`themes/<nombre>.css`) que da valores a un conjunto
4
+ cerrado de variables. Los componentes **solo** leen esas variables: ninguno lleva
5
+ colores, medidas, sombras, capas ni duraciones escritos a mano. Por eso cambiar de
6
+ tema cambia todo el aspecto sin tocar un componente.
7
+
8
+ El contrato vive en [`contract.json`](../contract.json) y lo comprueba
9
+ `pnpm check:ds` (que forma parte de `pnpm verify`): si a un tema le falta un token
10
+ obligatorio, el build falla.
11
+
12
+ ## Cómo se usa
13
+
14
+ ```css
15
+ @import 'orbital-ds/themes/qratia.fonts.css'; /* 0. las FUENTES del tema: lo PRIMERO del fichero */
16
+ @import 'tailwindcss';
17
+ @plugin '@tailwindcss/typography';
18
+ @import 'tw-animate-css';
19
+
20
+ @import 'orbital-ds/styles.css'; /* 1. la ESTRUCTURA común */
21
+ @import 'orbital-ds/themes/qratia.css'; /* 2. un TEMA (después, para poder sobrescribir) */
22
+
23
+ @source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
24
+ ```
25
+
26
+ El tema se importa **después** de la estructura: así puede sobrescribir también la
27
+ escala de radios y las sombras, que viven en `@theme`.
28
+
29
+ Las **fuentes** van en un fichero aparte por tema (`themes/<tema>.fonts.css`, solo un
30
+ `@import url(...)` de Google Fonts) porque un `@import` remoto solo vale al principio
31
+ de la hoja. Importado el primero, el empaquetador lo sube al inicio y se cargan. Dentro
32
+ del propio `<tema>.css` no se pueden poner.
33
+
34
+ Los títulos usan `--font-display` (por defecto, la misma fuente que el cuerpo; un tema
35
+ con fuente de titulares, como zyro o tactile, la sobrescribe). Vale para h1–h4 y para
36
+ **todos** los títulos de componente (card, dialog, sheet, alert, alert-dialog, drawer,
37
+ empty, popover), con los ejes de `--ds-display-variation`.
38
+
39
+ Para ajustar un valor sin crear un tema, se sobrescribe la variable al final:
40
+
41
+ ```css
42
+ :root { --primary: oklch(0.55 0.2 260); }
43
+ ```
44
+
45
+ ## Tokens obligatorios (todo tema, en `:root`)
46
+
47
+ | Grupo | Tokens |
48
+ |---|---|
49
+ | Forma | `--radius` |
50
+ | Superficies y texto | `--background`, `--foreground`, `--card`, `--card-foreground`, `--popover`, `--popover-foreground` |
51
+ | Acción | `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--accent`, `--accent-foreground` |
52
+ | Atenuado | `--muted`, `--muted-foreground` |
53
+ | Destructivo | `--destructive`, `--destructive-foreground` |
54
+ | Líneas y foco | `--border`, `--input`, `--ring` |
55
+ | Gráficos | `--chart-1` … `--chart-5` |
56
+ | Sidebar | `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` |
57
+ | Estados | `--danger`, `--warning`, `--success`, `--info`, `--neutral` y cada uno con su `-soft` |
58
+ | Texto acentuado | `--link`, `--link-hover` |
59
+ | Superficie hundida | `--inset`, `--inset-foreground` |
60
+ | Marca | `--brand`, `--brand-bright` |
61
+ | Tipografía | `--font-sans` (en `:root` o en `@theme`); opcional `--font-display` para titulares |
62
+
63
+ En `.dark` se redefine lo que cambie; `check:ds` avisa (no falla) de los tokens
64
+ principales que se hereden de la piel clara.
65
+
66
+ `--destructive` es el rojo de **acciones** (botón de borrar); `--danger` es el rojo
67
+ de **estado** (etiqueta de nivel crítico). Pueden coincidir, pero son huecos distintos.
68
+
69
+ ## Tokens con valor por defecto (el tema los puede cambiar)
70
+
71
+ Los define la estructura con un valor neutro; un tema los sobrescribe si quiere.
72
+
73
+ | Hueco | Variables |
74
+ |---|---|
75
+ | Radios semánticos | `--radius-control`, `--radius-overlay` (y la rampa `--radius-sm … 2xl`, derivada de `--radius`) |
76
+ | Sombras | `--shadow-card`, `--shadow-card-hover`, `--shadow-control`, `--shadow-raised`, `--shadow-overlay`, `--shadow-popover` |
77
+ | Altura de controles | `--ds-control-h-sm`, `-md`, `-lg` |
78
+ | Espaciado interno | `--ds-card-spacing`, `--ds-card-spacing-sm`, `--ds-field-px`, `--ds-cell-p`, `--ds-overlay-p`, `--ds-overlay-gap`, `--ds-popover-p`, `--ds-menu-p`, `--ds-menu-item-px`, `--ds-menu-item-py`, `--ds-button-px-sm/md/lg`, `--ds-badge-px` |
79
+ | Capas | `--ds-z-raised`, `--ds-z-sticky`, `--ds-z-sidebar` (sobre la cabecera sticky), `--ds-z-overlay` |
80
+ | Movimiento | `--ds-motion-fast`, `--ds-motion-base`, `--ds-motion-slow`, `--ds-motion-blink` |
81
+ | Foco | `--ds-ring-width` |
82
+ | Lateral | `--ds-sidebar-icon`, `--ds-sidebar-icon-stroke` (iconos), `--ds-sidebar-rail-w` (ancho contraído), `--ds-sidebar-rail-item` (tecla del raíl), `--ds-sidebar-logo` (logo y avatar), `--ds-sidebar-sep-inset` (separadores; negativo = de borde a borde). **Todo tema los define** (contrato) |
83
+ | **Gesto de tecla** | `--ds-key-outline`, `--ds-key-edge` (colores), `--ds-key-border` (contorno), `--ds-key-edge-w` / `-sm` / `-pressed` (arista en reposo, en controles pequeños y al pulsar), `--ds-key-press` / `-sm` (cuánto se hunde), `--ds-key-radius` / `-sm`, `--ds-key-weight`, `--ds-key-disabled-opacity`, `--ds-rule-w` (filete de superficies), `--ds-overlay-edge-w` (arista de diálogos). Valores neutros en la estructura; los usa la personalidad de un tema como `tactile` |
84
+ | **Rotulador** | `--ds-marker` (color; `transparent` lo apaga), `--ds-marker-thickness` (grosor de la franja), `--ds-marker-offset` (cuánto sube); gesto **común**: lo dibuja la estructura en los títulos de cualquier tema |
85
+ | **Títulos y etiquetas** | `--ds-display-variation` (ejes de la fuente de titulares, p. ej. `"SOFT" 50, "WONK" 1`), `--ds-heading-weight` (h1–h3), `--ds-title-weight`, `--ds-title-leading` (títulos de componente), `--ds-heading-tracking`, `--ds-label-tracking` (versalitas), `--ds-strong-weight`, `--ds-nav-weight`, `--ds-tabs-gap` |
86
+ | **Personalidad común** | `--ds-radius-pill`, `--ds-button-case`, `--ds-button-tracking`, `--ds-button-outline-w`, `--ds-shadow-button` / `-hover`, `--ds-hover-lift`, `--ds-hover-opacity`, `--ds-tab-weight` / `-active-weight`, `--ds-tab-indicator-w`, `--ds-label-weight`, `--ds-nav-active-weight`. Huecos que **cualquier** tema usa en su personalidad (píldoras, botones en mayúsculas, brillo, subrayado de pestañas…) |
87
+ | Velo | `--color-scrim` |
88
+ | **Materiales** | `--ds-card-backdrop`, `--ds-overlay-backdrop`, `--ds-field-backdrop`, `--ds-sidebar-backdrop` (un `backdrop-filter` completo; por defecto `none`) y `--ds-page-backdrop` (un `background-image` para el fondo de la página; por defecto `none`) |
89
+
90
+ Los **materiales** son lo que hace posible un tema de cristal como `zyro`: con valores
91
+ neutros no hay efecto ni coste; con `blur(28px) saturate(180%)` las superficies se
92
+ vuelven translúcidas.
93
+
94
+ ## Capa de marca (`brand.css`): lo que cambia una app, y nunca se pisa
95
+
96
+ Tres capas, de menos a más personal:
97
+
98
+ 1. **Estructura y componentes** (paquete): se actualizan.
99
+ 2. **Tema y personalidad** (paquete: `qratia`, `zyro`…): formas, sombras, materiales,
100
+ anatomía del sidebar. Se actualizan con versión y changelog.
101
+ 3. **Marca** (`src/brand.css`, **en la app**): el grupo estable de variables que una marca
102
+ suele cambiar (`brand.tokens` en `contract.json`: color principal, foco, enlace,
103
+ acento, radio, fuentes). Se importa **después** del tema, así gana, y **ninguna
104
+ actualización lo toca**. Sin fichero, o vacío, se aplica el estándar del tema.
105
+
106
+ ```css
107
+ @import 'orbital-ds/themes/qratia.css';
108
+ @import './brand.css'; /* tuyo: gana al tema */
109
+ ```
110
+
111
+ `pnpm exec orbital-ds-init` lo crea la primera vez (con las variables comentadas) y **nunca
112
+ sobrescribe** uno existente.
113
+
114
+ **Por qué una actualización no lo rompe:** los nombres de ese grupo son estables; quitar o
115
+ renombrar uno es versión **mayor**, con aviso antes. Además,
116
+ `orbital-ds-doctor --css src/brand.css` falla si el fichero usa una `--ds-*` que el paquete
117
+ ya no define, para que una renombrada no se ignore en silencio.
118
+
119
+ **Cambiar el color principal:** mueve juntas `primary`, `ring`, `link`, `brand`,
120
+ `sidebar-primary` y `chart-1`, y comprueba el contraste del texto sobre ellas. Nunca edites
121
+ el tema dentro de `node_modules` para personalizar una app.
122
+
123
+ ## Componentes con presets (patrones de configuración)
124
+
125
+ Un componente de **flujo o maqueta** (StepFlow, FormLayout, EmptyState, StatGroup, ConfirmAction) se configura con un
126
+ `preset`: una intención en inglés que **solo fija valores por defecto**; cualquier prop explícita lo sobrescribe, así sirve
127
+ en cualquier proyecto. Vocabulario común en `src/lib/presets.ts` (`DsDensity`, `DsPresentation`, `dsWarn`).
128
+
129
+ 1. **Configuración en inglés** (props, valores, tokens, `data-*`); **texto visible o accesible** por `useDsMessages()` en
130
+ los tres catálogos; comentarios y `@note` en español.
131
+ 2. **Nombre del preset = intención** (`quick`, `first-use`, `settings`), nunca el aspecto (`small-modal`).
132
+ 3. **Ejes independientes**: presentación (`dialog | page | inline | sheet`) y densidad (`compact | default | comfortable`)
133
+ son props distintas; los presets las combinan, no las fusionan.
134
+ 4. **El diseño sigue el ancho del contenedor** (container query), no el dispositivo ni la presentación.
135
+ 5. **Aviso en desarrollo** (`dsWarn`, mensaje en inglés) si la combinación no cuadra.
136
+ 6. **Ganchos del DOM**: `data-slot` y `data-preset` (más `data-presentation`/`data-density` si aplica).
137
+ 7. **Un `@note`** que diga cuándo usar cada preset. Catálogo hoy: `ChartCard` (glance · standard · focus · dense), `ContentCard` (basic · feature · media · horizontal, con `emphasis` elevated · outlined · filled · ghost), `Mosaic` (even · bento · trio), `PageShell` (content · detail · canvas), `PageHeader` (page · compact · canvas), `FilterBar` (inline · compact · stacked), `DataTable` (browse · manage · compact), `LoadingState` (list · card · table · detail), `PageLoader` (splash · route · section · overlay), `CommandPalette` (go · actions · search), `FileUpload` (drop · button), `ErrorPage` (not-found · forbidden · server-error · offline · maintenance, con `tone` neutral · playful), `DetailPanel` (side · bottom · full), `EntityList` (list · grid · compact), `StepFlow` (quick · activation · long), `FormLayout`
138
+ (inline · sectioned · settings), `NoticeReview` (read · acknowledge · resolve · respond), `EmptyState` (first-use · no-results · error · forbidden), `StatGroup` (overview ·
139
+ compact · comparison) y `ConfirmAction` (simple · typed).
140
+
141
+ **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`.
142
+
143
+ ## Avisos y comunicaciones in-app (qué canal usar)
144
+
145
+ Se elige el canal por **urgencia** y **persistencia**; cada app no lo decide a mano:
146
+
147
+ | Intención | Canal | Persiste | Interrumpe |
148
+ |---|---|---|---|
149
+ | Confirmar una acción de la persona | toast (`Toaster`/`Toast`) | no | no |
150
+ | Aviso de una sección | `Alert` | sí | no |
151
+ | Aviso que afecta a toda la página | `Banner` | hasta resolver | no |
152
+ | Asunto con seguimiento o decisión | campana (`NotificationCenter`) + `NoticeReview` | sí, con estado | solo si es crítico |
153
+ | Bloqueo que exige respuesta ya | `ConfirmAction` / `AlertDialog` | no | sí |
154
+
155
+ Mismo vocabulario en todos: tono `info | success | warning | danger` y estado `new → acknowledged → resolved`.
156
+ `NotificationItem onSelect` abre la revisión; `NoticeReview` tiene presets `read | acknowledge | resolve | respond`
157
+ (modal o `presentation="sheet"`).
158
+
159
+ ## Unidades
160
+
161
+ Medidas en `rem` (también en container queries); `em` solo relativo al propio componente; `px` solo en filetes y
162
+ bordes finos vía token. `pnpm check:ds` rechaza `@[Npx]` y medidas fijas en valores arbitrarios.
163
+
164
+ ## Reglas de nombres
165
+
166
+ - Todo en **inglés**: tokens, props y valores de variantes.
167
+ - Los nombres que Tailwind convierte en utilidades (`--color-*`, `--radius-*`,
168
+ `--shadow-*`) siguen su convención y **no llevan prefijo**. El resto de variables
169
+ propias llevan el prefijo **`--ds-`** para no chocar con las de una app.
170
+ - Un componente que necesite un hueco nuevo **añade el token** con un valor que deje
171
+ el aspecto como estaba; nunca escribe el valor en el componente.
172
+
173
+ ## Qué comprueba `pnpm check:ds`
174
+
175
+ 1. **Contrato**: cada tema define todos los tokens obligatorios.
176
+ 2. **Repetidos**: ninguna variable se define dos veces en el mismo bloque.
177
+ 3. **Valores fijos** en `src/ui/*.tsx`: colores literales (hex, `rgb()`, `oklch()`
178
+ salvo derivados de un token), `z-<n>`, `duration-<n>`, `bg-black`/`bg-white`,
179
+ sombras de la escala de Tailwind, `text-[<n>px]`, radios fuera de la rampa y
180
+ colores de la paleta de Tailwind.
181
+
182
+ 4. **Personalidad solo con variables**: una regla de personalidad (cualquier propiedad
183
+ que no sea `--x`) no escribe medidas, colores, pesos, opacidades, interlineados ni
184
+ duraciones; pide el hueco a una variable.
185
+ 5. **Familias completas** (`slotFamilies` en `contract.json`): si la personalidad
186
+ estiliza una pieza (`checkbox`), estiliza sus hermanas (`radio-group-item`). Familias:
187
+ choice, field, modal, floating, title, toggle, track.
188
+ 6. **Contraste AA** de los pares de texto principales y de los textos de estado; resuelve
189
+ `var(--x)`, así que un color derivado (`--sidebar-primary: var(--primary)`) también se mide.
190
+
191
+ Las reglas 4 y 5 son **error** en un tema con `"conformance": "strict"` en su ficha
192
+ (`<tema>.meta.json`) y **aviso** en los demás. **Todos los temas del paquete son estrictos**,
193
+ y un tema nuevo debe nacer así.
194
+
195
+ ### Un solo sitio para cada cosa
196
+
197
+ | Quién | Dónde cambia el aspecto | Qué toca |
198
+ |---|---|---|
199
+ | Autor de un tema | bloque «VARIABLES» del tema (`:root` y `.dark`) | valores; las reglas de PERSONALIDAD solo los leen |
200
+ | App (o su agente) | `src/brand.css` | cualquier variable pública: color, forma, fuentes, gesto (`--ds-key-*`, `--ds-marker`, `--ds-radius-pill`…) |
201
+
202
+ Ninguna regla escribe un valor, así que cambiar una variable cambia **todas** las piezas que
203
+ la usan, en cualquier tema. Si una variable que lee la personalidad deriva de otra que cambia
204
+ de piel (p. ej. una sombra con el color de marca), el tema la repite en `.dark`.
205
+
206
+ También se puede pasar el CSS de una app: `orbital-ds-doctor --css src/styles.css`
207
+ (detecta variables repetidas).
208
+
209
+ ## Crear un tema nuevo
210
+
211
+ 1. Copia `themes/qratia.css` (o `zyro.css`) a `themes/<nombre>.css`.
212
+ 2. Cambia los valores; no quites ninguno.
213
+ 3. `pnpm check:ds`: te dice qué falta.
214
+ 4. Opcional: usa los materiales para dar cristal, relieve o un fondo propio.
215
+
216
+ Se puede partir de un tema de shadcn (por ejemplo exportado desde tweakcn): usa los
217
+ mismos nombres estándar (`--background`, `--primary`…). Habrá que añadir los tokens
218
+ propios (`danger`, `warning`, `success`, `info`, `neutral`, `link`, `inset`, `brand`).
219
+
220
+ ## Cosas que un tema NO puede cambiar
221
+
222
+ La **anatomía** de un componente (otro diseño de sidebar o de tarjeta) no es un valor,
223
+ es estructura: se resuelve con variantes del componente. Un fondo animado (como la
224
+ malla WebGL de zyro) es código, no una variable: se ofrece como componente opcional.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "orbital-ds",
3
- "version": "0.25.0",
3
+ "version": "0.28.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",
package/scripts/cli.mjs CHANGED
@@ -210,7 +210,7 @@ function contexto(json) {
210
210
  marca: estado.marca?.activa ? estado.marca : null,
211
211
  brandCss: { fichero: existsSync(brand) ? relative(process.cwd(), brand).split(sep).join('/') : null, variables: brandVars, coloresAMano: estado.manual.colores.map((d) => d.name) },
212
212
  extras: { animaciones: estado.animaciones, motion: yaInstalado('motion'), echarts: yaInstalado('echarts'), tablas: yaInstalado('@tanstack/react-table') },
213
- componentes: Object.fromEntries(Object.entries(manifest.components).map(([n, c]) => [n, { import: c.import, exports: c.exports, ...(c.notes ? { notes: c.notes } : {}) }])),
213
+ componentes: Object.fromEntries(Object.entries(manifest.components).map(([n, c]) => [n, { import: c.import, exports: c.exports, ...(c.presets ? { presets: c.presets } : {}), ...(c.notes ? { notes: c.notes } : {}) }])),
214
214
  patrones,
215
215
  documentacion: {
216
216
  reglas: `${docs}/AGENTS.md`,
@@ -245,6 +245,11 @@ function contexto(json) {
245
245
  const sino = (v) => (v ? 'sí' : 'no');
246
246
  L.push('', '## Extras', `- Animaciones del tema: ${sino(datos.extras.animaciones)} · Motion: ${sino(datos.extras.motion)} · ECharts: ${sino(datos.extras.echarts)} · TanStack Table: ${sino(datos.extras.tablas)}`);
247
247
  L.push('', `## Componentes (${Object.keys(datos.componentes).length}) · import orbital-ds/ui/<nombre>`, Object.keys(datos.componentes).join(', '));
248
+ const conPresets = Object.entries(datos.componentes).filter(([, c]) => c.presets);
249
+ if (conPresets.length) {
250
+ L.push('', '### Presets (valor por defecto con *)');
251
+ for (const [n, c] of conPresets) L.push(`- ${n}: ${c.presets.values.map((v) => (v === c.presets.default ? `${v}*` : v)).join(' · ')}`);
252
+ }
248
253
  const conNotas = Object.entries(datos.componentes).filter(([, c]) => c.notes);
249
254
  if (conNotas.length) {
250
255
  L.push('', '### Notas de uso');
@@ -469,6 +469,13 @@ if (base && themeInfo[base]) {
469
469
  if (!/preset\??:/.test(src)) continue;
470
470
  if (!/data-preset=/.test(src)) errors.push(`ui/${f}: tiene prop preset pero no emite data-preset`);
471
471
  if (!/@note/.test(src)) errors.push(`ui/${f}: tiene prop preset pero ningún @note que explique cuándo usar cada uno`);
472
+ {
473
+ // El catálogo del manifiesto lee el tipo y el valor por defecto de la firma: tienen que coincidir.
474
+ const vals = [...(src.match(/type \w*Preset\s*=\s*([^;]+);/)?.[1] ?? '').matchAll(/"([^"]+)"/g)].map((x) => x[1]);
475
+ const def = src.match(/^\s*preset\s*=\s*"([a-z-]+)",?\s*$/m)?.[1];
476
+ if (!def) errors.push(`ui/${f}: el preset no tiene valor por defecto en la firma (preset = "…")`);
477
+ else if (!vals.includes(def)) errors.push(`ui/${f}: el preset por defecto «${def}» no está en su tipo (${vals.join(", ")})`);
478
+ }
472
479
  for (const m of src.matchAll(/type \w*Preset\s*=\s*([^;]+);/g)) {
473
480
  for (const v of m[1].matchAll(/"([^"]+)"/g)) {
474
481
  if (!/^[a-z]+(-[a-z]+)*$/.test(v[1])) errors.push(`ui/${f}: valor de preset «${v[1]}» fuera del estándar (inglés, minúsculas, kebab-case)`);