orbital-ds 0.30.0 → 0.35.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 +1 -1
- package/components.manifest.json +3216 -3160
- package/dist/hooks/use-ds-messages.d.ts +39 -0
- package/dist/lib/i18n.d.ts +39 -0
- package/dist/lib/i18n.js +117 -0
- package/dist/lib/template-syntax.d.ts +22 -0
- package/dist/lib/template-syntax.js +66 -0
- package/dist/motion.css +146 -0
- package/dist/styles.css +1699 -0
- package/dist/themes/chocolate.css +259 -0
- package/dist/themes/chocolate.fonts.css +2 -0
- package/dist/themes/chocolate.guide.md +30 -0
- package/dist/themes/chocolate.meta.json +61 -0
- package/dist/themes/chocolate.scoped.css +259 -0
- package/dist/themes/chocolate.tokens.json +49 -0
- package/dist/themes/fractalia.css +556 -0
- package/dist/themes/fractalia.fonts.css +3 -0
- package/dist/themes/fractalia.guide.md +86 -0
- package/dist/themes/fractalia.meta.json +112 -0
- package/dist/themes/fractalia.scoped.css +556 -0
- package/dist/themes/fractalia.tokens.json +39 -0
- package/dist/themes/friendly.css +375 -0
- package/dist/themes/friendly.fonts.css +2 -0
- package/dist/themes/friendly.guide.md +38 -0
- package/dist/themes/friendly.meta.json +82 -0
- package/dist/themes/friendly.scoped.css +375 -0
- package/dist/themes/friendly.tokens.json +45 -0
- package/dist/themes/lagoon.css +359 -0
- package/dist/themes/lagoon.fonts.css +2 -0
- package/dist/themes/lagoon.guide.md +47 -0
- package/dist/themes/lagoon.meta.json +85 -0
- package/dist/themes/lagoon.scoped.css +359 -0
- package/dist/themes/lagoon.tokens.json +49 -0
- package/dist/themes/liquid.css +510 -0
- package/dist/themes/liquid.fonts.css +7 -0
- package/dist/themes/liquid.guide.md +82 -0
- package/dist/themes/liquid.meta.json +134 -0
- package/dist/themes/liquid.scoped.css +510 -0
- package/dist/themes/liquid.tokens.json +47 -0
- package/dist/themes/matcha.css +259 -0
- package/dist/themes/matcha.fonts.css +2 -0
- package/dist/themes/matcha.guide.md +30 -0
- package/dist/themes/matcha.meta.json +61 -0
- package/dist/themes/matcha.scoped.css +259 -0
- package/dist/themes/matcha.tokens.json +49 -0
- package/dist/themes/qratia.css +264 -0
- package/dist/themes/qratia.fonts.css +2 -0
- package/dist/themes/qratia.guide.md +34 -0
- package/dist/themes/qratia.meta.json +49 -0
- package/dist/themes/qratia.scoped.css +264 -0
- package/dist/themes/qratia.tokens.json +49 -0
- package/dist/themes/stone.css +263 -0
- package/dist/themes/stone.fonts.css +2 -0
- package/dist/themes/stone.guide.md +30 -0
- package/dist/themes/stone.meta.json +47 -0
- package/dist/themes/stone.scoped.css +263 -0
- package/dist/themes/stone.tokens.json +49 -0
- package/dist/themes/tactile.css +596 -0
- package/dist/themes/tactile.fonts.css +3 -0
- package/dist/themes/tactile.guide.md +82 -0
- package/dist/themes/tactile.meta.json +182 -0
- package/dist/themes/tactile.scoped.css +596 -0
- package/dist/themes/tactile.tokens.json +42 -0
- package/dist/themes/twitter.css +364 -0
- package/dist/themes/twitter.fonts.css +6 -0
- package/dist/themes/twitter.guide.md +35 -0
- package/dist/themes/twitter.meta.json +90 -0
- package/dist/themes/twitter.scoped.css +364 -0
- package/dist/themes/twitter.tokens.json +45 -0
- package/dist/themes/y2k.css +259 -0
- package/dist/themes/y2k.fonts.css +2 -0
- package/dist/themes/y2k.guide.md +30 -0
- package/dist/themes/y2k.meta.json +59 -0
- package/dist/themes/y2k.scoped.css +259 -0
- package/dist/themes/y2k.tokens.json +49 -0
- package/dist/themes/zyro.css +442 -0
- package/dist/themes/zyro.fonts.css +2 -0
- package/dist/themes/zyro.guide.md +33 -0
- package/dist/themes/zyro.meta.json +74 -0
- package/dist/themes/zyro.scoped.css +442 -0
- package/dist/themes/zyro.tokens.json +46 -0
- package/dist/ui/accordion.js +1 -1
- package/dist/ui/alert-dialog.js +1 -1
- package/dist/ui/alert.js +2 -2
- package/dist/ui/attachment.js +1 -1
- package/dist/ui/auth-form.js +4 -4
- package/dist/ui/auth-layout.d.ts +3 -1
- package/dist/ui/auth-layout.js +7 -4
- package/dist/ui/auth-parts.js +4 -4
- package/dist/ui/avatar.js +1 -1
- package/dist/ui/ayuda.js +1 -1
- package/dist/ui/badge.d.ts +1 -1
- package/dist/ui/badge.js +1 -1
- package/dist/ui/banner.js +1 -1
- package/dist/ui/bottom-nav.js +1 -1
- package/dist/ui/breadcrumb.js +1 -1
- package/dist/ui/bubble.d.ts +1 -1
- package/dist/ui/bubble.js +3 -3
- package/dist/ui/button-group.js +1 -1
- package/dist/ui/button.d.ts +1 -1
- package/dist/ui/button.js +4 -4
- package/dist/ui/calendar.js +6 -6
- package/dist/ui/carousel.js +4 -4
- package/dist/ui/choice-card.js +1 -1
- package/dist/ui/combobox.js +4 -4
- package/dist/ui/command.js +2 -2
- package/dist/ui/content-card.js +2 -2
- package/dist/ui/context-menu.js +9 -9
- package/dist/ui/data-table.d.ts +13 -3
- package/dist/ui/data-table.js +164 -71
- package/dist/ui/date-picker.js +1 -1
- package/dist/ui/dialog.js +1 -1
- package/dist/ui/drawer.js +5 -5
- package/dist/ui/dropdown-menu.js +9 -9
- package/dist/ui/field.js +3 -3
- package/dist/ui/heatmap-grid.js +2 -2
- package/dist/ui/input-group.js +3 -3
- package/dist/ui/input-otp.js +1 -1
- package/dist/ui/instruction-editor.d.ts +51 -0
- package/dist/ui/instruction-editor.js +263 -0
- package/dist/ui/item.d.ts +1 -1
- package/dist/ui/item.js +1 -1
- package/dist/ui/marker.d.ts +1 -1
- package/dist/ui/marker.js +2 -2
- package/dist/ui/menubar.js +8 -8
- package/dist/ui/mfa-challenge.js +3 -3
- package/dist/ui/mfa-setup.js +1 -1
- package/dist/ui/navigation-menu.js +2 -2
- package/dist/ui/oauth-consent.js +3 -3
- package/dist/ui/pagination.js +2 -2
- package/dist/ui/panel.d.ts +1 -1
- package/dist/ui/panel.js +1 -0
- package/dist/ui/passkey-list.js +1 -1
- package/dist/ui/resizable.js +1 -1
- package/dist/ui/scroll-area.js +1 -1
- package/dist/ui/session-timeout.js +1 -1
- package/dist/ui/sheet.js +2 -2
- package/dist/ui/sidebar.js +7 -7
- package/dist/ui/sign-out-dialog.js +1 -1
- package/dist/ui/sparkline.d.ts +1 -1
- package/dist/ui/status-badge.d.ts +2 -2
- package/dist/ui/switch.js +1 -1
- package/dist/ui/table.js +2 -2
- package/dist/ui/tabs.d.ts +1 -1
- package/dist/ui/tabs.js +2 -2
- package/dist/ui/toast.js +3 -3
- package/dist/ui/toggle-group.js +1 -1
- package/dist/ui/toggle.js +3 -3
- package/dist/ui/tooltip.js +2 -2
- package/docs/CONTRACT.md +224 -224
- package/package.json +218 -188
- package/scripts/brand-core.mjs +20 -1
- package/scripts/cli.mjs +457 -457
- package/scripts/doctor.mjs +2 -0
- package/scripts/init.mjs +1 -1
- package/scripts/manifest.mjs +100 -100
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); en desuso desde 0.30: la estructura ya no lo dibuja; se conservan por compatibilidad |
|
|
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.
|
|
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); en desuso desde 0.30: la estructura ya no lo dibuja; se conservan por compatibilidad |
|
|
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 · grouped · tree), `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.
|