svelte-kit-vice/docs/process/PLAN-component-coherence.md

# PLAN — Coherencia del catálogo de componentes (fase 1: debilidades)

> **Kickoff para sesión nueva**: *"Lee docs/process/PLAN-component-coherence.md
> y continúa la tanda que toque."* Decisión de usuario (2026-07-02): primero
> resolver las debilidades medidas del sistema; la **web de información y de
> componentes** (ficha canónica + demos v3 + docs site) es la FASE SIGUIENTE —
> por eso las reglas D-* (demos) quedan explícitamente FUERA de esta fase.

## Diagnóstico (auditoría 2026-07-02)

`npm run component:audit`: **130 componentes → 75 PASS · 50 NEEDS-WORK · 5
BROKEN** (`cascade` · `gradient-builder` · `menu-dial` · `motion` · `qr-code`).
Por dimensión:

| Dimensión | Estado medido |
|---|---|
| Ejes transversales | Paleta-31 (`paletteScaleDecls`) en **7** recipes; size-bundle (`--size-*`) en **1** (pilot toggle); `data-variant` en 55 CSS |
| Estados (recipe) | `:focus-visible` falta en **11** (error) · `data-invalid` en 10 · `data-disabled` en 6 · `data-readonly` en 15 (warn) |
| Tokens | **17** recipes con tipografía literal (R-2.7) |
| Sema | 82 morfos con eventos → solo **41** declaran `expression:` (13 pack · 13 family-default · 1 delegated parseados); `persistence:` en 13; `a11ySemantic` en 9 |
| Motion | 15/15 recipes sin `@keyframes` locales ✓; firma de evento (CSS `data-event`) en **10** componentes; prop `motion` en 18 |
| A11y ancla | **33** interactivos sin URL APG (A-1.4, warn) |
| Docs por componente | **28** sin README (E-2.3); F-1.x (Baseline/Comparativa/Decisiones/Gaps) faltan en ~12–18 más |
| Demos (FUERA de fase) | 4 tab-union viejo · 7 sin snippet · 8 sin trace · 12 ▶ play sin wire · 7 chip-parity |

## Reglas de trabajo

- Sin agentes/workflows; responder en castellano, código/docs en inglés.
- NUNCA tocar `words/`, `palabras/`, `chronos/`, `media-player` (foráneo WIP).
- Una tanda = cambios + verificación (`component:audit --only` por componente
  tocado + `npm run check` scope) + commit. `git reset -q` antes de add.
- Sweeps: UN componente primero, verificar, luego el resto (no-cascade rule).
- Cada fix sistémico lleva su guard (regla nueva en audit o generador).

## Tandas

| Tanda | Contenido | Estado |
|---|---|---|
| **C0** | **Auditoría de conteos** (hallazgo usuario: "31 escalas" era 33 — UI+docs): guard I1 extendido a palette=33 · roles=9 · slots=12 (extracción sin comentarios); harness PALETTE_GROUPS +fuchsia+steel con assert de completitud; 14 menciones corregidas. **Pendiente**: misma medicina para steps=12 · planos depth=5 · sizes · weights · estilos tipográficos · packs | **HECHA (núcleo) 2026-07-02** |
| **C1** | **BROKEN mecánicos → 0 BROKEN**: válvula `R-x.y exception:` en audit (R-1.1/R-1.2/R-1.5/E-2.2 + filas checklist); cascade/motion/gradient-builder `texts.label`+langs; menu-dial default export; READMEs contrato (cascade·motion·menu-dial·qr-code: Baseline/Comparativa/Decisiones/Gaps/Passive+excepciones). cascade·motion·menu-dial → PASS; gradient-builder·qr-code → NEEDS-WORK (resto = D-* fase demos + C8) | **HECHA 2026-07-02** |
| **C2** | **Estados error-severity**. **(a) R-1.5 HECHA 2026-07-02**: el audit ahora reconoce las 4 evidencias sancionadas (`:focus-visible` · `:focus-within` · `:has(:focus)` · `[data-focused]` canónico) — añadir rings por recipe habría sido el anti-patrón "double border" (archetypes.css:164 ya da ring universal por arquetipo); 6 excepciones citadas (css-field/number-field → spin-field compartido; date-picker/dialog → foundation+content-exclusion; metrics/timeline → sin parte enfocable); clipboard+announce esperan su README (C8). **(b) R-1.2/1.3/1.4 HECHAS 2026-07-03**: válvula cableada también en R-1.3/R-1.4; fixes REALES verificados en navegador (switch/toggle/rating-group invalid=threat-element como checkbox·pin-input; toggle+pin-input readonly; spin-field readonly NUEVO en la capa compartida; ntp disabled); excepciones citadas (spin-field para css/number-field; dialog provider virtual; color-picker→color-field; date-range-field overlay de attrs; time-picker→time-field). ntp conserva R-1.3/R-1.4 warn para su pasada C8. media-player NO tocado (foráneo) | **HECHA** |
| **C3** | **R-2.7 tipografía literal** (17 recipes) — tokenizar o anotar `/* literal: */` justificado | pendiente |
| **C4** | **A-1.4 APG** (33 morfos) — URL del patrón W3C correspondiente; los sin patrón APG real → nota explícita | pendiente |
| **C5** | **Sema `expression:`** (~41 morfos con eventos sin declarar) — clasificar pack / family-default / delegated / none por componente (criterios D.4 de book-deviations); `persistence`/`a11ySemantic` donde el evento lo pida (tabla D.9 como referencia) | pendiente |
| **C6** | **Paleta universal** — `paletteScaleDecls` pasa de helper manual (7 usos) a paso del generador para toda recipe con tokens `palette-*` + regen + guard ("data-color sin cascade de paleta = error") | pendiente |
| **C7** | **Size-bundle sweep** (~90 recipes; patrón theming/reference §5, pilot toggle) + guard "recipe que re-declara size→font = warn" | pendiente |
| **C8** | **READMEs** — 28 nuevos + F-1.x incompletos (~18). Baseline/Comparativa (≥3 refs reales)/Decisiones/Gaps; passive → justificación. El más pesado: requiere investigación por componente | pendiente |
| **C9** | **Motion eventful gap** — decidir qué interactivos deben expresar firma de evento (hoy 10) y cablearla; criterio: alta frecuencia = sobrio (doctrina D.5) | pendiente |
| **C10** | **Tiers de madurez** — `stable · preview · experimental` en índice de componentes + criterio (PASS+README = stable) | pendiente |

FASE SIGUIENTE (no aquí): ficha canónica generada por componente, demos v3
(D-*), web de docs. Ver conversación 2026-07-02.

## Verificación de cierre de fase

`npm run component:audit` → 0 BROKEN, NEEDS-WORK solo por reglas D-* (demos,
fase siguiente); paleta y size-bundle universales con guard activo.