orbital-ds 0.12.0 → 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.
Files changed (57) hide show
  1. package/AGENTS.md +32 -4
  2. package/README.md +93 -93
  3. package/components.manifest.json +66 -14
  4. package/dist/motion.css +139 -0
  5. package/dist/styles.css +15 -2
  6. package/dist/themes/fractalia.css +473 -464
  7. package/dist/themes/fractalia.fonts.css +3 -3
  8. package/dist/themes/fractalia.guide.md +79 -77
  9. package/dist/themes/fractalia.meta.json +99 -96
  10. package/dist/themes/fractalia.scoped.css +473 -464
  11. package/dist/themes/friendly.css +7 -1
  12. package/dist/themes/friendly.meta.json +7 -0
  13. package/dist/themes/friendly.scoped.css +7 -1
  14. package/dist/themes/qratia.css +13 -8
  15. package/dist/themes/qratia.meta.json +8 -1
  16. package/dist/themes/qratia.scoped.css +13 -8
  17. package/dist/themes/tactile.css +7 -1
  18. package/dist/themes/tactile.meta.json +7 -0
  19. package/dist/themes/tactile.scoped.css +7 -1
  20. package/dist/themes/twitter.css +7 -1
  21. package/dist/themes/twitter.meta.json +7 -0
  22. package/dist/themes/twitter.scoped.css +7 -1
  23. package/dist/themes/zyro.css +7 -1
  24. package/dist/themes/zyro.meta.json +7 -0
  25. package/dist/themes/zyro.scoped.css +7 -1
  26. package/dist/ui/alert.js +6 -5
  27. package/dist/ui/attachment.d.ts +1 -1
  28. package/dist/ui/badge.js +6 -6
  29. package/dist/ui/banner.js +4 -4
  30. package/dist/ui/button.d.ts +1 -1
  31. package/dist/ui/combobox.js +1 -1
  32. package/dist/ui/context-menu.js +4 -4
  33. package/dist/ui/dropdown-menu.js +4 -4
  34. package/dist/ui/input-group.d.ts +1 -1
  35. package/dist/ui/item.d.ts +3 -3
  36. package/dist/ui/item.js +14 -4
  37. package/dist/ui/marker.d.ts +1 -1
  38. package/dist/ui/menubar.js +4 -4
  39. package/dist/ui/native-select.js +2 -2
  40. package/dist/ui/select.js +7 -8
  41. package/dist/ui/stat.d.ts +11 -1
  42. package/dist/ui/stat.js +13 -3
  43. package/dist/ui/status-badge.js +6 -6
  44. package/docs/adr/0002-sistemas-corporativos-al-modelo.md +176 -176
  45. package/docs/designer/flujo.md +79 -0
  46. package/docs/designer/patrones.md +116 -0
  47. package/docs/designer/revision.md +60 -0
  48. package/docs/designer/ux.md +71 -0
  49. package/package.json +9 -2
  50. package/scripts/brand-core.mjs +51 -13
  51. package/scripts/cli.mjs +370 -0
  52. package/scripts/doctor.mjs +578 -509
  53. package/scripts/init.mjs +187 -125
  54. package/scripts/manifest.mjs +85 -79
  55. package/scripts/setup.mjs +2 -1
  56. package/scripts/skill.mjs +67 -0
  57. package/skill/SKILL.md +47 -0
@@ -90,7 +90,7 @@ function MenubarItem({
90
90
  "data-inset": inset,
91
91
  "data-variant": variant,
92
92
  className: cn(
93
- "group/menubar-item gap-2.5 rounded-item px-(--ds-menu-item-px) py-(--ds-menu-item-py) text-sm focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-9.5 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:opacity-(--ds-disabled-opacity) [&_svg:not([class*='size-'])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive!",
93
+ "group/menubar-item gap-2.5 rounded-item px-(--ds-menu-item-px) py-(--ds-menu-item-py) text-sm data-highlighted:bg-accent data-highlighted:text-accent-foreground not-data-[variant=destructive]:data-highlighted:**:text-accent-foreground data-inset:pl-9.5 data-[variant=destructive]:text-destructive data-[variant=destructive]:data-highlighted:bg-destructive/10 data-[variant=destructive]:data-highlighted:text-destructive dark:data-[variant=destructive]:data-highlighted:bg-destructive/20 data-disabled:opacity-(--ds-disabled-opacity) [&_svg:not([class*='size-'])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive!",
94
94
  className
95
95
  ),
96
96
  ...props
@@ -110,7 +110,7 @@ function MenubarCheckboxItem({
110
110
  "data-slot": "menubar-checkbox-item",
111
111
  "data-inset": inset,
112
112
  className: cn(
113
- "relative flex cursor-default items-center gap-2.5 rounded-item py-(--ds-menu-item-py) pr-(--ds-menu-item-px) pl-9.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-9.5 data-disabled:pointer-events-none data-disabled:opacity-(--ds-disabled-opacity) [&_svg]:pointer-events-none [&_svg]:shrink-0",
113
+ "relative flex cursor-default items-center gap-2.5 rounded-item py-(--ds-menu-item-py) pr-(--ds-menu-item-px) pl-9.5 text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-highlighted:**:text-accent-foreground data-inset:pl-9.5 data-disabled:pointer-events-none data-disabled:opacity-(--ds-disabled-opacity) [&_svg]:pointer-events-none [&_svg]:shrink-0",
114
114
  className
115
115
  ),
116
116
  checked,
@@ -142,7 +142,7 @@ function MenubarRadioItem({
142
142
  "data-slot": "menubar-radio-item",
143
143
  "data-inset": inset,
144
144
  className: cn(
145
- "relative flex cursor-default items-center gap-2.5 rounded-item py-(--ds-menu-item-py) pr-(--ds-menu-item-px) pl-9.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-9.5 data-disabled:pointer-events-none data-disabled:opacity-(--ds-disabled-opacity) [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
145
+ "relative flex cursor-default items-center gap-2.5 rounded-item py-(--ds-menu-item-py) pr-(--ds-menu-item-px) pl-9.5 text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-highlighted:**:text-accent-foreground data-inset:pl-9.5 data-disabled:pointer-events-none data-disabled:opacity-(--ds-disabled-opacity) [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
146
146
  className
147
147
  ),
148
148
  ...props,
@@ -219,7 +219,7 @@ function MenubarSubTrigger({
219
219
  "data-slot": "menubar-sub-trigger",
220
220
  "data-inset": inset,
221
221
  className: cn(
222
- "gap-2 rounded-item px-(--ds-menu-item-px) py-(--ds-menu-item-py) text-sm focus:bg-accent focus:text-accent-foreground data-inset:pl-9.5 data-open:bg-accent data-open:text-accent-foreground [&_svg:not([class*='size-'])]:size-4",
222
+ "gap-2 rounded-item px-(--ds-menu-item-px) py-(--ds-menu-item-py) text-sm data-highlighted:bg-accent data-highlighted:text-accent-foreground data-inset:pl-9.5 data-open:bg-accent data-open:text-accent-foreground [&_svg:not([class*='size-'])]:size-4",
223
223
  className
224
224
  ),
225
225
  ...props
@@ -21,11 +21,11 @@ function NativeSelect({
21
21
  {
22
22
  "data-slot": "native-select",
23
23
  "data-size": size,
24
- className: "h-(--ds-control-h-md) w-full min-w-0 appearance-none rounded-control shadow-control border border-input bg-(--ds-field-bg) py-1 pr-8 pl-(--ds-field-px) text-sm transition-colors duration-(--ds-motion-snap) outline-none select-none selection:bg-primary selection:text-primary-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-(length:--ds-ring-width) focus-visible:ring-(--ds-ring-color) disabled:pointer-events-none disabled:cursor-not-allowed aria-invalid:border-(--ds-invalid-border) aria-invalid:ring-(length:--ds-ring-width) aria-invalid:ring-(--ds-invalid-ring) data-[size=sm]:h-(--ds-control-h-sm) dark:hover:bg-(--ds-field-bg-hover)",
24
+ className: "h-(--ds-control-h-md) w-full min-w-0 cursor-pointer appearance-none rounded-control shadow-control border border-input bg-(--ds-field-bg) py-1 pe-8 ps-(--ds-field-px) text-sm transition-colors duration-(--ds-motion-snap) outline-none select-none selection:bg-primary selection:text-primary-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-(length:--ds-ring-width) focus-visible:ring-(--ds-ring-color) disabled:pointer-events-none disabled:cursor-not-allowed aria-invalid:border-(--ds-invalid-border) aria-invalid:ring-(length:--ds-ring-width) aria-invalid:ring-(--ds-invalid-ring) data-[size=sm]:h-(--ds-control-h-sm) hover:bg-(--ds-field-bg-hover)",
25
25
  ...props
26
26
  }
27
27
  ),
28
- /* @__PURE__ */ jsx(ChevronDownIcon, { className: "pointer-events-none absolute top-1/2 right-3.5 size-4 -translate-y-1/2 text-muted-foreground select-none", "aria-hidden": "true", "data-slot": "native-select-icon" })
28
+ /* @__PURE__ */ jsx(ChevronDownIcon, { className: "pointer-events-none absolute top-1/2 end-3.5 size-4 -translate-y-1/2 text-muted-foreground select-none", "aria-hidden": "true", "data-slot": "native-select-icon" })
29
29
  ]
30
30
  }
31
31
  );
package/dist/ui/select.js CHANGED
@@ -28,7 +28,7 @@ function SelectTrigger({
28
28
  "data-slot": "select-trigger",
29
29
  "data-size": size,
30
30
  className: cn(
31
- "flex w-fit items-center justify-between gap-1.5 rounded-control shadow-control border border-input bg-(--ds-field-bg) px-(--ds-field-px) py-2 text-sm whitespace-nowrap transition-colors duration-(--ds-motion-snap) outline-none focus-visible:border-ring focus-visible:ring-(length:--ds-ring-width) focus-visible:ring-(--ds-ring-color) disabled:cursor-not-allowed disabled:opacity-(--ds-disabled-opacity) aria-invalid:border-(--ds-invalid-border) aria-invalid:ring-(length:--ds-ring-width) aria-invalid:ring-(--ds-invalid-ring) data-placeholder:text-muted-foreground data-[size=default]:h-(--ds-control-h-md) data-[size=sm]:h-(--ds-control-h-sm) *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 dark:hover:bg-(--ds-field-bg-hover) [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
31
+ "flex w-fit items-center justify-between gap-1.5 rounded-control shadow-control border border-input bg-(--ds-field-bg) px-(--ds-field-px) py-2 text-sm whitespace-nowrap transition-colors duration-(--ds-motion-snap) outline-none focus-visible:border-ring focus-visible:ring-(length:--ds-ring-width) focus-visible:ring-(--ds-ring-color) disabled:cursor-not-allowed disabled:opacity-(--ds-disabled-opacity) aria-invalid:border-(--ds-invalid-border) aria-invalid:ring-(length:--ds-ring-width) aria-invalid:ring-(--ds-invalid-ring) data-placeholder:text-muted-foreground data-[size=default]:h-(--ds-control-h-md) data-[size=sm]:h-(--ds-control-h-sm) *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 cursor-pointer hover:bg-(--ds-field-bg-hover) data-popup-open:bg-(--ds-field-bg-hover) [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
32
32
  className
33
33
  ),
34
34
  ...props,
@@ -47,8 +47,8 @@ function SelectTrigger({
47
47
  function SelectContent({
48
48
  className,
49
49
  children,
50
- position = "item-aligned",
51
- align = "center",
50
+ position = "popper",
51
+ align = "start",
52
52
  ...props
53
53
  }) {
54
54
  const alignItemWithTrigger = position === "item-aligned";
@@ -69,7 +69,7 @@ function SelectContent({
69
69
  "data-slot": "select-content",
70
70
  "data-align-trigger": alignItemWithTrigger,
71
71
  className: cn(
72
- "relative z-(--ds-z-overlay) max-h-(--available-height) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-popover bg-popover text-popover-foreground shadow-popover ring-(length:--ds-layer-ring-w) ring-(--ds-layer-ring) duration-(--ds-motion-fast) data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
72
+ "relative z-(--ds-z-overlay) max-h-[min(var(--available-height),var(--ds-select-max-h))] min-w-[max(var(--anchor-width),var(--ds-select-min-w))] max-w-(--ds-select-max-w) origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-popover bg-popover text-popover-foreground shadow-popover ring-(length:--ds-layer-ring-w) ring-(--ds-layer-ring) duration-(--ds-motion-fast) data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
73
73
  className
74
74
  ),
75
75
  ...props,
@@ -80,8 +80,7 @@ function SelectContent({
80
80
  {
81
81
  "data-position": alignItemWithTrigger ? "item-aligned" : "popper",
82
82
  className: cn(
83
- "data-[position=popper]:h-(--anchor-height) data-[position=popper]:w-full data-[position=popper]:min-w-(--anchor-width)",
84
- !alignItemWithTrigger && ""
83
+ "data-[position=popper]:w-full"
85
84
  ),
86
85
  children
87
86
  }
@@ -116,12 +115,12 @@ function SelectItem({
116
115
  {
117
116
  "data-slot": "select-item",
118
117
  className: cn(
119
- "relative flex w-full cursor-default items-center gap-2.5 rounded-item py-(--ds-menu-item-py) pr-8 pl-(--ds-menu-item-px) text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-(--ds-disabled-opacity) [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
118
+ "relative flex w-full cursor-pointer items-center gap-2.5 rounded-item py-(--ds-menu-item-py) pe-8 ps-(--ds-menu-item-px) text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground not-data-[variant=destructive]:data-highlighted:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-(--ds-disabled-opacity) [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
120
119
  className
121
120
  ),
122
121
  ...props,
123
122
  children: [
124
- /* @__PURE__ */ jsx("span", { className: "pointer-events-none absolute right-2 flex size-4 items-center justify-center", children: /* @__PURE__ */ jsx(SelectPrimitive.ItemIndicator, { children: /* @__PURE__ */ jsx(CheckIcon, { className: "pointer-events-none" }) }) }),
123
+ /* @__PURE__ */ jsx("span", { className: "pointer-events-none absolute end-2 flex size-4 items-center justify-center", children: /* @__PURE__ */ jsx(SelectPrimitive.ItemIndicator, { children: /* @__PURE__ */ jsx(CheckIcon, { className: "pointer-events-none" }) }) }),
125
124
  /* @__PURE__ */ jsx(SelectPrimitive.ItemText, { children })
126
125
  ]
127
126
  }
package/dist/ui/stat.d.ts CHANGED
@@ -1,5 +1,8 @@
1
1
  import * as class_variance_authority_types from 'class-variance-authority/types';
2
2
  import * as React from 'react';
3
+ import { Panel } from './panel.js';
4
+ import '@base-ui/react/use-render';
5
+ import 'class-variance-authority';
3
6
 
4
7
  type StatVariant = "card" | "inline";
5
8
  type StatSize = "sm" | "md" | "lg";
@@ -13,8 +16,15 @@ type StatProps = Omit<React.ComponentProps<"div">, "ref"> & {
13
16
  /** Tamaño fijo de la cifra; sin él, se adapta al ancho del contenedor. */
14
17
  size?: StatSize;
15
18
  tone?: StatTone;
19
+ /**
20
+ * KPI PULSABLE (solo en tarjeta): render={<button type="button" />} para que, p. ej., filtre la lista
21
+ * de debajo. Lleva hover, foco y, con `pressed`, el estado activo (aria-pressed + anillo, no solo color).
22
+ */
23
+ render?: React.ComponentProps<typeof Panel>["render"];
24
+ /** Activo (filtro aplicado): aria-pressed y anillo del primario. Úsalo con render={<button />}. */
25
+ pressed?: boolean;
16
26
  };
17
- declare function Stat({ className, variant, size, tone, children, ...props }: StatProps): React.JSX.Element;
27
+ declare function Stat({ className, variant, size, tone, render, pressed, children, ...props }: StatProps): React.JSX.Element;
18
28
  declare function StatLabel({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
19
29
  type StatValueProps = Omit<React.ComponentProps<"div">, "children"> & {
20
30
  /** Número (se formatea con Intl en el idioma activo), texto ya formateado o null = sin dato. */
package/dist/ui/stat.js CHANGED
@@ -46,17 +46,27 @@ const statValueSize = {
46
46
  lg: "text-4xl",
47
47
  auto: "text-2xl @3xs/stat:text-3xl @xs/stat:text-4xl"
48
48
  };
49
- function Stat({ className, variant = "card", size, tone = "neutral", children, ...props }) {
49
+ const statPressable = "cursor-pointer text-start outline-offset-2 transition-shadow duration-(--ds-motion-fast) ease-(--ds-ease-standard) hover:shadow-card-hover focus-visible:outline-solid focus-visible:outline-(length:--ds-ring-width) focus-visible:outline-(--ds-ring-color) data-active:outline-solid data-active:outline-(length:--ds-ring-width) data-active:outline-primary motion-reduce:transition-none";
50
+ function Stat({ className, variant = "card", size, tone = "neutral", render, pressed, children, ...props }) {
50
51
  const labelId = React.useId();
51
52
  const ctx = React.useMemo(() => ({ variant, size: size ?? "auto", labelId }), [variant, size, labelId]);
53
+ const pulsable = variant === "card" && render != null;
52
54
  const shared = {
53
55
  "data-slot": "stat",
54
56
  "data-variant": variant,
55
57
  "data-size": size ?? "auto",
56
58
  "data-tone": tone,
57
- className: cn(statVariants({ variant, tone }), className)
59
+ className: cn(statVariants({ variant, tone }), pulsable && statPressable, className)
58
60
  };
59
- return /* @__PURE__ */ jsx(StatContext.Provider, { value: ctx, children: variant === "card" ? /* @__PURE__ */ jsx(Panel, { role: "group", "aria-labelledby": labelId, ...shared, ...props, children }) : /* @__PURE__ */ jsx("dl", { ...shared, ...props, children }) });
61
+ return /* @__PURE__ */ jsx(StatContext.Provider, { value: ctx, children: variant === "card" ? /* @__PURE__ */ jsx(
62
+ Panel,
63
+ {
64
+ ...pulsable ? { render, "aria-pressed": pressed, "data-active": pressed ? "" : void 0 } : { role: "group", "aria-labelledby": labelId },
65
+ ...shared,
66
+ ...props,
67
+ children
68
+ }
69
+ ) : /* @__PURE__ */ jsx("dl", { ...shared, ...props, children }) });
60
70
  }
61
71
  function StatPart({
62
72
  term = false,
@@ -63,12 +63,12 @@ const statusBadgeVariants = cva(
63
63
  }
64
64
  },
65
65
  compoundVariants: [
66
- // Suave: fondo -soft y texto del estado (pares AA comprobados por check:ds).
67
- { variant: "soft", level: "critical", className: "bg-danger-soft text-danger" },
68
- { variant: "soft", level: "warning", className: "bg-warning-soft text-warning" },
69
- { variant: "soft", level: "ok", className: "bg-success-soft text-success" },
70
- { variant: "soft", level: "info", className: "bg-info-soft text-info" },
71
- { variant: "soft", level: "neutral", className: "bg-neutral-soft text-neutral" },
66
+ // Suave: fondo -soft y texto del estado o, con --ds-on-soft, en tinta (pares AA comprobados por check:ds).
67
+ { variant: "soft", level: "critical", className: "bg-danger-soft text-[color:var(--ds-on-soft,var(--danger))]" },
68
+ { variant: "soft", level: "warning", className: "bg-warning-soft text-[color:var(--ds-on-soft,var(--warning))]" },
69
+ { variant: "soft", level: "ok", className: "bg-success-soft text-[color:var(--ds-on-soft,var(--success))]" },
70
+ { variant: "soft", level: "info", className: "bg-info-soft text-[color:var(--ds-on-soft,var(--info))]" },
71
+ { variant: "soft", level: "neutral", className: "bg-neutral-soft text-[color:var(--ds-on-soft,var(--neutral))]" },
72
72
  // Contorno: filete del estado y texto del estado sobre el fondo de campo.
73
73
  { variant: "outline", level: "critical", className: "border-danger/50 text-danger" },
74
74
  { variant: "outline", level: "warning", className: "border-warning/50 text-warning" },
@@ -1,176 +1,176 @@
1
- # ADR 0002 — Adaptar un sistema corporativo (Fractalia) al modelo de orbital-ds
2
-
3
- - **Estado:** propuesta (análisis previo a implementar)
4
- - **Fecha:** 2026-10-13
5
- - **Origen:** tema `fractalia` (`src/themes/fractalia.*`) y su capa de componentes propia
6
- (`fractalia.components.css` + `fractalia.components.md`, siete piezas: gauge, escudo, estado,
7
- progreso, fuerza de contraseña, stepper y loader).
8
-
9
- ## Principio
10
-
11
- **Se adapta el sistema corporativo a nuestro modelo, nunca al revés.**
12
-
13
- | Capa | Qué aporta Fractalia | Dónde vive |
14
- |---|---|---|
15
- | Valores (color, forma, medidas, tipo, movimiento) | los de su DS | variables del tema `fractalia.css` (y la marca de cada app en su `brand.css`) |
16
- | Personalidad (gesto firma) | píldora en mayúsculas, pestaña activa rellena… | sección PERSONALIDAD del tema, **solo con tokens públicos** |
17
- | Componentes | las siete piezas | **núcleo** (`src/ui/`), genéricos, reutilizables por cualquier tema |
18
-
19
- Un tema **no trae componentes**. Si una pieza de Fractalia no existe en el núcleo, se crea en el
20
- núcleo con API genérica y tokens `--ds-*`; Fractalia solo le da sus valores. Así la misma pieza sirve
21
- en qratia, tactile o cualquier tema futuro, y Fractalia se ve fiel.
22
-
23
- ---
24
-
25
- ## 1. Qué ha supuesto el tema `fractalia` (ya hecho en `feat/fractalia-wizard`)
26
-
27
- - Cumple el contrato y es `strict`. Correcciones necesarias (sin cambio visual): familias «choice»
28
- (`radio-group-item`) y «title» (`drawer-title`, `empty-title`) completas.
29
- - Tres pares de su propio DS bajo AA (texto de estado sobre su fondo suave: danger 4.19, warning 4.23,
30
- neutral 4.41): **declarados** en `a11y.exceptions` de la ficha (el doctor avisa, no falla). El doctor
31
- acepta ahora excepciones también en estos pares.
32
- - `"branding": "faithful"`: el asistente recomienda usarlo **fiel**. Antes derivaba siempre la paleta
33
- entera desde un color y habría borrado su identidad; ahora tiene tres modos (fiel / solo primario /
34
- completo) y enseña la ficha del tema antes de aplicar.
35
- - Genera `fractalia.tokens.json` (informes con ECharts) y su versión con ámbito; el escaparate lo
36
- descubre solo.
37
-
38
- ## 2. Hallazgos del análisis
39
-
40
- ### H1 · El tema rodea tokens públicos con variables privadas
41
-
42
- La personalidad de fractalia pinta con `--zf-*` propiedades que el núcleo YA expone como token
43
- público. Resultado: una app no puede ajustarlas desde `brand.css` con el nombre estándar, y otro tema
44
- que copie fractalia hereda el atajo.
45
-
46
- | Regla de fractalia | Token público que ya existe | Adaptación |
47
- |---|---|---|
48
- | `button { border-radius: var(--zf-radius-label) }` | `--ds-radius-button` | `--ds-radius-button: 32px` y quitar la regla |
49
- | `badge { border-radius: … }` | `--ds-radius-badge` | `--ds-radius-badge: 32px` |
50
- | `tabs-trigger/toggle { border-radius: … }` | `--ds-radius-tab` | `--ds-radius-tab: 32px` (el contenedor, `--ds-radius-tab` + `--ds-tabs-list-p`) |
51
- | campos `background: var(--zf-field-bg)` | `--ds-field-bg` (16 componentes lo leen) | `--ds-field-bg: #ecf1f8` y quitar la regla de familia «field» |
52
- | `switch` apagado `background: var(--zf-track-off)` | `--ds-switch-track-off` | `--ds-switch-track-off: #c8cdd8` |
53
- | títulos `font-weight: var(--zf-heading-weight)` | `--ds-title-weight`, `--ds-overlay-title-weight` | fijarlos a 700 |
54
- | foco `outline: 2px … offset 2px` | `--ds-ring-width`, `--ds-ring-color` | `--ds-ring-width: 2px`; falta `--ds-ring-offset` (ver H4) |
55
- | hover primario `--zf-primary-hover` | `--brand-bright` (mismo valor en claro) | apoyar el hover en un token público (ver H4) |
56
-
57
- ### H2 · Huecos del núcleo que fractalia deja con el valor neutro aunque su DS los define
58
-
59
- | Token | Valor neutro (núcleo) | Valor del DS de Fractalia | Fuente |
60
- |---|---|---|---|
61
- | `--ds-radius-track` | radio lg (12px en fractalia) | **4px** | progress-bar |
62
- | `--ds-track-h` | 0.75rem | 12px (coincide) | progress-bar |
63
- | `--ds-step-size` | 2rem | **34px** (24 en móvil) | empresa-item-step |
64
- | `--ds-status-dot` | 0.5rem | **12px** (16 / 24) | status-ball |
65
- | `--ds-legend-swatch` | 0.625rem | **8px** | leyendas de gráficas |
66
- | `--ds-motion-pulse` | 2 × parpadeo | **1500ms** · `cubic-bezier(.4,0,.6,1)` | motion-duration.pulse |
67
- | `--ds-badge-px` / `--ds-badge-py` | 0.625rem / … | **8px / 2px** | tag |
68
- | `--ds-ring-width` | 3px | **2px** | focus |
69
- | `--ds-radius-check`, `--ds-check-size` | 6px, 1rem | según checkbox.md | checkbox |
70
-
71
- ### H3 · Pesos de letra: el tema carga 400/700 y el núcleo pide 500 y 600
72
-
73
- - Tokens del núcleo con 500 (`--ds-nav-weight`, `--ds-tab-weight`, `--ds-table-head-weight`,
74
- `--ds-overlay-title-weight`) y 600 (`--ds-title-weight`, `--ds-button-weight`, `--ds-strong-weight`…).
75
- Con Roboto 400/700, el navegador pinta 500 como **400** y 600 como **700**: el aspecto no es el del DS.
76
- **Adaptación:** fractalia fija todos los `--ds-*-weight` a 400 o 700.
77
- - **Hueco del núcleo:** 31 usos de `font-medium` (y 1 `font-semibold`) escritos a mano en 25
78
- componentes. Ningún tema puede cambiarlos. **Propuesta:** token `--ds-medium-weight` (500 por defecto,
79
- sin cambio visual) y sustituir esas clases. Beneficia a cualquier tema con pocas variantes de fuente.
80
-
81
- ### H4 · Huecos que faltan en el núcleo (para no necesitar privadas)
82
-
83
- | Necesidad (genérica, no solo de Fractalia) | Token propuesto | Valor neutro (aspecto actual) |
84
- |---|---|---|
85
- | Desactivado con color, no con opacidad | `--ds-button-disabled-bg`, `-fg`, `-border` (**opcionales**: sin definir, cada variante usa su color de respaldo) + `--ds-button-disabled-opacity` | sin definir → opacidad `--ds-disabled-opacity`, como hoy |
86
- | Hover del botón primario con otro color | `--ds-button-primary-hover`, `-hover-fg` | `color-mix(in oklab, var(--primary) 80%, transparent)` (= `bg-primary/80`) |
87
- | Colores del botón outline / secundario | `--ds-button-outline-bg`, `-fg`, `-border`, `--ds-button-secondary-border` | los de siempre |
88
- | Radio del contenedor de pestañas · peso de la insignia | `--ds-radius-tabs-list`, `--ds-badge-weight` | radio de control · peso de etiqueta |
89
- | Separación del anillo de foco | `--ds-ring-offset` | 0 |
90
- | Capas de estado (hover / pulsado) | `--ds-state-hover`, `--ds-state-press` | los valores que hoy usa cada componente |
91
-
92
- Se añaden con valor neutro (nada cambia en los otros temas) y fractalia los rellena.
93
-
94
- ### H5 · Cinco vocabularios de tono
95
-
96
- El núcleo ya tiene cuatro: `StatusLevel` (`critical·warning·ok·info·neutral·none`), `DsDataTone`
97
- (`primary·info·success·warning·danger·neutral·chart-1…5`), `StatTone` (`good·warn·bad·neutral`) y
98
- `StepStatus`. Fractalia trae un quinto (`low/medium/high`, `protected/alert`, `pending`, `analyzing`,
99
- `pink/orange/purple`).
100
-
101
- **Estándar:** las piezas nuevas usan `DsDataTone` como único vocabulario de color. El significado de
102
- dominio (riesgo bajo/medio/alto, protegido/alerta) lo traduce la app o un mapa documentado en la pieza
103
- (`low → success`, `medium → warning`, `high → danger`, `analyzing/pending → neutral`). No se renombra
104
- nada existente (sería versión mayor); `StatusLevel` y `StatTone` siguen como alias.
105
- **Pendiente:** los tonos decorativos pink/orange/purple (2.0–2.6:1, solo UI no textual) no caben en
106
- los semánticos; o se usan las series `chart-*` o se crea una paleta decorativa pública (decisión).
107
-
108
- ### H6 · La capa de componentes rompe piezas existentes
109
-
110
- Usa cinco `data-slot` que ya son del núcleo: `progress`, `progress-track`, `stepper`, `stepper-item`,
111
- `status-badge`. Importarla cambia el aspecto de `Progress`, `Stepper` y `StatusBadge` en toda la app.
112
- **No se importa nunca tal cual.**
113
-
114
- ### H7 · La capa incumple las reglas del modelo
115
-
116
- - Colores hex, medidas en px, pesos y tamaños de letra a mano (no `strict`).
117
- - `--fc-*` duplica valores del tema (y su `.dark` repite hex).
118
- - Valores en español (`baja`, `media`, `centrado`, `data-tipo`, `nivel`): el modelo exige inglés.
119
- - Es CSS + HTML a mano: sin React, sin `data-slot` propios del núcleo, accesibilidad manual,
120
- textos sin i18n («Nivel de fuerza:», «Paso X de 5»…).
121
- - No respeta RTL salvo un caso (`status-badge`).
122
-
123
- ## 3. Mapa pieza a pieza (reutilizable por cualquier tema)
124
-
125
- | Pieza de Fractalia | ¿Existe en el núcleo? | Decisión | API genérica propuesta |
126
- |---|---|---|---|
127
- | **Gauge** (anillo 360° / arco 180°, progreso o tramos, leyenda, escala) | No (Sparkline, ProportionBar y EChart gauge son otra cosa) | **Nuevo** `Gauge` | `value` (0–max), `max`, `shape="ring\|semi"`, `tone: DsDataTone`, `segments?: {value,tone,label}[]`, partes `GaugeValue`, `GaugeLabel`, `GaugeCaption`; leyenda con el `Legend` existente; `role="meter"` + `aria-valuetext` |
128
- | **Escudo** + **radar** | No | **Nuevo** `Shield`, `ShieldRadar` | `Shield value` (0–1) o `children` (insignia), `size`; `ShieldRadar tone` con anillos animados (`--ds-motion-pulse`, reducido = quieto); `role="img"` + texto i18n; trazado del escudo genérico, tokens `--ds-shield-*` |
129
- | **Estado** dot / icon / hero / user | Parcial: `StatusDot` | **Ampliar** `StatusDot` (solo añadir `size="sm\|md\|lg"`) + **nuevo** `StatusHero` (disco con halo e insignia) | el «user» es un `Avatar` (+N): se cubre con `Avatar`/`AvatarGroup` existentes |
130
- | **Progreso** bar / estado / nivel | Parcial: `Progress`, `ProportionBar` | barra simple = `Progress` (fractalia da `--ds-radius-track`, `--ds-track-h`). **Nuevo** `TaskProgress` (etiqueta + contador + estado `idle\|running\|done\|error` + icono) y `LevelMeter` (nivel con etiqueta) | `role="progressbar"` / `meter`; textos «No iniciado / En curso / Completado» en i18n |
131
- | **Fuerza de contraseña** | No | **Nuevo** `PasswordStrength` | `score` 0–4 o `level="weak\|medium\|strong"`, `segments` (5); `role="meter"`, `aria-live`; textos en i18n |
132
- | **Stepper** dots / cuadrantes / item | Parcial: `Stepper` | **Nuevo** `StepDots` y `StepProgressRing` (cuadrantes); el item = `StepperIndicator` con `--ds-step-size` | `count`, `current`, `completed`; texto «Paso X de N» en i18n |
133
- | **Loader** ilustrado | Parcial: `Spinner` | **Nuevo** `TaskLoader` | `icon` (la ilustración la pone la app), `value?` (sin él, indeterminado), `state="running\|done"`; `role="status"` |
134
-
135
- Cada pieza nueva: un fichero en `src/ui/`, `data-slot` propio, solo tokens (`--ds-<pieza>-*` en la
136
- estructura con valor neutro), textos en en/es/pt-BR, clases lógicas (RTL), demo en el escaparate y
137
- entrada en el manifiesto. Fractalia da sus valores en `fractalia.css`.
138
-
139
- ## 4. Estándar para cualquier sistema corporativo futuro
140
-
141
- 1. **Ficha primero**: `<tema>.meta.json` con `"branding": "faithful"`, `status`
142
- (verificado / aproximado / diseñado / pendiente) y `a11y.exceptions` justificadas.
143
- 2. **Valores, no reglas**: si existe un token público para una propiedad, se rellena el token; la
144
- personalidad solo para lo que ningún token cubre.
145
- 3. **Sin privadas que sombreen públicas**. Propuesta de comprobación en el doctor: un mapa
146
- `slotTokens` en `contract.json` («`button` · `border-radius` → `--ds-radius-button`») y aviso
147
- (error en `strict`) si una regla de personalidad pinta esa propiedad.
148
- 4. **Pesos cargados = pesos usados**: el doctor compara los `--ds-*-weight` con los pesos de
149
- `<tema>.fonts.css` y avisa si pide uno no cargado.
150
- 5. **Componentes al núcleo**: antes de crear, buscar en `components.manifest.json`; si existe, ampliar
151
- (solo añadir); si no, pieza genérica nueva. Nunca CSS de componentes dentro de un tema.
152
- 6. **Un vocabulario de tono** (`DsDataTone`) y nombres en inglés.
153
- 7. **Huecos del DS documentados**, no inventados: lo que la fuente no especifica se marca PROPUESTA en
154
- la ficha y se valida con diseño.
155
-
156
- ## 5. Plan por fases (cada una con su validación)
157
-
158
- | Fase | Contenido | Validación |
159
- |---|---|---|
160
- | **F1 · Tema por tokens** ✅ hecho: 33 propiedades × 2 pieles idénticas; solo cambian los valores del DS de H2 | H1 + H2 + pesos de H3 en `fractalia.css`; quitar las privadas sustituibles | `pnpm verify`; comparar valores calculados antes/después de cada slot (sin cambio visual salvo los valores del DS de H2); `check:ds -- --aaa` |
161
- | **F2 · Huecos del núcleo** ✅ hecho (botón, pestañas, insignia; `--ds-medium-weight` pendiente); tokens.json de los 6 temas sin cambios | H4 + `--ds-medium-weight` (H3), con valor neutro | `pnpm verify` + escaparate compilado; el resto de temas idénticos (tokens.json sin cambios) |
162
- | **F1b · Resto de temas** | traducir friendly, tactile, twitter y zyro a sus huecos (35 avisos de `slotTokens` hoy), con la misma comparación antes/después; ojo: `--ds-field-bg` lo leen también outline (botón, insignia) | comparación de valores efectivos por tema; después, `slotTokens` pasa a error en strict |
163
- | **F3 · Doctor** ✅ hecho: pesos cargados (1d) y huecos públicos (`slotTokens`, aviso) | `slotTokens` (estándar 3) y pesos cargados (estándar 4) | probar que falla con el fractalia actual y pasa tras F1 |
164
- | **F4 · Componentes** ✅ hechos: Shield/ShieldRadar, Gauge, PasswordStrength, StepDots, StepRing, TaskProgress, LevelMeter, StatusHero, TaskLoader y StatusDot size; renderizado comprobado | por orden: `Shield`/`ShieldRadar`, `Gauge`, `PasswordStrength`, `StepDots`/`StepProgressRing`, `TaskProgress`/`LevelMeter`, `StatusHero` + tamaños de `StatusDot`, `TaskLoader` | por pieza: doctor (tokens, textos, demo), typecheck, build, `check:bundle`, manifiesto, demo en los 6 temas × claro/oscuro, `--aaa`, RTL (clases lógicas) |
165
- | **F5 · Decisiones de diseño** | ver §6 | con diseño de Fractalia |
166
-
167
- Versión: F1–F4 son añadidos compatibles → **menor** (0.11.x / 0.12.0).
168
-
169
- ## 6. Decisiones abiertas (de diseño Fractalia, no técnicas)
170
-
171
- 1. Montserrat **800** para el porcentaje del escudo: añadirlo a `fractalia.fonts.css` o usar 700.
172
- 2. Gauge: grosor del trazo (propuesta 12px) y umbrales numéricos de riesgo.
173
- 3. Tonos decorativos pink/orange/purple: series `chart-*` o paleta decorativa pública.
174
- 4. Halos de `StatusHero` y glow del loader/radar: tokens con valores aproximados hasta que diseño los fije.
175
- 5. Versiones móviles de gauge, escudo, estado y progreso de nivel.
176
- 6. Ilustraciones del loader: SVG o Lottie (la pieza las recibe como `icon`, sirve para ambas).
1
+ # ADR 0002 — Adaptar un sistema corporativo (Fractalia) al modelo de orbital-ds
2
+
3
+ - **Estado:** propuesta (análisis previo a implementar)
4
+ - **Fecha:** 2026-10-13
5
+ - **Origen:** tema `fractalia` (`src/themes/fractalia.*`) y su capa de componentes propia
6
+ (`fractalia.components.css` + `fractalia.components.md`, siete piezas: gauge, escudo, estado,
7
+ progreso, fuerza de contraseña, stepper y loader).
8
+
9
+ ## Principio
10
+
11
+ **Se adapta el sistema corporativo a nuestro modelo, nunca al revés.**
12
+
13
+ | Capa | Qué aporta Fractalia | Dónde vive |
14
+ |---|---|---|
15
+ | Valores (color, forma, medidas, tipo, movimiento) | los de su DS | variables del tema `fractalia.css` (y la marca de cada app en su `brand.css`) |
16
+ | Personalidad (gesto firma) | píldora en mayúsculas, pestaña activa rellena… | sección PERSONALIDAD del tema, **solo con tokens públicos** |
17
+ | Componentes | las siete piezas | **núcleo** (`src/ui/`), genéricos, reutilizables por cualquier tema |
18
+
19
+ Un tema **no trae componentes**. Si una pieza de Fractalia no existe en el núcleo, se crea en el
20
+ núcleo con API genérica y tokens `--ds-*`; Fractalia solo le da sus valores. Así la misma pieza sirve
21
+ en qratia, tactile o cualquier tema futuro, y Fractalia se ve fiel.
22
+
23
+ ---
24
+
25
+ ## 1. Qué ha supuesto el tema `fractalia` (ya hecho en `feat/fractalia-wizard`)
26
+
27
+ - Cumple el contrato y es `strict`. Correcciones necesarias (sin cambio visual): familias «choice»
28
+ (`radio-group-item`) y «title» (`drawer-title`, `empty-title`) completas.
29
+ - Tres pares de su propio DS bajo AA (texto de estado sobre su fondo suave: danger 4.19, warning 4.23,
30
+ neutral 4.41): **declarados** en `a11y.exceptions` de la ficha (el doctor avisa, no falla). El doctor
31
+ acepta ahora excepciones también en estos pares.
32
+ - `"branding": "faithful"`: el asistente recomienda usarlo **fiel**. Antes derivaba siempre la paleta
33
+ entera desde un color y habría borrado su identidad; ahora tiene tres modos (fiel / solo primario /
34
+ completo) y enseña la ficha del tema antes de aplicar.
35
+ - Genera `fractalia.tokens.json` (informes con ECharts) y su versión con ámbito; el escaparate lo
36
+ descubre solo.
37
+
38
+ ## 2. Hallazgos del análisis
39
+
40
+ ### H1 · El tema rodea tokens públicos con variables privadas
41
+
42
+ La personalidad de fractalia pinta con `--zf-*` propiedades que el núcleo YA expone como token
43
+ público. Resultado: una app no puede ajustarlas desde `brand.css` con el nombre estándar, y otro tema
44
+ que copie fractalia hereda el atajo.
45
+
46
+ | Regla de fractalia | Token público que ya existe | Adaptación |
47
+ |---|---|---|
48
+ | `button { border-radius: var(--zf-radius-label) }` | `--ds-radius-button` | `--ds-radius-button: 32px` y quitar la regla |
49
+ | `badge { border-radius: … }` | `--ds-radius-badge` | `--ds-radius-badge: 32px` |
50
+ | `tabs-trigger/toggle { border-radius: … }` | `--ds-radius-tab` | `--ds-radius-tab: 32px` (el contenedor, `--ds-radius-tab` + `--ds-tabs-list-p`) |
51
+ | campos `background: var(--zf-field-bg)` | `--ds-field-bg` (16 componentes lo leen) | `--ds-field-bg: #ecf1f8` y quitar la regla de familia «field» |
52
+ | `switch` apagado `background: var(--zf-track-off)` | `--ds-switch-track-off` | `--ds-switch-track-off: #c8cdd8` |
53
+ | títulos `font-weight: var(--zf-heading-weight)` | `--ds-title-weight`, `--ds-overlay-title-weight` | fijarlos a 700 |
54
+ | foco `outline: 2px … offset 2px` | `--ds-ring-width`, `--ds-ring-color` | `--ds-ring-width: 2px`; falta `--ds-ring-offset` (ver H4) |
55
+ | hover primario `--zf-primary-hover` | `--brand-bright` (mismo valor en claro) | apoyar el hover en un token público (ver H4) |
56
+
57
+ ### H2 · Huecos del núcleo que fractalia deja con el valor neutro aunque su DS los define
58
+
59
+ | Token | Valor neutro (núcleo) | Valor del DS de Fractalia | Fuente |
60
+ |---|---|---|---|
61
+ | `--ds-radius-track` | radio lg (12px en fractalia) | **4px** | progress-bar |
62
+ | `--ds-track-h` | 0.75rem | 12px (coincide) | progress-bar |
63
+ | `--ds-step-size` | 2rem | **34px** (24 en móvil) | empresa-item-step |
64
+ | `--ds-status-dot` | 0.5rem | **12px** (16 / 24) | status-ball |
65
+ | `--ds-legend-swatch` | 0.625rem | **8px** | leyendas de gráficas |
66
+ | `--ds-motion-pulse` | 2 × parpadeo | **1500ms** · `cubic-bezier(.4,0,.6,1)` | motion-duration.pulse |
67
+ | `--ds-badge-px` / `--ds-badge-py` | 0.625rem / … | **8px / 2px** | tag |
68
+ | `--ds-ring-width` | 3px | **2px** | focus |
69
+ | `--ds-radius-check`, `--ds-check-size` | 6px, 1rem | según checkbox.md | checkbox |
70
+
71
+ ### H3 · Pesos de letra: el tema carga 400/700 y el núcleo pide 500 y 600
72
+
73
+ - Tokens del núcleo con 500 (`--ds-nav-weight`, `--ds-tab-weight`, `--ds-table-head-weight`,
74
+ `--ds-overlay-title-weight`) y 600 (`--ds-title-weight`, `--ds-button-weight`, `--ds-strong-weight`…).
75
+ Con Roboto 400/700, el navegador pinta 500 como **400** y 600 como **700**: el aspecto no es el del DS.
76
+ **Adaptación:** fractalia fija todos los `--ds-*-weight` a 400 o 700.
77
+ - **Hueco del núcleo:** 31 usos de `font-medium` (y 1 `font-semibold`) escritos a mano en 25
78
+ componentes. Ningún tema puede cambiarlos. **Propuesta:** token `--ds-medium-weight` (500 por defecto,
79
+ sin cambio visual) y sustituir esas clases. Beneficia a cualquier tema con pocas variantes de fuente.
80
+
81
+ ### H4 · Huecos que faltan en el núcleo (para no necesitar privadas)
82
+
83
+ | Necesidad (genérica, no solo de Fractalia) | Token propuesto | Valor neutro (aspecto actual) |
84
+ |---|---|---|
85
+ | Desactivado con color, no con opacidad | `--ds-button-disabled-bg`, `-fg`, `-border` (**opcionales**: sin definir, cada variante usa su color de respaldo) + `--ds-button-disabled-opacity` | sin definir → opacidad `--ds-disabled-opacity`, como hoy |
86
+ | Hover del botón primario con otro color | `--ds-button-primary-hover`, `-hover-fg` | `color-mix(in oklab, var(--primary) 80%, transparent)` (= `bg-primary/80`) |
87
+ | Colores del botón outline / secundario | `--ds-button-outline-bg`, `-fg`, `-border`, `--ds-button-secondary-border` | los de siempre |
88
+ | Radio del contenedor de pestañas · peso de la insignia | `--ds-radius-tabs-list`, `--ds-badge-weight` | radio de control · peso de etiqueta |
89
+ | Separación del anillo de foco | `--ds-ring-offset` | 0 |
90
+ | Capas de estado (hover / pulsado) | `--ds-state-hover`, `--ds-state-press` | los valores que hoy usa cada componente |
91
+
92
+ Se añaden con valor neutro (nada cambia en los otros temas) y fractalia los rellena.
93
+
94
+ ### H5 · Cinco vocabularios de tono
95
+
96
+ El núcleo ya tiene cuatro: `StatusLevel` (`critical·warning·ok·info·neutral·none`), `DsDataTone`
97
+ (`primary·info·success·warning·danger·neutral·chart-1…5`), `StatTone` (`good·warn·bad·neutral`) y
98
+ `StepStatus`. Fractalia trae un quinto (`low/medium/high`, `protected/alert`, `pending`, `analyzing`,
99
+ `pink/orange/purple`).
100
+
101
+ **Estándar:** las piezas nuevas usan `DsDataTone` como único vocabulario de color. El significado de
102
+ dominio (riesgo bajo/medio/alto, protegido/alerta) lo traduce la app o un mapa documentado en la pieza
103
+ (`low → success`, `medium → warning`, `high → danger`, `analyzing/pending → neutral`). No se renombra
104
+ nada existente (sería versión mayor); `StatusLevel` y `StatTone` siguen como alias.
105
+ **Pendiente:** los tonos decorativos pink/orange/purple (2.0–2.6:1, solo UI no textual) no caben en
106
+ los semánticos; o se usan las series `chart-*` o se crea una paleta decorativa pública (decisión).
107
+
108
+ ### H6 · La capa de componentes rompe piezas existentes
109
+
110
+ Usa cinco `data-slot` que ya son del núcleo: `progress`, `progress-track`, `stepper`, `stepper-item`,
111
+ `status-badge`. Importarla cambia el aspecto de `Progress`, `Stepper` y `StatusBadge` en toda la app.
112
+ **No se importa nunca tal cual.**
113
+
114
+ ### H7 · La capa incumple las reglas del modelo
115
+
116
+ - Colores hex, medidas en px, pesos y tamaños de letra a mano (no `strict`).
117
+ - `--fc-*` duplica valores del tema (y su `.dark` repite hex).
118
+ - Valores en español (`baja`, `media`, `centrado`, `data-tipo`, `nivel`): el modelo exige inglés.
119
+ - Es CSS + HTML a mano: sin React, sin `data-slot` propios del núcleo, accesibilidad manual,
120
+ textos sin i18n («Nivel de fuerza:», «Paso X de 5»…).
121
+ - No respeta RTL salvo un caso (`status-badge`).
122
+
123
+ ## 3. Mapa pieza a pieza (reutilizable por cualquier tema)
124
+
125
+ | Pieza de Fractalia | ¿Existe en el núcleo? | Decisión | API genérica propuesta |
126
+ |---|---|---|---|
127
+ | **Gauge** (anillo 360° / arco 180°, progreso o tramos, leyenda, escala) | No (Sparkline, ProportionBar y EChart gauge son otra cosa) | **Nuevo** `Gauge` | `value` (0–max), `max`, `shape="ring\|semi"`, `tone: DsDataTone`, `segments?: {value,tone,label}[]`, partes `GaugeValue`, `GaugeLabel`, `GaugeCaption`; leyenda con el `Legend` existente; `role="meter"` + `aria-valuetext` |
128
+ | **Escudo** + **radar** | No | **Nuevo** `Shield`, `ShieldRadar` | `Shield value` (0–1) o `children` (insignia), `size`; `ShieldRadar tone` con anillos animados (`--ds-motion-pulse`, reducido = quieto); `role="img"` + texto i18n; trazado del escudo genérico, tokens `--ds-shield-*` |
129
+ | **Estado** dot / icon / hero / user | Parcial: `StatusDot` | **Ampliar** `StatusDot` (solo añadir `size="sm\|md\|lg"`) + **nuevo** `StatusHero` (disco con halo e insignia) | el «user» es un `Avatar` (+N): se cubre con `Avatar`/`AvatarGroup` existentes |
130
+ | **Progreso** bar / estado / nivel | Parcial: `Progress`, `ProportionBar` | barra simple = `Progress` (fractalia da `--ds-radius-track`, `--ds-track-h`). **Nuevo** `TaskProgress` (etiqueta + contador + estado `idle\|running\|done\|error` + icono) y `LevelMeter` (nivel con etiqueta) | `role="progressbar"` / `meter`; textos «No iniciado / En curso / Completado» en i18n |
131
+ | **Fuerza de contraseña** | No | **Nuevo** `PasswordStrength` | `score` 0–4 o `level="weak\|medium\|strong"`, `segments` (5); `role="meter"`, `aria-live`; textos en i18n |
132
+ | **Stepper** dots / cuadrantes / item | Parcial: `Stepper` | **Nuevo** `StepDots` y `StepProgressRing` (cuadrantes); el item = `StepperIndicator` con `--ds-step-size` | `count`, `current`, `completed`; texto «Paso X de N» en i18n |
133
+ | **Loader** ilustrado | Parcial: `Spinner` | **Nuevo** `TaskLoader` | `icon` (la ilustración la pone la app), `value?` (sin él, indeterminado), `state="running\|done"`; `role="status"` |
134
+
135
+ Cada pieza nueva: un fichero en `src/ui/`, `data-slot` propio, solo tokens (`--ds-<pieza>-*` en la
136
+ estructura con valor neutro), textos en en/es/pt-BR, clases lógicas (RTL), demo en el escaparate y
137
+ entrada en el manifiesto. Fractalia da sus valores en `fractalia.css`.
138
+
139
+ ## 4. Estándar para cualquier sistema corporativo futuro
140
+
141
+ 1. **Ficha primero**: `<tema>.meta.json` con `"branding": "faithful"`, `status`
142
+ (verificado / aproximado / diseñado / pendiente) y `a11y.exceptions` justificadas.
143
+ 2. **Valores, no reglas**: si existe un token público para una propiedad, se rellena el token; la
144
+ personalidad solo para lo que ningún token cubre.
145
+ 3. **Sin privadas que sombreen públicas**. Propuesta de comprobación en el doctor: un mapa
146
+ `slotTokens` en `contract.json` («`button` · `border-radius` → `--ds-radius-button`») y aviso
147
+ (error en `strict`) si una regla de personalidad pinta esa propiedad.
148
+ 4. **Pesos cargados = pesos usados**: el doctor compara los `--ds-*-weight` con los pesos de
149
+ `<tema>.fonts.css` y avisa si pide uno no cargado.
150
+ 5. **Componentes al núcleo**: antes de crear, buscar en `components.manifest.json`; si existe, ampliar
151
+ (solo añadir); si no, pieza genérica nueva. Nunca CSS de componentes dentro de un tema.
152
+ 6. **Un vocabulario de tono** (`DsDataTone`) y nombres en inglés.
153
+ 7. **Huecos del DS documentados**, no inventados: lo que la fuente no especifica se marca PROPUESTA en
154
+ la ficha y se valida con diseño.
155
+
156
+ ## 5. Plan por fases (cada una con su validación)
157
+
158
+ | Fase | Contenido | Validación |
159
+ |---|---|---|
160
+ | **F1 · Tema por tokens** ✅ hecho: 33 propiedades × 2 pieles idénticas; solo cambian los valores del DS de H2 | H1 + H2 + pesos de H3 en `fractalia.css`; quitar las privadas sustituibles | `pnpm verify`; comparar valores calculados antes/después de cada slot (sin cambio visual salvo los valores del DS de H2); `check:ds -- --aaa` |
161
+ | **F2 · Huecos del núcleo** ✅ hecho (botón, pestañas, insignia; `--ds-medium-weight` pendiente); tokens.json de los 6 temas sin cambios | H4 + `--ds-medium-weight` (H3), con valor neutro | `pnpm verify` + escaparate compilado; el resto de temas idénticos (tokens.json sin cambios) |
162
+ | **F1b · Resto de temas** | traducir friendly, tactile, twitter y zyro a sus huecos (35 avisos de `slotTokens` hoy), con la misma comparación antes/después; ojo: `--ds-field-bg` lo leen también outline (botón, insignia) | comparación de valores efectivos por tema; después, `slotTokens` pasa a error en strict |
163
+ | **F3 · Doctor** ✅ hecho: pesos cargados (1d) y huecos públicos (`slotTokens`, aviso) | `slotTokens` (estándar 3) y pesos cargados (estándar 4) | probar que falla con el fractalia actual y pasa tras F1 |
164
+ | **F4 · Componentes** ✅ hechos: Shield/ShieldRadar, Gauge, PasswordStrength, StepDots, StepRing, TaskProgress, LevelMeter, StatusHero, TaskLoader y StatusDot size; renderizado comprobado | por orden: `Shield`/`ShieldRadar`, `Gauge`, `PasswordStrength`, `StepDots`/`StepProgressRing`, `TaskProgress`/`LevelMeter`, `StatusHero` + tamaños de `StatusDot`, `TaskLoader` | por pieza: doctor (tokens, textos, demo), typecheck, build, `check:bundle`, manifiesto, demo en los 6 temas × claro/oscuro, `--aaa`, RTL (clases lógicas) |
165
+ | **F5 · Decisiones de diseño** | ver §6 | con diseño de Fractalia |
166
+
167
+ Versión: F1–F4 son añadidos compatibles → **menor**: publicado como **0.12.0**.
168
+
169
+ ## 6. Decisiones abiertas (de diseño Fractalia, no técnicas)
170
+
171
+ 1. Montserrat **800** para el porcentaje del escudo: añadirlo a `fractalia.fonts.css` o usar 700.
172
+ 2. Gauge: grosor del trazo (propuesta 12px) y umbrales numéricos de riesgo.
173
+ 3. Tonos decorativos pink/orange/purple: series `chart-*` o paleta decorativa pública.
174
+ 4. Halos de `StatusHero` y glow del loader/radar: tokens con valores aproximados hasta que diseño los fije.
175
+ 5. Versiones móviles de gauge, escudo, estado y progreso de nivel.
176
+ 6. Ilustraciones del loader: SVG o Lottie (la pieza las recibe como `icon`, sirve para ambas).