kaizen-lib 0.2.13 → 0.2.14

package/README.md

@@ -1,337 +1,338 @@
-# kaizen-lib
-
-Tokens y componentes compartidos entre los fronts de Kaizen. Un solo paquete, con
-subpath exports: cada parte se importa por separado y el resto no entra al bundle.
-
-Se publica en **TypeScript crudo**, sin build. Los consumidores son Next + React 19 +
-styled-components con `moduleResolution: "bundler"`, así que lo transpilan ellos.
-
-## Estado
-
-| Subpath | Qué es | Estado |
-|---|---|---|
-| `kaizen-lib/tokens` | Referencias `var(--kz-*)` tipadas | listo |
-| `kaizen-lib/tokens.css` | Valores por defecto, tema oscuro y claro | listo |
-| `kaizen-lib/ui` | Componentes (`IconButton`, `ReactionButton`, `Medidor`, `Relieve`, `LangSelector`, `Modal`, `Badge`, `BottomNav`, `PanelExpandible`, `DiscoHaxball`) | en curso |
-
-## ¿Qué uso para qué?
-
-Antes de escribir un `styled.button` a mano o un ciclador de idioma propio, revisá esta
-tabla. Si tu caso está acá, es un defecto reconstruirlo local — usá esto, y si no
-alcanza, extendé el componente en vez de bypassearlo (ver `implement.md` del harness:
-"un duplicado local de algo que ya existe compartido se reemplaza por el compartido").
-
-| Necesito... | Uso | No es... |
-|---|---|---|
-| Un botón redondo de sólo ícono en una topbar (notificaciones, perfil, cerrar) | `IconButton` | — |
-| Que ese botón tenga fondo teñido cuando está seleccionado (la página actual, un filtro aplicado) | `IconButton` con `active` | `ReactionButton` (ver abajo, distinción a propósito) |
-| Un ícono que cambia de color al reaccionar (me gusta, guardar, favorito) — **sin** fondo teñido | `ReactionButton` | `IconButton` con `active` |
-| El relieve neumórfico (círculo con sombra, sin relleno) alrededor de un `IconButton` | `Relieve` envolviendo el `IconButton` | una prop de `IconButton` — ver por qué en su docblock |
-| Un ciclador de idioma con banderas en la topbar | `LangSelector` | reconstruir el ciclado a mano — ya lo resuelve, con `Relieve` incluido |
-| Un panel flotante que bloquea el resto de la página hasta que se resuelve (formulario, confirmación, contenido a pantalla completa) | `Modal` | un overlay propio — portal, foco atrapado, `Escape`, scroll bloqueado y anidamiento ya están resueltos ahí |
-| Un arco/medidor que muestra cuánto de un total está ocupado | `Medidor` | un `<progress>` o una barra propia |
-| Una píldora de estado (activo, vencido, un rol, una etiqueta) con fondo lavado y texto del mismo tono | `Badge` | un `styled.span` propio por producto — es exactamente lo que ya había triplicado |
-| La navegación principal fija abajo en el teléfono (ícono + rótulo por destino) | `BottomNav`, y `bottomNavOffset` de padding inferior en lo que no debe quedar tapado | una barra propia — ya estaba cuadruplicada |
-| Un panel de pantalla con título, un número que resume el contenido y un cuerpo que se pliega (sin desmontarse) | `PanelExpandible` | un `<details>` o un acordeón propio — el indicador queda a la vista con el panel cerrado, que es lo que justifica plegarlo |
-| Espaciado, radios, color, tipografía, sombra | `kaizen-lib/tokens` (`space`, `radius`, `fg`, `accent`, `font`, `shadow`, `relief`...) | un valor a mano — cada uno es una referencia `var(--kz-*)` |
-| Mostrar la ficha/disco de Haxball de un equipo (para elegir un equipo representativo, o para lucir el catálogo de camisetas) | `DiscoHaxball` + `CAMISETAS_HAXBALL`; el avatar (`texto`) se valida al guardarlo con `recortarAvatarHaxball` | una imagen propia — es una aproximación visual generada por SVG, no requiere ningún asset |
-
-Ningún componente trae íconos ni banderas: los recibe como `children`/`icono`, y el
-producto elige de dónde salen (`react-icons`, `react-country-flag`, SVG propio).
-
-## Instalación
-
-```bash
-npm install kaizen-lib
-```
-
-`react` y `styled-components` son **peerDependencies** y las pone el consumidor. Si
-alguna vez quedan como `dependencies`, el consumidor termina con dos instancias de
-styled-components y se rompen el theming y el SSR de un modo difícil de diagnosticar.
-
-En `next.config`:
-
-```ts
-const nextConfig = { transpilePackages: ['kaizen-lib'] };
-```
-
-## Tokens
-
-El contrato es uno solo: **los nombres**. Los valores los define cada producto.
-
-```ts
-import styled from 'styled-components';
-import { surface, fg, space, radius } from 'kaizen-lib/tokens';
-
-const Card = styled.div`
-  background: ${surface[2]};
-  color: ${fg.DEFAULT};
-  padding: ${space[4]};
-  border-radius: ${radius.md};
-`;
-```
-
-```css
-/* globals.css — opcional: valores por defecto, después los pisás con los tuyos */
-@import 'kaizen-lib/tokens.css';
-
-:root {
-  --kz-accent: #e8318f; /* la marca del producto */
-}
-```
-
-**Adopción parcial.** Si un producto redefine sólo algunos tokens, el resto cae al
-valor por defecto. Si no importa `tokens.css` y no define un token que un componente
-usa, el estilo simplemente no se aplica — no hay error. Por eso los tests exigen que
-todo token de la API esté definido en `defaults.css`.
-
-**Tema.** Oscuro en `:root`; claro cuando `<html>` lleva la clase `light`. Es el
-mecanismo de tutipoker-school-front, el único consumidor con toggle real.
-
-**Elevación.** Cuatro niveles de uso fijo: `0` página, `1` panel, `2` card, `3` overlay.
-`sunken` es el pozo (inputs, tracks) y va más oscuro que su contenedor.
-
-## Componentes
-
-```tsx
-import { IconButton } from 'kaizen-lib/ui';
-
-<IconButton label="Cambiar tema" size="lg" onClick={alternar}>
-  <IconoLuna />
-</IconButton>
-
-<IconButton as={Link} href="/notificaciones" label="Notificaciones, 3 sin leer" badge={3}>
-  <IconoCampana />
-</IconButton>
-```
-
-**`IconButton`** es el botón redondo de sólo ícono de una topbar. `label` es obligatorio
-(es el nombre accesible). Con `badge` dibuja un contador, y ese número es decorativo: la
-cuenta va dentro del `label`, porque el idioma no es asunto de la librería. Con `as` toma
-otro elemento —un `<Link>` de Next— sin que la librería dependa de Next. `size="lg"` es el
-área táctil de 44px. Con `motivo` queda bloqueado pero enfocable, para poder mostrar por
-qué.
-
-La librería no trae íconos: cada producto usa los suyos.
-
-```tsx
-import { ReactionButton } from 'kaizen-lib/ui';
-
-<ReactionButton tone="danger" active={likeado} glow count={likes} label={`Me gusta, ${likes}`}>
-  <IconoCorazon />
-</ReactionButton>
-```
-
-**`ReactionButton`** es un ícono que cambia de color al reaccionar (`tone`: `neutral` |
-`accent` | `success` | `danger` | `warning` | `info`), con resplandor opcional (`glow`,
-del mismo color vía `currentColor`) y una cuenta al lado (`count`; `0` se muestra, no es
-una ausencia). No es `IconButton` con más props: **nunca tiñe el fondo**. `IconButton` es
-"esto está seleccionado" (la página actual, un filtro aplicado) y por eso tiñe el círculo
-entero; `ReactionButton` es "reaccioné con esto" (un me gusta, un guardado), y ahí sólo el
-ícono cambia — un corazón marcado no necesita, además, un círculo rosa detrás.
-
-Un color que los seis tonos no cubren —la marca de un producto, no una categoría
-semántica— se pisa con `style`, porque el color activo sale de la variable CSS
-`--kz-icon-on` y un estilo en línea le gana a la regla de la librería:
-
-```tsx
-<ReactionButton
-  active={guardado}
-  style={{ '--kz-icon-on': 'var(--mi-color-de-marca)' } as React.CSSProperties}
-  label="Guardar"
->
-  <IconoMarcador />
-</ReactionButton>
-```
-
-```tsx
-import { Medidor } from 'kaizen-lib/ui';
-
-<Medidor valor={8} maximo={10} sentido="menos-es-mejor" label="Anotados: 8 de 10" />
-```
-
-**`Medidor`** es un arco que dice cuánto de un total está ocupado, pintado por escalón. No es
-un control: es un `role="img"`, así que si el dato tiene que llevar a algún lado lo envuelve
-un link o un botón del producto. `label` es obligatorio y va en palabras — el arco y el
-número del centro son decorativos, y el color nunca es el único portador del significado.
-
-Los cuatro escalones salen de la **proporción** `valor / maximo`, no del valor (8 no significa
-lo mismo sobre 10 que sobre 22). Sobre una escala de 0 a 10: `10` tope, `8` a `9,99` alto,
-`4` a `7,99` medio, menos de `4` bajo. Cada corte es inclusivo abajo.
-
-`sentido` es obligatorio y decide qué extremo es el bueno, porque eso lo define lo que el
-número *significa* en el producto y no el componente:
-
-| Escalón | `menos-es-mejor` | `mas-es-mejor` |
-|---|---|---|
-| bajo (< 40%) | verde | rojo |
-| medio (40–79%) | azul | naranja |
-| alto (80–99%) | naranja | azul |
-| tope (100%) | rojo | verde |
-
-`menos-es-mejor` es "cuánto lugar queda": vacío es una oportunidad, lleno una puerta
-cerrada. `mas-es-mejor` es un progreso o una meta. Usa los tonos `success`, `info`,
-`warning` y `danger`, así que un producto que ya los definió no declara nada nuevo. El
-centro muestra `valor/maximo` y se reemplaza con `children` cuando el formato es del producto.
-
-```tsx
-import { IconButton, Relieve } from 'kaizen-lib/ui';
-import Link from 'next/link';
-
-<Relieve>
-  <IconButton label="Notificaciones, 3 sin leer" badge={3}><IconoCampana /></IconButton>
-</Relieve>
-
-<Relieve $prendido={enPerfil}>
-  <IconButton as={Link} href="/perfil" active={enPerfil} label="Perfil"><IconoPerfil /></IconButton>
-</Relieve>
-```
-
-**`Relieve`** envuelve a `IconButton` con el relieve neumórfico: un círculo sin relleno ni
-borde, dibujado por un par de sombras opuestas (`--kz-relief-out`) que se invierten al
-presionar (`--kz-relief-in`) o con `$prendido` (el equivalente sostenido de "esto está
-activo" o "vos estás acá"). Es un `<span>` alrededor del control y no un
-`styled(IconButton)`: `IconButton` es polimórfico (`as`), y styled-components
-intercepta el `as` de cualquier componente que envuelve, así que envolverlo así lo haría
-saltear toda su lógica. El relieve es neutro por defecto (negro/blanco) — un producto con
-marca lo tiñe redefiniendo esos tres tokens, igual que con cualquier otro.
-
-```tsx
-import { LangSelector } from 'kaizen-lib/ui';
-
-<LangSelector
-  actual={i18n.language}
-  onChange={(codigo) => i18n.changeLanguage(codigo)}
-  etiqueta={(siguiente) => `Cambiar idioma a ${siguiente.nombre}`}
-  opciones={[
-    { codigo: 'es', nombre: 'Español', icono: <ReactCountryFlag countryCode="AR" /> },
-    { codigo: 'en', nombre: 'English', icono: <ReactCountryFlag countryCode="US" /> },
-  ]}
-/>
-```
-
-**`LangSelector`** es el botón de idioma de una topbar: cicla a la siguiente opción en
-cada tap y muestra el ícono del idioma actual, con el relieve de `Relieve` ya incluido
-(a diferencia de `IconButton`, acá no hace falta envolverlo aparte — todo consumidor lo
-quería). No trae banderas — mismo criterio que `IconButton` no trae íconos —, así que
-`icono` es cosa del producto; `react-country-flag` (ya usado en tuxon-front) es una
-opción probada. `etiqueta` arma el nombre accesible a partir de la opción siguiente y la
-actual — es obligatoria y sin default: la frase y el idioma son del producto (dos ya
-difieren: uno anuncia el destino, "Cambiar idioma a English"; otro el estado, "Idioma:
-English. Cambiar idioma"). `onChange` recibe el código de la opción siguiente; qué hacer
-con eso (`i18n.changeLanguage`, `next-intl`, lo que sea) es del producto — la librería no
-sabe qué mecanismo de traducción hay atrás.
-
-```tsx
-import { Modal } from 'kaizen-lib/ui';
-
-<Modal
-  open={abierto}
-  onClose={cerrar}
-  title="Eliminar cepa"
-  description="Esta acción no se puede deshacer."
-  footer={<Acciones><Boton onClick={cerrar}>Cancelar</Boton><Boton onClick={eliminar}>Eliminar</Boton></Acciones>}
->
-  <p>Se van a borrar también sus lotes asociados.</p>
-</Modal>
-```
-
-**`Modal`** es el shell único de un panel flotante: portalea a `document.body`, atrapa el
-foco y lo devuelve a quien lo abrió al cerrar, cierra con `Escape`/click afuera/la X, y
-bloquea el scroll del fondo. Lleva una pila interna para el anidamiento real (un modal de
-confirmación abierto encima de un formulario): sólo el de más arriba atiende `Escape`, y el
-scroll se libera recién cuando se cierra el último.
-
-Sin `title` no hay nombre accesible propio — pasá `ariaLabel`. `size` (`sm`|`md`|`lg`|`xl`)
-fija el ancho máximo del panel; `maxWidth` lo pisa con un valor explícito. `disableClose`
-bloquea la X, el overlay y `Escape` a la vez — para una operación en curso, no para "no
-quiero que cierre nunca". `dismissOnOverlay={false}` sólo desactiva el click afuera, para
-un formulario a medio llenar que sigue queriendo cerrar con la X o `Escape`. `closeLabel`
-(default `'Cerrar'`) es el nombre accesible de la X — mismo criterio que `etiqueta` de
-`LangSelector`: un consumidor con más de un idioma lo pisa, el resto no lo toca.
-
-Lo que **no** trae: un `placement` lateral (drawer) y un padding compacto de cuerpo son
-casos de un solo consumidor cada uno (`components/ui/Dialog` de valle-verde) — se resuelven
-ahí con un wrapper local hasta que un segundo consumidor los pida acá.
-
-```tsx
-import { Badge } from 'kaizen-lib/ui';
-
-<Badge tone="success">Activo</Badge>
-<Badge tone="danger" bordered>Vencido</Badge>
-```
-
-**`Badge`** es una píldora de estado: fondo lavado + texto del mismo tono (`neutral` |
-`accent` | `success` | `danger` | `warning` | `info`, default `neutral`), mayúsculas
-apretadas. Elicitado de tres implementaciones ya duplicadas (taboo-next, valle-verde,
-kaizen-next) — el look es el de valle-verde. `bordered` agrega un borde de 1px del color
-pleno del tono, para cuando el fondo lavado solo no alcanza de contraste contra la
-superficie de atrás; no es una segunda estética, es el mismo tono con más peso.
-
-```tsx
-import Link from 'next/link';
-import { BottomNav, bottomNavOffset } from 'kaizen-lib/ui';
-
-<BottomNav
-  items={[{ id: 'inicio', label: 'Inicio', icon: <IoHomeOutline />, href: '/' }, ...]}
-  activeId={activo}
-  maxWidth={640}
-  ariaLabel="Secciones"
-  linkAs={Link}
-/>
-
-const Contenido = styled.main`padding-bottom: ${bottomNavOffset};`;
-```
-
-**`BottomNav`** es la barra de navegación fija abajo del teléfono: ícono + rótulo por
-destino, el activo con color de acento y una franja arriba (no sólo color). Elicitada de
-cuatro barras ya duplicadas (mixbol, valle-verde, tuxon, platenzen). Existe hasta
-`maxWidth` px y arriba se apaga por CSS, sin desmontarse, para no parpadear al hidratar.
-
-Qué decide el producto: `activeId` (si un destino matchea exacto o por prefijo es regla de
-sus rutas), `linkAs` (su router; sin él, `<a>`), y `ariaLabel` (su idioma, sin default).
-`onSelect(item, event)` se llama antes de navegar; con `event.preventDefault()` el
-destino hace otra cosa sin dejar de ser un link.
-
-Mientras se ve, publica `--kz-bottom-nav-offset` (su alto más el inset inferior del
-dispositivo). La barra es fija, así que el contenido lleva `bottomNavOffset` de padding
-inferior y lo que flota (FAB, avisos) lo suma a su `bottom`; donde la barra no está, vale
-`0px`.
-
-```tsx
-import { PanelExpandible } from 'kaizen-lib/ui';
-
-<PanelExpandible titulo="Comprometido" indicador="30 g" leyenda="faltan entregar">
-  <Tabla />
-</PanelExpandible>
-```
-
-**`PanelExpandible`** es un panel de pantalla: cabecera con el título y un indicador
-(`indicador` + `leyenda`, o varios con `indicadores`), y un cuerpo que se pliega. Plegado
-**no desmonta**: el contenido conserva filtros y selección. El control accesible es el
-chevron (`aria-expanded`); toda la cabecera responde al click. Controlado (`abierto` +
-`onCambiar`) o no (`abiertoInicial`). Con `plegable={false}` conserva el formato sin
-chevron, para una pantalla de un solo panel. `duracionMs` (default 300) fija la animación
-y el momento en que el cuerpo se oculta. `etiquetaPlegar`/`etiquetaDesplegar` traducen el
-nombre del chevron. La columna del plegable es `minmax(0, 1fr)`: una tabla ancha adentro
-se compacta o scrollea, no empuja el panel fuera de la pantalla.
-
-## Desarrollo
-
-```bash
-npm run check   # typecheck + tests
-```
-
-Los tests verifican dos cosas:
-
-- **Paridad** (`tokens.test.ts`): todo token de la API está definido en el CSS y todo
-  token del CSS está en la API. El tema claro no inventa tokens ni deja colores sin
-  redefinir.
-- **Contraste** (`defaults.test.ts`): los pares texto/fondo de la paleta por defecto
-  cumplen WCAG 2.1 (4.5:1 texto, 3:1 no textual), en los dos temas.
-
-Si cambiás un color, el número lo da la suite, no el ojo.
-
-## Licencia
-
-MIT
+# kaizen-lib
+
+Tokens y componentes compartidos entre los fronts de Kaizen. Un solo paquete, con
+subpath exports: cada parte se importa por separado y el resto no entra al bundle.
+
+Se publica en **TypeScript crudo**, sin build. Los consumidores son Next + React 19 +
+styled-components con `moduleResolution: "bundler"`, así que lo transpilan ellos.
+
+## Estado
+
+| Subpath | Qué es | Estado |
+|---|---|---|
+| `kaizen-lib/tokens` | Referencias `var(--kz-*)` tipadas | listo |
+| `kaizen-lib/tokens.css` | Valores por defecto, tema oscuro y claro | listo |
+| `kaizen-lib/ui` | Componentes (`IconButton`, `ReactionButton`, `Medidor`, `Relieve`, `LangSelector`, `Modal`, `Badge`, `BottomNav`, `PanelExpandible`, `Stepper`, `DiscoHaxball`) | en curso |
+
+## ¿Qué uso para qué?
+
+Antes de escribir un `styled.button` a mano o un ciclador de idioma propio, revisá esta
+tabla. Si tu caso está acá, es un defecto reconstruirlo local — usá esto, y si no
+alcanza, extendé el componente en vez de bypassearlo (ver `implement.md` del harness:
+"un duplicado local de algo que ya existe compartido se reemplaza por el compartido").
+
+| Necesito... | Uso | No es... |
+|---|---|---|
+| Un botón redondo de sólo ícono en una topbar (notificaciones, perfil, cerrar) | `IconButton` | — |
+| Que ese botón tenga fondo teñido cuando está seleccionado (la página actual, un filtro aplicado) | `IconButton` con `active` | `ReactionButton` (ver abajo, distinción a propósito) |
+| Un ícono que cambia de color al reaccionar (me gusta, guardar, favorito) — **sin** fondo teñido | `ReactionButton` | `IconButton` con `active` |
+| El relieve neumórfico (círculo con sombra, sin relleno) alrededor de un `IconButton` | `Relieve` envolviendo el `IconButton` | una prop de `IconButton` — ver por qué en su docblock |
+| Un ciclador de idioma con banderas en la topbar | `LangSelector` | reconstruir el ciclado a mano — ya lo resuelve, con `Relieve` incluido |
+| Un panel flotante que bloquea el resto de la página hasta que se resuelve (formulario, confirmación, contenido a pantalla completa) | `Modal` | un overlay propio — portal, foco atrapado, `Escape`, scroll bloqueado y anidamiento ya están resueltos ahí |
+| Un arco/medidor que muestra cuánto de un total está ocupado | `Medidor` | un `<progress>` o una barra propia |
+| Una píldora de estado (activo, vencido, un rol, una etiqueta) con fondo lavado y texto del mismo tono | `Badge` | un `styled.span` propio por producto — es exactamente lo que ya había triplicado |
+| La navegación principal fija abajo en el teléfono (ícono + rótulo por destino) | `BottomNav`, y `bottomNavOffset` de padding inferior en lo que no debe quedar tapado | una barra propia — ya estaba cuadruplicada |
+| Un panel de pantalla con título, un número que resume el contenido y un cuerpo que se pliega (sin desmontarse) | `PanelExpandible` | un `<details>` o un acordeón propio — el indicador queda a la vista con el panel cerrado, que es lo que justifica plegarlo |
+| Los pasos de un recorrido (un formulario en etapas, un trámite), con el actual marcado | `Stepper`; la paleta se pisa con `--kz-stepper-*` (ver su docblock) | una barra de progreso propia — las líneas se llenan en orden y respeta `prefers-reduced-motion` |
+| Espaciado, radios, color, tipografía, sombra | `kaizen-lib/tokens` (`space`, `radius`, `fg`, `accent`, `font`, `shadow`, `relief`...) | un valor a mano — cada uno es una referencia `var(--kz-*)` |
+| Mostrar la ficha/disco de Haxball de un equipo (para elegir un equipo representativo, o para lucir el catálogo de camisetas) | `DiscoHaxball` + `CAMISETAS_HAXBALL`; el avatar (`texto`) se valida al guardarlo con `recortarAvatarHaxball` | una imagen propia — es una aproximación visual generada por SVG, no requiere ningún asset |
+
+Ningún componente trae íconos ni banderas: los recibe como `children`/`icono`, y el
+producto elige de dónde salen (`react-icons`, `react-country-flag`, SVG propio).
+
+## Instalación
+
+```bash
+npm install kaizen-lib
+```
+
+`react` y `styled-components` son **peerDependencies** y las pone el consumidor. Si
+alguna vez quedan como `dependencies`, el consumidor termina con dos instancias de
+styled-components y se rompen el theming y el SSR de un modo difícil de diagnosticar.
+
+En `next.config`:
+
+```ts
+const nextConfig = { transpilePackages: ['kaizen-lib'] };
+```
+
+## Tokens
+
+El contrato es uno solo: **los nombres**. Los valores los define cada producto.
+
+```ts
+import styled from 'styled-components';
+import { surface, fg, space, radius } from 'kaizen-lib/tokens';
+
+const Card = styled.div`
+  background: ${surface[2]};
+  color: ${fg.DEFAULT};
+  padding: ${space[4]};
+  border-radius: ${radius.md};
+`;
+```
+
+```css
+/* globals.css — opcional: valores por defecto, después los pisás con los tuyos */
+@import 'kaizen-lib/tokens.css';
+
+:root {
+  --kz-accent: #e8318f; /* la marca del producto */
+}
+```
+
+**Adopción parcial.** Si un producto redefine sólo algunos tokens, el resto cae al
+valor por defecto. Si no importa `tokens.css` y no define un token que un componente
+usa, el estilo simplemente no se aplica — no hay error. Por eso los tests exigen que
+todo token de la API esté definido en `defaults.css`.
+
+**Tema.** Oscuro en `:root`; claro cuando `<html>` lleva la clase `light`. Es el
+mecanismo de tutipoker-school-front, el único consumidor con toggle real.
+
+**Elevación.** Cuatro niveles de uso fijo: `0` página, `1` panel, `2` card, `3` overlay.
+`sunken` es el pozo (inputs, tracks) y va más oscuro que su contenedor.
+
+## Componentes
+
+```tsx
+import { IconButton } from 'kaizen-lib/ui';
+
+<IconButton label="Cambiar tema" size="lg" onClick={alternar}>
+  <IconoLuna />
+</IconButton>
+
+<IconButton as={Link} href="/notificaciones" label="Notificaciones, 3 sin leer" badge={3}>
+  <IconoCampana />
+</IconButton>
+```
+
+**`IconButton`** es el botón redondo de sólo ícono de una topbar. `label` es obligatorio
+(es el nombre accesible). Con `badge` dibuja un contador, y ese número es decorativo: la
+cuenta va dentro del `label`, porque el idioma no es asunto de la librería. Con `as` toma
+otro elemento —un `<Link>` de Next— sin que la librería dependa de Next. `size="lg"` es el
+área táctil de 44px. Con `motivo` queda bloqueado pero enfocable, para poder mostrar por
+qué.
+
+La librería no trae íconos: cada producto usa los suyos.
+
+```tsx
+import { ReactionButton } from 'kaizen-lib/ui';
+
+<ReactionButton tone="danger" active={likeado} glow count={likes} label={`Me gusta, ${likes}`}>
+  <IconoCorazon />
+</ReactionButton>
+```
+
+**`ReactionButton`** es un ícono que cambia de color al reaccionar (`tone`: `neutral` |
+`accent` | `success` | `danger` | `warning` | `info`), con resplandor opcional (`glow`,
+del mismo color vía `currentColor`) y una cuenta al lado (`count`; `0` se muestra, no es
+una ausencia). No es `IconButton` con más props: **nunca tiñe el fondo**. `IconButton` es
+"esto está seleccionado" (la página actual, un filtro aplicado) y por eso tiñe el círculo
+entero; `ReactionButton` es "reaccioné con esto" (un me gusta, un guardado), y ahí sólo el
+ícono cambia — un corazón marcado no necesita, además, un círculo rosa detrás.
+
+Un color que los seis tonos no cubren —la marca de un producto, no una categoría
+semántica— se pisa con `style`, porque el color activo sale de la variable CSS
+`--kz-icon-on` y un estilo en línea le gana a la regla de la librería:
+
+```tsx
+<ReactionButton
+  active={guardado}
+  style={{ '--kz-icon-on': 'var(--mi-color-de-marca)' } as React.CSSProperties}
+  label="Guardar"
+>
+  <IconoMarcador />
+</ReactionButton>
+```
+
+```tsx
+import { Medidor } from 'kaizen-lib/ui';
+
+<Medidor valor={8} maximo={10} sentido="menos-es-mejor" label="Anotados: 8 de 10" />
+```
+
+**`Medidor`** es un arco que dice cuánto de un total está ocupado, pintado por escalón. No es
+un control: es un `role="img"`, así que si el dato tiene que llevar a algún lado lo envuelve
+un link o un botón del producto. `label` es obligatorio y va en palabras — el arco y el
+número del centro son decorativos, y el color nunca es el único portador del significado.
+
+Los cuatro escalones salen de la **proporción** `valor / maximo`, no del valor (8 no significa
+lo mismo sobre 10 que sobre 22). Sobre una escala de 0 a 10: `10` tope, `8` a `9,99` alto,
+`4` a `7,99` medio, menos de `4` bajo. Cada corte es inclusivo abajo.
+
+`sentido` es obligatorio y decide qué extremo es el bueno, porque eso lo define lo que el
+número *significa* en el producto y no el componente:
+
+| Escalón | `menos-es-mejor` | `mas-es-mejor` |
+|---|---|---|
+| bajo (< 40%) | verde | rojo |
+| medio (40–79%) | azul | naranja |
+| alto (80–99%) | naranja | azul |
+| tope (100%) | rojo | verde |
+
+`menos-es-mejor` es "cuánto lugar queda": vacío es una oportunidad, lleno una puerta
+cerrada. `mas-es-mejor` es un progreso o una meta. Usa los tonos `success`, `info`,
+`warning` y `danger`, así que un producto que ya los definió no declara nada nuevo. El
+centro muestra `valor/maximo` y se reemplaza con `children` cuando el formato es del producto.
+
+```tsx
+import { IconButton, Relieve } from 'kaizen-lib/ui';
+import Link from 'next/link';
+
+<Relieve>
+  <IconButton label="Notificaciones, 3 sin leer" badge={3}><IconoCampana /></IconButton>
+</Relieve>
+
+<Relieve $prendido={enPerfil}>
+  <IconButton as={Link} href="/perfil" active={enPerfil} label="Perfil"><IconoPerfil /></IconButton>
+</Relieve>
+```
+
+**`Relieve`** envuelve a `IconButton` con el relieve neumórfico: un círculo sin relleno ni
+borde, dibujado por un par de sombras opuestas (`--kz-relief-out`) que se invierten al
+presionar (`--kz-relief-in`) o con `$prendido` (el equivalente sostenido de "esto está
+activo" o "vos estás acá"). Es un `<span>` alrededor del control y no un
+`styled(IconButton)`: `IconButton` es polimórfico (`as`), y styled-components
+intercepta el `as` de cualquier componente que envuelve, así que envolverlo así lo haría
+saltear toda su lógica. El relieve es neutro por defecto (negro/blanco) — un producto con
+marca lo tiñe redefiniendo esos tres tokens, igual que con cualquier otro.
+
+```tsx
+import { LangSelector } from 'kaizen-lib/ui';
+
+<LangSelector
+  actual={i18n.language}
+  onChange={(codigo) => i18n.changeLanguage(codigo)}
+  etiqueta={(siguiente) => `Cambiar idioma a ${siguiente.nombre}`}
+  opciones={[
+    { codigo: 'es', nombre: 'Español', icono: <ReactCountryFlag countryCode="AR" /> },
+    { codigo: 'en', nombre: 'English', icono: <ReactCountryFlag countryCode="US" /> },
+  ]}
+/>
+```
+
+**`LangSelector`** es el botón de idioma de una topbar: cicla a la siguiente opción en
+cada tap y muestra el ícono del idioma actual, con el relieve de `Relieve` ya incluido
+(a diferencia de `IconButton`, acá no hace falta envolverlo aparte — todo consumidor lo
+quería). No trae banderas — mismo criterio que `IconButton` no trae íconos —, así que
+`icono` es cosa del producto; `react-country-flag` (ya usado en tuxon-front) es una
+opción probada. `etiqueta` arma el nombre accesible a partir de la opción siguiente y la
+actual — es obligatoria y sin default: la frase y el idioma son del producto (dos ya
+difieren: uno anuncia el destino, "Cambiar idioma a English"; otro el estado, "Idioma:
+English. Cambiar idioma"). `onChange` recibe el código de la opción siguiente; qué hacer
+con eso (`i18n.changeLanguage`, `next-intl`, lo que sea) es del producto — la librería no
+sabe qué mecanismo de traducción hay atrás.
+
+```tsx
+import { Modal } from 'kaizen-lib/ui';
+
+<Modal
+  open={abierto}
+  onClose={cerrar}
+  title="Eliminar cepa"
+  description="Esta acción no se puede deshacer."
+  footer={<Acciones><Boton onClick={cerrar}>Cancelar</Boton><Boton onClick={eliminar}>Eliminar</Boton></Acciones>}
+>
+  <p>Se van a borrar también sus lotes asociados.</p>
+</Modal>
+```
+
+**`Modal`** es el shell único de un panel flotante: portalea a `document.body`, atrapa el
+foco y lo devuelve a quien lo abrió al cerrar, cierra con `Escape`/click afuera/la X, y
+bloquea el scroll del fondo. Lleva una pila interna para el anidamiento real (un modal de
+confirmación abierto encima de un formulario): sólo el de más arriba atiende `Escape`, y el
+scroll se libera recién cuando se cierra el último.
+
+Sin `title` no hay nombre accesible propio — pasá `ariaLabel`. `size` (`sm`|`md`|`lg`|`xl`)
+fija el ancho máximo del panel; `maxWidth` lo pisa con un valor explícito. `disableClose`
+bloquea la X, el overlay y `Escape` a la vez — para una operación en curso, no para "no
+quiero que cierre nunca". `dismissOnOverlay={false}` sólo desactiva el click afuera, para
+un formulario a medio llenar que sigue queriendo cerrar con la X o `Escape`. `closeLabel`
+(default `'Cerrar'`) es el nombre accesible de la X — mismo criterio que `etiqueta` de
+`LangSelector`: un consumidor con más de un idioma lo pisa, el resto no lo toca.
+
+Lo que **no** trae: un `placement` lateral (drawer) y un padding compacto de cuerpo son
+casos de un solo consumidor cada uno (`components/ui/Dialog` de valle-verde) — se resuelven
+ahí con un wrapper local hasta que un segundo consumidor los pida acá.
+
+```tsx
+import { Badge } from 'kaizen-lib/ui';
+
+<Badge tone="success">Activo</Badge>
+<Badge tone="danger" bordered>Vencido</Badge>
+```
+
+**`Badge`** es una píldora de estado: fondo lavado + texto del mismo tono (`neutral` |
+`accent` | `success` | `danger` | `warning` | `info`, default `neutral`), mayúsculas
+apretadas. Elicitado de tres implementaciones ya duplicadas (taboo-next, valle-verde,
+kaizen-next) — el look es el de valle-verde. `bordered` agrega un borde de 1px del color
+pleno del tono, para cuando el fondo lavado solo no alcanza de contraste contra la
+superficie de atrás; no es una segunda estética, es el mismo tono con más peso.
+
+```tsx
+import Link from 'next/link';
+import { BottomNav, bottomNavOffset } from 'kaizen-lib/ui';
+
+<BottomNav
+  items={[{ id: 'inicio', label: 'Inicio', icon: <IoHomeOutline />, href: '/' }, ...]}
+  activeId={activo}
+  maxWidth={640}
+  ariaLabel="Secciones"
+  linkAs={Link}
+/>
+
+const Contenido = styled.main`padding-bottom: ${bottomNavOffset};`;
+```
+
+**`BottomNav`** es la barra de navegación fija abajo del teléfono: ícono + rótulo por
+destino, el activo con color de acento y una franja arriba (no sólo color). Elicitada de
+cuatro barras ya duplicadas (mixbol, valle-verde, tuxon, platenzen). Existe hasta
+`maxWidth` px y arriba se apaga por CSS, sin desmontarse, para no parpadear al hidratar.
+
+Qué decide el producto: `activeId` (si un destino matchea exacto o por prefijo es regla de
+sus rutas), `linkAs` (su router; sin él, `<a>`), y `ariaLabel` (su idioma, sin default).
+`onSelect(item, event)` se llama antes de navegar; con `event.preventDefault()` el
+destino hace otra cosa sin dejar de ser un link.
+
+Mientras se ve, publica `--kz-bottom-nav-offset` (su alto más el inset inferior del
+dispositivo). La barra es fija, así que el contenido lleva `bottomNavOffset` de padding
+inferior y lo que flota (FAB, avisos) lo suma a su `bottom`; donde la barra no está, vale
+`0px`.
+
+```tsx
+import { PanelExpandible } from 'kaizen-lib/ui';
+
+<PanelExpandible titulo="Comprometido" indicador="30 g" leyenda="faltan entregar">
+  <Tabla />
+</PanelExpandible>
+```
+
+**`PanelExpandible`** es un panel de pantalla: cabecera con el título y un indicador
+(`indicador` + `leyenda`, o varios con `indicadores`), y un cuerpo que se pliega. Plegado
+**no desmonta**: el contenido conserva filtros y selección. El control accesible es el
+chevron (`aria-expanded`); toda la cabecera responde al click. Controlado (`abierto` +
+`onCambiar`) o no (`abiertoInicial`). Con `plegable={false}` conserva el formato sin
+chevron, para una pantalla de un solo panel. `duracionMs` (default 300) fija la animación
+y el momento en que el cuerpo se oculta. `etiquetaPlegar`/`etiquetaDesplegar` traducen el
+nombre del chevron. La columna del plegable es `minmax(0, 1fr)`: una tabla ancha adentro
+se compacta o scrollea, no empuja el panel fuera de la pantalla.
+
+## Desarrollo
+
+```bash
+npm run check   # typecheck + tests
+```
+
+Los tests verifican dos cosas:
+
+- **Paridad** (`tokens.test.ts`): todo token de la API está definido en el CSS y todo
+  token del CSS está en la API. El tema claro no inventa tokens ni deja colores sin
+  redefinir.
+- **Contraste** (`defaults.test.ts`): los pares texto/fondo de la paleta por defecto
+  cumplen WCAG 2.1 (4.5:1 texto, 3:1 no textual), en los dos temas.
+
+Si cambiás un color, el número lo da la suite, no el ojo.
+
+## Licencia
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-lib",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "description": "Tokens y componentes compartidos entre los fronts de Kaizen.",
   "license": "MIT",
   "author": "Nicolás Sandobal",

package/src/ui/Stepper.tsx

@@ -0,0 +1,265 @@
+'use client';
+
+import { useEffect, useRef, type ReactNode } from 'react';
+import styled, { css } from 'styled-components';
+import { accent, fg, font, hairline, motion, space, surface } from '../tokens';
+
+/**
+ * Pasos de un recorrido: círculos unidos por líneas. Elicitado del stepper del
+ * formulario de adhesión de valle-verde (`FormV2Stepper`).
+ *
+ * Cada paso es un estado de tres: **completo** (antes del actual), **actual** y
+ * **pendiente**. Completo y actual se pintan igual —el actual suma un halo y la
+ * etiqueta en negrita—; la línea que une dos pasos se llena cuando el de la
+ * derecha se alcanza.
+ *
+ * ## Decisiones
+ *
+ * - **Se anima por defecto.** Al avanzar, la línea se llena primero y el
+ *   círculo se pinta cuando ella llega; al retroceder, al revés. Un salto de
+ *   varios pasos llena las líneas en cadena, una tras otra. Con
+ *   `prefers-reduced-motion` (o `animado={false}`) cambia de una.
+ * - **Es un `<ol>`, no un control.** El paso actual lleva
+ *   `aria-current="step"`. Si los pasos tienen que ser clickeables, es otro
+ *   componente: un stepper que navega tiene que resolver qué pasos se pueden
+ *   visitar, y eso es del producto.
+ * - **La paleta sale de los tokens**, y cada producto la pisa con variables
+ *   propias del componente sobre la raíz (o un ancestro), sin forkearlo:
+ *
+ *   | Variable | Qué pinta | Default |
+ *   |---|---|---|
+ *   | `--kz-stepper-pleno` | La línea llena, el borde y el ícono de un paso alcanzado | `accent` |
+ *   | `--kz-stepper-lavado` | El fondo de un paso alcanzado | `accent.soft` |
+ *   | `--kz-stepper-pista` | La línea vacía | `hairline.strong` |
+ *   | `--kz-stepper-pendiente` | El fondo de un paso pendiente | `surface.sunken` |
+ *   | `--kz-stepper-tamano` | El diámetro del círculo | `40px` |
+ *   | `--kz-stepper-grosor` | El grosor de la línea | `4px` |
+ *
+ * - **Ocupa el ancho de su contenedor**, en columnas iguales: para un stepper
+ *   compacto, el contenedor le pone `max-width`.
+ *
+ * ```tsx
+ * <Stepper
+ *   label="Pasos de la adhesión"
+ *   actual={paso}
+ *   pasos={[
+ *     { etiqueta: 'Datos', icono: <FaUser /> },
+ *     { etiqueta: 'Necesidades', icono: <FaLeaf /> },
+ *     { etiqueta: 'Confirmación', icono: <FaCheck /> },
+ *   ]}
+ * />
+ * ```
+ */
+
+export type PasoStepper = {
+  /** El nombre del paso. Se lee siempre, aunque `ocultarEtiquetasBajo` lo esconda a la vista. */
+  etiqueta: ReactNode;
+  /** Lo que va en el círculo. Sin ícono, el número del paso. */
+  icono?: ReactNode;
+};
+
+export type StepperProps = {
+  pasos: PasoStepper[];
+  /** Índice del paso actual, desde 0. Fuera de rango se recorta. */
+  actual: number;
+  /** Nombre accesible de la lista ("Pasos de la adhesión"). */
+  label: string;
+  /** Si los cambios de paso se animan (por defecto, sí). */
+  animado?: boolean;
+  /** Cuánto tarda en llenarse cada línea, en ms. Default 300. */
+  duracionMs?: number;
+  /**
+   * Debajo de este ancho de pantalla (px) las etiquetas no se dibujan; quedan
+   * para el lector de pantalla. Sin esto, se ven siempre.
+   */
+  ocultarEtiquetasBajo?: number;
+  className?: string;
+};
+
+type Estado = 'completo' | 'actual' | 'pendiente';
+
+const PLENO = `var(--kz-stepper-pleno, ${accent.DEFAULT})`;
+const LAVADO = `var(--kz-stepper-lavado, ${accent.soft})`;
+const PISTA = `var(--kz-stepper-pista, ${hairline.strong})`;
+const PENDIENTE = `var(--kz-stepper-pendiente, ${surface.sunken})`;
+const TAMANO = 'var(--kz-stepper-tamano, 40px)';
+const GROSOR = 'var(--kz-stepper-grosor, 4px)';
+
+/** Aire entre el círculo y la punta de la línea. */
+const SEPARACION = '6px';
+
+const Lista = styled.ol`
+  display: grid;
+  grid-auto-columns: minmax(0, 1fr);
+  grid-auto-flow: column;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+`;
+
+const Paso = styled.li`
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: ${space[2]};
+  min-width: 0;
+`;
+
+/**
+ * La línea va del borde derecho de este círculo al izquierdo del siguiente: la
+ * dibuja cada paso salvo el último. El relleno es un `scaleX` (no un `width`),
+ * que el navegador anima sin recalcular el layout.
+ */
+const Linea = styled.span<{ $llena: boolean; $duracion: number; $demora: number }>`
+  position: absolute;
+  top: calc(${TAMANO} / 2 - ${GROSOR} / 2);
+  left: calc(50% + ${TAMANO} / 2 + ${SEPARACION});
+  right: calc(-50% + ${TAMANO} / 2 + ${SEPARACION});
+  height: ${GROSOR};
+  border-radius: 999px;
+  background: ${PISTA};
+  overflow: hidden;
+
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    background: ${PLENO};
+    transform-origin: left center;
+    transform: scaleX(${({ $llena }) => ($llena ? 1 : 0)});
+    transition: transform ${({ $duracion }) => $duracion}ms ${motion.ease} ${({ $demora }) => $demora}ms;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    &::after { transition: none; }
+  }
+`;
+
+const Circulo = styled.span<{ $estado: Estado; $duracion: number; $demora: number }>`
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: ${TAMANO};
+  height: ${TAMANO};
+  flex-shrink: 0;
+  border-radius: 50%;
+  font-size: calc(${TAMANO} * 0.4);
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+  ${({ $estado }) => ($estado === 'pendiente'
+    ? css`
+      color: ${fg.subtle};
+      background: ${PENDIENTE};
+      border: 1px solid ${hairline.DEFAULT};
+      box-shadow: 0 0 0 0 transparent;
+    `
+    : css`
+      color: ${PLENO};
+      background: ${LAVADO};
+      border: 1px solid color-mix(in srgb, ${PLENO} 35%, transparent);
+      box-shadow: 0 0 0 ${$estado === 'actual' ? '4px' : '0'} color-mix(in srgb, ${PLENO} 16%, transparent);
+    `)}
+  transition-property: color, background-color, border-color, box-shadow;
+  transition-duration: ${({ $duracion }) => $duracion}ms;
+  transition-timing-function: ${motion.ease};
+  transition-delay: ${({ $demora }) => $demora}ms;
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+`;
+
+const Etiqueta = styled.span<{ $estado: Estado; $ocultarBajo?: number }>`
+  max-width: 100%;
+  font-family: ${font.family};
+  font-size: ${font.xs};
+  font-weight: ${({ $estado }) => ($estado === 'actual' ? 700 : 500)};
+  line-height: 1.3;
+  color: ${({ $estado }) => ($estado === 'actual' ? fg.DEFAULT : fg.muted)};
+  text-align: center;
+  overflow-wrap: anywhere;
+
+  ${({ $ocultarBajo }) => $ocultarBajo !== undefined && css`
+    @media (max-width: ${$ocultarBajo - 0.02}px) {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      overflow: hidden;
+      clip-path: inset(50%);
+      white-space: nowrap;
+    }
+  `}
+`;
+
+const estadoDe = (indice: number, actual: number): Estado => {
+  if (indice < actual) return 'completo';
+  if (indice === actual) return 'actual';
+  return 'pendiente';
+};
+
+/**
+ * Cuánto espera cada pieza para que el cambio se lea en orden. Avanzando de
+ * `desde` a `hasta`, la línea `i` (entre los pasos `i` e `i + 1`) se llena
+ * después de las anteriores, y el círculo `i + 1` se pinta cuando su línea
+ * termina. Retrocediendo, el espejo: el círculo se apaga a la vez que empieza a
+ * vaciarse su línea, y el anterior cuando ella termina.
+ */
+function demoras(desde: number, hasta: number, duracion: number) {
+  const linea = (i: number): number => {
+    if (hasta > desde && i >= desde && i < hasta) return (i - desde) * duracion;
+    if (hasta < desde && i >= hasta && i < desde) return (desde - 1 - i) * duracion;
+    return 0;
+  };
+  const circulo = (i: number): number => {
+    if (hasta > desde && i > desde && i <= hasta) return (i - desde) * duracion;
+    if (hasta < desde && i > hasta && i <= desde) return (desde - i) * duracion;
+    return 0;
+  };
+  return { linea, circulo };
+}
+
+export function Stepper({
+  pasos,
+  actual,
+  label,
+  animado = true,
+  duracionMs = 300,
+  ocultarEtiquetasBajo,
+  className,
+}: StepperProps) {
+  const ultimo = Math.max(0, pasos.length - 1);
+  const indice = Number.isFinite(actual) ? Math.min(ultimo, Math.max(0, Math.trunc(actual))) : 0;
+
+  // El paso que se mostraba antes de este render: de ahí sale el sentido del cambio.
+  const previo = useRef(indice);
+  const desde = previo.current;
+  useEffect(() => {
+    previo.current = indice;
+  }, [indice]);
+
+  const duracion = animado ? Math.max(0, duracionMs) : 0;
+  const { linea, circulo } = demoras(desde, indice, duracion);
+
+  return (
+    <Lista aria-label={label} className={className}>
+      {pasos.map((paso, i) => {
+        const estado = estadoDe(i, indice);
+        return (
+          <Paso key={i} aria-current={estado === 'actual' ? 'step' : undefined} data-estado={estado}>
+            {i < ultimo && (
+              <Linea aria-hidden="true" $llena={i < indice} $duracion={duracion} $demora={linea(i)} />
+            )}
+            <Circulo aria-hidden="true" $estado={estado} $duracion={duracion} $demora={circulo(i)}>
+              {paso.icono ?? i + 1}
+            </Circulo>
+            <Etiqueta $estado={estado} $ocultarBajo={ocultarEtiquetasBajo}>{paso.etiqueta}</Etiqueta>
+          </Paso>
+        );
+      })}
+    </Lista>
+  );
+}

package/src/ui/index.ts

@@ -17,3 +17,5 @@ export { DiscoHaxball, CAMISETAS_HAXBALL, recortarAvatarHaxball, LUGARES_AVATAR_
 export type { CamisetaHaxball, NombreCamiseta } from './DiscoHaxball';
 export { PanelExpandible } from './PanelExpandible';
 export type { PanelExpandibleProps } from './PanelExpandible';
+export { Stepper } from './Stepper';
+export type { PasoStepper, StepperProps } from './Stepper';