Cómo se usa el kit

SCOPE — @solu30/ui-kit

Package: @solu30/ui-kit Maintainer: Luna (design systems) / Forge (executor)

Ningún número de este doc se escribe a mano. Decía «4.13.0» y «80+ components» con el paquete en 5.14.0 y 334 componentes: dos versiones mayores de atraso, y nadie se enteró porque un doc no falla. El valor de hoy sale de node ~/GitHub/ui-kit/scripts/estado-kit.mjs (superficie) y node ~/GitHub/ui-kit/scripts/medir-uso.mjs (cuánto se importa cada pieza).

What this package IS

Cross-vertical UI component library: componentes, design tokens, utils de imagen de Cloudflare y el theming de Tailwind. La consumen los 13 verticales y 39 packages @solu30/*.

What this package is NOT

• Not a vertical-specific component. Nothing in here can import from a vertical.
• Not a data layer. No DB calls, no API routes, no Drizzle schemas.
• Not a layout framework. It provides primitives; the vertical composes them.

Design token contract

Los estilos DEBEN usar tokens definidos por el cmpPreset (src/tailwind-preset.ts), que es el source of truth. Tokens válidos:

• Fondos: bg-bkg, bg-container, bg-inner, bg-upper
• Texto: text-content (+ opacity, ej. text-content/70)
• Bordes: border-content, border (default --ui-border)
• Accent / status: text-primary, bg-primary, text-green/red/yellow/purple/orange
• Namespace interno ui-* (sólidos horneados, dirección 0.72) — VERIFICADOS en el preset: bg-ui-bg-secondary, text-ui-content-secondary, text-ui-content-muted, border-ui-border, text-ui-success/warning/error/info, text-ui-accent.
• NUNCA hex inline ni hsl(var(--*)).

Deuda conocida (token migration — tarea trackeada): clases no definidas por el preset (clases muertas que no renderizan): text-foreground-muted/-subtle/-secondary, bg-background-secondary/-raised, border-border-subtle/-strong (~124 componentes), y los sufijos de status bg-ui-success-bg/border-ui-success-border (el preset define ui.success como color sólido, no las variantes -bg/-border, usadas hoy en tv.ts STATUS_COLORS success/warning/error/info y en tokens/colors.ts). Migración full = esfuerzo separado, con decisión de vocabulario pendiente (text-content/70 opacity vs sólidos text-ui-content-muted) y posible necesidad de DEFINIR tokens faltantes en el preset. Ver tareas del plan.

See docs/INSTRUCTIONS.md for the full authoring rules.

Scope boundaries

@solu30/ui-kit/geo → movido a @solu30/ui-geo (ADR-219)

El subpath ./geo (GeoMap, Leaflet + react-leaflet) se extrajo del foundation al package 2-domain @solu30/ui-geo como parte del split del god-package (ADR-219). Migración de import: @solu30/ui-kit/geo → @solu30/ui-geo (nombres de símbolos idénticos). Guía completa: docs/migration/ui-kit-3.0.md.

Los peers se limpian con el código, en el mismo commit

El split de ADR-219 se llevó el código de geo y de los charts, y dejó los peers atrás: leaflet, react-leaflet, recharts y date-fns siguieron declarados durante dos versiones mayores con cero archivos que los importaran (recharts sobrevivía en un comentario). Se sacaron el 2026-08-26 a pedido de Martín — «elimina leaflet del kit, eso no va acá».

Un peer huérfano no rompe nada, y por eso nadie lo mira: son optional, así que ningún consumidor los resolvía. Lo que hace es mentir sobre lo que el paquete necesita, y en un kit que consumen 13 verticales y 39 packages esa mentira se lee como «el ui-kit quiere Leaflet». Un extract no termina hasta que el manifiesto dice la verdad.

La regla, entonces: peerDependencies es superficie, no plomería. Al mover o borrar un componente, se verifica en el mismo commit si su peer quedó sin dueño:

for dep in $(node -e "console.log(Object.keys(require('./package.json').peerDependencies).join(' '))"); do
  echo "$dep: $(grep -rl "$dep" src | grep -v '\.test\.' | wc -l) archivos"
done

Hoy quedan 8 peers y los únicos NO opcionales son react y react-dom, que es lo que un ui-kit debería pedir y nada más.

INSTRUCTIONS — @solu30/ui-kit

Authoring rules (MANDATORY)

1. Tokens del cmpPreset — DECISIÓN DE VOCABULARIO PENDIENTE

⚠️ Esta sección estaba ROTA y se neutralizó (task 3159). Mapeaba text-content/70 → text-foreground-secondary, bg-content/5 → bg-background-secondary, border-content/10 → border-border-subtle, etc. Esos tokens target NO están definidos en el cmpPreset (src/tailwind-preset.ts) — son clases muertas que no renderizan. La migración "solid colors" (dietaly/docs/plans/ui-kit-solid-colors-spec.md) se aplicó a ~124 componentes pero su vocabulario destino nunca se agregó al preset. NO sigas esta tabla.

Tokens VERIFICADOS (definidos en el preset, usar estos):

• Fondos: bg-bkg, bg-container, bg-inner, bg-upper
• Texto: text-content (+ opacity: text-content/70)
• Bordes: border-content, border (default)
• Accent/status: text-primary, text-green/red/yellow/purple/orange
• Namespace ui-* (definidos): bg-ui-bg-secondary, text-ui-content-secondary, text-ui-content-muted, border-ui-border, text-ui-success/warning/error/info, bg-ui-{success,warning,error,info}-bg, border-ui-{success,warning,error,info}-border, text-ui-accent
• NUNCA hex inline ni hsl(var(--*)).

No verificados / probablemente muertos (no usar hasta confirmar en el preset): text-foreground-*, bg-background-*, border-border-*.

Decisión pendiente (task trackeada): elegir el vocabulario canónico — opacity (text-content/70, permitido por CLAUDE.md global) vs sólidos horneados (text-ui-content-*, dirección 0.72 del kit) — definir en el preset los tokens que falten, y migrar los ~124 componentes. Hasta entonces, esta tab NO es contrato autoritativo.

2. No hex inline, no CSS vars con /N arbitrario

text-[var(--ui-content)]/60   ← PROHIBIDO
bg-[var(--ui-primary)]/10     ← PROHIBIDO (usar token semántico o clase utilitaria)

3. tsc limpio antes de cualquier PR

pnpm --filter @solu30/ui-kit tsc --noEmit debe pasar en cero errores.

4. Modificar un componente existente

• Leer el componente completo antes de editar.
• Usar SOLO tokens verificados del cmpPreset (sección 1). NO migrar a text-foreground-*/bg-background-* (muertos).
• Si encontrás clases con esos tokens muertos → es la deuda trackeada (task migración tokens), NO improvisar el reemplazo hasta que se decida el vocabulario.

5. Agregar un componente nuevo

• Sólo clases semánticas desde el inicio.
• Exportar desde el subpath-barrel que corresponda (src/subpath-barrels/display.ts, feedback.ts, …); el barrel raíz src/index.ts los re-exporta a todos (ADR-227), no se edita por componente.
• Test co-locado *.test.tsx con renderKit (ver README § Tests).
• Crear un changeset (.changeset/<slug>.md) en la misma unidad de trabajo. CHANGELOG.md se GENERA (pnpm changeset version) — nunca se edita a mano ni lleva sección [Unreleased].

6. Clases con gaps conocidos (pendientes de resolución por Natura)

Las siguientes clases con /N NO tienen mapeo determinístico en la tabla aún y requieren decisión de Natura antes de convertir:

• bg-ui-success/10, bg-ui-error/10 (trend badges en StatCard)
• bg-primary/20 (default prop iconBg en StatCard — es un prop caller-controlled)
• hover:bg-upper/50 — bg-upper no figura en la tabla semántica
• [var(--ui-*)]/N en SectionCard — patrón CSS-var-con-alpha, fuera del mapeo actual

7. RSC boundary — pasar iconos a componentes "use client" (ADR-192)

EmptyState es un Client Component. Pasar icon={LucideComponent} desde un Server Component causa crash ("Only plain objects can be passed…"). Usar iconName en su lugar:

// Server Component (RSC) — CORRECTO
import { EmptyState } from "@solu30/ui-kit";
<EmptyState iconName="package" title="Sin paquetes" />

// Client Component — sigue funcionando igual
import { PackageIcon } from "lucide-react";
<EmptyState icon={PackageIcon} title="Sin paquetes" />

iconName acepta cualquier LucideIconName (re-exportado desde @solu30/ui-kit). El icono se resuelve lazy con lucide-react/dynamic — no bundlea el set completo. EmptyStateAction.iconName funciona igual para botones de acción.

Otros componentes con icon?: ComponentType (StatCard, MetricCard, SectionHeader) son también "use client" pero sus callers típicos son client — no requieren migración aún. Evaluar caso por caso cuando aparezca necesidad concreta desde RSC.