orbital-ds 0.40.0 → 0.41.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 (64) hide show
  1. package/AGENTS.md +1 -1
  2. package/components.manifest.json +221 -1
  3. package/dist/hooks/use-ds-messages.d.ts +82 -0
  4. package/dist/lib/a2ui-catalog.d.ts +42 -0
  5. package/dist/lib/a2ui-catalog.js +558 -0
  6. package/dist/lib/a2ui.d.ts +289 -0
  7. package/dist/lib/a2ui.js +215 -0
  8. package/dist/lib/ai-events.d.ts +15 -0
  9. package/dist/lib/ai-events.js +202 -0
  10. package/dist/lib/auth-flow.d.ts +3 -1
  11. package/dist/lib/auth-flow.js +24 -3
  12. package/dist/lib/i18n.d.ts +82 -0
  13. package/dist/lib/i18n.js +246 -0
  14. package/dist/styles.css +23 -1
  15. package/dist/ui/a2ui-renderer.d.ts +33 -0
  16. package/dist/ui/a2ui-renderer.js +793 -0
  17. package/dist/ui/agent-events.d.ts +32 -0
  18. package/dist/ui/agent-events.js +108 -0
  19. package/dist/ui/alert.d.ts +1 -1
  20. package/dist/ui/attachment.d.ts +2 -2
  21. package/dist/ui/auth-form.d.ts +3 -1
  22. package/dist/ui/auth-form.js +34 -6
  23. package/dist/ui/badge.d.ts +1 -1
  24. package/dist/ui/banner.d.ts +1 -1
  25. package/dist/ui/bubble.d.ts +1 -1
  26. package/dist/ui/button-group.d.ts +1 -1
  27. package/dist/ui/button.d.ts +2 -2
  28. package/dist/ui/chain-of-thought.d.ts +19 -0
  29. package/dist/ui/chain-of-thought.js +90 -0
  30. package/dist/ui/chat-composer.d.ts +39 -0
  31. package/dist/ui/chat-composer.js +192 -0
  32. package/dist/ui/conversation-list.d.ts +24 -0
  33. package/dist/ui/conversation-list.js +141 -0
  34. package/dist/ui/empty.d.ts +1 -1
  35. package/dist/ui/field.d.ts +1 -1
  36. package/dist/ui/generated-image.d.ts +14 -0
  37. package/dist/ui/generated-image.js +65 -0
  38. package/dist/ui/generated-table.d.ts +11 -0
  39. package/dist/ui/generated-table.js +59 -0
  40. package/dist/ui/icon-tile.d.ts +2 -2
  41. package/dist/ui/item.d.ts +2 -2
  42. package/dist/ui/markdown.d.ts +14 -0
  43. package/dist/ui/markdown.js +123 -0
  44. package/dist/ui/marker.d.ts +1 -1
  45. package/dist/ui/message-actions.d.ts +12 -0
  46. package/dist/ui/message-actions.js +79 -0
  47. package/dist/ui/panel.d.ts +1 -1
  48. package/dist/ui/reasoning.d.ts +10 -0
  49. package/dist/ui/reasoning.js +62 -0
  50. package/dist/ui/sidebar.d.ts +1 -1
  51. package/dist/ui/sparkline.d.ts +1 -1
  52. package/dist/ui/stat.d.ts +1 -1
  53. package/dist/ui/status-badge.d.ts +3 -3
  54. package/dist/ui/suggestions.d.ts +8 -0
  55. package/dist/ui/suggestions.js +39 -0
  56. package/dist/ui/tabs.d.ts +1 -1
  57. package/dist/ui/toggle.d.ts +1 -1
  58. package/dist/ui/tool-call.d.ts +15 -0
  59. package/dist/ui/tool-call.js +74 -0
  60. package/dist/ui/workflow-run.d.ts +23 -0
  61. package/dist/ui/workflow-run.js +185 -0
  62. package/docs/designer/criterio.md +87 -87
  63. package/docs/designer/patrones.md +3 -1
  64. package/package.json +238 -228
@@ -0,0 +1,185 @@
1
+ "use client";
2
+ import { jsx, jsxs } from "react/jsx-runtime";
3
+ import {
4
+ AlertCircleIcon,
5
+ CheckCircle2Icon,
6
+ CircleDashedIcon,
7
+ MinusCircleIcon,
8
+ RotateCcwIcon,
9
+ SquareIcon
10
+ } from "lucide-react";
11
+ import { useDsMessages } from "../hooks/use-ds-messages.js";
12
+ import { dsFormat } from "../lib/i18n.js";
13
+ import { cn } from "../lib/utils.js";
14
+ import { Button } from "./button.js";
15
+ import { Spinner } from "./spinner.js";
16
+ function flat(nodes) {
17
+ return nodes.flatMap((n) => [n, ...n.branches ? flat(n.branches) : []]);
18
+ }
19
+ const TEXT = {
20
+ pending: "text-muted-foreground",
21
+ running: "text-info",
22
+ done: "text-success",
23
+ error: "text-danger",
24
+ skipped: "text-muted-foreground"
25
+ };
26
+ function StatusIcon({ status }) {
27
+ if (status === "running") return /* @__PURE__ */ jsx(Spinner, { "aria-hidden": true, role: "presentation", className: "size-3.5" });
28
+ if (status === "done") return /* @__PURE__ */ jsx(CheckCircle2Icon, {});
29
+ if (status === "error") return /* @__PURE__ */ jsx(AlertCircleIcon, {});
30
+ if (status === "skipped") return /* @__PURE__ */ jsx(MinusCircleIcon, {});
31
+ return /* @__PURE__ */ jsx(CircleDashedIcon, {});
32
+ }
33
+ function Node({ node, last }) {
34
+ const t = useDsMessages();
35
+ const status = node.status ?? "pending";
36
+ const statusText = {
37
+ pending: t.workflowWaiting,
38
+ running: t.workflowRunning,
39
+ done: t.workflowSucceeded,
40
+ error: t.workflowFailed,
41
+ skipped: t.workflowSkipped
42
+ };
43
+ return /* @__PURE__ */ jsxs(
44
+ "li",
45
+ {
46
+ "data-slot": "workflow-node",
47
+ "data-status": status,
48
+ "aria-current": status === "running" ? "step" : void 0,
49
+ className: "relative flex gap-3 pb-4 last:pb-0",
50
+ children: [
51
+ !last ? /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "absolute start-2.5 top-6 bottom-0 w-px -translate-x-1/2 bg-(--ds-track-bg)" }) : null,
52
+ /* @__PURE__ */ jsx(
53
+ "span",
54
+ {
55
+ "aria-hidden": true,
56
+ className: cn(
57
+ "relative mt-0.5 flex size-5 shrink-0 items-center justify-center rounded-full bg-background [&_svg]:size-4",
58
+ TEXT[status]
59
+ ),
60
+ children: /* @__PURE__ */ jsx(StatusIcon, { status })
61
+ }
62
+ ),
63
+ /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1", children: [
64
+ /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-baseline gap-x-2", children: [
65
+ /* @__PURE__ */ jsx(
66
+ "span",
67
+ {
68
+ className: cn(
69
+ "text-sm",
70
+ status === "pending" || status === "skipped" ? "text-muted-foreground" : "text-foreground",
71
+ status === "running" && "text-shimmer"
72
+ ),
73
+ children: node.title
74
+ }
75
+ ),
76
+ /* @__PURE__ */ jsx("span", { className: cn("text-xs", TEXT[status]), children: statusText[status] }),
77
+ node.duration ? /* @__PURE__ */ jsx("span", { className: "ms-auto text-xs tabular-nums text-muted-foreground", children: node.duration }) : null
78
+ ] }),
79
+ node.description ? /* @__PURE__ */ jsx("span", { className: "text-xs text-muted-foreground", children: node.description }) : null,
80
+ node.branches?.length ? /* @__PURE__ */ jsx(
81
+ "div",
82
+ {
83
+ role: "group",
84
+ "aria-label": t.workflowParallel,
85
+ className: "mt-1 grid gap-2 rounded-lg border border-border bg-muted/40 p-3 @[32rem]:grid-cols-2",
86
+ children: /* @__PURE__ */ jsx("ol", { className: "contents", children: node.branches.map((b) => /* @__PURE__ */ jsxs(
87
+ "li",
88
+ {
89
+ "data-slot": "workflow-branch",
90
+ "data-status": b.status ?? "pending",
91
+ className: "flex items-start gap-2 text-sm",
92
+ children: [
93
+ /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: cn("mt-0.5 [&_svg]:size-4", TEXT[b.status ?? "pending"]), children: /* @__PURE__ */ jsx(StatusIcon, { status: b.status ?? "pending" }) }),
94
+ /* @__PURE__ */ jsxs("span", { className: "min-w-0 flex-1", children: [
95
+ /* @__PURE__ */ jsx("span", { className: "block truncate", children: b.title }),
96
+ b.duration ? /* @__PURE__ */ jsx("span", { className: "text-xs tabular-nums text-muted-foreground", children: b.duration }) : null
97
+ ] })
98
+ ]
99
+ },
100
+ b.id
101
+ )) })
102
+ }
103
+ ) : null
104
+ ] })
105
+ ]
106
+ }
107
+ );
108
+ }
109
+ function WorkflowRun({
110
+ name,
111
+ status = "running",
112
+ nodes,
113
+ onCancel,
114
+ onRetry,
115
+ className,
116
+ ...props
117
+ }) {
118
+ const t = useDsMessages();
119
+ const all = flat(nodes);
120
+ const done = all.filter((n) => n.status === "done" || n.status === "skipped").length;
121
+ const label = {
122
+ running: t.workflowRunning,
123
+ succeeded: t.workflowSucceeded,
124
+ failed: t.workflowFailed,
125
+ cancelled: t.workflowCancelled
126
+ };
127
+ const tone = {
128
+ running: "text-info",
129
+ succeeded: "text-success",
130
+ failed: "text-danger",
131
+ cancelled: "text-muted-foreground"
132
+ };
133
+ const pct = all.length ? Math.round(done / all.length * 100) : 0;
134
+ return /* @__PURE__ */ jsxs(
135
+ "section",
136
+ {
137
+ "data-slot": "workflow-run",
138
+ "data-status": status,
139
+ className: cn("@container flex flex-col gap-4 rounded-xl border border-border bg-card p-4 text-card-foreground", className),
140
+ ...props,
141
+ children: [
142
+ /* @__PURE__ */ jsxs("header", { className: "flex flex-wrap items-center gap-x-3 gap-y-2", children: [
143
+ /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-1 flex-col", children: [
144
+ /* @__PURE__ */ jsx("h3", { className: "truncate text-sm font-(--ds-strong-weight)", children: name }),
145
+ /* @__PURE__ */ jsxs("p", { className: "text-xs text-muted-foreground", children: [
146
+ /* @__PURE__ */ jsx("span", { className: tone[status], children: label[status] }),
147
+ " \xB7 ",
148
+ dsFormat(t.workflowProgress, { done, total: all.length })
149
+ ] })
150
+ ] }),
151
+ status === "running" && onCancel ? /* @__PURE__ */ jsxs(Button, { variant: "outline", size: "sm", onClick: onCancel, children: [
152
+ /* @__PURE__ */ jsx(SquareIcon, { "data-icon": "inline-start" }),
153
+ t.workflowCancel
154
+ ] }) : null,
155
+ (status === "failed" || status === "cancelled") && onRetry ? /* @__PURE__ */ jsxs(Button, { variant: "outline", size: "sm", onClick: onRetry, children: [
156
+ /* @__PURE__ */ jsx(RotateCcwIcon, { "data-icon": "inline-start" }),
157
+ t.workflowRetry
158
+ ] }) : null
159
+ ] }),
160
+ /* @__PURE__ */ jsx(
161
+ "div",
162
+ {
163
+ role: "progressbar",
164
+ "aria-valuemin": 0,
165
+ "aria-valuemax": 100,
166
+ "aria-valuenow": pct,
167
+ "aria-label": dsFormat(t.workflowProgress, { done, total: all.length }),
168
+ className: "h-1 overflow-hidden rounded-full bg-(--ds-track-bg)",
169
+ children: /* @__PURE__ */ jsx(
170
+ "div",
171
+ {
172
+ className: cn("h-full rounded-full transition-[width]", status === "failed" ? "bg-danger" : status === "succeeded" ? "bg-success" : "bg-primary"),
173
+ style: { width: `${pct}%` }
174
+ }
175
+ )
176
+ }
177
+ ),
178
+ /* @__PURE__ */ jsx("ol", { children: nodes.map((n, i) => /* @__PURE__ */ jsx(Node, { node: n, last: i === nodes.length - 1 }, n.id)) })
179
+ ]
180
+ }
181
+ );
182
+ }
183
+ export {
184
+ WorkflowRun
185
+ };
@@ -1,87 +1,87 @@
1
- # Diseñador orbital-ds · 5. Criterio visual (armonía y elección de elementos)
2
-
3
- Cómo **analizar el aspecto** de una pantalla y **elegir el elemento correcto** (¿tarjeta, ítem, bento, imagen,
4
- efecto?) antes de componerla. Va entre `patrones.md` (qué patrón) y `revision.md` (comprobación). Si choca con el
5
- contrato o el tema, gana el sistema; esto sirve para elegir **dentro** de él.
6
-
7
- Origen: síntesis de referentes de la industria. Las fuentes son guías públicas y artículos de práctica; los números
8
- concretos son orientativos, no normas. Contrasta lo que dependa de una cifra.
9
-
10
- ## 1. Qué enseñan los referentes (y cómo se traduce aquí)
11
-
12
- | Referente | Idea útil | En orbital-ds |
13
- |---|---|---|
14
- | **Apple HIG** (claridad, deferencia, profundidad; en iOS 26, jerarquía · armonía · consistencia) | El contenido manda; la interfaz se aparta. El vidrio/material va en la capa de **control y navegación**, no en la de contenido. | `glass` y fondos vivos solo en cabeceras, lateral, paneles flotantes o fondos de acceso; nunca detrás de texto largo ni de tablas. |
15
- | **Material 3 Expressive** (Google) | Dar **énfasis** (color, forma, tamaño) al elemento clave ayuda a encontrarlo antes; un grupo no pequeño prefiere versiones calmadas. La mejora medida de forma independiente es moderada, no mágica. | Un solo elemento enfatizado por vista (`variant` principal, tarjeta `feature`/`hero`); el resto, calmado. Respeta `--ds-density` y el tema. |
16
- | **Nielsen** (10 heurísticas) | Estado visible, consistencia, minimalismo, recuperarse de errores. | `ux.md`. Cada elemento extra compite con lo importante. |
17
- | **Polaris / GOV.UK** | Documentan **cuándo usar y cuándo NO usar** cada pieza. | Los `@note` del manifiesto; si dudas entre dos piezas, lee el `@note` de ambas. |
18
- | **Carbon / Primer / Atlassian** | Tokens y patrones antes que píxeles; un componente «experimental» no se usa de base. | Variables `--ds-*`; nada de medidas a mano. |
19
-
20
- ## 2. Cómo analizar una pantalla (en este orden, 8 pasos)
21
-
22
- Puntúa cada uno 0–2 (0 falla · 1 mejorable · 2 bien). Por debajo de 12/16, rehaz antes de entregar.
23
-
24
- 1. **Jerarquía.** Mirando entrecerrado: ¿se distingue **una** cosa principal, luego lo secundario, luego el resto?
25
- Tamaño y peso primero, color después. Si todo destaca, nada destaca.
26
- 2. **Ritmo y agrupación.** La proximidad agrupa: más espacio **entre** grupos que **dentro**. Misma separación para
27
- lo del mismo nivel (usa los espacios del sistema, `--ds-density`; no inventes).
28
- 3. **Alineación y rejilla.** Bordes comunes; columnas coherentes; la bento o el mosaico con `Mosaic`, no con
29
- anchos sueltos. Orden del DOM = orden de lectura (el orden visual no debe contradecirlo).
30
- 4. **Contraste y legibilidad.** Texto sobre imagen **siempre con velo** (`--ds-card-scrim`); estado nunca solo con color; AA mínimo.
31
- 5. **Consistencia.** Mismo patrón para el mismo problema; mismas esquinas, sombras y gestos que el tema.
32
- 6. **Densidad.** ¿Cuánto hay por pantalla? Una vista de trabajo admite densidad; una de decisión, aire. Más de ~9 celdas
33
- en un bloque bento diluye la jerarquía.
34
- 7. **Estados.** Vacío, carga (forma del contenido), error con reintento, éxito, desactivado, foco, hover/pulsado.
35
- 8. **Movimiento.** Explica origen o cambio de estado; ritmo del tema; quieto con movimiento reducido.
36
-
37
- ## 3. Elegir el elemento (árbol de decisión)
38
-
39
- **¿Qué tengo que mostrar?**
40
- - **Una entidad que se lista y se actúa** (agente, dispositivo, proyecto) → `Item variant="card"` (+ `ItemMedia`/`IconTile`,
41
- `ItemActions`). No `Card` + `Item` a mano.
42
- - **Contenido con título, texto y a veces imagen** (artículo, producto, recurso) → `ContentCard` con su `preset`
43
- (`basic` · `feature` · `media` · `horizontal` · `cover`).
44
- - **Una cifra o una tendencia** → `StatGroup` / KPI / `ChartCard preset="glance"`. No una tarjeta de texto con un número.
45
- - **Un grupo de bloques de distinto peso** (resumen, portada, panel) → `Mosaic preset="bento" | "hero" | "showcase"` con `MosaicItem span`.
46
- - **Un bloque único de sección con cabecera, contenido y pie** → `Card`.
47
- - **Una lista larga homogénea** → `EntityList` / `DataTable`; no un mosaico.
48
- - **Agrupar sin caja** → separador y espacio, no otra tarjeta (nada de tarjetas dentro de tarjetas).
49
-
50
- **Tarjeta con imagen o fondo (`ContentCard preset="cover"`, `Card backdrop`):**
51
- - Úsala cuando la imagen **es** el contenido (destino, producto, campaña). No para decorar un formulario.
52
- - Título corto sobre el velo; ninguna información crítica solo en la imagen; `alt` o `aria-hidden` según informe o decore.
53
- - Un fondo vivo (`backdrop` mesh/aurora/dots, `animated`) como mucho en 1–2 tarjetas por vista; son énfasis, no textura general.
54
-
55
- **Efectos de interacción (`hoverable`, `spotlight`, `glow`):**
56
- - Solo en tarjetas **pulsables** (llevan enlace o acción). Un efecto de «clicable» en algo que no lo es engaña.
57
- - Uno por tarjeta (elige `hoverable` **o** `spotlight`); el hover es refuerzo, nunca el único aviso (táctil no tiene hover).
58
-
59
- **Bento — reglas:**
60
- - Es una **jerarquía**, no una rejilla de cajas iguales: 1 celda protagonista, 2–3 medianas, el resto pequeñas.
61
- - Cada celda cuenta una cosa; la protagonista lleva el mensaje principal.
62
- - En móvil cae a una columna conservando el orden de importancia.
63
-
64
- **Revelar y cargar:**
65
- - Entrada al desplazar (`Reveal`): solo bloques fuera de la primera pantalla; no en listas que se filtran o reordenan.
66
- - Listas largas: `LoadMore` (botón, con el resto visible; `auto` solo como extra) antes que scroll infinito; para saltar a una
67
- página o trabajar con datos, `Pagination`.
68
- - Texto largo en una tarjeta: `ShowMore`.
69
- - Búsqueda mientras se escribe: `SearchBox` (recientes y populares al enfocar; estados vacío/error; la app pone la consulta).
70
-
71
- ## 4. Armonía: lo que hace que «se vea cuidado»
72
- - **Una voz.** Un énfasis por vista; el resto, calmado. Un tema = un gesto firma.
73
- - **Radios coherentes:** el radio de lo de dentro es menor que el de su contenedor (los tokens ya lo resuelven; no pongas `rounded-*` sueltos).
74
- - **Sombras y capas:** solo las del tema (`shadow-*`, `--ds-card-glow`); la elevación indica interactividad o capa, no decoración.
75
- - **Titulares y párrafos:** equilibrados (`text-wrap: balance` en títulos, `pretty` en párrafos), longitud de línea cómoda (≈ 45–75 caracteres).
76
- - **Color:** de la marca solo el primario como acento; neutros del tema; los estados con su tono semántico.
77
- - **Espacio:** el aire es parte del diseño; recortarlo para «meter más» baja la jerarquía.
78
- - **Detalle de estado:** foco visible, desactivado legible, carga con forma real, error con salida.
79
-
80
- ## 5. Si algo no se puede lograr con el sistema
81
- No lo fuerces con estilos propios: dilo, propón la combinación de patrones más cercana y anota el hueco (variable o
82
- variante que faltaría) para la librería. Es mejor un hueco anotado que una pantalla fuera del sistema.
83
-
84
- ## Fuentes
85
- Apple HIG y su revisión Liquid Glass (resúmenes: createwithswift.com, superdesign.dev); Google Design, «Expressive Design: research»
86
- y el estudio independiente (ACM, 2026); Nielsen Norman Group (10 heurísticas); guías «cuándo usar / cuándo no» de Polaris y
87
- GOV.UK; guías de bento y de carga progresiva (Smashing Magazine, uxpatterns.dev). Verifica en las fuentes oficiales si una decisión depende de una cifra.
1
+ # Diseñador orbital-ds · 5. Criterio visual (armonía y elección de elementos)
2
+
3
+ Cómo **analizar el aspecto** de una pantalla y **elegir el elemento correcto** (¿tarjeta, ítem, bento, imagen,
4
+ efecto?) antes de componerla. Va entre `patrones.md` (qué patrón) y `revision.md` (comprobación). Si choca con el
5
+ contrato o el tema, gana el sistema; esto sirve para elegir **dentro** de él.
6
+
7
+ Origen: síntesis de referentes de la industria. Las fuentes son guías públicas y artículos de práctica; los números
8
+ concretos son orientativos, no normas. Contrasta lo que dependa de una cifra.
9
+
10
+ ## 1. Qué enseñan los referentes (y cómo se traduce aquí)
11
+
12
+ | Referente | Idea útil | En orbital-ds |
13
+ |---|---|---|
14
+ | **Apple HIG** (claridad, deferencia, profundidad; en iOS 26, jerarquía · armonía · consistencia) | El contenido manda; la interfaz se aparta. El vidrio/material va en la capa de **control y navegación**, no en la de contenido. | `glass` y fondos vivos solo en cabeceras, lateral, paneles flotantes o fondos de acceso; nunca detrás de texto largo ni de tablas. |
15
+ | **Material 3 Expressive** (Google) | Dar **énfasis** (color, forma, tamaño) al elemento clave ayuda a encontrarlo antes; un grupo no pequeño prefiere versiones calmadas. La mejora medida de forma independiente es moderada, no mágica. | Un solo elemento enfatizado por vista (`variant` principal, tarjeta `feature`/`hero`); el resto, calmado. Respeta `--ds-density` y el tema. |
16
+ | **Nielsen** (10 heurísticas) | Estado visible, consistencia, minimalismo, recuperarse de errores. | `ux.md`. Cada elemento extra compite con lo importante. |
17
+ | **Polaris / GOV.UK** | Documentan **cuándo usar y cuándo NO usar** cada pieza. | Los `@note` del manifiesto; si dudas entre dos piezas, lee el `@note` de ambas. |
18
+ | **Carbon / Primer / Atlassian** | Tokens y patrones antes que píxeles; un componente «experimental» no se usa de base. | Variables `--ds-*`; nada de medidas a mano. |
19
+
20
+ ## 2. Cómo analizar una pantalla (en este orden, 8 pasos)
21
+
22
+ Puntúa cada uno 0–2 (0 falla · 1 mejorable · 2 bien). Por debajo de 12/16, rehaz antes de entregar.
23
+
24
+ 1. **Jerarquía.** Mirando entrecerrado: ¿se distingue **una** cosa principal, luego lo secundario, luego el resto?
25
+ Tamaño y peso primero, color después. Si todo destaca, nada destaca.
26
+ 2. **Ritmo y agrupación.** La proximidad agrupa: más espacio **entre** grupos que **dentro**. Misma separación para
27
+ lo del mismo nivel (usa los espacios del sistema, `--ds-density`; no inventes).
28
+ 3. **Alineación y rejilla.** Bordes comunes; columnas coherentes; la bento o el mosaico con `Mosaic`, no con
29
+ anchos sueltos. Orden del DOM = orden de lectura (el orden visual no debe contradecirlo).
30
+ 4. **Contraste y legibilidad.** Texto sobre imagen **siempre con velo** (`--ds-card-scrim`); estado nunca solo con color; AA mínimo.
31
+ 5. **Consistencia.** Mismo patrón para el mismo problema; mismas esquinas, sombras y gestos que el tema.
32
+ 6. **Densidad.** ¿Cuánto hay por pantalla? Una vista de trabajo admite densidad; una de decisión, aire. Más de ~9 celdas
33
+ en un bloque bento diluye la jerarquía.
34
+ 7. **Estados.** Vacío, carga (forma del contenido), error con reintento, éxito, desactivado, foco, hover/pulsado.
35
+ 8. **Movimiento.** Explica origen o cambio de estado; ritmo del tema; quieto con movimiento reducido.
36
+
37
+ ## 3. Elegir el elemento (árbol de decisión)
38
+
39
+ **¿Qué tengo que mostrar?**
40
+ - **Una entidad que se lista y se actúa** (agente, dispositivo, proyecto) → `Item variant="card"` (+ `ItemMedia`/`IconTile`,
41
+ `ItemActions`). No `Card` + `Item` a mano.
42
+ - **Contenido con título, texto y a veces imagen** (artículo, producto, recurso) → `ContentCard` con su `preset`
43
+ (`basic` · `feature` · `media` · `horizontal` · `cover`).
44
+ - **Una cifra o una tendencia** → `StatGroup` / KPI / `ChartCard preset="glance"`. No una tarjeta de texto con un número.
45
+ - **Un grupo de bloques de distinto peso** (resumen, portada, panel) → `Mosaic preset="bento" | "hero" | "showcase"` con `MosaicItem span`.
46
+ - **Un bloque único de sección con cabecera, contenido y pie** → `Card`.
47
+ - **Una lista larga homogénea** → `EntityList` / `DataTable`; no un mosaico.
48
+ - **Agrupar sin caja** → separador y espacio, no otra tarjeta (nada de tarjetas dentro de tarjetas).
49
+
50
+ **Tarjeta con imagen o fondo (`ContentCard preset="cover"`, `Card backdrop`):**
51
+ - Úsala cuando la imagen **es** el contenido (destino, producto, campaña). No para decorar un formulario.
52
+ - Título corto sobre el velo; ninguna información crítica solo en la imagen; `alt` o `aria-hidden` según informe o decore.
53
+ - Un fondo vivo (`backdrop` mesh/aurora/dots, `animated`) como mucho en 1–2 tarjetas por vista; son énfasis, no textura general.
54
+
55
+ **Efectos de interacción (`hoverable`, `spotlight`, `glow`):**
56
+ - Solo en tarjetas **pulsables** (llevan enlace o acción). Un efecto de «clicable» en algo que no lo es engaña.
57
+ - Uno por tarjeta (elige `hoverable` **o** `spotlight`); el hover es refuerzo, nunca el único aviso (táctil no tiene hover).
58
+
59
+ **Bento — reglas:**
60
+ - Es una **jerarquía**, no una rejilla de cajas iguales: 1 celda protagonista, 2–3 medianas, el resto pequeñas.
61
+ - Cada celda cuenta una cosa; la protagonista lleva el mensaje principal.
62
+ - En móvil cae a una columna conservando el orden de importancia.
63
+
64
+ **Revelar y cargar:**
65
+ - Entrada al desplazar (`Reveal`): solo bloques fuera de la primera pantalla; no en listas que se filtran o reordenan.
66
+ - Listas largas: `LoadMore` (botón, con el resto visible; `auto` solo como extra) antes que scroll infinito; para saltar a una
67
+ página o trabajar con datos, `Pagination`.
68
+ - Texto largo en una tarjeta: `ShowMore`.
69
+ - Búsqueda mientras se escribe: `SearchBox` (recientes y populares al enfocar; estados vacío/error; la app pone la consulta).
70
+
71
+ ## 4. Armonía: lo que hace que «se vea cuidado»
72
+ - **Una voz.** Un énfasis por vista; el resto, calmado. Un tema = un gesto firma.
73
+ - **Radios coherentes:** el radio de lo de dentro es menor que el de su contenedor (los tokens ya lo resuelven; no pongas `rounded-*` sueltos).
74
+ - **Sombras y capas:** solo las del tema (`shadow-*`, `--ds-card-glow`); la elevación indica interactividad o capa, no decoración.
75
+ - **Titulares y párrafos:** equilibrados (`text-wrap: balance` en títulos, `pretty` en párrafos), longitud de línea cómoda (≈ 45–75 caracteres).
76
+ - **Color:** de la marca solo el primario como acento; neutros del tema; los estados con su tono semántico.
77
+ - **Espacio:** el aire es parte del diseño; recortarlo para «meter más» baja la jerarquía.
78
+ - **Detalle de estado:** foco visible, desactivado legible, carga con forma real, error con salida.
79
+
80
+ ## 5. Si algo no se puede lograr con el sistema
81
+ No lo fuerces con estilos propios: dilo, propón la combinación de patrones más cercana y anota el hueco (variable o
82
+ variante que faltaría) para la librería. Es mejor un hueco anotado que una pantalla fuera del sistema.
83
+
84
+ ## Fuentes
85
+ Apple HIG y su revisión Liquid Glass (resúmenes: createwithswift.com, superdesign.dev); Google Design, «Expressive Design: research»
86
+ y el estudio independiente (ACM, 2026); Nielsen Norman Group (10 heurísticas); guías «cuándo usar / cuándo no» de Polaris y
87
+ GOV.UK; guías de bento y de carga progresiva (Smashing Magazine, uxpatterns.dev). Verifica en las fuentes oficiales si una decisión depende de una cifra.
@@ -108,7 +108,9 @@ Formato: **cuándo** · **piezas** · **reglas** · **evita**.
108
108
  - **Primero el flujo:** `defineAuthFlow(preset)` (`orbital-ds/lib/auth-flow`) decide audiencia (`internal` ·
109
109
  `external`), métodos, registro, segundo factor y aspecto. Presets: `standard` · `social` · `passwordless` ·
110
110
  `partner` · `enterprise` · `hybrid` (plantilla por SSO y externos con cuenta propia, enrutados por dominio con
111
- `routeAuthIdentifier`) · `sso-only`. `validateAuthFlow` avisa de combinaciones sin sentido.
111
+ `routeAuthIdentifier`) · `sso-staff` (SSO interno + acceso externo: dos puertas sin escribir —«Continuar con SSO», directo al proveedor, y
112
+ «Acceso para personas externas», con correo y contraseña, passkey y 2FA obligatorio, por invitación— con
113
+ `AuthForm entry={flow.entry}`; no necesita `internalDomains`) · `sso-only`. `validateAuthFlow` avisa de combinaciones sin sentido.
112
114
  - **Interno o externo:** en `hybrid` (y `enterprise`) el correo decide la puerta. `internalDomains` → SSO de la
113
115
  plantilla (sin registro, sin 2FA propio: lo pone el directorio); el resto, cuenta propia con el 2FA y el registro
114
116
  del flujo. `access: { internal, external }` ajusta métodos, `mfaRequired` y `signUp` de cada puerta;