orbital-ds 0.16.0 → 0.17.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/GRAFICOS.md CHANGED
@@ -109,14 +109,21 @@ export default {
109
109
 
110
110
  ## La marca de la app en los informes
111
111
 
112
- `<tema>.tokens.json` trae los valores del **tema**. Si la app tiene marca propia (`brand.css`), mezcla sus
113
- colores en `tokens` antes de llamar:
112
+ `<tema>.tokens.json` trae los valores del **tema**. Si la app tiene marca propia (`brand.css`), mézclala en
113
+ `tokens` antes de llamar. `orbital-ds/brand` deriva la marca con el mismo cálculo que el asistente y
114
+ `withBrandTokens` la mezcla (series `chart-1…5`, textos, borde y superficie):
114
115
 
115
116
  ```ts
116
- const tokens = { ...tema.light, palette: ["#1d63d8", ...tema.light.palette.slice(1)] }
117
+ import { deriveBrand, parseColor, withBrandTokens } from "orbital-ds/brand"
118
+ import tema from "orbital-ds/themes/qratia.tokens.json"
119
+
120
+ const marca = deriveBrand(parseColor("#1d63d8")!, {})
121
+ const tokens = withBrandTokens(tema.light, marca.claro) // oscuro: (tema.dark, marca.oscuro)
117
122
  ```
118
123
 
119
- Los valores de la marca los da `pnpm exec orbital-ds-init --primary "<color>" --dry-run`.
124
+ Si la marca está escrita a mano en `brand.css`, pasa sus valores como piel:
125
+ `withBrandTokens(tema.light, { "chart-1": "#1d63d8" })`. Para ver lo que escribiría el asistente:
126
+ `pnpm exec orbital-ds-init --primary "<color>" --dry-run`.
120
127
 
121
128
  ## Seguridad
122
129
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "orbital-ds",
3
- "version": "0.16.0",
3
+ "version": "0.17.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",
@@ -32,6 +32,7 @@
32
32
  "skill",
33
33
  "scripts/manifest.mjs",
34
34
  "scripts/brand-core.mjs",
35
+ "scripts/brand-core.d.mts",
35
36
  "scripts/setup.mjs",
36
37
  "scripts/brand-file.mjs",
37
38
  "scripts/i18n.mjs"
@@ -55,6 +56,10 @@
55
56
  "types": "./dist/hooks/*.d.ts",
56
57
  "import": "./dist/hooks/*.js"
57
58
  },
59
+ "./brand": {
60
+ "types": "./scripts/brand-core.d.mts",
61
+ "import": "./scripts/brand-core.mjs"
62
+ },
58
63
  "./package.json": "./package.json",
59
64
  "./contract.json": "./contract.json",
60
65
  "./components.manifest.json": "./components.manifest.json"
@@ -0,0 +1,48 @@
1
+ /** Tipos de `orbital-ds/brand` (núcleo de marca: scripts/brand-core.mjs). */
2
+ export type Rgb = { r: number; g: number; b: number }
3
+ export type Oklch = { l: number; c: number; h: number }
4
+ /** Tokens de una piel, sin el prefijo `--` (p. ej. `primary`, `ring`, `chart-1`). */
5
+ export type BrandSkin = Record<string, string>
6
+ export interface BrandBase { papel?: Rgb; tinta?: Rgb; fondoO?: Rgb; textoO?: Rgb }
7
+ export interface BrandOptions {
8
+ acento?: Rgb
9
+ secundario?: Rgb | null
10
+ marcador?: boolean
11
+ gestos?: boolean
12
+ /** Neutros reales del tema: el contraste se mide contra SU lienzo. */
13
+ base?: BrandBase
14
+ }
15
+ export interface BrandResult {
16
+ claro: BrandSkin
17
+ oscuro: BrandSkin
18
+ avisos: string[]
19
+ pares: Array<{ piel: "claro" | "oscuro"; nombre: string; r: number; min: number }>
20
+ muestras: Record<string, unknown>
21
+ }
22
+ /** Forma de `<tema>.tokens.json` → `.light` / `.dark`. */
23
+ export interface ChartTokens {
24
+ palette: string[]
25
+ foreground: string
26
+ muted: string
27
+ border: string
28
+ surface: string
29
+ surfaceForeground: string
30
+ fontSans: string
31
+ fontDisplay: string
32
+ motionBaseMs: number
33
+ motionSlowMs: number
34
+ }
35
+
36
+ export function parseColor(raw: string): Rgb | null
37
+ export function rgbToOklch(c: Rgb): Oklch
38
+ export const ok: (l: number, c: number, h: number) => Rgb
39
+ export const hex: (c: Rgb) => string
40
+ export function ratio(a: Rgb, b: Rgb): number
41
+ export function derivar(primario: Rgb, opts: BrandOptions): BrandResult
42
+ export function derivarSeries(primario: Rgb, secundario: Rgb | null, lienzo: Rgb, opts?: { oscura?: boolean }): Rgb[]
43
+
44
+ export const deriveBrand: typeof derivar
45
+ export const deriveChartSeries: typeof derivarSeries
46
+ export const contrastRatio: typeof ratio
47
+ export const toHex: typeof hex
48
+ export function withBrandTokens<T extends ChartTokens>(tokens: T, skin: BrandSkin): T
@@ -2,7 +2,8 @@
2
2
  * orbital-ds · núcleo de MARCA: color (OKLCH) y derivación de una marca completa a
3
3
  * partir del primario, con comprobación de contraste. Sin dependencias ni APIs de
4
4
  * Node: lo usan `orbital-ds-init` (terminal) y el escaparate (navegador), así que
5
- * los dos calculan exactamente lo mismo.
5
+ * los dos calculan exactamente lo mismo. Público como `orbital-ds/brand` (tipos en
6
+ * brand-core.d.mts; alias en inglés al final).
6
7
  */
7
8
  /* ═══════════════════════════════ COLOR ═══════════════════════════════════════ */
8
9
  const clamp01 = (x) => Math.min(1, Math.max(0, x));
@@ -191,3 +192,30 @@ export function derivar(primario, { acento, secundario = null, marcador = true,
191
192
  return { claro, oscuro, avisos, pares, muestras: { papel, tinta, prim, suave, acentoC, fondoO, textoO, primO, seriesC, seriesO, secundario } };
192
193
  }
193
194
 
195
+
196
+ /* ═══════════════════════════ API PÚBLICA (orbital-ds/brand) ═══════════════════ */
197
+ /** Alias en inglés de la API pública. */
198
+ export const deriveBrand = derivar;
199
+ export const deriveChartSeries = derivarSeries;
200
+ export const contrastRatio = ratio;
201
+ export const toHex = hex;
202
+
203
+ /**
204
+ * Mezcla una piel de la marca (`deriveBrand(...).claro` u `.oscuro`) en los tokens de un tema
205
+ * (`<tema>.tokens.json` → `.light` / `.dark`) para `renderEChartToSvg`. Solo pisa lo que la marca
206
+ * trae: series `chart-1…5` (posiciones 0–4 de la paleta), textos, borde y superficie.
207
+ */
208
+ export function withBrandTokens(tokens, skin) {
209
+ const palette = [...tokens.palette];
210
+ for (let i = 0; i < 5; i++) if (skin[`chart-${i + 1}`]) palette[i] = skin[`chart-${i + 1}`];
211
+ const pick = (k, fb) => skin[k] ?? fb;
212
+ return {
213
+ ...tokens,
214
+ palette,
215
+ foreground: pick('foreground', tokens.foreground),
216
+ muted: pick('muted-foreground', tokens.muted),
217
+ border: pick('border', tokens.border),
218
+ surface: pick('popover', tokens.surface),
219
+ surfaceForeground: pick('popover-foreground', tokens.surfaceForeground),
220
+ };
221
+ }