orbital-ds 0.13.2 → 0.14.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/README.md CHANGED
@@ -1,93 +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`, `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
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), `liquid` (Liquid Glass de Apple), `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