75 KiB

Raw Blame History Unescape Escape

title	type	audience	authority	status	source
Eidos Theming — Changelog (dated sprint records)	notes	human + agent	chronicle — records of WHAT HAPPENED to the theming system, kept verbatim; the living reference is THEMING.md + the per-channel RFCs + the code	chronicle	extracted from THEMING.md ss13/ss20-ss38 (2026-07-02 docs reconciliation); relocated from src/uix/eidos/THEMING_CHANGELOG.md (docs-book F7.3)

Eidos Theming — Changelog

Dated sprint records (corrections, incidents, commit references) extracted verbatim from THEMING.md. Each section keeps its original §N number — THEMING.md holds a numbered stub per section with the living decision and the pointer here, so historical §N citations across the corpus resolve. Nothing here is the current API by itself: where a section defined doctrine that is still alive, the stub in THEMING.md says so and points at the living source (RFC / config / generator).

13. Integración con Sema (`event:*` scope) — SUPERSEDED

Original body of THEMING §13. Superseded by the two-moment motion model (eidos-motion.md); kept as decision context.

Sema emite data-event-* durante hold windows perceptuales. Eidos reacciona vía events.css (animations) o vía tokens scoped a event:*.

Tokens scoped a `event:*`

Permite que un token cambie SU VALOR durante una señal:

recipes.toast = {
  // Color base — scope 'host'
  'bg': {
    value: 'var(--color-surface-raised)',
    scope: 'host'
  },

  // Override durante señal de announce — el toast cambia su bg
  // mientras dura la señal perceptual
  'bg-during-announce': {
    value: 'var(--color-primary-element)',
    scope: 'event:announce'
  }
};

CSS generado:

[data-toast] {
  --toast-bg: var(--color-surface-raised);
}
[data-toast][data-event='announce'] {
  --toast-bg-during-announce: var(--color-primary-element);
}

El recipe usa el token apropiado:

[data-toast] {
  background: var(--toast-bg);
}
[data-toast][data-event='announce'] {
  background: var(--toast-bg-during-announce);
}

Por qué NO usar `data-motion-ref`

eidos-motion.md propuso un atributo nuevo data-motion-ref y un registry separado. TSC absorbe esa necesidad sin nueva superficie DOM: el scope event:* se materializa contra data-event='X' que sema ya emite.

Reduced motion

Eidos lee data-motion (la pref global proyectada por ActivePrefs):

[data-motion='reduce'] [data-event][data-event-phase='active'] {
  animation-duration: 1ms;
  transition-duration: 1ms;
}

Cobertura per-event vive en events.css. Cobertura per-token (durante señal) puede vivir como composite scope [event:X, motion:reduce] si necesitas afinar.

20. Correcciones del engine de theming (2026-06-01)

Dos bugs del engine de theming detectados al construir el tema untitled-ui (web/routes/temas/untitled-ui) y corregidos a nivel engine (no parcheados en el theme), de modo que aplican a todos los themes y consumidores.

20.1 — Densidad inerte (`data-density` no hacía nada)

Síntoma: cambiar data-density entre compact / comfortable / spacious no movía nada en pantalla. El sistema de densidad parecía muerto.

Causa: el generador emitía los escalares de densidad (--density-scale, --density-space-scale, --density-control-scale, --density-content-scale) y los redeclaraba por [data-density='…'], pero las primitivas --space-* y --control-height-* eran px fijos que nunca los consumían. Los escalares existían y cambiaban, pero ningún token los usaba → cero efecto visible.

Fix (lib/render-css.ts): nuevo helper appendDensityScaledDeclarations que emite --space-{n} y --control-height-{k} como calc(<valor> * var(--density-{space|control}-scale)). El valor cero se emite tal cual (0px). A comfortable el escalar es 1, así que el resultado es idéntico al valor crudo — cero regresión para quien nunca cambia de densidad. Las primitivas de tamaño (--size-{k}-*) y el padding de los recipes heredan el escalado porque referencian var(--space-*) / var(--control-height-*).

Resultado (verificado): a compact el espaciado y las alturas se reducen (×0.84 / ×0.90), a spacious crecen (×1.16 / ×1.12).

Nota: solo se escalan space y control-height (los dos ejes con escalar dedicado y mapeo claro). La tipografía NO se escala con densidad — igual que Radix Themes / Untitled UI, la densidad afecta a ritmo y altura de controles, no al cuerpo de texto. El zoom global que SÍ escala la tipografía es un eje aparte (data-scaling) — ver §23.

Actualización (eje de scaling): los escalares --density-scale y --density-content-scale que el generador emitía originalmente fueron eliminados al introducir el eje scaling (§23). La densidad hoy emite solo --density-space-scale y --density-control-scale; el helper se generalizó a appendScaledMetricDeclarations, que compone calc(<raw> * var(--density-…-scale) * var(--scaling)) — densidad y scaling se multiplican.

20.2 — `contrast` ilegible sobre sólidos

Síntoma: el texto de los botones / badges / banners / cards de variante solid salía oscuro sobre un fondo saturado oscuro (p. ej. botón primario del base: texto purple-12 #402060 sobre purple-9 #8e4ec6 ≈ 2:1, ilegible).

Causa: el slot de color contrast mapeaba por defecto al step 12 ("texto de alto contraste", pensado para fondos CLAROS), y los recipes usan --color-{role}-contrast como color de texto SOBRE el sólido (step 9). Step 12 sobre step 9 = oscuro-sobre-oscuro.

Fix (lib/render-css.ts, loop de slots en renderThemeCss): el slot contrast, cuando usa el valor por defecto, ahora resuelve a var(--color-content-on-solid, var(--primitive-{role}-12)) — el color on-solid del theme (blanco), con el step 12 como fallback. Un override explícito del slot (roles: { x: { scale, slots: { contrast: '1' } } }) se respeta verbatim, así que roles monocromos que invierten su texto (p. ej. un primario carbón que apunta contrast al step 1) siguen funcionando.

--color-{role}-contrast se consume exclusivamente como fg sobre sólidos (button / badge / banner / card / calendar-range / color-picker ring) — verificado por grep — así que el cambio es seguro y no afecta a ningún uso de "texto oscuro sobre fondo claro" (ese es el slot text, step 11).

Verificación

npx vitest run src/uix/eidos: sin regresión — las únicas fallas son 3 pre-existentes (words huérfanos + wrappers, track aparte), confirmadas con baseline (git stash del cambio). El test active-eidos-config se actualizó para asertar la nueva forma density-aware de --space-4 / --control-height-xxs.
npm run generate:eidos-css regenerado (la densidad vive en el CSS estático precompilado; el contrast vive en el bloque de tema runtime).

21. Modelo de color de dos niveles (RFC — RESUELTO en §25)

Resuelto (2026-06-02). El modelo de color quedó decidido — ver §25. Se adoptó "paleta rica + capa semántica de alias / auto-derivación" y se descartó "intent = ancla de un solo color" (Radix no lo hace, y con una paleta rica el problema que motivaba el ancla desaparece). Lo de abajo se conserva como registro histórico de la propuesta original.

Tras el sprint de theming surgió una observación de fondo (comparando con Radix Themes): hoy cada rol de color exige una escala de 12 pasos, incluidos los 5 intents evaluativos (affirm / fulfill / risk / threat / loss). Eso obliga a autorar ramps a mano para hues fuera de la librería base (12 escalas) y es propenso a error — un intent es conceptualmente un color, no un ramp interactivo.

La propuesta (dos niveles: accents/neutral ricos + intents de un solo color ancla con slots derivados por color-mix(), más ampliar la librería hacia paridad Radix) está documentada como RFC en COLOR_MODEL_RFC.md. (Estado original: propuesta. Resuelto en §25 — se adoptó paleta rica + alias / auto-derivación y se descartó el ancla de un solo color.)

22. Mejoras pendientes del theming

Auditoría completa 2026-06-01: THEMING_AUDIT_2026-06-01.md — informe priorizado (P0–P3) en 6 frentes. Incluye defectos reales verificados (tokens de foundation inexistentes, neutral ilegible en dark, alpha scales fabricadas, tokens de densidad muertos, huecos de tests) más todo lo de abajo.

Backlog vivo de mejoras al sistema. Ordenado por impacto, no por prioridad.

✅ Modelo de color — paleta + roles/intents derivados (mayor · resuelto 2026-06-02) — adoptado el modelo Radix-style: paleta de 33 escalas (diseñable por el tema) + roles de jerarquía como alias explícito + intents auto-derivados por convención del libro (identidad = step 9). Se descartó el "intent = ancla de un solo color". Modelo completo en §25 / COLOR_MODEL_RFC.md.
✅ Variant surface/soft vía alpha en vez de tinte opaco (resuelto 2026-06-02) — el tinte soft por rol (Button + Badge {role}-soft-bg) se computaba opaco (step-1 track + color-mix opaco en hover) → no componía sobre fondos no uniformes. Resuelto con tokens derivados --color-{role}-surface (= --primitive-{role}-a2) + --color-{role}-surface-hover (= a3), translúcidos por construcción. Ver §24.2.

23. Eje de `scaling` (zoom global) — 2026-06-02

Eje independiente de la densidad, en paridad con el scaling de Radix Themes. Diseño completo en SCALING_RFC.md.

23.1 — Qué es y en qué se diferencia de la densidad

Son dos ejes ortogonales que se multiplican:

Eje	Atributo	Qué mueve	Tipografía
Densidad	`data-density` (`compact` / `comfortable` / `spacious`)	ritmo de layout (`space`) + altura de controles (`control-height`)	NO — el cuerpo de texto queda fijo
Scaling	`data-scaling` (`90` / `95` / `100` / `105` / `110`)	zoom global: `space` + `control-height` + `font-size` + `icon-size`	SÍ — escala el cuerpo de texto

Densidad = "más/menos aire entre cosas, controles más bajos, mismo texto". Scaling = "agranda/encoge todo proporcionalmente", igual que el zoom del navegador pero acotado al subárbol del tema. Conceptualmente: densidad es una decisión de diseño (compacto vs holgado); scaling es una decisión de accesibilidad / preferencia de tamaño del usuario.

23.2 — Qué escala y qué NO

--scaling (default var(--scaling-100) = 1) multiplica solo métricas en px cuyo crecimiento proporcional es correcto:

✅ --space-{n}, --control-height-{k} (también llevan el escalar de densidad)
✅ --font-size-{name}, --icon-size-{k}

NO escala (a propósito):

❌ line-height — es un ratio sin unidad; escalar el font-size ya escala el interlineado real.
❌ --radius-*, --border-*, sombras — un zoom de UI no engorda bordes ni radios proporcionalmente (Radix tampoco lo hace); mantenerlos fijos conserva la nitidez del chrome.

23.3 — Generación + proyección

lib/render-css.ts:

appendScalingDeclarations emite las constantes --scaling-{90..110} (STATIC_SCALING en lib/primitives/static.ts) + --scaling: var(--scaling-100) en :root.
appendScaledMetricDeclarations(declarations, prefix, record, densityScaleVar?) envuelve cada métrica en calc(<raw>[ * var(--density-…-scale)] * var(--scaling)). El valor cero se emite tal cual. space y control-height pasan el densityScaleVar; font-size e icon-size no (no dependen de densidad).
renderScalingBlocks emite [data-scaling='90'] { --scaling: var(--scaling-90); } … para los niveles ≠ 100. Como todas las métricas leen var(--scaling), reescribir esa única variable reproyecta el subárbol entero — cero redeclaración por token.

A 100 el escalar es 1 → idéntico al valor crudo, cero regresión para quien no toca scaling.

23.4 — API (`ActiveEidos`)

Simétrica a density:

createActiveEidos({
  scaling: '110',                  // estático
  // o reactivo:
  scalingSource: { get: () => prefs.scaling, onChange: (fn) => prefs.subscribe(fn) }
})

ActiveEidos escribe data-scaling en el target junto a data-theme / data-mode / data-density, y lo limpia en dispose(). La preferencia viaja por ActiveEidosPreferenceSource.getScaling(); DEFAULT_SCALING es '100'.

24. Correcciones P2 del engine (2026-06-02)

Dos defectos de calidad de la auditoría (THEMING_AUDIT_2026-06-01.md P2-2, P2-4), corregidos a nivel engine para que apliquen a todos los temas.

24.1 — Texto on-solid ilegible sobre sólidos claros (P2-2)

Síntoma: el texto de los botones / badges solid de roles con sólido claro (amarillo, ámbar, risk=naranja) salía blanco sobre claro — naranja-9 con blanco ≈ 2.3:1, sub-AA.

Causa: el slot contrast (color del texto SOBRE el sólido) resolvía por defecto a --color-content-on-solid (blanco) para todos los roles. Correcto para sólidos oscuros (purple, red), ilegible para sólidos claros.

Fix (render-css.ts): pick por luminancia. En generación, el engine calcula la ratio de contraste WCAG (gamma-linealizada, wcagContrastRatio) entre onSolid y el step-9 del rol. Si onSolid falla (< 3:1), el slot resuelve a --color-content-on-solid-contrast (un oscuro, nuevo semantic opcional content.onSolidContrast, #1c1917 en base) en vez de blanco.

risk (orange #f76b15)  →  texto #1c1917  =  5.89:1  ✓  (era ~2.3:1 con blanco)
primary (purple)       →  texto #fff     =  5.18:1  ✓  (se mantiene)
threat (red)           →  texto #fff     =  3.91:1  ✓  (convención, ≥3:1)

Solo risk volcó a oscuro en el tema base; el resto mantiene blanco. Un override explícito slots.contrast se respeta verbatim (p. ej. neutral sigue en step-12). El umbral 3:1 es el mínimo AA para UI / texto grande — ancla principista, no número mágico.

24.2 — Superficies tintadas opacas → translúcidas vía alpha (P2-4)

Síntoma: el fondo de la variante soft por rol (Button + Badge) era opaco → al superponerse sobre fondos no uniformes (filas a rayas, imágenes, gradientes) tapaba el fondo en vez de teñirlo.

Causa: {role}-soft-bg = var(--color-{role}-track) (step-1, opaco) y el hover un color-mix opaco.

Fix: nuevos tokens de rol derivados, translúcidos por construcción (usan el alpha compositing-inverse §P1-1, consistente con el sólido):

--color-{role}-surface        =  var(--primitive-{role}-a2)   /* soft bg     */
--color-{role}-surface-hover  =  var(--primitive-{role}-a3)   /* soft bg hover */

Button y Badge soft consumen esos tokens. Sobre la superficie por defecto se ven casi idénticos (a2 ≈ el step-1 anterior); sobre fondos no uniformes ahora componen correctamente.

Toast y Tabs NO se tocaron — aunque la auditoría los listó, son tarjetas: el toast tiene fondo neutral opaco y la tab-list un surface-default ya translúcido. La opacidad ahí es correcta por diseño (no quieres ver el contenido de la página a través de un toast). La fórmula opaca que §22 documentaba mal era la de soft-bg-hover de Button, ya migrada.

25. Modelo de color — paleta + roles/intents derivados (2026-06-02)

Decisiones cerradas sobre el modelo de color. Resuelve el RFC §21. Es, 1:1, el modelo de Radix Themes: una paleta de escalas + una capa semántica de alias + override por componente. Lo único propio es que los intents (capa del libro) auto-derivan de la paleta por convención.

25.1 — Las tres capas

Capa	Qué es	Cómo se define
Paleta	librería de escalas de 12 pasos	`--scale-{name}-{step}` (+ alpha `--scale-{name}-a{step}`) · directamente usable · diseñable por el tema
Roles (jerarquía)	`primary` · `secondary` · `tertiary`	alias explícito a una escala (decisión de marca · obligatorio)
Intents	`neutral` + `affirm`/`fulfill`/`risk`/`threat`/`loss`	auto-derivados de la paleta por convención del libro · identidad = step 9 · slots derivan normal · override opcional

Los componentes consumen la capa semántica (--color-{role}-{slot}) y pueden override su color a cualquier escala vía la prop color / data-color.

25.2 — Paleta (la fuente, diseñable)

Escalas funcionales de 12 pasos: 1-2 fondos · 3-5 componente · 6-8 bordes · 9 sólido · 10 hover · 11-12 texto. El representativo de una escala es el step 9 (el sólido), NO el medio geométrico (step 6, que es un tono de borde lavado). Cada rol expone 13 slots desde esos 12 pasos — bg2·2 (2.º nivel de fondo), separator·6 (divisor sutil), border-hover·8 y text-strong·12 re-exponen steps que el contrato inicial de 9 había tirado; eran necesidades reales de UI/a11y (ver §25.2 · "13 slots").
Directamente usable: cualquier paso es var(--scale-{name}-{step}) (p. ej. var(--scale-green-10)). No existe alias corto --{name}-{step}: dos formas para el mismo valor crearían ambigüedad sobre cuál es la canónica.
Diseñable: la paleta la trae el tema (dominio del diseñador). El framework envía una paleta por defecto de 33 escalas (en lib/themes/color-scales.ts
- base.ts). Muchas se sembraron desde Radix Colors —un buen punto de partida— pero la paleta es NUESTRA, sin perseguir paridad con nadie. Un tema la reemplaza/amplía; un color de marca se añade como una escala (autorada o generada), nunca como un valor inline suelto.

Regla de pertenencia — por qué 33 y no un número mágico

El tamaño de la paleta no es un tope fijo (el viejo "32 y punto" era un proxy barato de "no metas relleno"). Una familia se gana su slot solo si cruza las tres puertas — así el criterio escala sin depender de un número:

Hueco perceptual real — rellena un vacío en el plano croma-hue (distancia ΔE Oklab entre familias vecinas en hue, NO grados crudos: un hueco de 36° en la banda azul de bajo croma pesa perceptualmente menos que uno de 24° entre magentas saturados, porque a bajo croma los puntos están más cerca del origen a-b).
Nombre + demanda — es un color que la gente pide con nombre propio (marca, gráficas), no una transición sin nombre.
No confusable — no está más apretada que el suelo del set enviado (~0.023 ΔE Oklab en el sólido). El "≥ 0.04 absoluto" sería mentira: la propia paleta enviada tiene 7 pares por debajo de 0.04 en el step 9 — pares Radix-canónicos distintos-pero-cercanos que aceptamos (grandfathered): teal/jade (0.024, el más ajustado), green/grass, violet/iris, red/ruby, red/tomato, green/jade, ruby/crimson. La puerta prohíbe empeorar ese suelo, no alcanzar un ideal que el set nunca cumplió.

fuchsia (~H334, #cf28bb) cruza las tres limpio: hueco real (plum→pink, el 3.er mayor del plano a-b), nombre fuerte + muy pedida, y ΔE 0.042 a su vecina más cercana (plum) — holgado sobre el suelo. Por eso entra; el 33 es consecuencia de la regla, no al revés. Descartadas por fallar alguna puerta: cerulean/azure (hueco modesto una vez ponderado + nombre débil en la banda azul, que "resiste nombres"), chartreuse (pega con lime).

La invariante se verifica en la SALIDA, no en la entrada

La puerta 3 vale lo que el generador más flojo. Hay tres generadores — autorado, generatePalette (paramétrico, lib/generate-palette.ts) y deriveScheme (M3 runtime, $color)— y cualquiera puede escupir dos familias confusables sin que una puerta de entrada lo frene (medido: generatePalette a tone +0.12 funde yellow = lime, ΔE 0.0). Por eso la garantía es un test sobre la salida — lib/palette-invariant.test.ts — que:

corre sobre los tres generadores;
usa dos suelos honestos: sólido (step 9) ≥ 0.02 (el confusable que importa, el acento que usan los componentes) e idéntico ≥ 0.002 en cualquier step;
chequea varios steps (3 · 9 · 11): tints y texto colisionan peor que el sólido (green↔jade cae a 0.003 en el step 3), así que medir solo el 9 subestima la confusabilidad;
exceptúa monochrome: colapsar la jerarquía a una tinta es intencional (diferencia por tono + énfasis, no por hue), no un defecto.

El builder clampa el tono a ≤ +0.08 justo para no entrar en la zona donde las familias claras blanquean hacia el techo de gamut y se funden.

Jerarquía e intent nunca comparten escala (guard G1)

Un alias de jerarquía (primary/secondary/tertiary) y un intent valenciado (affirm/fulfill/risk/threat/loss) no pueden resolver a la misma escala: sería un hue con dos significados opuestos — "acento de marca" y, p. ej., "pérdida". El modelo no lo impedía por sí solo, así que completeColorRoleMap (lib/config-types.ts) lo valida y lanza — una config de tema colisionante es un error y debe fallar alto, no recolorear semántica en silencio. neutral está exento (es el intent no-valenciado; comparte el gris legítimamente con el chrome neutro). En el builder, el picker de jerarquía excluye las escalas que un intent ya ocupa — el mismo candado a nivel de UX.

25.3 — Roles de jerarquía (alias explícito)

primary / secondary / tertiary son decisiones de marca sin color canónico: el tema DEBE mapearlos a una escala de la paleta. Pueden llevar override de slots (p. ej. un primario monocromo con slots: { contrast: '1' }).

25.4 — Intents auto-derivados (convención del libro)

Los 6 intents tienen color canónico definido en el libro Diseñando lo que ocurre. La convención INTENT → escala vive en CANONICAL_INTENT_SCALES (lib/config-types.ts): neutral→gray · affirm→teal · fulfill→green · risk→amber · threat→red · loss→plum.
Un intent omitido del mapa de roles auto-deriva de la paleta por esa convención (completeColorRoleMap, consumido por render-css y la validación). Su identidad es el sólido (step 9); los 13 slots derivan normal. La paleta debe proveer esas escalas (o el tema overridea el intent mapeándolo explícito).
Tipos: en ColorRoleMap la jerarquía es obligatoria y los intents opcionales — Record<HierarchyColorRole, V> & Partial<Record<Intent, V>>.
neutral es el 6º intent pero sin valencia: funciona como gris de superficies/bordes/texto, por eso auto-deriva a una escala gris (no es una señal valenced). Las 5 valenced llevan la carga.
Doctrina: el color EXPRESA el intent, no lo define — la valencia/activación la lleva la capa sema (sonido/haptic/motion); el color solo aporta la identidad de hue.

Intents nunca solo por color (CVD / WCAG 1.4.1 · guard G3)

El color es un canal, no el único. WCAG 1.4.1: el significado que comunica el color debe comunicarse también por un canal no cromático — icono, forma, texto/etiqueta o ARIA (role/live-region). No es opcional: los dos pares valenciados colapsan en daltonismo — affirm(teal)/fulfill(green) son dos verdes, y risk(amber)/threat(red) se confunden en protanopia/deuteranopia. Es la cara concreta de "el color EXPRESA el intent, no lo define".

affirm ≠ fulfill (no intercambiables): affirm = positivo de baja activación (confirmación suave — checkbox marcado, toggle on, "guardado"); fulfill = positivo de alta activación (objetivo cumplido — proceso/tarea completada). Por eso Toggle/Checkbox/Radio/Select solo exponen affirm; Button y las superficies de estado exponen ambos.

Estado (auditado 2026-07-01) — la mayoría cumple por diseño: Toast (icono por intent), Metrics.Delta (flecha de tendencia), Field (role=alert + live-region), Switch (posición del thumb), Checkbox/Radio (icono), Form (ErrorSummary con texto), PasswordField (etiqueta de fuerza), Stepper (forma + número). Regla: un componente que señaliza estado evaluativo debe enviar su cue no-cromático por defecto, como éstos — no delegarlo al app.

Hueco a cerrar — Meter: la zona (below/optimum/above) cambia solo por color (valueText es opcional). Debe enviar por defecto un cue de forma/icono por zona.
Acciones con intent (Button · IconButton · SplitButton · Fab · ToggleGroup): el significado lo lleva la etiqueta de la acción ("Borrar"); el intent tinta como refuerzo — no es violación mientras haya etiqueta. La regla: un control con intent evaluativo nunca icon-only sin aria-label, y su glifo/etiqueta porta el significado, no solo el hue.
No confundir con afordancia: el color de foco/selección (fields, table, calendar, listbox…) es branding, no estado evaluativo — no cae bajo esta regla (el foco ya lo marca el outline; la selección, aria-selected).

Enforcement: la composición es runtime, así que un lint estático no prueba que cada instancia lleve su cue. La garantía es doctrinal + el default de cada componente de estado. Un dev-warning opt-in sobre [data-intent] sin cue reconocible queda como trabajo futuro.

25.5 — Override por componente

Cualquier componente acepta color="..." (cualquier escala de la paleta) → la cascada _accent-* del recipe remapea sus tokens a esa escala para esa instancia. Equivalente a <Button color="grass"> de Radix.

25.6 — Por qué se DESCARTÓ el "ancla por rol"

El RFC §21 proponía declarar un intent como un solo hex ({ anchor }) y derivar los slots inline con color-mix(). Se descartó: Radix no lo hace (genera una escala desde un hex y la aliasa), y con una paleta rica el problema que lo motivaba (autorar 12 pasos a mano para loss → el bug de loss=azul) desaparece solo: loss simplemente aliasa la escala plum, que ya existe en la paleta. El modelo final es paleta rica + alias / auto-derivación, no ancla.

25.7 — Framework vs tema

Framework: envía la paleta por defecto (33 escalas) — para el tema base y para quien no traiga la suya.
Tema de marca (p. ej. Grafito): trae su propia paleta + mapea la jerarquía; los intents auto-derivan. El framework no persigue paridad con ninguna librería — la paleta base es un punto de partida, no un contrato.

26. Theme builder en runtime — `eidos.applyColorScheme` (2026-06-04)

El RFC §6.2 (un seed → todo el sistema) está implementado como API de primera clase. Un app re-tematiza desde UN color de marca con una llamada, sin tocar el CSS:

const result = eidos.applyColorScheme('#8e4ec6', {
  variant: 'tonal',                  // 'tonal' | 'vibrant' | 'monochrome'
  temper: 0.12,                      // cohesión de intents (mantiene hue)
  overrides: { tertiary: '#3e63dd' } // fija un rol; el resto deriva del seed
})
eidos.clearColorScheme()             // revierte a los primitives del tema

Qué hace: compone el motor uix.color — deriveScheme (Material 3 → jerarquía

neutral) → generateScale (12 pasos por rol) → APCA on-solid → alpha compositing-inverse — en un override de la capa de binding --primitive-{role}-* (+ --color-{role}-contrast). Override del binding reproyecta cada --color-{role}-{slot} y el chrome neutral (surface/content/border) aguas abajo. La paleta de 33 escalas y los slots NO se tocan.

Capas (matemática pura → composición pura → aplicación DOM):

Pieza	Dónde	Qué
matemática	`arts/color` (`$color`)	`deriveScheme` / `generateScale` / `temper` / APCA / alpha — pura, isomórfica
composición	`eidos/lib/build-scheme.ts`	`buildScheme(seed, opts)` → `{ variables, roles }` — pura, testeable
runtime	`ActiveEidos.applyColorScheme`	resuelve donantes + background del tema activo, escribe el bloque de estilo, sigue light/dark

Sigue el modo: las curvas-donantes + el background salen del tema activo, así que el esquema se re-deriva en cada apply() (cambio de modo → ramp light vs dark). El bloque uix-eidos-scheme se escribe después del de tema para ganar en orden de cascada.

Override por rol + temper = doctrina de §25.4 / RFC §6.2: la jerarquía deriva (override per-rol opcional), los intents mantienen su hue y solo afinan temperatura. applyColorScheme devuelve BuildSchemeResult (steps hex + stepsOklch

solid / on-solid / pinned por rol) para introspección de UI.

Wide-gamut: el bloque apila hex fallback + oklch() por paso (vía schemeDeclarations), y generateScale retiene el OKLCH raw sin clamp — un seed vívido (croma > sRGB) sale wide-gamut en P3. Ver §27.

Demo en vivo: /temas/color (el builder usa el mismo buildScheme). Tests: build-scheme.test.ts + active-eidos.test.ts.

27. Salida wide-gamut OKLCH (default-on) (2026-06-04)

RFC §7 estrategia A, implementada por defecto. Cada paso de paleta se emite dos veces: el hex como fallback universal + un hermano oklch() que gana donde el navegador lo soporta (Chrome 111+ / Safari 15.4+ / Firefox 113+).

:root {
  --scale-purple-9: #8e4ec6;                     /* fallback sRGB */
  --scale-purple-9: oklch(0.5556 0.1829 305.86); /* gana -> gamut del display */
}

Solo las hojas opacas --scale-{name}-{step} ganan el hermano; las capas --primitive-* / --color-* son var() (heredan) y las alpha siguen como color-mix / rgba. Valores vacíos / no-color no reciben hermano.
sRGB idéntico: el hex y el oklch() derivado de un sRGB pintan el mismo color (verificado: --scale-purple-9 → oklch(...) pinta #8e4ec6). El wide-gamut REAL aparece cuando el origen excede sRGB (tema OKLCH / esquema generado vívido). La paleta Radix shipped es sRGB → idéntica hoy; wide-gamut visible de la paleta = Fase 3.
Default-on, sin flag: es el comportamiento del framework. render-css.ts > appendColorScaleDeclarations.
El generador SÍ produce wide-gamut REAL: buildScheme / applyColorScheme (§26) retienen el OKLCH raw de generateScale (sin clamp), así que un seed cuyo croma excede sRGB renderiza más saturado en P3 que su hex fallback — el bloque apila hex + oklch() por paso vía schemeDeclarations(result, { fallback }). El demo /temas/color lo demuestra con el slider vivacidad P3 (badge «fuera de sRGB → P3» al cruzar el gamut; verificado: croma 0.18 → 0.31).

28. Accesibilidad forced-colors + ramp de bordes (2026-06-05)

Forced-colors (Windows High Contrast) — bajo @media (forced-colors: active) el navegador auto-mapea bordes / texto / fondos a system colors (forced-color-adjust: auto), PERO elimina box-shadow — y el focus ring de eidos (--focus-ring) es un box-shadow, así que el foco desaparecía. Fix: la foundation emite siempre

@media (forced-colors: active) {
  :focus-visible { outline: 2px solid Highlight; outline-offset: 2px; }
}

Los componentes que ya enfocan con outline (p. ej. Button) conservan el suyo por especificidad; este es el fallback para los de box-shadow. renderForcedColorsBlock en render-css.ts.

prefers-contrast: more (macOS "Aumentar contraste", etc.) — bloque aparte que refuerza el chrome neutral para quien pide más contraste: bordes a pasos más fuertes (subtle/default/strong → neutral 7/8/9) + texto de-enfatizado más legible (secondary → 12, muted → 11). Sólidos + texto primario ya son alto-contraste. Usa :root:root (especificidad 0,2,0) para ganar al :root del tema sin depender del orden; referencia --primitive-neutral-* (resuelven del cascade; si un tema los omite, la declaración se ignora — degrada con gracia). Estrictamente aditivo (gated por el media query) y estrictamente MÁS fuerte, así que no puede regresar el look por defecto. renderPrefersContrastBlock en render-css.ts.

Ramp de bordes — el slot de rol border pasó de step 6 → step 7. En la escala funcional de Radix el 6 es un separador sutil y el 7 es el UI element border; el 6 se leía lavado en bordes reales (outline / surface / controles). element / hover / active (3 / 4 / 5) se mantienen (canónicos de Radix para component-bg). DEFAULT_COLOR_ROLE_SLOT_STEPS. Verificado en navegador (checkbox + token --color-{role}-border → step 7).

29. Profundidad (depth) — canal unificado + eventful (2026-06-05)

La profundidad es un canal unificado y eventful, no tres sistemas sueltos (sombra + superficie + z). Guía canónica: DEPTH_ENGINE_RFC.md. Dos momentos:

Estado — data-depth='{plane}' aplica un plano en reposo (flush · raised · overlay · modal · recessed) que cohere superficie + sombra + z. Los tokens --depth-{plane}-{cue} componen los primitivos existentes (--color-surface-*, --shadow-*, --z-index-*), así que la mezcla es mode-aware gratis. La regla [data-depth] aplica las señales aditivas seguras (box-shadow = gota shadow + rim-light halo, más z-index); surface queda opt-in (no pisa fondos de componente). El halo es un rim de borde superior computado en oklab (color-mix(in oklab, white N%, transparent)): invisible sobre superficies claras (manda la gota), señal de elevación sobre oscuras — la respuesta mode-adaptive a "la sombra miente en dark".
Evento — al emerger la sombra crece desde plano → la de reposo (sube); al presionar se aplana (recede). Vive en la firma (present-rise / press-squeeze sobre data-event-*), coordinado con motion + sound + haptic desde un solo evento. Generic: un elemento flush (sin sombra) = no-op. Degrada con prefers-reduced-motion.

Jaula abierta: el set de planos es config-driven (EidosConfig.depth.planes — añade/renombra/retunea); los primitivos siguen accesibles (box-shadow/z-index crudo a un paso); la capa eventful es aditiva y anulable (sobreescribe keyframes/signatures). Demo en vivo: /temas/profundidad.

Adopción (hecha, 2026-06-05): los componentes elevados consumen el canal — sus tokens de sombra (--{c}-…-shadow en recipes/base.ts, o el box-shadow directo) componen var(--depth-{plane}-shadow), var(--depth-{plane}-halo), así que el halo llega a popover · dialog · drawer · dropdown/context/navigation-menu · menubar · select · tooltip · card · combobox · command · link-preview · words. La z-index la sigue gestionando cada componente (las bandas z son más finas que los 5 planos) — la adopción es solo de la señal sombra+halo, cero riesgo de stacking. La adopción plena vía atributo data-depth (que unificaría también la z) queda como opción futura.

Atmósfera (frost, hecha 2026-06-05): cue blur por plano + regla opt-in [data-depth='{plane}'][data-frost] → superficie translúcida (color-mix(surface var(--depth-{plane}-translucency, 80%), transparent)) + backdrop-filter: blur(var(--depth-{plane}-blur)). Gated, nunca por defecto (un overlay opaco sigue opaco salvo que pida data-frost). El builder runtime ActiveEidos.applyDepth(planes) / clearDepth() (+ buildDepth puro, exportado de $uix/eidos) retune cualquier cue de plano en vivo — hermano de applyColorScheme / applyTypeScale. Demo: /temas/profundidad §Materiales.

Opacidad = función de la elevación (cue translucency, 2026-06-27): así como la sombra crece con la elevación, la opacidad del frost también — es un cue de plano (--depth-{plane}-translucency), no un valor fijo. Planos más altos = más opacos: un modal lee como vidrio sólido y legible, un raised queda aéreo. Foundation: overlay 68% · modal 80%. El tema cristal abre el rango (raised 52% · overlay 66% · modal 80%) para que el escalón sea claramente perceptible. El frost rule consume var(--depth-{plane}-translucency, 80%); un plano sin declararlo cae al 80%. (Antes la translucidez era idéntica en toda elevación — un error: no acompañaba a la sombra.)

Tier de sombra interior (--shadow-inset-*, 2026-06-15): la escala de sombra gana un tier inset mode-aware, distinto de las sombras de gota (exteriores) y de los inset-rings (anillo nítido inset 0 0 0 Npx, otro eje):

Token	Light	Dark
`--shadow-inset-subtle`	`inset 0 1px 2px rgb(15 23 42 / 0.08)`	`inset 0 1px 2px rgb(0 0 0 / 0.30)`
`--shadow-inset-deep`	`inset 0 2px 4px rgb(15 23 42 / 0.12)`	`inset 0 2px 4px rgb(0 0 0 / 0.45)`

El plano recessed lo consume (--depth-recessed-shadow: var(--shadow-inset-subtle)), sustituyendo el color-mix(neutral-contrast …) inline previo — que en dark daba un borde claro (embossado) en vez de un hundido; ahora es mode-correcto (inset oscuro en ambos modos). Referencias: Tailwind inset-shadow-{2xs,xs,sm}, Bootstrap shadow-inset, Chakra inner. Disponible además para estados pressed / wells.

Inset-ring (--ring-inset-width, 2026-06-15): eje hermano pero distinto — un anillo interior nítido (no difuminado), como el inset-ring de Tailwind (inset 0 0 0 Npx <color>). El ancho sale de la escala --border-width-* (--ring-inset-width por defecto thick=2px, retunable por tema / override por uso); el color va por el hook --ring-inset-color. No se puede hacer un token único --ring-inset pre-resuelto: CSS hornea los var() anidados en el scope donde se declara (:root), así que el color/ancho por-elemento no propagaría — la expresión vive en el punto de uso: box-shadow: inset 0 0 0 var(--ring-inset-width) var(--ring-inset-color, currentColor). Consumidores: date-field (focus de segmento), drag-drop (accepting 1px / dragover 2px), float-panel (focus + grabbed + resize-grip), select (item checked+highlighted). Las marcas laterales de un solo lado (range-calendar inset ±2px 0 0 0) no son anillos → se quedan. De paso, este eje da el primer uso real a los pasos thin/thick de --border-width-*.

Escala de blur canónica (--blur-*, 2026-06-15): el desenfoque es un primitivo (STATIC_BLUR → lib/primitives/static.ts), no un px disperso. Valores alineados a Tailwind, escalados por --scaling como --icon-size-*:

Token	px	= Tailwind
`--blur-none`	0	—
`--blur-sm`	4	xs
`--blur-md`	8	sm
`--blur-lg`	12	md
`--blur-xl`	16	lg
`--blur-xxl`	24	xl

Dos modelos de referencia: Tailwind (escala numérica cruda) y Apple (materiales semánticos ultraThin…thick que acoplan blur+translucidez). Eidos toma el de Tailwind como eje crudo y lo compone en la capa semántica de profundidad: los planos consumen --blur-* (--depth-overlay-blur: var(--blur-lg), --depth-modal-blur: var(--blur-xl)), igual que color separa --scale-* (crudo) de los roles. Un futuro tema "cristal" acopla blur+alpha por plano (el modelo Apple) sobre esta escala. Consumidores ya migrados: planos overlay/modal, tooltip (frost), dialog/drawer (overlay-blur). Nada inventa px de blur a mano.

Gradientes themeables (--gradient-angle-* + gradients, 2026-06-15): eje de dos capas, espejo de Tailwind (que declara 0 gradientes nombrados — solo maquinaria):

Direcciones (--gradient-angle-*): las 8 brújulas de Tailwind como ángulos CSS (to-t 0deg · to-tr 45 · to-r 90 · to-br 135 · to-b 180 · to-bl 225 · to-l 270 · to-tl 315).
Nombrados (gradients config → --gradient-*): extensibles (jaula abierta: extendEidosConfig({ primitives: { gradients: {…} } })), role/surface-composed → mode-aware vía los tokens que referencian. Default fuerte mínimo: un solo nombrado, --gradient-shimmer (barrido de carga; lo consume image). Un tema añade sus gradientes de marca aquí.

Los gradientes funcionales (color-picker HSV/checkerboard, conic de progress/meter, líneas 1px de cropper/tree-grid, máscara de scroll de tabs, split bicolor de range-calendar, grip de float-panel, barra de carga de command) no son de tema y siguen crudos — no son decorativos. skeleton tinta su shimmer por variante de color (data-driven), así que conserva su gradiente local pero dogfoodea var(--gradient-angle-to-r).

Eje de degradados — el 6º builder (build-gradient + applyGradients, 2026-06-27): sobre la capa de tokens, un builder simétrico a color/depth/type/shape/space. Lo que no hace nadie: los gradientes se derivan de roles de color en OKLCH, así que un --gradient-{name} retinta con la semilla y flipea light/dark gratis (Tailwind/Open Props/Panda mezclan dos extremos literales; Material 3 no tiene eje de gradientes).

Modelo compartido en $libs/gradient (puro, zero-dep → README): el MISMO Gradient (linear/radial/conic/mesh; stop = ref de rol | literal OKLCH | css) que consumen el eje y el futuro GradientBuilder (soma) — un gradiente construido es también un token. gradientToCss serializa los role-refs a var(--color-…), default in oklch.
Factories derivadas de rol (de $uix/eidos): deepen(role) (rampa de un color, paso 9→11), sheen(role) (barrido highlight), halo(role) (glow radial), aurora(roles) (mesh de N blobs radiales por rol, determinista, sobre surface — auto-retinta; nadie tiene un mesh derivado de paleta, todos congelan hex literal).
Runtime: ActiveEidos.applyGradients({ brand: deepen('primary'), aurora: aurora([...]) }) escribe un bloque gestionado de --gradient-{name} (re-derivado en cambio de modo), + gradient en ThemeSeed/applyTheme. Gamut-safe por construcción (los role-refs ya pasaron por el motor de color; un literal OKLCH lleva su fallback hex en la capa consumidora).
Interpolación in oklch por defecto (no el srgb turbio de los midpoints grises); presets de hue-path (longer/shorter) para auroras/iridiscencias desde 2 stops. shimmer migrado a in oklch.
parseGradient (CSS → modelo, round-trip lossless) queda para la Fase 2 — lo necesita el editor.

Dogfood: la demo /demos/cristal reemplazó sus ~12 gradientes hardcodeados por applyGradients({ aurora: aurora([...]), brand: {…} }) — gradiente = token themeable que retinta.

Breakpoints — fuente única + container queries (EidosConfig.breakpoints, --breakpoint-*, 2026-06-15): la fuente de verdad de los breakpoints es el servicio runtime ActiveDom (el dev los setea vía createActiveUix({ dom: { breakpoints } }); BREAKPOINTS_DEFAULT es solo el seed). ActiveEidos threadea dom.breakpoints.current a renderStaticCss, que los emite como tokens --breakpoint-{sm..xxl} y los usa en los @media de tipografía responsive — así el CSS generado deja de congelarse en un const duplicado y sigue los breakpoints configurados. Container queries: una recipe declara overrides por breakpoint en la key reservada container (hermana de composition):

recipes: { card: { container: { md: { 'pad': 'var(--space-6)' } } } }
// → @container (min-width: 768px) { [data-card] { --card-pad: var(--space-6) } }

El generador (emitContainerQueries) usa los mismos breakpoints configurados (px literal — CSS prohíbe var() en condiciones @container/@media, así que la sincronía solo es posible generándolo). Opt-in: un ancestro con data-container activa container-type: inline-size. Eje themeable, 0 consumidores hoy (jaula abierta).

Opacidad — escala coordinada de dos capas (--opacity-*, 2026-06-15): mismo patrón dual que la sombra (numérico + semántico).

Numérico (--opacity-{0,5,…,100}, Tailwind step-5): granularidad fina para interfaces etéreas / cristal (capas translúcidas en el tramo bajo).
Semántico (los roles que consumen los recipes): ghost 0.3 · disabled 0.4 · scrim 0.45 · muted 0.65 · overlay 0.65 · subtle 0.8 · press 0.85 · hover 0.9 · full 1. disabled = 0.4 (estándar moderno ≈ Material 38%).

Unificación: el estado disabled se renderizaba con ~10 valores distintos (0.45–0.72) en recipes (disabled-opacity) + CSS ([data-disabled]/:disabled). Ahora TODOS consumen var(--opacity-disabled). La deriva ad-hoc de CSS (muted/ghost/subtle) migrada a sus roles. Quedan crudos solo los de animación (spinner keyframe) y scroll-frames (rol no semántico). Retunable por tema, como size/sombra/superficie (decisión del usuario).

Border-width — escala lineal (--border-width-*, 2026-06-15): adoptada la lineal de Bootstrap (none 0 · thin 1 · medium 2 · thick 3 · heavy 4) — la única escala de referencia que tiene el 3px que los componentes usan (Tailwind salta 1/2/4/8). Podados los pasos muertos hairline(0.5) y el viejo medium(1.5) (0 consumidores); medium retuneado a 2, thick a 3, heavy(4) nuevo. Los 3 consumidores de thick(2px) — focus-ring de select, quote-border, separator — + el default de --ring-inset-width movidos a medium(2px, sin cambio visual). Todos los anchos crudos tokenizados (consumo completo de la escala — la tesis de la auditoría): 3px→thick, 2px→medium, 1px→var(--border-width), 1.5px→medium (chevron de navigation-menu) en ~35 ficheros. Así un tema retunea el ancho de borde de una vez (p. ej. --border-width denso) y todos los bordes lo siguen.

Tracking — caps para mayúsculas (--tracking-*, 2026-06-15): añadidos caps 0.04em (micro-tracking canónico de etiquetas en MAYÚSCULAS — el patrón dominante en menús/headings) y widest 0.1em. Los 11 letter-spacing crudos de CSS migrados a sus roles (0.04→caps · 0.05→wider · 0.02→wide · 0.1→widest). El letterSpacing óptico por-tamaño de la escala tipográfica (xxs/xs…) NO se migra: es la corrección óptica intrínseca de cada paso.

Pendiente (menor): el cue scrim está disponible como token (--depth-{plane}-scrim) pero sin regla cableada — el backdrop dim de los modales lo gestiona hoy cada componente.

30. Forma (shape) — continuidad + familias + anidado + eventful (2026-06-05)

La forma es un canal, no un número de border-radius. Guía canónica: SHAPE_ENGINE_RFC.md. La magnitud sigue en --radius-* (intacta); shape añade los ejes que todos dejan planos. El primer squircle-como-token de la web (el campo entero es arco + estático; la continuidad solo existía en Apple, atada a plataforma).

Continuidad — --shape-smoothing (exponente superelipse: 1 = arco, 2 = squircle) + familias vía data-shape='{family}' → corner-shape: rounded (round) · continuous (superellipse(var(--shape-smoothing))) · cut (bevel) · scoop. Opt-in (no pisa círculos/píldoras) y progresivo: degrada al arco de border-radius donde no hay corner-shape (Chromium 2025+).
Armonía anidada — [data-shape-nest] deriva border-radius: max(0px, var(--shape-outer-radius) − var(--shape-nest-gap)): el hijo queda concéntrico al padre (que expone su radio en --shape-outer-radius). El concéntrico de 4 esquinas requiere radios finitos: a full (9999px) el radio se recorta a ½ de la dimensión menor de cada elemento, así que un hijo de proporción distinta no puede serlo en las 4. Pero sí en las superiores (radio_card − gap) si las inferiores quedan rectas — la geometría del reproductor iOS. El demo /temas/forma lo mide (ResizeObserver, porque el cap es valor usado no legible en CSS) y lo aplica al top de la carátula.
Eventful (dos momentos) — la forma en reposo (data-shape) + el morph al pulsar: la firma press-squeeze cuadra la esquina un instante (--shape-smoothing 2→3→2, registrado con @property para que interpole). Cross-modal: un evento mueve escala + sombra + esquina. Degrada con prefers-reduced-motion. No-op en familias no-continuous.
Jaula abierta — escala + familias config-driven (EidosConfig.primitives.shape); el border-radius crudo siempre a un paso; builder runtime ActiveEidos.applyShape(seed) / clearShape() (+ buildShape puro, exportado de $uix/eidos) para dialar continuidad / nestGap / familias en vivo. Demo: /temas/forma.
Default por tier — la firma (2026-06-28) — la continuidad dejó de ser opt-in inerte. Las SUPERFICIES nacen squircle por default; los controles se quedan en arco. Razón geométrica: a radio de superficie (≥~10px) arco y squircle divergen (premium); a radio de control (~6px) son indistinguibles → el split no cuesta coherencia. Dos tiers, regla de foundation enumerada (renderShapeBlocks → :where(<superficies>) { corner-shape: var(--shape-surface-default, …) }):
- Tier A — paneles flotantes [data-{c}-content] (dialog/drawer/popover/dropdown/context/ menubar/navigation-menu/select/combobox/tooltip/link-preview + [data-command]); los pickers heredan vía Popover.
- Tier B — superficies no-flotantes (sin marcador compartido → enumeradas): [data-card], [data-banner], [data-radio-cards-item].
- NO por [data-archetype='content']: ese arquetipo también marca tabs/accordion/collapsible/ table content (no-superficies) → un hook sobre-aplicaría. Enumerar es preciso.
- :where() (especificidad 0) deja ganar al prop shape → el prop pasa de opt-IN (activar squircle) a opt-OUT (shape='rounded' escapa a arco) en superficies. Knob de tema --shape-surface-default (unset → squircle; round revierte el tier entero). Degrada al arco donde no hay corner-shape. Guard test (superficies sí, controles/filas/pills no) en active-eidos-config.test.ts.

Pendiente (futuro): afinar el exponente por defecto si "2" canta en superficies grandes (--shape-smoothing es dial de un token, A/B en dialog) y extender el prop shape de opt-out a las superficies que aún no lo exponen (hoy lo tienen button/card/+pocos). Pills/avatares ya quedan fuera por construcción (no entran en la enumeración).

31. Estructura (espacio · densidad · escala) — el espacio como ritmo (2026-06-05)

Los sistemas estructurales (a diferencia de los expresivos) son solo-estado — el escenario, no el suceso. Guía canónica: STRUCTURE_ENGINE_RFC.md. Tres ejes ortogonales:

Densidad — [data-density='compact'|'comfortable'|'spacious'] reescala el layout (space
- control-height) sin tocar la legibilidad del texto. 3 niveles × 2 ejes (config-driven).
Scaling — [data-scaling='90'..'110'] es el zoom global (incluye tipografía; paridad Radix), compone con densidad.
Espacio (el ritmo) — --space-{key} se emite como calc(value · var(--density-space-scale) · var(--scaling)). El value ya no es solo px plano: buildSpaceScale(seed) (puro) + ActiveEidos.applySpacing(seed) / clearSpacing() lo regeneran desde una unidad base (base × N, modular) y opcionalmente fluido (growth > 1 → cada paso clamp() que respira entre 480 y 1280px, reusando el fluidClamp del type scale). Preserva la composición density × scaling. Hermano de applyTypeScale — opt-in sobre la escala authored (STATIC_SPACE intacta). Exportado de $uix/eidos. Demo: /temas/estructura.

Doctrina: el espacio es ritmo, no una tabla de píxeles. Modular + fluido + compuesto con densidad × zoom desde una semilla. El campo entero shippea una escala plana estática; el espacio fluido (que casi nadie hace para el espacio, solo para el tipo) + los tres ejes integrados son el diferencial. Estructural = solo-estado (sin dos momentos — el modelo eventful es de los canales expresivos).

Pendiente (futuro): applyTheme(seed) — una semilla que componga tipo + espacio (ritmo compartido), capstone del cuarteto→quinteto de builders.

32. Focus ring — modelo de dos anillos parametrizado (2026-06-11)

El foco de los inputs estaba implementado distinto en cada componente (el anillo del [data-archetype]:focus-visible del foundation sobre el <input>, anillos ad-hoc [data-x-input]:focus-visible, el color-mix propio del textarea…). Resultado: un doble marco al editar (anillo interior + exterior), inconsistente entre componentes.

Solución — un único modelo de dos anillos, parametrizado a nivel de tema:

Token nuevo: --focus-ring-inner-width (= 0 por defecto). Definido en primitives/static.ts > STATIC_FOCUS_RING.innerWidth, tipado en FocusRingPrimitiveSet (config-types.ts), emitido en render-css.ts.

El anillo canónico (--focus-ring del foundation y todos los *-focus-shadow de los campos en recipes/base.ts) es ahora dos anillos:

inset 0 0 0 var(--focus-ring-inner-width) var(--focus-ring-color),                       /* interior */
0 0 0 var(--focus-ring-offset) var(--color-surface-default),                             /* hueco */
0 0 0 calc(var(--focus-ring-offset) + var(--focus-ring-width)) var(--focus-ring-color)   /* exterior */

Con inner-width: 0 el anillo interior es invisible → un solo marco exterior.

El anillo del foundation [data-archetype]:focus-visible excluye los elementos internos de campo (:not(input):not(textarea):not(select):not([data-archetype='segment'])): su foco lo muestra el control que los envuelve (archetypes.css).
Quitados los anillos interiores ad-hoc: [data-css-field-input]:focus-visible, [data-number-field-input]:focus-visible; el textarea pasa a box-shadow: var(--focus-ring).

Para encender el anillo interior en un tema: subir --focus-ring-inner-width > 0 → aparece la segunda línea en todos los inputs a la vez, sin tocar componentes.

Doctrina: el foco es un concepto de tema, no de componente. Dos anillos definidos una sola vez y parametrizados; los componentes no reinventan su anillo.

Backlog — tokens retirados en la unificación

Al unificar, la cascada per-data-color --_{css-field,number-field}-accent-* quedó sin uso (solo la consumía el anillo interior ad-hoc) y se retiró. Quedan registrados aquí por si se quiere reintroducir que css-field / number-field tiñan su foco por data-color (como hacen date/time/color-field con sus segmentos):

Componente	Tokens retirados	Cascada
`css-field`	`--_css-field-accent-border` · `--_css-field-accent-track` · `--_css-field-accent-text`	`[data-css-field][data-color='…']` × 8 (primary/secondary/neutral/affirm/fulfill/risk/threat/loss)
`number-field`	`--_number-field-accent-border` · `--_number-field-accent-track` · `--_number-field-accent-text`	`[data-number-field][data-color='…']` × 8

Para reinstaurarlos: re-declarar el trío en el bloque base + la cascada data-color, y consumir accent-border en el anillo del campo. Hoy ambos usan el --focus-ring-color genérico (consistente con el resto), así que data-color no tiñe su foco — decisión deliberada de la unificación.

Outline en superficies — `box-shadow` muere en HCM/overflow (2026-06-29)

El anillo box-shadow tiene tres fragilidades en controles autónomos sobre una superficie (no campos): (1) box-shadow desaparece bajo forced-colors / HCM (§28); (2) lo recorta un ancestro overflow: hidden; (3) su capa de hueco hardcodea var(--color-surface-default) (arriba), así que sobre un plano raised / overlay / relleno el hueco no casa con el fondo → halo desalineado.

Por eso el tier de controles de superficie usa outline:

outline: var(--focus-ring-width) solid var(--focus-ring-color);
outline-offset: var(--focus-ring-offset);   /* o 0 flush para input / scrollbar */

outline sigue el border-radius en todo navegador evergreen, no lo recorta overflow, y el fallback de forced-colors ya mapea outline (§28). Es el patrón de button / card y ~40 componentes. Los últimos 5 en box-shadow se migraron en ab62cca7: command-input, collapsible-trigger, scroll-area-scrollbar, toggle, splitter.

Los campos (input / textarea / segmentos) SÍ siguen en box-shadow — necesitan el anillo INTERIOR parametrizable (--focus-ring-inner-width) que outline, al ser una sola línea, no puede dar. El modelo de dos anillos de arriba es para ellos.

Orphan: tras migrar los 5, el token --focus-ring (box-shadow) quedó sin consumidores en CSS (solo lo citan docs). Se deja como token público de foundation; podarlo es decisión de API aparte (junto con los --{x}-bg-hover huérfanos, mismo blocker de base.css).

33. Glifos de stepper themeables (`spin-field`) — 2026-06-11

Los botones increment/decrement pintan su glifo desde un token, no desde markup obligatorio. Un trigger sin children renderiza el glifo por defecto vía :empty::before; pasar children lo overridea por instancia. El glifo es decorativo — el botón se etiqueta con su aria-label (morfo), así que content en un pseudo-elemento es seguro (mismo patrón que --date-range-field-separator-glyph).

Cuatro tokens, dos por layout (viven en el recipe compartido spin-field — ver §34):

Token	Default	Layout
`--spin-field-control-increment-glyph`	`'+'`	split
`--spin-field-control-decrement-glyph`	`'−'` (`\2212`)	split
`--spin-field-control-increment-glyph-stacked`	`'▲'` (`\25B2`)	stacked
`--spin-field-control-decrement-glyph-stacked`	`'▼'` (`\25BC`)	stacked

El CSS resuelve una variable interna --_spin-field-increment-glyph que apunta al token split por defecto y se re-apunta al hermano -stacked bajo [data-steppers='stacked'], de modo que una sola regla content sirve ambos layouts. Un tema retinta/reforma overrideando cualquiera de los cuatro (globalmente o scoped por componente con [data-number-field] { --spin-field-control-… }); el color del glifo ya viaja por --spin-field-control-color* (no se duplica aquí).

Por qué cuatro y no dos: split usa el par horizontal +/−; la columna stacked usa flechas verticales ▲/▼. Un único par no puede tener ambos defaults a la vez, y forzar ▲/▼ en split (o +/− en stacked) rompe la convención. Cada par es independiente.

34. `spin-field` — visual compartido del stepper-field (`number-field` / `css-field`) — 2026-06-11

number-field y css-field son el mismo visual (campo con borde + input + botones increment/decrement + scrubber, layouts split/stacked, sizes/variants/colors, glifos); solo difieren en el modelo de valor (soma: número vs valor CSS). Tener dos recipes + dos CSS clonados causaba drift: refinar uno (botones cuadrados, flush, divisor) dejaba el otro con el look viejo. La respuesta canónica no es duplicar — es compartir estructuralmente, el mismo patrón que toggle-group reusa toggle.

Cómo:

Recipe único spin-field en recipes/base.ts → tokens --spin-field-* (geometría, superficie, control, glifos). NO hay --number-field-* / --css-field-*.
CSS único components/spin-field/spin-field.css con todas las reglas del stepper-field, seleccionando [data-spin-field*]. Cargado por el @import de foundation en index.css (no tiene .svelte propio que lo auto-importe).
Identidad estructural en los morfos de number-field y css-field: cada part declara data-spin-field / -input / -increment-trigger / -decrement-trigger / -scrubber (presence attrs). El Provider los emite vía syncAttrs; los sub-parts (cuyo soma hardcodea sus attrs) los emiten en su getter props. number-field.css y css-field.css quedan como stubs.

Theming por componente: aunque los tokens son compartidos, un tema puede tintar solo uno scopeando el token al data- del componente — [data-number-field] { --spin-field-bg: … } lo hereda el stepper porque vive dentro de ese elemento. El default es compartido.

Resultado: una sola fuente del visual del stepper-field. Un fix se aplica a los dos (y a cualquier futuro spin-field) sin posibilidad de drift. date/time/color-field son segmentados (sin steppers) — comparten solo la superficie del campo, lo que sería un refactor aparte.

35. Canon de escalas — auditoría de theming (2026-06-15)

Sprint de auditoría que llevó las escalas del theming a paridad con las referencias (Tailwind · Material 3 · Apple HIG · Bootstrap · Radix) y, sobre todo, forzó su consumo: la tesis de la auditoría es que una escala canónica que los componentes no consumen (la bypassan con literales) deriva en N variantes del mismo valor. Cada eje es ahora retunable por tema (igual que size/sombra/superficie) y los recipes consumen el token, nunca un literal. Detalle por-eje en el addendum de §29; tokens en la tabla de §6.

Eje	Token(s)	Canon	Decisión clave
Blur	`--blur-{none,sm,md,lg,xl,xxl}`	0/4/8/12/16/24 (Tailwind)	numérico crudo; los planos de depth lo consumen (`--depth-*-blur`)
Inner-shadow	`--shadow-inset-{subtle,deep}`	mode-aware (light slate / dark negro)	lo usa el plano `recessed`; ≠ inset-ring
Inset-ring	`--ring-inset-width` + `--ring-inset-color`	`inset 0 0 0 var(width) var(color)` en el punto de uso	un token único pre-resuelto es imposible (CSS hornea el `var()` anidado en `:root`)
Gradientes	`--gradient-angle-` + `gradients`→`--gradient-`	8 direcciones + nombrados role-composed	Tailwind ship 0 nombrados → solo `shimmer`; los funcionales (HSV, conic, líneas) NO son de tema
Breakpoints	`--breakpoint-{sm..xxl}`, `EidosConfig.breakpoints`	fuente = `ActiveDom` (runtime, dev-settable)	`ActiveEidos` threadea `dom.breakpoints` al generador; los `@media` dejan de congelarse
Container queries	recipe key `container` → `@container` + `[data-container]`	px literal generado (CSS prohíbe `var()` en `@container`)	jaula abierta, 0 consumidores hoy
Opacidad	`--opacity-{0..100}` + semánticos	dual numérico + semántico; `disabled 0.4` (≈ Material 38%)	unificado (~10 valores de disabled → 1); numérico fino = glass-friendly
Border-width	`--border-width-{none,thin,medium,thick,heavy}`	lineal Bootstrap 0/1/2/3/4 (única ref con el 3px real)	todos los anchos crudos tokenizados (~35 ficheros)
Tracking	`--tracking-{…,caps,widest}`	+ `caps 0.04em` (MAYÚSCULAS) + `widest 0.1em`	11 `letter-spacing` crudos migrados; el óptico por-tamaño NO

Incidente registrado: una reescritura masiva por PowerShell (WriteAllText) corrompió 11 ficheros (o→p); recuperados con git checkout + rehechos con la herramienta Edit. Regla: modificar ficheros del repo SOLO con Edit/Write, nunca PowerShell en bloque.

Fase 7 (size→fuente — parcial): documentados los 3 arquetipos canónicos (control · compact · dense, §5) + --size-* como referencia del control. Guard de coherencia activo: ningún font-size-*/icon-size-* de recipe puede ser literal px/rem (cierra el hueco del guard solo-CSS). Arreglados los últimos hardcodes (toggle, avatar → --font-size-*, valores preservados). El icon-size de password-field desde --control-height-* es correcto (es el tamaño del botón reveal, no del glifo) — falso positivo de la auditoría. Deferido: el refactor a consumir el bundle del arquetipo (en vez de re-declarar el mapeo) — grande, con edge-cases (fuentes semánticas por-parte, sistema --text-N de accordion) + edición en paralelo; el guard es lo que impide la deriva mientras tanto.

Bloque C — números mágicos sueltos (z-index · duración · border/ring)

Cierre de los literales que bypasseaban una escala ya existente. Regla: un literal que iguala un paso de escala DEBE consumir el token; nada de "intencionales".

z-index de overlays flotantes — viven en una escala nombrada propia, --z-index-overlay-* (STATIC_Z_INDEX_OVERLAY en lib/primitives/static.ts), separada del ladder global --z-index-* (que ordena los depth planes). Los overlays se portalan al <body> como hermanos entre sí y de los modales, así que comparten una banda plana baja donde cada peldaño queda justo por encima del scrim modal: un menú / select / popover abierto DENTRO de un dialog debe pintar por encima de él. La capa flotante de soma espeja el z computado del content sobre su positioner (soma/layers/floating/floating.svelte.ts) — por eso la banda NO puede ser el ladder 300–900: dropdown 300 < modal 700 ocultaría un dropdown abierto dentro de un dialog. Peldaños (bottom→top): inline · backdrop · content · floating · tooltip · detached · toast — tooltip por encima de floating (un tooltip tapa al dropdown, no al revés), toast por encima de la banda FloatPanel de soma (layers/stacking.svelte.ts). Cada recipe consume su peldaño vía var(--z-index-overlay-*): cero enteros crudos, y el guard contracts.test.ts ("overlay z-index against raw integers") los prohíbe. Los z-index: 0..5 de apilado local (avatar, tabs, sticky cells) son ordenación relativa intra-componente, NO esta banda — se quedan.
Duración — los que igualaban un paso de la escala la consumen: dialog enter 120ms→var(--duration-fast), exit 280ms→var(--duration-slow) (asimetría rápida-entra/lenta-sale preservada, ya 100% en escala); card emerge 320ms→var(--duration-slow); banner/code-block/link 120ms→fast. Los fallbacks muertos , 220ms/, 720ms (checkbox/button, cuyo recipe ya declaraba el token) se quitaron. Excepción razonada: press-duration 80ms, spinner-duration 720ms, loading-indicator-duration 900ms se quedan como token de recipe — son periodos de animación continua (giro / shimmer) o un press deliberadamente sub-fast, NO transiciones de interacción; la escala de 5 pasos (instant..slow) es para interacciones, no tiene sitio para ellos.
Border / ring width — los anchos únicos de borde/ring que igualaban un paso (2px=medium, 3px=thick, 1px=thin) se tokenizaron a var(--border-width-*) (avatar border + badge + carve, drawer drag-ring, slider thumb, grid-list focus-ring, toast accent-stripe → thick, table/menu cell/content border → var(--border-width)). Valor-preservante, cero cambio visual. Lo que se queda como escala dimensional propia (NO es el concepto border-width re-derivado): el ring del avatar sm/md/lg = 1.5/2/3px (el 1.5 quedó fuera de la escala global al podar el 0.5/1.5), ring-thickness 3..10px, track-width, content-width, offsets — escalas locales coherentes, no literales sueltos.

36. Gap canónico trigger→panel — offset token-driven (2026-06-22)

El sideOffset de Floating UI es un número JS — no acepta var(--token). Por eso cada flotante hardcodeaba su gap (0/4/6/8, incoherente). Canon:

@property --floating-gap <length> — registrada para que JS resuelva el px vía getComputedStyle (las custom props sin registrar devuelven el var(...) literal, no el valor). Tokens por arquetipo: --floating-gap-menu: var(--space-1) · --floating-gap-panel: var(--space-1-5). Regla foundation [data-floating-gap='menu'|'panel'] { --floating-gap: … }. Todo emitido en render-css.ts.
El posicionador compartido (soma/layers/floating/floating.svelte.ts) lee el --floating-gap resuelto del content vía un $derived sobre contentRef.current (reactivo; antes era un rAF de una pasada que NUNCA disparaba para menús portalizados → caían al sideOffset y salían pegados — fix 2026-06-28) y lo usa como offset de Floating UI (fallback al sideOffset numérico). Es el OFFSET, no un margin CSS: la flecha viaja con él (un margin la despegaría del ancla en popover/tooltip). Por eso NO se reutilizó el data-canonical-gap de split-button (margin — solo válido sin flecha).
Stamp condicional en el content eidos: data-floating-gap={rest.sideOffset === undefined ? 'panel'|'menu' : undefined} (como split-button). Un sideOffset puesto por el consumidor gana; solo el default cae al token. Los 5 pickers default sideOffset=undefined para seguir el token del panel (componen PopoverContent).

Arquetipo	Componentes	Gap
`menu` (gap pequeño)	dropdown · context · sub-menus · menubar · select · navigation-menu	`--floating-gap-menu` (`var(--space-1)`)
`panel`	popover · combobox · link-preview · 5 pickers (vía `PopoverContent`)	`--floating-gap-panel` (`--space-1-5`)

Fuera: command (dialog/inline, no anclado a trigger), onion-menu (radial). Para retunear el gap de un tema: override --floating-gap-menu / --floating-gap-panel.

Actualización 2026-06-28 — dos cosas: (1) --floating-gap-menu pasó de 0 a var(--space-1) (los menús dejan de salir pegados al trigger); (2) el read del canon en FloatingContent pasó de un rAF (que no entregaba el valor a los menús portalizados → solo nav-menu, CSS-posicionado, cogía el token) a un $derived reactivo sobre contentRef. Sin el (2), el (1) no llegaba a dropdown/menubar/select. En paralelo, en archetypes.css el focus-ring universal ([data-archetype]:focus-visible) ahora EXCLUYE item/option/content: las filas de menú/lista usan el highlight canónico también en :focus-visible (igual que el hover), y los paneles flotantes (content) ya no dibujan el anillo gordo alrededor de todo el float — su elevación (borde + sombra) es el límite.

37. Touch-target — 44px en táctil, gated por puntero (2026-06-28)

Eje de a11y que el ARCHETYPE_COHERENCE_AUDIT marcó 🔴 (0 componentes garantizaban 44/48px). Doctrina: agrandar el tap-target a 44px solo en @media (pointer: coarse) (táctil) — el desktop (puntero fino) mantiene su densidad compacta, cero regresión, la regla queda gated fuera. Validado reference-grade por React Spectrum (escala auto medium/large por tipo de puntero); el resto del campo web (Radix/MUI/Chakra) no lo gatea.

Controles (button + arquetipos trigger/close/action) — archetypes.css: @media (pointer: coarse) { :where(<arquetipos>, [data-button]):not([data-size='lg']):not([data-size='xl']) { min-block-size: 44px; min-inline-size: 44px } }. El :not(lg)(xl) hace doble función: salta los tamaños ya ≥44 (el min-* solo CRECE xs/sm/md, nunca encoge) Y sube la especificidad a 0,2,0 para ganarle al min-block-size del recipe (un :where() a 0,0,0 perdería).
Filas de lista (menu/select/listbox/command) — list-surface.css: sube --list-item-height (el suelo de min-block-size que cada lista puentea) a 44 para xs/sm/md en coarse.
Marcadores (checkbox/radio/switch) — NO se agranda el visual. Crecer la caja a 44px es un mecanismo de layout de Compose (sizeIn); ningún referente web lo porta. El patrón web (React Aria) es la fila etiquetada como target: [data-radio-group-row] (dot + texto) → min-block-size: 44px en coarse. La caja desnuda agrupada ya cumple WCAG 2.5.8 (24px, AA) por la excepción Spacing (los círculos de 24px no se intersectan con gap ≥4px; checkbox 12px / radio 12-16px). AAA (44px) = la fila, por la excepción Equivalent de WCAG 2.5.5. (Un pseudo de 44px que desborda al vecino NO vale: WCAG excluye el área solapada de la medición.) Pendiente: fila etiquetada de checkbox/switch — son cajas desnudas sin fila propia (label vía Field/consumidor) → tarea de Field.

Fuentes verificadas a mano: WCAG 2.5.5/2.5.8, Compose a11y, React Aria, React Spectrum. Commits a265d39a (controles) · c0904fc6 (filas) · 2750b9ce (fila de radio).

38. Capa de estado (state-layer) — feedback neutro unificado (2026-06-28)

El feedback neutro de interacción (hover / press / selected de un control sin valencia) estaba implementado de ~5 maneras distintas en ~60 archivos: surface-swap (background: var(--color-surface-raised)), color-mix(currentColor X%) ad-hoc, opacity-dim, tokens --{x}-bg-hover bespoke por componente… El ARCHETYPE_COHERENCE_AUDIT (Arq. 8) y el plugin de diseño marcaron lo mismo 🔴: ~168 reglas :hover resolviendo el MISMO efecto de cinco formas.

Solución — un único state-layer (modelo MD3), parametrizado a nivel de tema (archetypes.css > :root):

--state-hover:    color-mix(in srgb, currentColor  8%, transparent);
--state-press:    color-mix(in srgb, currentColor 12%, transparent);
--state-selected: color-mix(in srgb, currentColor 12%, transparent);

Basado en currentColor → theme-adaptive sin valores por-tema: el mismo token tiñe correcto en light y en dark (donde el surface-swap fijo perdía contraste — ganancia neta). Es el state-layer de Material Design 3 (hover 8% · press/selected 12%).

Doctrina — qué tier usa el state-layer

Tier neutro / ghost (la mayoría: triggers, items, ghost, controles sin valencia) → state-layer. Es el dueño del feedback neutro.
Tier valenced (solid / soft por color) → mantiene su hover de paleta en el recipe (sistema de Button: solid→solid-hover, soft→element). NO se toca — es el patrón de referencia (Radix/Material), no bespoke.
El shift de color de TEXTO (--{x}-color-hover) se conserva por componente — el state-layer solo reemplaza el idioma de fondo.

Mecanismo — overlay, no replace

Base transparente (la mayoría): background: var(--state-hover).
Base rellena (tiene background-color propio): overlay en capa → background-image: linear-gradient(var(--state-hover), var(--state-hover)) — pinta el tinte SOBRE el fondo base sin perderlo (filled-safe). Es la forma usada en el rollout.

Cobertura

Pilot: accordion-trigger (a13ca387).
Rollout: 19 componentes neutros (7de6c76b) — collapsible, breadcrumb, calendar, pagination, toolbar, file-upload, tag-group, editable, stepper, spin-field, select, radio-cards, … (cada --{x}-bg-hover neutro → --state-hover).
Fold transversal (e7e4870d) — las dos reglas neutras canónicas de archetypes.css pasan al state-layer:
- [data-archetype='trigger']:hover — el opacity-dim (0.85) → tinte --state-hover (el dim atenuaba también el texto; el tinte no).
- El highlight de item / option (hover/focus/highlighted/selected en dropdown · context · select · combobox · listbox · command) — surface-raised → --state-hover (conservando color: content-primary).

Pendiente

Poda de los --{x}-bg-hover huérfanos en lib/recipes/base.ts (sin uso tras el rollout) + guard test (ningún recipe neutro declara su propio --{x}-bg-hover). Diferido por un entanglement de base.css con trabajo concurrente.
tabs + color-picker (hover bespoke) — diferidos por el mismo motivo.

Doctrina: el feedback neutro es un concepto de tema, no de componente — paralelo exacto al focus ring (§32). Un state-layer definido una vez y parametrizado; los componentes no reinventan su hover.

Última revisión: 2026-06-29. Si algo en este doc no coincide con el código, el código gana — pero abre un issue para que actualicemos el doc.

75 KiB Raw Blame History Unescape Escape