kaizen-lib 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolás Sandobal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# 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 (por ahora `IconButton`) | en curso |
+
+## 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.
+
+## 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

@@ -0,0 +1,52 @@
+{
+  "name": "kaizen-lib",
+  "version": "0.2.0",
+  "description": "Tokens y componentes compartidos entre los fronts de Kaizen.",
+  "license": "MIT",
+  "author": "Nicolás Sandobal",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikosanarg/kaizen-lib.git"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/testing"
+  ],
+  "exports": {
+    "./tokens": "./src/tokens/index.ts",
+    "./tokens.css": "./src/tokens/defaults.css",
+    "./ui": "./src/ui/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run test"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "styled-components": ">=6"
+  },
+  "devDependencies": {
+    "@testing-library/react": "16.3.2",
+    "@testing-library/user-event": "14.6.1",
+    "@types/node": "24.10.1",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "jsdom": "29.1.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "styled-components": "6.4.2",
+    "typescript": "5.9.3",
+    "vitest": "5.0.1"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/tokens/defaults.css

@@ -0,0 +1,185 @@
+/*
+  Valores por defecto de los tokens de kaizen-lib.
+
+  Importar este archivo es OPCIONAL y sirve para dos cosas: arrancar un
+  proyecto sin definir nada, y tener un valor de respaldo para cada token
+  mientras la adopción es parcial. Un producto con identidad propia redefine
+  los que le importan en su propio `globals.css`, después de este import.
+
+  La paleta es deliberadamente neutra: gris azulado y un azul de acento. No es
+  la marca de ningún producto y no debería serlo — si se pareciera a alguno, el
+  resto heredaría esa identidad sin haberla elegido.
+
+  Tema: oscuro en `:root`, claro cuando `<html>` lleva la clase `light`. El
+  mecanismo sale de tutipoker-school-front, el único consumidor con un toggle
+  real (`context/useDarkMode.tsx`), para no inventar un tercero.
+
+  Los pares de contraste de estos valores los verifica `defaults.test.ts`
+  contra los mínimos de WCAG 2.1. Si cambiás un color, corré los tests: el
+  número lo da la suite, no el ojo.
+*/
+
+:root {
+  /* ---- Superficies -------------------------------------------------------
+     Cuatro niveles de elevación con uso fijo; no se mezclan libremente. El
+     modelo viene de kaizen-next, que es el que lo dejó explícito.
+       0  fondo de página
+       1  panel o sección
+       2  card dentro de un panel
+       3  overlay: modal, popover, dropdown
+     `sunken` es el pozo: va más oscuro que su contenedor (inputs, tracks,
+     wells), así que no es un quinto nivel de la escala sino su opuesto. */
+  --kz-surface-0: #0b0d10;
+  --kz-surface-1: #14171c;
+  --kz-surface-2: #1b1f26;
+  --kz-surface-3: #232830;
+  --kz-surface-sunken: #07080a;
+  --kz-surface-hover: #262c35;
+  --kz-surface-active: #2e3540;
+
+  /* ---- Texto -------------------------------------------------------------
+     Tres niveles. `subtle` es el piso: por debajo de eso no hay token porque
+     no habría contraste suficiente, y el que lo necesite está pidiendo texto
+     ilegible. El texto que va ENCIMA de un color de acento o semántico no es
+     un nivel de `fg`: cada tono trae el suyo (`--kz-accent-fg`, `--kz-danger-fg`). */
+  --kz-fg: #e8ecf1;
+  --kz-fg-muted: #a3adba;
+  --kz-fg-subtle: #8792a1;
+
+  /* ---- Bordes y foco ----------------------------------------------------- */
+  --kz-hairline: #262b33;
+  --kz-hairline-strong: #3a424e;
+  /* Anillo de foco. Es un elemento no textual: el mínimo que le aplica es
+     3:1, no 4.5:1. */
+  --kz-ring: #5b9dff;
+
+  /* ---- Acento ------------------------------------------------------------
+     `soft` es el fondo lavado para chips y estados seleccionados; el texto que
+     va encima de `soft` es el acento mismo, no `accent-fg`. */
+  --kz-accent: #5a9df8;
+  --kz-accent-hover: #78b0fa;
+  --kz-accent-active: #3b82f6;
+  --kz-accent-soft: rgba(90, 157, 248, 0.16);
+  --kz-accent-fg: #06111f;
+
+  /* ---- Tonos semánticos --------------------------------------------------
+     Cuatro tonos × tres ranuras. `danger` y `warning` ganan sobre `error` y
+     `warn` por ser los nombres que más consumidores ya usaban. */
+  --kz-success: #3ad07d;
+  --kz-success-soft: rgba(58, 208, 125, 0.16);
+  --kz-success-fg: #04180d;
+
+  --kz-danger: #f87171;
+  --kz-danger-soft: rgba(248, 113, 113, 0.16);
+  --kz-danger-fg: #1d0505;
+
+  --kz-warning: #f0ab3e;
+  --kz-warning-soft: rgba(240, 171, 62, 0.16);
+  --kz-warning-fg: #1c1002;
+
+  --kz-info: #56c4f5;
+  --kz-info-soft: rgba(86, 196, 245, 0.16);
+  --kz-info-fg: #04161f;
+
+  /* ---- Sombras ----------------------------------------------------------- */
+  --kz-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
+  --kz-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.45);
+  --kz-shadow-lg: 0 10px 30px rgba(0, 0, 0, 0.5);
+  --kz-shadow-xl: 0 24px 60px rgba(0, 0, 0, 0.6);
+
+  /* ---- Espaciado ---------------------------------------------------------
+     Escala en pasos de 4px. Los saltos (no hay 7, 9, 11) son a propósito: una
+     escala continua no es una escala, es un número libre con prefijo. */
+  --kz-space-1: 4px;
+  --kz-space-2: 8px;
+  --kz-space-3: 12px;
+  --kz-space-4: 16px;
+  --kz-space-5: 20px;
+  --kz-space-6: 24px;
+  --kz-space-8: 32px;
+  --kz-space-10: 40px;
+  --kz-space-12: 48px;
+  --kz-space-16: 64px;
+
+  /* ---- Radios ------------------------------------------------------------
+     No hay token para 0: eso es `0`, y darle nombre sólo agrega una
+     indirección que hay que resolver al leer. */
+  --kz-radius-sm: 4px;
+  --kz-radius-md: 8px;
+  --kz-radius-lg: 12px;
+  --kz-radius-xl: 20px;
+  --kz-radius-pill: 999px;
+  --kz-radius-circle: 50%;
+
+  /* ---- Tipografía -------------------------------------------------------- */
+  --kz-font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --kz-font-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+
+  --kz-font-xs: 12px;
+  --kz-font-sm: 14px;
+  --kz-font-md: 16px;
+  --kz-font-lg: 20px;
+  --kz-font-xl: 26px;
+  --kz-font-2xl: 34px;
+
+  /* ---- Movimiento --------------------------------------------------------
+     Una sola duración para los cambios de estado de un control (hover, foco,
+     encendido). Lo que necesite otra es una animación, no una transición. */
+  --kz-duration-fast: 120ms;
+  --kz-ease: cubic-bezier(0.2, 0, 0, 1);
+}
+
+/*
+  Tema claro. Sólo se redefine lo que cambia —color y sombra—: espaciado,
+  radios y tipografía valen igual en los dos temas y repetirlos acá sería una
+  segunda fuente que algún día diverge.
+
+  Las superficies no se "aclaran" una a una: se invierte la relación. En
+  oscuro la página es lo más negro y las cards suben; en claro la página es
+  gris y las cards son blancas. Por eso 1, 2 y 3 son todas blancas y lo que
+  las separa del fondo es el hairline.
+*/
+:root.light {
+  --kz-surface-0: #f4f6f9;
+  --kz-surface-1: #ffffff;
+  --kz-surface-2: #ffffff;
+  --kz-surface-3: #ffffff;
+  --kz-surface-sunken: #e8ecf1;
+  --kz-surface-hover: #eef1f5;
+  --kz-surface-active: #e2e7ee;
+
+  --kz-fg: #12161c;
+  --kz-fg-muted: #4d5762;
+  --kz-fg-subtle: #656f7c;
+
+  --kz-hairline: #e1e6ec;
+  --kz-hairline-strong: #c4ccd6;
+  --kz-ring: #1d4ed8;
+
+  --kz-accent: #1d62d8;
+  --kz-accent-hover: #1a56bf;
+  --kz-accent-active: #17499f;
+  --kz-accent-soft: rgba(29, 98, 216, 0.12);
+  --kz-accent-fg: #ffffff;
+
+  --kz-success: #11763d;
+  --kz-success-soft: rgba(17, 118, 61, 0.12);
+  --kz-success-fg: #ffffff;
+
+  --kz-danger: #c02626;
+  --kz-danger-soft: rgba(192, 38, 38, 0.12);
+  --kz-danger-fg: #ffffff;
+
+  --kz-warning: #96500a;
+  --kz-warning-soft: rgba(150, 80, 10, 0.12);
+  --kz-warning-fg: #ffffff;
+
+  --kz-info: #0b5f8a;
+  --kz-info-soft: rgba(11, 95, 138, 0.12);
+  --kz-info-fg: #ffffff;
+
+  --kz-shadow-sm: 0 1px 2px rgba(16, 24, 40, 0.08);
+  --kz-shadow-md: 0 4px 12px rgba(16, 24, 40, 0.1);
+  --kz-shadow-lg: 0 10px 30px rgba(16, 24, 40, 0.12);
+  --kz-shadow-xl: 0 24px 60px rgba(16, 24, 40, 0.16);
+}

package/src/tokens/index.ts

@@ -0,0 +1,157 @@
+/**
+ * Nombres de los tokens de diseño de kaizen-lib (`--kz-*`).
+ *
+ * Esto NO declara valores: son referencias `var(...)` para escribir estilos sin
+ * literales mágicos y con autocompletado. Los valores viven en CSS —
+ * `defaults.css` acá, o el `globals.css` de cada producto.
+ *
+ * La regla es de taboo-next, que la aprendió al revés: su `tokens.ts` original
+ * declaraba los valores en TypeScript en paralelo a los de `globals.css`, y no
+ * lo importaba ni un componente. Dos fuentes de verdad, las dos ignoradas. Por
+ * eso acá sólo hay referencias, y `tokens.test.ts` falla si alguna se escapa.
+ *
+ * El contrato en una línea: si un token está acá, tiene que estar definido en
+ * `defaults.css`, y al revés. Los tests lo verifican en las dos direcciones.
+ */
+
+/**
+ * Superficies por nivel de elevación. El uso de cada nivel es fijo — elegir
+ * por "cuánto quiero que resalte" es lo que termina en seis grises distintos
+ * que significan lo mismo.
+ *
+ * - `0` fondo de página
+ * - `1` panel o sección
+ * - `2` card dentro de un panel
+ * - `3` overlay: modal, popover, dropdown
+ *
+ * `sunken` no es un quinto nivel: va más oscuro que su contenedor (inputs,
+ * tracks, wells). `hover` y `active` son estados de una superficie
+ * clickeable, no elevaciones.
+ */
+export const surface = {
+  0: 'var(--kz-surface-0)',
+  1: 'var(--kz-surface-1)',
+  2: 'var(--kz-surface-2)',
+  3: 'var(--kz-surface-3)',
+  sunken: 'var(--kz-surface-sunken)',
+  hover: 'var(--kz-surface-hover)',
+  active: 'var(--kz-surface-active)',
+} as const;
+
+/**
+ * Color de texto sobre una superficie. El texto que va encima de un color de
+ * acento o semántico es la ranura `fg` de ese tono (`accent.fg`, `danger.fg`).
+ */
+export const fg = {
+  DEFAULT: 'var(--kz-fg)',
+  muted: 'var(--kz-fg-muted)',
+  subtle: 'var(--kz-fg-subtle)',
+} as const;
+
+/** Bordes de 1px. `strong` es para separar, no para decorar. */
+export const hairline = {
+  DEFAULT: 'var(--kz-hairline)',
+  strong: 'var(--kz-hairline-strong)',
+} as const;
+
+/** Anillo de foco. Elemento no textual: el mínimo de contraste es 3:1. */
+export const ring = 'var(--kz-ring)';
+
+/**
+ * Acento de marca. `soft` es el fondo lavado de chips y estados
+ * seleccionados; encima de `soft` va el acento mismo, no `fg`.
+ */
+export const accent = {
+  DEFAULT: 'var(--kz-accent)',
+  hover: 'var(--kz-accent-hover)',
+  active: 'var(--kz-accent-active)',
+  soft: 'var(--kz-accent-soft)',
+  fg: 'var(--kz-accent-fg)',
+} as const;
+
+/**
+ * Tonos semánticos. Tres ranuras cada uno: el color pleno, el fondo lavado y
+ * el texto que va encima del pleno.
+ */
+export const success = {
+  DEFAULT: 'var(--kz-success)',
+  soft: 'var(--kz-success-soft)',
+  fg: 'var(--kz-success-fg)',
+} as const;
+
+export const danger = {
+  DEFAULT: 'var(--kz-danger)',
+  soft: 'var(--kz-danger-soft)',
+  fg: 'var(--kz-danger-fg)',
+} as const;
+
+export const warning = {
+  DEFAULT: 'var(--kz-warning)',
+  soft: 'var(--kz-warning-soft)',
+  fg: 'var(--kz-warning-fg)',
+} as const;
+
+export const info = {
+  DEFAULT: 'var(--kz-info)',
+  soft: 'var(--kz-info-soft)',
+  fg: 'var(--kz-info-fg)',
+} as const;
+
+export const shadow = {
+  sm: 'var(--kz-shadow-sm)',
+  md: 'var(--kz-shadow-md)',
+  lg: 'var(--kz-shadow-lg)',
+  xl: 'var(--kz-shadow-xl)',
+} as const;
+
+/** Escala de espaciado, en pasos de 4px. Las claves salteadas son a propósito. */
+export const space = {
+  1: 'var(--kz-space-1)',
+  2: 'var(--kz-space-2)',
+  3: 'var(--kz-space-3)',
+  4: 'var(--kz-space-4)',
+  5: 'var(--kz-space-5)',
+  6: 'var(--kz-space-6)',
+  8: 'var(--kz-space-8)',
+  10: 'var(--kz-space-10)',
+  12: 'var(--kz-space-12)',
+  16: 'var(--kz-space-16)',
+} as const;
+
+/** Radios. Para 0 no hay token: se escribe `0`. */
+export const radius = {
+  sm: 'var(--kz-radius-sm)',
+  md: 'var(--kz-radius-md)',
+  lg: 'var(--kz-radius-lg)',
+  xl: 'var(--kz-radius-xl)',
+  pill: 'var(--kz-radius-pill)',
+  circle: 'var(--kz-radius-circle)',
+} as const;
+
+export const font = {
+  family: 'var(--kz-font-family)',
+  mono: 'var(--kz-font-mono)',
+  xs: 'var(--kz-font-xs)',
+  sm: 'var(--kz-font-sm)',
+  md: 'var(--kz-font-md)',
+  lg: 'var(--kz-font-lg)',
+  xl: 'var(--kz-font-xl)',
+  '2xl': 'var(--kz-font-2xl)',
+} as const;
+
+/** Transición de un cambio de estado de control: hover, foco, encendido. */
+export const motion = {
+  fast: 'var(--kz-duration-fast)',
+  ease: 'var(--kz-ease)',
+} as const;
+
+export type Surface = keyof typeof surface;
+export type Space = keyof typeof space;
+export type Radius = keyof typeof radius;
+export type Shadow = keyof typeof shadow;
+export type FontSize = Exclude<keyof typeof font, 'family' | 'mono'>;
+
+/** Los cuatro tonos semánticos, para tipar la prop `tone` de un componente. */
+export type Tone = 'success' | 'danger' | 'warning' | 'info';
+
+export const tone = { success, danger, warning, info } as const;

package/src/ui/IconButton.tsx

@@ -0,0 +1,173 @@
+'use client';
+
+import type { ComponentPropsWithoutRef, ElementType, MouseEvent } from 'react';
+import styled, { css } from 'styled-components';
+import { accent, danger, fg, font, motion, radius, ring, surface } from '../tokens';
+
+export type IconButtonSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Lado del círculo, en px. `lg` es el área táctil mínima de una topbar móvil
+ * (44px): si el control va en una barra que se toca con el pulgar, es el que
+ * corresponde. No son tokens porque son medidas de este componente, no una
+ * escala que otros usen.
+ */
+const LADO: Record<IconButtonSize, number> = { sm: 32, md: 40, lg: 44 };
+
+/** Tope del badge: "+9" ocupa lo mismo que un dígito y dice lo mismo. */
+const BADGE_MAXIMO = 9;
+
+type Propios = {
+  /**
+   * Nombre accesible. Obligatorio: un botón de sólo ícono sin rótulo no existe
+   * para un lector de pantalla. También es el tooltip nativo, salvo que haya
+   * `motivo`.
+   *
+   * Si hay `badge`, la cuenta va **dentro** del label ("Notificaciones, 3 sin
+   * leer"): el número visual es decorativo (`aria-hidden`) y el idioma del
+   * texto no es asunto de esta librería.
+   */
+  label: string;
+  /** El ícono. La librería no trae íconos: cada producto usa los suyos. */
+  children: React.ReactNode;
+  size?: IconButtonSize;
+  /** Encendido: filtro aplicado, panel abierto, sección actual. */
+  active?: boolean;
+  /**
+   * Contador. `0`, `undefined` y negativos no dibujan nada: "0 avisos" no es
+   * un aviso. Pasado el tope se muestra "+9".
+   */
+  badge?: number;
+  /**
+   * Motivo por el que está bloqueado. Marca `aria-disabled` en vez del
+   * `disabled` nativo: un botón realmente deshabilitado no recibe mouse ni
+   * foco, así que nunca podría mostrar el motivo — que es lo único que hay
+   * para comunicar.
+   */
+  motivo?: string;
+};
+
+type Props<T extends ElementType> = Propios & {
+  /** Renderiza otro elemento o componente (un `<Link>` de Next, un `<a>`). */
+  as?: T;
+} & Omit<ComponentPropsWithoutRef<T>, keyof Propios | 'as'>;
+
+const Raiz = styled.button<{ $size: IconButtonSize; $active: boolean }>`
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: ${({ $size }) => LADO[$size]}px;
+  height: ${({ $size }) => LADO[$size]}px;
+  padding: 0;
+  border: none;
+  border-radius: ${radius.circle};
+  background: ${({ $active }) => ($active ? accent.soft : 'transparent')};
+  color: ${({ $active }) => ($active ? accent.DEFAULT : fg.muted)};
+  font-family: inherit;
+  text-decoration: none;
+  cursor: pointer;
+  transition:
+    background ${motion.fast} ${motion.ease},
+    color ${motion.fast} ${motion.ease};
+
+  svg {
+    display: block;
+    width: 22px;
+    height: 22px;
+  }
+
+  &:focus-visible {
+    outline: 2px solid ${ring};
+    outline-offset: 2px;
+  }
+
+  ${({ $active }) =>
+    !$active &&
+    css`
+      &:hover:not([aria-disabled='true']) {
+        background: ${surface.hover};
+        color: ${fg.DEFAULT};
+      }
+
+      &:active:not([aria-disabled='true']) {
+        background: ${surface.active};
+      }
+    `}
+
+  &[aria-disabled='true'] {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+`;
+
+const Contador = styled.span`
+  position: absolute;
+  top: 2px;
+  right: 2px;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 4px;
+  border-radius: ${radius.pill};
+  background: ${danger.DEFAULT};
+  color: ${danger.fg};
+  font-size: ${font.xs};
+  font-weight: 700;
+  line-height: 18px;
+  text-align: center;
+  pointer-events: none;
+`;
+
+function textoDelBadge(badge: number | undefined): string | null {
+  if (badge === undefined || !Number.isFinite(badge) || badge < 1) return null;
+  return badge > BADGE_MAXIMO ? `+${BADGE_MAXIMO}` : String(Math.floor(badge));
+}
+
+/**
+ * Botón redondo de sólo ícono: el de la derecha de una topbar (notificaciones,
+ * usuario, idioma, tema).
+ *
+ * Sin `as` es un `<button type="button">`. Con `as` toma otro elemento y no le
+ * pone `type`, que en un `<a>` sería un atributo inválido.
+ */
+export function IconButton<T extends ElementType = 'button'>({
+  label,
+  children,
+  size = 'md',
+  active = false,
+  badge,
+  motivo,
+  as,
+  onClick,
+  ...rest
+}: Props<T>) {
+  const bloqueado = Boolean(motivo);
+  const textoBadge = textoDelBadge(badge);
+  const esBoton = as === undefined || as === 'button';
+
+  return (
+    <Raiz
+      {...rest}
+      as={as}
+      type={esBoton ? 'button' : undefined}
+      $size={size}
+      $active={active}
+      aria-label={label}
+      aria-pressed={esBoton && active ? true : undefined}
+      aria-current={!esBoton && active ? 'page' : undefined}
+      aria-disabled={bloqueado || undefined}
+      title={motivo ?? label}
+      onClick={(evento: MouseEvent<HTMLElement>) => {
+        if (bloqueado) {
+          evento.preventDefault();
+          return;
+        }
+        (onClick as ((e: MouseEvent<HTMLElement>) => void) | undefined)?.(evento);
+      }}
+    >
+      {children}
+      {textoBadge ? <Contador aria-hidden="true">{textoBadge}</Contador> : null}
+    </Raiz>
+  );
+}

package/src/ui/index.ts

@@ -0,0 +1,2 @@
+export { IconButton } from './IconButton';
+export type { IconButtonSize } from './IconButton';