orbital-ds 0.10.1 → 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.
- package/AGENTS.md +63 -7
- package/README.md +93 -87
- package/components.manifest.json +1906 -1713
- package/contract.json +37 -0
- package/dist/hooks/use-ds-messages.d.ts +17 -0
- package/dist/lib/i18n.d.ts +17 -0
- package/dist/lib/i18n.js +54 -3
- package/dist/motion.css +139 -0
- package/dist/styles.css +124 -0
- package/dist/themes/fractalia.css +473 -0
- package/dist/themes/fractalia.fonts.css +3 -0
- package/dist/themes/fractalia.guide.md +79 -0
- package/dist/themes/fractalia.meta.json +99 -0
- package/dist/themes/fractalia.scoped.css +473 -0
- package/dist/themes/fractalia.tokens.json +39 -0
- package/dist/themes/friendly.css +7 -1
- package/dist/themes/friendly.meta.json +7 -0
- package/dist/themes/friendly.scoped.css +7 -1
- package/dist/themes/qratia.css +13 -8
- package/dist/themes/qratia.meta.json +8 -1
- package/dist/themes/qratia.scoped.css +13 -8
- package/dist/themes/tactile.css +7 -1
- package/dist/themes/tactile.meta.json +7 -0
- package/dist/themes/tactile.scoped.css +7 -1
- package/dist/themes/twitter.css +7 -1
- package/dist/themes/twitter.meta.json +7 -0
- package/dist/themes/twitter.scoped.css +7 -1
- package/dist/themes/zyro.css +7 -1
- package/dist/themes/zyro.meta.json +7 -0
- package/dist/themes/zyro.scoped.css +7 -1
- package/dist/ui/accordion.js +1 -1
- package/dist/ui/alert.js +6 -5
- package/dist/ui/attachment.d.ts +1 -1
- package/dist/ui/attachment.js +1 -1
- package/dist/ui/badge.js +7 -7
- package/dist/ui/banner.js +6 -6
- package/dist/ui/button-group.js +1 -1
- package/dist/ui/button.d.ts +1 -1
- package/dist/ui/button.js +7 -7
- package/dist/ui/calendar.js +2 -2
- package/dist/ui/chart.js +3 -3
- package/dist/ui/combobox.js +2 -2
- package/dist/ui/command.js +1 -1
- package/dist/ui/context-menu.js +4 -4
- package/dist/ui/dropdown-menu.js +4 -4
- package/dist/ui/empty.js +1 -1
- package/dist/ui/field.js +2 -2
- package/dist/ui/gauge.d.ts +40 -0
- package/dist/ui/gauge.js +157 -0
- package/dist/ui/heatmap-grid.js +1 -1
- package/dist/ui/input-group.d.ts +1 -1
- package/dist/ui/input-group.js +1 -1
- package/dist/ui/input.js +1 -1
- package/dist/ui/item.d.ts +3 -3
- package/dist/ui/item.js +15 -5
- package/dist/ui/kbd.js +1 -1
- package/dist/ui/label.js +1 -1
- package/dist/ui/legend.d.ts +3 -1
- package/dist/ui/legend.js +15 -1
- package/dist/ui/level-meter.d.ts +16 -0
- package/dist/ui/level-meter.js +60 -0
- package/dist/ui/marker.d.ts +1 -1
- package/dist/ui/menubar.js +5 -5
- package/dist/ui/message.js +2 -2
- package/dist/ui/native-select.js +2 -2
- package/dist/ui/navigation-menu.js +1 -1
- package/dist/ui/password-strength.d.ts +14 -0
- package/dist/ui/password-strength.js +61 -0
- package/dist/ui/progress.js +1 -1
- package/dist/ui/proportion-bar.js +2 -2
- package/dist/ui/questionnaire.js +2 -2
- package/dist/ui/select.js +7 -8
- package/dist/ui/shield.d.ts +21 -0
- package/dist/ui/shield.js +141 -0
- package/dist/ui/sidebar.js +1 -1
- package/dist/ui/stat.d.ts +11 -1
- package/dist/ui/stat.js +13 -3
- package/dist/ui/status-badge.d.ts +3 -2
- package/dist/ui/status-badge.js +10 -8
- package/dist/ui/status-hero.d.ts +12 -0
- package/dist/ui/status-hero.js +60 -0
- package/dist/ui/step-dots.d.ts +10 -0
- package/dist/ui/step-dots.js +40 -0
- package/dist/ui/step-ring.d.ts +12 -0
- package/dist/ui/step-ring.js +35 -0
- package/dist/ui/table.js +1 -1
- package/dist/ui/tabs.js +1 -1
- package/dist/ui/task-loader.d.ts +14 -0
- package/dist/ui/task-loader.js +50 -0
- package/dist/ui/task-progress.d.ts +18 -0
- package/dist/ui/task-progress.js +84 -0
- package/dist/ui/toggle.js +1 -1
- package/docs/adr/0002-sistemas-corporativos-al-modelo.md +176 -0
- package/docs/designer/flujo.md +79 -0
- package/docs/designer/patrones.md +116 -0
- package/docs/designer/revision.md +60 -0
- package/docs/designer/ux.md +71 -0
- package/package.json +9 -2
- package/scripts/brand-core.mjs +55 -15
- package/scripts/cli.mjs +370 -0
- package/scripts/doctor.mjs +578 -451
- package/scripts/init.mjs +329 -111
- package/scripts/manifest.mjs +85 -79
- package/scripts/setup.mjs +2 -1
- package/scripts/skill.mjs +67 -0
- package/skill/SKILL.md +47 -0
package/AGENTS.md
CHANGED
|
@@ -43,6 +43,14 @@ adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
|
|
|
43
43
|
|
|
44
44
|
## Movimiento (animación)
|
|
45
45
|
|
|
46
|
+
- **Animaciones de fábrica sin código: `@import 'orbital-ds/motion.css'`** (después del tema; el asistente lo añade si
|
|
47
|
+
lo activas). Entradas en cascada de tarjetas, paneles, KPI, filas-tarjeta, avisos, cabeceras y filas de tabla, y
|
|
48
|
+
superficies pulsables. Cada grupo tiene su interruptor con un tipo del CATÁLOGO: `--ds-enter-surfaces`,
|
|
49
|
+
`--ds-enter-notices`, `--ds-enter-headers`, `--ds-enter-rows` = `ds-auto-enter` (sube) · `ds-auto-fade` ·
|
|
50
|
+
`ds-auto-pop` (crece) · `ds-auto-slide` (de lado, RTL) · `ds-auto-focus` (se enfoca) · `none`. Cada tema elige
|
|
51
|
+
según su personalidad y lo declara en su ficha (`motion.auto`); el doctor comprueba que sea del catálogo y que
|
|
52
|
+
ficha y CSS coincidan. La app lo cambia en `brand.css`. Sin el import, no anima nada.
|
|
53
|
+
|
|
46
54
|
- **El tema gobierna el «cómo»**: ritmo (`--ds-motion-*`), curvas (`--ds-ease-*`) y coreografía
|
|
47
55
|
(`--ds-motion-distance`, `-scale`, `-blur`, `--ds-spring-bounce`, `--ds-motion-stagger`,
|
|
48
56
|
`--ds-motion-press-scale`). Cada tema trae el suyo de fábrica; la app lo ajusta en `brand.css`.
|
|
@@ -97,9 +105,35 @@ adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
|
|
|
97
105
|
|
|
98
106
|
## Instalar en una app
|
|
99
107
|
|
|
100
|
-
`pnpm exec orbital-ds
|
|
101
|
-
|
|
102
|
-
|
|
108
|
+
**Orden única: `pnpm exec orbital-ds`** (menú) · `orbital-ds init` (configuración inicial) · `orbital-ds theme [tema]`
|
|
109
|
+
(cambiar de tema conservando marca y extras) · `orbital-ds doctor` · `orbital-ds i18n` · `orbital-ds help [orden]`.
|
|
110
|
+
Las órdenes sueltas (`orbital-ds-init`, `-doctor`, `-i18n`) siguen valiendo como atajos.
|
|
111
|
+
|
|
112
|
+
`orbital-ds init` (= `pnpm exec orbital-ds-init`): elige tema (enseña su ficha: esencia, paleta, gesto, excepciones de
|
|
113
|
+
contraste), elige **cómo aplicar la marca** y, si lo aceptas, escribe `brand.css`, conecta el CSS de
|
|
114
|
+
la app (bloque de imports en orden), anota DESIGN.md, instala Motion y pasa el doctor.
|
|
115
|
+
|
|
116
|
+
- **Modos de marca** (`--mode`): `faithful` (el tema tal cual, sin derivar nada; quita un bloque
|
|
117
|
+
generado con `--update`), `primary` (solo el primario —foco, enlace, lateral activo, serie 1— sobre
|
|
118
|
+
la paleta del tema, con el contraste medido contra SU lienzo) y `full` (paleta entera derivada).
|
|
119
|
+
- La ficha del tema recomienda el modo con `"branding"`. Un tema de un **sistema corporativo**
|
|
120
|
+
(p. ej. `fractalia`) declara `"branding": "faithful"`: no le derives la paleta.
|
|
121
|
+
- Sin preguntas: `--theme fractalia --connect` (fiel) · `--primary <color> --mode primary --theme <tema>` ·
|
|
122
|
+
`--primary <color> --theme <tema> --connect --motion` (completa).
|
|
123
|
+
|
|
124
|
+
## Diseñar con orbital-ds (diseñador para agentes)
|
|
125
|
+
|
|
126
|
+
Para crear o revisar pantallas y flujos, sigue `docs/designer/`: **flujo.md** (contexto real, modo, mapa del flujo y
|
|
127
|
+
modelo mental de la persona, orden de autoridad), **patrones.md** (P1–P12: página, lista de entidades, detalle, tabla,
|
|
128
|
+
formulario, asistente, panel de datos, destructiva, estados, avisos, búsqueda, ajustes), **ux.md** (heurísticas,
|
|
129
|
+
carga cognitiva, formularios, textos, WCAG 2.2 AA, responsivo) y **revision.md** (lista observable y anti-patrones).
|
|
130
|
+
Regla de oro: **nunca te sales del sistema**; si algo no se puede hacer con componentes y variables, se anota como hueco.
|
|
131
|
+
|
|
132
|
+
- `orbital-ds context` (o `--json`): el estado real de la app para un agente (tema, marca, extras, componentes con
|
|
133
|
+
sus notas, patrones). Las notas de uso de cada componente se escriben en el propio fichero con `@note`.
|
|
134
|
+
- `orbital-ds skill`: instala en la app el skill de Claude Code **orbital-ds-designer** (`.claude/skills/`). Es fino:
|
|
135
|
+
lee esta documentación del paquete instalado, así que se actualiza con cada versión; `orbital-ds skill --check` en
|
|
136
|
+
el verify avisa si quedó de otra versión. El asistente lo ofrece en sus extras.
|
|
103
137
|
|
|
104
138
|
## Cómo comprobar tu trabajo
|
|
105
139
|
|
|
@@ -144,6 +178,26 @@ personalidad use **solo variables** (ni medidas, ni colores, ni pesos) y que est
|
|
|
144
178
|
**familias completas** de piezas (`slotFamilies` en `contract.json`: si das tinta al
|
|
145
179
|
`checkbox`, también al `radio-group-item`).
|
|
146
180
|
|
|
181
|
+
## Adaptar un sistema corporativo (p. ej. Fractalia)
|
|
182
|
+
|
|
183
|
+
Se adapta el sistema al modelo, nunca al revés (decisión y plan: `docs/adr/0002-sistemas-corporativos-al-modelo.md`):
|
|
184
|
+
|
|
185
|
+
1. **Valores a los huecos.** Cada valor de su DS va a la variable pública que ya lo cubre (`--ds-radius-button`,
|
|
186
|
+
`--ds-field-bg`, `--ds-switch-track-off`, `--ds-*-weight`…). La personalidad solo para lo que ningún hueco
|
|
187
|
+
cubre. El doctor avisa si una regla pinta una propiedad que tiene hueco (`slotTokens` del contrato).
|
|
188
|
+
2. **Si falta el hueco, se añade** al núcleo con un valor que deje igual a los demás temas (p. ej. el
|
|
189
|
+
desactivado con color: `--ds-button-disabled-bg/-fg/-border`, opcionales con respaldo por variante).
|
|
190
|
+
3. **Pesos cargados = pesos usados**: el doctor avisa si una `--ds-*-weight` pide un peso que `<tema>.fonts.css`
|
|
191
|
+
no carga.
|
|
192
|
+
4. **Sus componentes van al núcleo, genéricos** (nunca CSS de componentes dentro de un tema): antes de crear,
|
|
193
|
+
busca en el manifiesto y amplía (solo añadir). Tono con el vocabulario común (`DsDataTone`); el significado
|
|
194
|
+
de dominio (riesgo bajo/medio/alto) lo traduce la app. Medidas y efectos en `--ds-<pieza>-*`; animación con
|
|
195
|
+
CSS y el ritmo del tema (`--ds-motion-pulse`, `--ds-ease-pulse`), quieta con movimiento reducido.
|
|
196
|
+
Piezas de estado y progreso: `Shield`/`ShieldRadar`, `Gauge`, `PasswordStrength`, `StepDots`, `StepRing`,
|
|
197
|
+
`TaskProgress`, `LevelMeter`, `StatusHero`, `TaskLoader` y `StatusDot size`. Pista común: `--ds-track-bg`.
|
|
198
|
+
5. **Fidelidad comprobada**: compara el valor efectivo de cada propiedad antes y después de traducir (claro y
|
|
199
|
+
oscuro); solo deben cambiar los valores de su DS que antes no se aplicaban.
|
|
200
|
+
|
|
147
201
|
## Estándar de integración (cómo debe ajustarse una app)
|
|
148
202
|
|
|
149
203
|
Para que una app (o un agente que la edite) use orbital-ds sin romper nada:
|
|
@@ -152,14 +206,16 @@ Para que una app (o un agente que la edite) use orbital-ds sin romper nada:
|
|
|
152
206
|
2. **Solo variables públicas.** Nada de variables privadas de un tema: pueden renombrarse. Usa `--ds-*` y los tokens del contrato (`--zw-*` de `tactile` están obsoletas: usa `--ds-key-outline`, `--ds-key-edge` y `--ds-marker`).
|
|
153
207
|
3. **Sin `!important` ni selectores propios** para vencer a la librería (lateral, raíl, botones). Si algo no se puede ajustar con un token, es un hueco de la librería: abre un issue.
|
|
154
208
|
4. **El tema se elige con un solo `@import`** (o `pnpm theme`). Los temas con ámbito (`*.scoped.css`) son solo para un banco de pruebas; la marca (`brand.css`) gana siempre, también sobre ellos.
|
|
155
|
-
5. **Patrón de página.** La cabecera lleva solo botón de menú, título y, siempre visibles, idioma y tema (y avisos si la app los tiene). El subtítulo y las acciones de la vista van al inicio del contenido, centrado en un ancho máximo; solo un lienzo (mapa, kanban, editor) ocupa todo el ancho.
|
|
156
|
-
6. **
|
|
157
|
-
7.
|
|
209
|
+
5. **Patrón de página.** La cabecera lleva solo botón de menú, título y, siempre visibles, idioma y tema (y avisos si la app los tiene). **Opcional: un buscador o paleta de comandos** («Ir a…», ⌘K) cuando es la navegación principal de la app: en escritorio, un `InputGroup` compacto que abre `Command`; en móvil, solo el botón con el icono de búsqueda. El subtítulo y las acciones de la vista van al inicio del contenido, centrado en un ancho máximo; solo un lienzo (mapa, kanban, editor) ocupa todo el ancho.
|
|
210
|
+
6. **Listas de entidades** (agentes, herramientas, dispositivos): `Item variant="card"` con su `ItemMedia` (o `IconTile`), `ItemContent` y `ItemActions`. Toma el gesto de la tarjeta de cada tema (filete y arista en tactile, sin borde en fractalia…); no compongas `Card` + `Item` a mano.
|
|
211
|
+
7. **`Select` con `items`.** Pasa la lista `{ value, label }` al `Select` para que el disparador muestre la etiqueta y no el valor antes de abrirse (también en el HTML del servidor). La lista se abre debajo del campo, al menos tan ancha como él y con ≈ 8 filas (`--ds-select-max-h`).
|
|
212
|
+
8. **Cada tema se documenta y se elige informado.** Lee `orbital-ds/themes/<tema>.guide.md` y su ficha `<tema>.meta.json` (esencia, gesto firma, paleta, accesibilidad, qué valores son aproximados) antes de usar o ajustar un tema.
|
|
213
|
+
9. **Comprueba antes de dar algo por bueno:** `pnpm exec orbital-ds doctor --css src/brand.css --ui src` (marca y vistas: nada fuera del sistema) y el `verify` de la app.
|
|
158
214
|
|
|
159
215
|
### Accesibilidad (WCAG 2.2)
|
|
160
216
|
|
|
161
217
|
- **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.
|
|
162
218
|
- **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.
|
|
163
|
-
- **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.
|
|
219
|
+
- **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).
|
|
164
220
|
- **Foco siempre visible** (anillo de 3:1 como mínimo) y sin que otro elemento lo tape.
|
|
165
221
|
- **Una marca nueva debe volver a pasar el doctor.** Cambiar `--primary` obliga a revisar `--primary-foreground`, `--link` y `--ring`.
|
package/README.md
CHANGED
|
@@ -1,87 +1,93 @@
|
|
|
1
|
-
# orbital-ds
|
|
2
|
-
|
|
3
|
-
Sistema de diseño genérico: **estructura común + temas intercambiables + ~60 componentes**
|
|
4
|
-
sobre [Base UI](https://base-ui.com) y Tailwind v4 (los de shadcn en su versión Base UI).
|
|
5
|
-
|
|
6
|
-
- `styles.css` — la ESTRUCTURA: mapea variables de tema a utilidades de Tailwind y define los
|
|
7
|
-
tokens semánticos (radios, alturas, sombras, espaciado, capas, movimiento, foco, materiales)
|
|
8
|
-
y la capa base. No lleva colores ni fuentes.
|
|
9
|
-
- `themes/<tema>.css` — un TEMA: paleta (claro/oscuro), radio base y tipografía.
|
|
10
|
-
Hoy: `qratia
|
|
11
|
-
|
|
12
|
-
- `
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
@import '
|
|
21
|
-
@
|
|
22
|
-
@
|
|
23
|
-
@import '
|
|
24
|
-
@import 'orbital-ds/
|
|
25
|
-
@
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
pnpm exec orbital-ds-init
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
`--
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
##
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
1
|
+
# orbital-ds
|
|
2
|
+
|
|
3
|
+
Sistema de diseño genérico: **estructura común + temas intercambiables + ~60 componentes**
|
|
4
|
+
sobre [Base UI](https://base-ui.com) y Tailwind v4 (los de shadcn en su versión Base UI).
|
|
5
|
+
|
|
6
|
+
- `styles.css` — la ESTRUCTURA: mapea variables de tema a utilidades de Tailwind y define los
|
|
7
|
+
tokens semánticos (radios, alturas, sombras, espaciado, capas, movimiento, foco, materiales)
|
|
8
|
+
y la capa base. No lleva colores ni fuentes.
|
|
9
|
+
- `themes/<tema>.css` — un TEMA: paleta (claro/oscuro), radio base y tipografía.
|
|
10
|
+
Hoy: `qratia`, `zyro` (cristal), `friendly`, `twitter`, `tactile` y `fractalia` (sistema corporativo de
|
|
11
|
+
Fractalia, para usarlo fiel). Añadir otro = añadir otro fichero.
|
|
12
|
+
- `themes/<tema>.fonts.css` — las fuentes del tema (un `@import url()`; va el primero).
|
|
13
|
+
- `ui/*` — componentes, uno por fichero (`orbital-ds/ui/button`, …): quien no usa gráficos
|
|
14
|
+
no necesita `recharts`, quien no usa el calendario no necesita `react-day-picker`.
|
|
15
|
+
- `contract.json` + `pnpm check:ds` — el contrato de tema y su comprobación.
|
|
16
|
+
|
|
17
|
+
## Uso en una app (Tailwind v4)
|
|
18
|
+
|
|
19
|
+
```css
|
|
20
|
+
@import 'orbital-ds/themes/qratia.fonts.css'; /* fuentes: lo primero */
|
|
21
|
+
@import 'tailwindcss';
|
|
22
|
+
@plugin '@tailwindcss/typography';
|
|
23
|
+
@import 'tw-animate-css';
|
|
24
|
+
@import 'orbital-ds/styles.css'; /* estructura */
|
|
25
|
+
@import 'orbital-ds/themes/qratia.css'; /* tema (después de la estructura) */
|
|
26
|
+
@source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
import { Button } from 'orbital-ds/ui/button';
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Cambiar de identidad = cambiar `qratia` por `zyro` en esas dos líneas de tema/fuentes.
|
|
34
|
+
Detalle del contrato, tokens y reglas de nombres en [`docs/CONTRACT.md`](docs/CONTRACT.md).
|
|
35
|
+
|
|
36
|
+
## Generar la marca desde un color (asistente)
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
pnpm exec orbital-ds-init # asistente interactivo
|
|
40
|
+
pnpm exec orbital-ds-init --primary "#1D63D8" # sin preguntas (CI, scripts)
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
A partir del **color primario** (hex, `rgb()`, `hsl()` u `oklch()`) deriva en OKLCH los neutros teñidos
|
|
44
|
+
(papel, tinta, tarjeta, bordes, lateral), el texto sobre el primario, el enlace y el foco, en piel clara y
|
|
45
|
+
oscura, y **comprueba el contraste** (AA 4,5:1). Si un color no llega, lo ajusta lo mínimo y te lo dice.
|
|
46
|
+
Escribe solo un bloque delimitado en `brand.css`; con `--update` lo reescribe y lo tuyo de fuera no se
|
|
47
|
+
toca. Opciones: `--theme`, `--accent`, `--no-marker` (apaga el rotulador de `tactile`), `--dry-run`,
|
|
48
|
+
`--yes`, `--out`. Sin dependencias.
|
|
49
|
+
|
|
50
|
+
**Modos de marca** (`--mode`; el asistente los ofrece con el recomendado por la ficha del tema):
|
|
51
|
+
`faithful` deja el tema tal cual (lo que piden los temas de un sistema corporativo, como `fractalia`:
|
|
52
|
+
`--theme fractalia --connect`), `primary` cambia solo el primario sobre la paleta del tema y `full`
|
|
53
|
+
deriva la paleta entera.
|
|
54
|
+
|
|
55
|
+
## Guía de cada tema
|
|
56
|
+
|
|
57
|
+
Cada tema lleva su documentación, que viaja con el paquete:
|
|
58
|
+
|
|
59
|
+
- `orbital-ds/themes/<tema>.guide.md` — guía de diseño: esencia, gesto firma, principios, referencias (qué se tomó de cada una), paleta, tipografía, formas, accesibilidad y estado de los valores (confirmados, aproximados o de diseño propio).
|
|
60
|
+
- `orbital-ds/themes/<tema>.meta.json` — la misma ficha legible por máquina.
|
|
61
|
+
|
|
62
|
+
`pnpm check:ds` falla si a un tema le falta alguna de las dos. Un tema nuevo debe nacer con ambas.
|
|
63
|
+
|
|
64
|
+
## Marca de una app
|
|
65
|
+
|
|
66
|
+
Lo propio de cada app (color principal, acento, radio, fuentes) va en **su** `src/brand.css`,
|
|
67
|
+
importado después del tema. Ninguna actualización de orbital-ds lo toca. `pnpm exec orbital-ds-init`
|
|
68
|
+
lo crea la primera vez. Detalle en [`docs/CONTRACT.md`](docs/CONTRACT.md).
|
|
69
|
+
|
|
70
|
+
## Regla
|
|
71
|
+
|
|
72
|
+
Ningún componente lleva valores propios (colores, medidas, sombras, z-index, duraciones):
|
|
73
|
+
pide un hueco a una variable. Para cambiar el aspecto se cambia el tema, no el componente.
|
|
74
|
+
Si un componente necesita un hueco nuevo, se AÑADE el token con un valor que deje el aspecto
|
|
75
|
+
como estaba. `pnpm check:ds` lo comprueba.
|
|
76
|
+
|
|
77
|
+
## Desarrollo
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pnpm install
|
|
81
|
+
pnpm verify # doctor + typecheck + build
|
|
82
|
+
pnpm check:ds # solo el contrato de tema y los valores fijos
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Peers obligatorios: `react`, `react-dom`, `@base-ui/react`, `tailwindcss`, `tailwind-merge`,
|
|
86
|
+
`class-variance-authority`, `clsx`, `lucide-react`, `tw-animate-css`.
|
|
87
|
+
Opcionales (solo si usas ese componente): `recharts`, `sonner`, `next-themes`, `cmdk`,
|
|
88
|
+
`date-fns` + `react-day-picker`, `embla-carousel-react`, `input-otp`,
|
|
89
|
+
`react-resizable-panels`, `@shadcn/react`.
|
|
90
|
+
|
|
91
|
+
## Licencia
|
|
92
|
+
|
|
93
|
+
MIT © Fractalia Systems
|