@eduardoalvarez/arrecife 0.5.1 → 0.7.0

package/llms.txt

@@ -1,262 +1,566 @@
 # @eduardoalvarez/arrecife
 
-> GENERADO por `scripts/build-llms.mjs`. No lo edites a mano: la prosa está en
-> `docs/llms.plantilla.md` y el inventario sale de los tipos en cada build.
-> `pnpm check:llms` falla si este archivo y el código dejan de decir lo mismo.
+> GENERATED by `scripts/build-llms.mjs`. Do not edit by hand: the prose lives in
+> `docs/llms.template.md` and the inventory comes out of the types on every
+> build. `pnpm check:llms` fails if this file and the code stop saying the same
+> thing.
 
-Librería de componentes de la identidad visual de Eduardo Álvarez. React 19,
-TypeScript, Tailwind v4, shadcn/ui sobre Radix.
+The component library of Eduardo Álvarez's visual identity. React 19,
+TypeScript, Tailwind v4, shadcn/ui on top of Radix.
 
-Este documento es para un agente que escribe código en un proyecto que consume la
-librería. Si estás trabajando **dentro** del repo de Arrecife, el documento es
-`AGENTS.md`, no este.
+This document is for an agent writing code in a project that consumes the
+library. If you are working **inside** the Arrecife repo, the document is
+`AGENTS.md`, not this one.
 
-## Lo primero: no reimplementes lo que ya está aquí
+## First things first: do not reimplement what is already here
 
-Antes de escribir una tarjeta, un botón, una cabecera o un pie, busca en el
-inventario de más abajo. La librería existe porque cinco proyectos escribían las
-mismas piezas cada uno por su cuenta y se desincronizaban. Un componente nuevo
-escrito a mano en el proyecto consumidor reintroduce exactamente ese problema.
+Before writing a card, a button, a header or a footer, look through the inventory
+below. The library exists because five projects were each writing the same pieces
+on their own and drifting apart. A new component hand-written in the consuming
+project reintroduces exactly that problem.
 
-Tampoco escribas colores, tamaños ni espaciados a mano. Todo valor del sistema
-tiene un token y una utilidad de Tailwind; un `#hex` o un `p-[13px]` en el
-proyecto consumidor es la señal de que se eligió el camino equivocado.
+Do not hand-write colors, sizes or spacing either. Every value in the system has
+a token and a Tailwind utility; a `#hex` or a `p-[13px]` in the consuming project
+is the sign that the wrong path was taken.
 
-## Instalación
+## Installation
 
 ```bash
 pnpm add @eduardoalvarez/arrecife
 ```
 
-Requisitos, y no son opcionales:
+Requirements, and they are not optional:
 
 | | |
 | --- | --- |
-| React | `^19.0.0` y `react-dom` `^19.0.0`, como peer dependencies |
-| Tailwind | v4. **No hay preset de v3**: la salida es `@theme`, que v3 no entiende |
-| Node | `>=22.18.0` para las subrutas que corren en build (`./og`, `./tokens`) |
+| React | `^19.0.0` and `react-dom` `^19.0.0`, as peer dependencies |
+| Tailwind | v4. **There is no v3 preset**: the output is `@theme`, which v3 does not understand |
+| Node | `>=22.18.0` for the subpaths that run at build time (`./og`, `./tokens`) |
 
-Radix, `clsx`, `tailwind-merge`, `class-variance-authority`, `date-fns` y
-`react-day-picker` vienen como dependencias de la librería. No hace falta
-instalarlos ni declararlos.
+Radix, `clsx`, `tailwind-merge`, `class-variance-authority`, `date-fns` and
+`react-day-picker` come as dependencies of the library. You do not need to
+install or declare them.
 
-**No lleva `lucide-react` ni ninguna librería de iconos.** Los glifos que los
-componentes necesitan van inline, heredan `currentColor` y miden 1em.
+**It ships no icon set.** The glyphs the components
+need are inline, inherit `currentColor` and measure 1em.
 
-## Configuración de Tailwind
+## Tailwind configuration
 
-Dos líneas, en este orden, en la hoja de estilos de entrada del proyecto:
+Two lines, in this order, in the project's entry stylesheet:
 
 ```css
 @import "tailwindcss";
 @import "@eduardoalvarez/arrecife/tokens/theme.css";
 ```
 
-Sin la segunda, los componentes se montan sin ningún estilo del sistema: las
-clases que usan (`bg-surface-raised`, `text-h1`, `rounded-card`) no existen en un
-Tailwind pelado.
+Without the second one, the components mount with none of the system's styles:
+the classes they use (`bg-surface-raised`, `text-h1`, `rounded-card`) do not
+exist in a bare Tailwind.
 
-Tailwind tiene que escanear la librería para no purgar esas clases. Si el
-proyecto declara `@source`, incluye el paquete:
+Tailwind has to scan the library so it does not purge those classes. If the
+project declares `@source`, include the package:
 
 ```css
 @source "../node_modules/@eduardoalvarez/arrecife/dist";
 ```
 
-### Modo claro y modo oscuro
+### Light mode and dark mode
 
-**El modo oscuro es el primario y es el default.** Un proyecto oscuro no declara
-nada. Un proyecto en modo claro declara el atributo en `<html>`:
+**Dark mode is primary and it is the default.** A dark project declares nothing.
+A project in light mode declares the attribute on `<html>`:
 
 ```html
 <html data-theme="light">
 ```
 
-No hay clase `dark:`. La variante disponible es `light:`, para los casos del modo
-claro invertido, y casi nunca hace falta: los tokens ya cambian solos.
+There is no `dark:` class. The variant available is `light:`, for the cases of
+inverted light mode, and it is almost never needed: the tokens already switch on
+their own.
 
-### Fuentes
+### Fonts
 
-La librería declara las familias **por nombre** y no las carga. El proyecto carga
-Bricolage Grotesque (`font-display`), Geist (`font-sans`) y JetBrains Mono
-(`font-mono`) como prefiera —`next/font`, `@fontsource`, un `<link>`—. Si no las
-carga, el navegador cae al fallback y la tipografía se ve mal.
+The library declares the families **by name** and does not load them. The project
+loads Bricolage Grotesque (`font-display`), Geist (`font-sans`) and JetBrains
+Mono (`font-mono`) however it prefers — `next/font`, `@fontsource`, a `<link>`.
+If it does not load them, the browser falls back and the typography looks wrong.
 
-El nombre tiene que coincidir **exactamente** con el que declaran los tokens, y
-esto ya ha fallado en dos proyectos:
+The name has to match **exactly** the one the tokens declare, and this has
+already failed in two projects:
 
-| Utilidad | Nombre que pide el token |
+| Utility | Name the token asks for |
 | --- | --- |
 | `font-display` | `"Bricolage Grotesque"` |
 | `font-sans` | `"Geist"` |
 | `font-mono` | `"JetBrains Mono"` |
 
-Varios paquetes de fuentes las publican como `"Bricolage Grotesque Variable"` o
-`"Geist Variable"`. Registrar el `@font-face` con ese nombre NO carga lo que los
-tokens piden: la familia cae al sistema en silencio, sin error en consola. El
-`font-family` del `@font-face` es un alias que elige el proyecto, así que se
-escribe con el nombre de la tabla.
+Several font packages publish them as `"Bricolage Grotesque Variable"` or
+`"Geist Variable"`. Registering the `@font-face` under that name does NOT load
+what the tokens ask for: the family falls back to the system silently, with no
+console error. The `@font-face`'s `font-family` is an alias the project chooses,
+so write it with the name from the table.
 
-## Qué importar de dónde
+## What to import from where
 
-La elección importa, y por dos motivos distintos. Cuatro subrutas **no arrastran
-React**, así que pueden consumirse desde un worker, un `astro.config.mjs`, un
-script de build o un generador con Satori. Otras dos piden una **dependencia de
-pares opcional** que solo instala quien las use.
+The choice matters, for two different reasons. Four subpaths **do not drag React
+in**, so they can be consumed from a worker, an `astro.config.mjs`, a build
+script or a Satori generator. Another two ask for an **optional peer dependency**
+that only whoever uses them installs.
 
-| Subruta | Arrastra React | Pide además | Para qué |
+| Subpath | Drags React | Also requires | What for |
 | --- | --- | --- | --- |
-| `@eduardoalvarez/arrecife` | sí | — | Componentes, primitivos, marca, `cn`. Reexporta tokens y tema |
-| `@eduardoalvarez/arrecife/tokens` | **no** | — | El objeto `tokens` en JS. Satori, Astro, scripts |
-| `@eduardoalvarez/arrecife/tokens/theme.css` | — | — | El `@theme` de Tailwind v4 |
-| `@eduardoalvarez/arrecife/tema` | **no** | — | `scriptTema` para el `<head>`, y leer o cambiar el modo |
-| `@eduardoalvarez/arrecife/og` | **no** | — | Las plantillas de Open Graph para Satori |
-| `@eduardoalvarez/arrecife/shiki` | **no** | — | El tema de resaltado de sintaxis |
-| `@eduardoalvarez/arrecife/brand` | sí | — | Logo, isotipo y mascota como componentes |
-| `@eduardoalvarez/arrecife/form` | sí | `react-hook-form` | La capa de formulario: etiquetas, errores y `aria-*` |
-| `@eduardoalvarez/arrecife/chart` | sí | `recharts` | El chasis de las gráficas y la paleta de series |
-| `@eduardoalvarez/arrecife/assets/*` | — | — | Los PNG de la marca |
-
-Importar la raíz desde un script de build para sacar un token es el error que las
-subrutas existen para evitar: arrastra React entero a un worker que no lo monta.
-
-`./form` y `./chart` están fuera de la raíz por el motivo simétrico: si colgaran
-del índice principal, los proyectos que no dibujan gráficas ni usan React Hook
-Form tendrían que instalar esas dependencias igualmente para que su bundler
-resolviera un import que nunca ejecutan.
+| `@eduardoalvarez/arrecife` | yes | — | Components, primitives, brand, `cn`. Re-exports tokens and theme |
+| `@eduardoalvarez/arrecife/tokens` | **no** | — | The `tokens` object in JS. Satori, Astro, scripts |
+| `@eduardoalvarez/arrecife/tokens/theme.css` | — | — | Tailwind v4's `@theme` |
+| `@eduardoalvarez/arrecife/theme` | **no** | — | `themeScript` for the `<head>`, and reading or changing the mode |
+| `@eduardoalvarez/arrecife/variants` | **no** | — | The class vocabulary: `buttonVariants`, `badgeVariants`, `CARD_SURFACE` |
+| `@eduardoalvarez/arrecife/og` | **no** | — | The Open Graph templates for Satori |
+| `@eduardoalvarez/arrecife/shiki` | **no** | — | The syntax highlighting theme |
+| `@eduardoalvarez/arrecife/brand` | yes | — | Logo, isotype and mascot as components |
+| `@eduardoalvarez/arrecife/social` | yes, on the server only | — | The nine social icons, loose. No `"use client"` |
+| `@eduardoalvarez/arrecife/icons` | yes | `@phosphor-icons/react` | `Icon`, which draws a Phosphor icon at the system's size, and at the weight its role asks for |
+| `@eduardoalvarez/arrecife/form` | yes | `react-hook-form` | The form layer: labels, errors and `aria-*` |
+| `@eduardoalvarez/arrecife/chart` | yes | `recharts` | The chart chassis and the series palette |
+| `@eduardoalvarez/arrecife/assets/*` | — | — | The brand PNGs |
+
+Importing the root from a build script to get one token is the mistake the
+subpaths exist to prevent: it drags all of React into a worker that never mounts
+it.
+
+`./form`, `./chart` and `./icons` sit outside the root for the symmetric reason:
+if they hung off the main index, the projects that draw no charts, use no React
+Hook Form and need no icons would have to install those dependencies anyway so
+their bundler could resolve an import they never execute. Two of the five consume
+zero icons.
+
+### Next, Server Components and `"use client"`
+
+The root, `./brand`, `./form` and `./chart` ship `"use client"` in the published
+`dist/`, and they are the only four. They render React and their Radix primitives call `createContext` at
+module scope, so without the directive a Next project with the App Router cannot
+import them at all: it fails at build time with
+`TypeError: (0 , r.createContext) is not a function`.
+
+You do not add anything: importing `Button` from a Server Component works, and
+the boundary is already where it belongs. What you should NOT do is wrap the
+import in an adapter of your own marked `"use client"` — that was the workaround
+before 0.6.0 and it pulled 272 KB of client chunk in for components that never
+needed it.
+
+The five portable subpaths do NOT carry the directive, and that is the half that
+matters in a Server Component: `./tokens`, `./theme`, `./variants`, `./og` and
+`./shiki` stay on the server. Neither does `./social`, which is a third case: it
+renders React — it is nine `<svg>` — so it can never be portable, but it holds no
+state and nothing about it needs a client boundary. It is the only way to put a
+social icon in a Server Component, and § «The social icons come from `./social`»
+below says why the grouped form cannot do it. If all you need are classes — for a `<div>`, an
+`<a>` or an Astro island you do not want to hydrate — import them from
+`./variants` and nothing crosses to the client:
+
+```tsx
+// A Server Component, or an .astro frontmatter. No React reaches the browser.
+import { buttonVariants, CARD_SURFACE } from '@eduardoalvarez/arrecife/variants';
+
+<a className={buttonVariants({ variant: 'tertiary' })} href="/cursos">./ver_cursos →</a>
+<div className={CARD_SURFACE}>…</div>
+```
+
+In Astro and in plain Vite the directive is inert — a string literal at the top
+of a module. Rollup may warn `Module level directives cause errors when bundled`
+and nothing else happens: one `dist` serves the Next projects and the Astro ones.
 
 ```ts
-// Bien, en un generador de OG o en astro.config.mjs
+// Good, in an OG generator or in astro.config.mjs
 import { tokens } from '@eduardoalvarez/arrecife/tokens';
 import { arrecife } from '@eduardoalvarez/arrecife/shiki';
 
-// Bien, en el <head> de un Astro que no monta React
-import { scriptTema } from '@eduardoalvarez/arrecife/tema';
+// Good, in the <head> of an Astro that mounts no React
+import { themeScript } from '@eduardoalvarez/arrecife/theme';
 
-// Mal: monta React donde no hace falta
+// Bad: mounts React where it is not needed
 import { tokens } from '@eduardoalvarez/arrecife';
 ```
 
-### El tema, y el parpadeo de la primera pintura
+### The theme, and the first-paint flash
 
-`ThemeToggle` es el botón; lo difícil está en `./tema`. Sin `scriptTema` inline en
-el `<head>`, la primera pintura sale con el modo por defecto y el elegido entra
-un frame después: en un sitio oscuro que el usuario dejó en claro, eso es un
-fogonazo blanco en cada carga.
+`ThemeToggle` is the button; the hard part is in `./theme`. Without `themeScript`
+inline in the `<head>`, the first paint comes out in the default mode and the
+chosen one arrives a frame later: on a dark site the user left in light mode,
+that is a white flash on every load.
 
 ```astro
 ---
-import { scriptTema } from '@eduardoalvarez/arrecife/tema';
+import { themeScript } from '@eduardoalvarez/arrecife/theme';
 ---
 <head>
-  <script is:inline set:html={scriptTema} />
+  <!-- The site follows the reader's OS, falling back to dark. -->
+  <script is:inline set:html={themeScript()} />
+
+  <!-- Or: this site IS dark, and the OS is not consulted. -->
+  <script is:inline set:html={themeScript({ base: 'dark' })} />
 </head>
 ```
 
-Tiene que ir INLINE. Un `<script src>`, aunque sea síncrono, se descarga, y el
-parpadeo vuelve. El script reengancha en `astro:after-swap` porque las
-transiciones de vista reemplazan el `<html>` entero.
+`base` is not «the fallback», it is «this site IS this mode». A stored choice
+still wins over it, so the toggle keeps working — it sets what happens when
+nobody has chosen yet. Use it when the project has already decided its mode and
+does not want the OS overruling that.
+
+It has to go INLINE. A `<script src>`, even a synchronous one, gets downloaded,
+and the flash comes back. The script re-attaches on `astro:after-swap` because
+view transitions replace the whole `<html>`.
+
+### `npx arrecife` — run it once after installing
+
+Two things break with **no error at all**, and the command catches both.
+
+**Tailwind purges everything the components emit** unless the stylesheet has
+`@source "<path>/node_modules/@eduardoalvarez/arrecife/dist"`. It does not scan
+`node_modules`. There is no console error and no undefined class: the card mounts
+with no padding, no radius and no border. The path is relative to the SHEET, not
+to the project root, and the command computes it.
+
+**A `--color-*` of yours silently replaces ours.** A project coming from shadcn
+has `@theme inline { --color-accent: var(--accent); }` — shadcn's `--accent` is
+the hover surface, `#17303E`, and ours is the brand turquoise, `#35D6C0`. That
+one line repainted 88 classes inside the library's own components grey. Five
+names collide in total; four agree on the value and are harmless, and the command
+tells them apart.
+
+Do not silence it by removing the `@import`: the fix is the `@source` line, or
+renaming your own token.
+
+### `SidebarNav` groups, and the icon replaces the prompt
+
+```tsx
+<SidebarNav aria-label="Administración" brand={<>…</>} version="v0.6.0" branch="main">
+  <SidebarItem href="/admin" icon={<Icon as={SquaresFour} />} active>Resumen</SidebarItem>
+
+  <SidebarGroup label="Ventas">
+    <SidebarItem href="/admin/ventas" icon={<Icon as={CreditCard} />}>Ventas</SidebarItem>
+    <SidebarItem href="/admin/cupones" icon={<Icon as={Ticket} />}>Cupones</SidebarItem>
+  </SidebarGroup>
+</SidebarNav>
+```
+
+Past about eight items a flat sidebar stops being readable. Each `SidebarGroup`
+is a nested list named by its label, so a screen reader says «lista Ventas, 3
+elementos» instead of one list of eleven. The label is a paragraph and **not** a
+heading on purpose: a sidebar is navigation, and a heading here would land in the
+page's own outline.
+
+**`icon` replaces the `▸`, it does not join it.** Do not pass a glyph and expect
+the prompt as well. A sidebar with no icons keeps the prompt on every item, which
+is what a four-section blog admin wants.
+
+**`brand` does not replace `title`.** `title` is the eyebrow and also the `nav`'s
+accessible name when it is a string; a logo is not an accessible name, so pass
+`aria-label` when you use `brand`. See `docs/decisions.md` § 32.
+
+**It collapses to a rail, and the toggle is CONTROLLED:**
+
+```tsx
+const [collapsed, setCollapsed] = useState(false);
+
+<SidebarNav
+  collapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+  brand={<Wordmark />}
+  mark={<Isotype className="h-6" />}
+  user={<Avatar … />}
+>
+```
+
+There is no uncontrolled mode: this state is almost always persisted, and an
+internal one would fight the cookie you already keep. `onCollapsedChange` is also
+what makes the toggle appear — `collapsed` on its own is a rail with no way out,
+which is a layout and not an accident.
 
-### Los iconos de redes van agrupados
+Collapsed, the widths become `w-sidebar-rail` (56) and `w-sidebar` (256), and the
+component owns them only when it can collapse. It does **not** transition, on
+purpose. `brand` is hidden and `mark` takes its place, because a wordmark does
+not fit in a rail. Every label stays in the accessibility tree as `sr-only`, so
+do not «simplify» by dropping the children of a collapsed item. See
+`docs/decisions.md` § 34.
+
+### `Nav` is two slots and one height
+
+Almost everything an app shell wants from a site bar is already a slot:
 
 ```tsx
-// ❌ no existe
+<Nav
+  size="compact"                                  // 56px, for a shell with a sidebar
+  brand={<a href="/"><Logo /><span><span className="text-accent">~/</span>cursos</span></a>}
+  actions={session ? <UserMenu /> : <Button size="sm" asChild><Link href="/login">Entrar</Link></Button>}
+>
+  <NavItem href="/cursos" active>cursos</NavItem>
+</Nav>
+```
+
+`brand` and `actions` are `ReactNode`, so a wordmark, a user menu, a theme toggle
+or a search box go in without the library knowing anything about sessions.
+**Session state does not get a prop** — it is project infrastructure, and the
+library takes none.
+
+`size="compact"` is 56px instead of 64, for a bar that shares the screen with a
+sidebar. It is a prop and not a class because the height lives on `Nav`'s inner
+container: `className` reaches the `<header>` and stops there, so passing `h-14`
+does nothing.
+
+**One `Nav` per page.** It renders the site's `banner` landmark, and two banners
+on one page is an accessibility failure — which is also why `PageHeader` goes
+inside `<main>` and is not a landmark. See `docs/decisions.md` § 30.
+
+### Icons are yours, the way they are drawn is not
+
+The library ships no icon set and `lib/glyphs.tsx` is not exported: it is the
+minimum set the primitives need and it does not grow. What the library does ship
+is the drawing.
+
+```tsx
+import { GraduationCap, Trash } from '@phosphor-icons/react';
+import { Icon } from '@eduardoalvarez/arrecife/icons';
+
+// 1em, and `tone="action"` by default — `regular`, the stroke the document names
+<Icon as={GraduationCap} />
+
+// Inside a control with no text, the name goes on the CONTROL
+<Button size="icon-sm" variant="secondary" aria-label="Borrar la fila">
+  <Icon as={Trash} />
+</Button>
+
+// Alone and meaning something on its own, it gets a name
+<Icon as={Trophy} label="Curso completado" />
+```
+
+**Do not size them by hand.** `size-4`, `size-3.5`, `size-6` scattered through a
+codebase is what this replaces: at 1em the icon takes the size of the text it
+sits in — 13px beside `text-label`, 15px beside `text-ui` — and nobody picks a
+number.
+
+**The weight is not yours to pick either, but it is not one value.** `tone` names
+what the icon is doing and the weight follows from it. There are three and there
+is no fourth:
+
+| `tone` | Weight | What it is |
+| --- | --- | --- |
+| `action` · the default | `regular` | An icon that is a control or names one. It is the system's line: 16 on a 256 grid = 0.0625em, against the document's 1.6 on a 24 grid = 0.0667em. Six per cent apart, which is no pixel on any screen |
+| `current` | `fill` | The one of a set you are on — the sidebar item carrying `aria-current` |
+| `quiet` | `light` | Furniture: a marker in a metadata row, not a control and not a state |
+
+```tsx
+<SidebarItem href="/cursos" active icon={<Icon as={GraduationCap} tone="current" />}>
+  cursos
+</SidebarItem>
+```
+
+`current` is the one that earns the axis. An active item already paints itself
+biolume, and colour on its own is the channel WCAG 1.4.1 says may not carry
+meaning alone; the fill is the second channel, and it is the one that survives a
+forced-colours mode. `weight` is deliberately **not** a prop: Phosphor ships six
+and this system reads three, because `thin`, `bold` and `duotone` have no role
+behind them here.
+
+`@phosphor-icons/react` is an **optional** peer dependency. If your project uses
+no icons you install nothing; two of the five do exactly that.
+
+**An icon is not illustration, and the two never substitute for each other.**
+Tiburoncín — the faces, the poses, the fin — is the mascot; it comes from
+`./brand`, and the manual says where a face may appear: empty states,
+confirmations, errors, course progress, celebration, and nowhere else. An icon is
+functional vocabulary and goes wherever a control needs a label it cannot spell.
+Do not put an icon where the system asks for a face, and do not put a face where
+a control wants an icon.
+
+**In Next, import from `@phosphor-icons/react/ssr` inside a Server Component.**
+Phosphor's default build reads `IconContext` through `useContext`, and a hook in
+a Server Component throws. It ships no `"use client"` to stop you, so the failure
+arrives at render rather than at build. The `/ssr` entry is the same icons
+without the context read, and `Icon` works with either.
+
+See `docs/decisions.md` § 29 and § 35.
+
+### `Stat`'s delta says direction, not judgement
+
+```tsx
+<Stat
+  label="alumnos"
+  value="1.284"
+  delta={{ value: '+12 esta semana', direction: 'up' }}
+/>
+```
+
+`direction` picks the arrow and **never the colour**. «+12 alumnos» and «+12
+errores» point the same way and mean opposite things, so whether a number is good
+news is `tone`'s job and yours: `neutral` for a datum, `alert` when the number IS
+the problem, `achievement` when it is the reward. `alert` and `achievement` paint
+the same sand on purpose — the API is the meaning, the colour is the
+implementation. See `docs/decisions.md` § 28.
+
+`delta.value` arrives already formatted, like `value`: the library imposes no
+locale and computes no percentage. `spark` is a `ReactNode` and the library ships
+no sparkline — pass your own, exactly like `icon`.
+
+**Do not colour the number.** A neutral `Stat` renders its value in primary ink,
+and biolume goes on the icon badge and the sparkline instead: three accents in
+one card and the figure stops being the loudest thing in it. `alert` and
+`achievement` DO paint the number sand, which is how «this number is not just a
+number» is said. See `docs/decisions.md` § 31.
+
+**`icon` is a badge in the corner opposite the title**, in a circle tinted at
+10 % of the tone. You pass the glyph; the circle, the tint and the size are the
+component's.
+
+### The two shapes of `EmptyState`
+
+```tsx
+// The empty state IS the screen: a search with no results, a 404, a section
+// with nothing in it yet. It carries the face, and `expression` is mandatory.
+<EmptyState expression="waiting" title="Sin resultados" description="…" />
+
+// The hole INSIDE something else: a table page, a dashboard widget. No face, no
+// surface, no border — the table or the card already draws the region.
+<EmptyState variant="inline" title="No hay lecciones en esta página" />
+
+// ❌ does not compile: the props are a union, and `inline` has no face
+<EmptyState variant="inline" expression="waiting" title="…" />
+```
+
+`inline` takes an optional `icon` — a `ReactNode` the project passes and sizes,
+at 1em and in `currentColor`, like `Stat`'s. The library ships no icons.
+
+Do not reach for `page` inside a table because the face is «nicer»: an admin
+screen with a dozen empty regions gets a dozen mascots, which is what made every
+consuming project write its own empty state instead of using this one.
+
+### The social icons come from `./social`
+
+```tsx
+// ❌ does not exist: the root publishes them grouped, not loose
 import { GitHub } from '@eduardoalvarez/arrecife';
 
-// ✅
+// ✅ the normal form
+import { GitHub } from '@eduardoalvarez/arrecife/social';
+
+// ✅ for iterating the catalogue
 import { social } from '@eduardoalvarez/arrecife';
 <social.GitHub />
 ```
 
-Los ocho: `GitHub`, `LinkedIn`, `X`, `Instagram`, `Discord`, `YouTube`, `Rss`,
-`Correo`. Van bajo namespace porque uno se llama `X` y sueltos colisiona.
+All nine: `GitHub`, `LinkedIn`, `X`, `Instagram`, `Discord`, `YouTube`, `Rss`,
+`Email`, `Newsletter`. `Newsletter` is the bell: a way to follow, like `Rss`,
+named for what it means.
 
-Los glifos internos —`Close`, `ChevronDown`, `Sol`— **no se exportan** y no van a
-exportarse: son el juego mínimo de los primitivos. Un componente que necesita un
-icono lo recibe por prop (`Stat` tiene `icon`, cada `Red` de `Footer` tiene el
-suyo). No pidas que se publiquen: pasa el tuyo.
+**In a Server Component the subpath is mandatory, not preferred.** The root
+carries `"use client"`, and a client reference crosses the boundary per EXPORT —
+the properties of a plain object are not exports, so `social.LinkedIn` is
+`undefined` on the server and `undefined` as an element type kills the build at
+prerender. `./social` carries no directive: it renders on the server and ships no
+client JS. Use `social` only when mapping a list of names onto icons.
+
+The root keeps the group because one of them is called `X`, and loose at the root
+it collides. In the subpath, alias it: `import { X as XIcon }`.
+
+The internal glyphs — `Close`, `ChevronDown`, `Sun` — are **not exported** and
+are not going to be: they are the primitives' minimum set. A component that needs
+an icon receives it as a prop (`Stat` has `icon`, each `SocialLink` in `Footer`
+has its own). Do not ask for them to be published: pass your own.
 
 ## Tokens
 
-La fuente es un objeto de TypeScript y la salida CSS se genera de él, así que el
-mismo valor está disponible en los dos sitios y no pueden discrepar.
+The source is a TypeScript object and the CSS output is generated from it, so the
+same value is available in both places and they cannot disagree.
 
-| Token | Custom property | Utilidad de Tailwind |
+| Token | Custom property | Tailwind utility |
 | --- | --- | --- |
-| `colors[modo].surfaceRaised` | `--color-surface-raised` | `bg-surface-raised` |
+| `colors[mode].surfaceRaised` | `--color-surface-raised` | `bg-surface-raised` |
 | `brand.hull` | `--color-brand-hull` | `bg-brand-hull` |
-| `typeScale.h1` | `--text-h1` | `text-h1` (arrastra line-height, weight y tracking) |
+| `typeScale.h1` | `--text-h1` | `text-h1` (brings line-height, weight and tracking) |
 | `fonts.display` | `--font-display` | `font-display` |
 | `radius.card` | `--radius-card` | `rounded-card` |
 | `spacing.stepLg` | `--spacing-step-lg` | `p-step-lg`, `gap-step-lg`, `mb-step-lg` |
 | `spacing.section` | `--spacing-section` | `py-section`, `mb-section` |
 | `control.md` | `--spacing-control-md` | `px-control-md` |
 | `control.icon` | `--spacing-control-icon` | `size-control-icon` (42×42) |
-| `gradient[modo].hero` | `--gradient-hero` | `degradado-hero` |
-| `size.nav` | `--spacing-nav` | `h-nav` |
+| `gradient[mode].hero` | `--gradient-hero` | `gradient-hero` |
+| `size.nav` / `size.navCompact` | `--spacing-nav` / `--spacing-nav-compact` | `h-nav` / `h-nav-compact` |
 | `size.content` / `size.wide` | `--container-content` / `--container-wide` | `max-w-content` / `max-w-wide` |
 | `limits.measure` | `--container-measure` | `max-w-measure` |
 | `shadow.standard` | `--shadow-standard` | `shadow-standard` |
 | `motion` | `--duration-standard`, `--ease-standard` | `duration-standard`, `ease-standard` |
 
-`transition-standard` es la única transición del sistema y solo puede animar
-color y borde: así está escrita la utilidad.
-
-**Los escalones de espaciado llevan `step` en el nombre y no es opcional.**
-`p-md` no es una clase de Arrecife: en un proyecto con Tailwind v4 cae en la
-escala numérica y no hace nada visible. El ritmo de página es `p-step-md`,
-`gap-step-sm`, `py-step-xl`. Llevan prefijo porque `xs, sm, md, lg, xl` son los
-nombres de la escala `--container-*` de Tailwind, y un `--spacing-md` propio se
-comía `max-w-md` en todo el proyecto sin avisar de nada. `max-w-*`, `w-*` y `h-*`
-son de Tailwind y se usan tal cual. Guía de migración desde la 0.2.0:
-<https://github.com/Proskynete/arrecife/blob/main/docs/migracion-0.3.md>.
-
-## Reglas del sistema que el código consumidor no debe romper
-
-Son decisiones de identidad, ya medidas. Romperlas produce código que compila y
-se ve mal, o que falla la auditoría de accesibilidad del proyecto.
-
-1. **Cero hex literales.** Todo color sale de un token o de su custom property.
-2. **`Button variant="conversion"` va una sola vez por pantalla.** No se fuerza en
-   runtime; dos en la misma página son un error de diseño.
-3. **No hay variante de peligro en `Button`.** El error del sistema vive en los
-   avisos y en la validación de campo, no en un botón rojo.
-4. **`secondary` nunca se rellena el fondo.** Es borde y texto.
-5. **Sin animaciones de entrada.** Modales, menús, tooltips y toasts aparecen
-   donde van a quedarse. La única excepción es el spinner de `Button loading`.
-6. **La semántica y la escala son independientes.** Un `h2` que debe verse
-   pequeño es `<Text as="h2" variant="h3">`, nunca un `h3` que miente sobre la
-   jerarquía.
-7. **`textMuted` no va nunca sobre `surfaceRaised`**: da 4.07 en oscuro. Sobre
-   superficie elevada —menús, tabs activos— el token es `textSecondary`.
-8. **Un fondo teñido con un color semántico lleva texto de token de texto**, no
-   del color semántico. El color se queda en el borde y en el glifo. Poner
-   `accent` sobre su propio tinte al 8 % da 4.12 y no llega a AA.
-9. **`Progress` exige `label`.** Una barra sin nombre accesible no dice de qué es.
-10. **`Button size="icon"` exige `aria-label`.** No lleva texto.
-11. **Las caras de la mascota solo aparecen** en estados vacíos, confirmaciones,
-    errores, progreso de curso y celebración. Nunca en hero, precios, servicios,
-    contacto ni CV.
-12. **La aleta no es un parámetro libre**: `espuma` sobre fondo oscuro, `color`
-    sobre fondo claro. Los componentes ya la eligen por el fondo.
-
-## Lo que la librería NO hace, a propósito
-
-Estas son las confusiones que más veces se cometen al consumirla.
-
-- **No trae Shiki.** Publica el *tema*, no el resaltador. `CodeBlock` recibe el
-  código **ya resaltado** por la herramienta del proyecto.
-- **No formatea fechas.** `ArticleCard`, `TalkCard` y compañía reciben la fecha ya
-  formateada por el proyecto: la librería no impone locale. `dateTime` es aparte,
-  en ISO, para el atributo del `<time>`.
-- **`NewsletterForm` no hace el POST.** Es presentacional: recibe `state` y emite
-  `onSubmitEmail`. La llamada la hace el proyecto con su proveedor.
-- **No trae enrutador.** Los componentes con enlaces aceptan `asChild` para
-  envolver el `Link` del framework.
-- **No carga fuentes.** Las declara por nombre.
-- **No hay preset de Tailwind v3.**
-
-## Patrones de uso
+`transition-standard` is the system's only transition and it can only animate
+color and border: that is how the utility is written.
+
+**The spacing steps carry `step` in the name and it is not optional.** `p-md` is
+not an Arrecife class: in a Tailwind v4 project it lands on the numeric scale and
+does nothing visible. Page rhythm is `p-step-md`, `gap-step-sm`, `py-step-xl`.
+They carry a prefix because `xs, sm, md, lg, xl` are the names of Tailwind's
+`--container-*` scale, and a `--spacing-md` of our own was swallowing `max-w-md`
+across the whole project with nothing warning about it. `max-w-*`, `w-*` and
+`h-*` belong to Tailwind and are used as they are. Migration guide from 0.2.0:
+<https://github.com/Proskynete/arrecife/blob/main/docs/migration-0.3.md>.
+
+## System rules the consuming code must not break
+
+These are identity decisions, already measured. Breaking them produces code that
+compiles and looks wrong, or that fails the project's accessibility audit.
+
+1. **Zero literal hexes.** Every color comes from a token or its custom property.
+2. **`Button variant="conversion"` appears once per screen.** It is not enforced
+   at runtime; two on the same page are a design error.
+3. **`Button variant="destructive"` is for the irreversible only.** Never for
+   «cancel» on a form, and not inside an `AlertDialog` — there the confirm button
+   stays `primary`, because the title, the focus on cancel and the no-click-outside
+   already carry the weight. See `docs/decisions.md` § 21.
+4. **`secondary` is never filled.** It is border and text.
+5. **No entrance animations.** Modals, menus, tooltips and toasts appear where
+   they will stay. The only exception is the `Button loading` spinner.
+6. **Semantics and scale are independent.** An `h2` that has to look small is
+   `<Text as="h2" variant="h3">`, never an `h3` that lies about the hierarchy.
+7. **`textMuted` never goes over `surfaceRaised`**: it gives 4.07 in dark. Over a
+   raised surface — menus, active tabs — the token is `textSecondary`.
+8. **A background tinted with a semantic color carries text from a text token**,
+   not from the semantic color. The color stays on the border and on the glyph.
+   Putting `accent` over its own tint at 8 % gives 4.12 and does not reach AA.
+9. **`Progress` requires `label`.** A bar with no accessible name does not say
+   what it is about.
+10. **`Button size="icon"` and `size="icon-sm"` require `aria-label`.** They carry
+    no text. `icon` is 42×42 and is a page action; `icon-sm` is 32×32 and is for a
+    dense table row.
+11. **The mascot's faces only appear** in empty states, confirmations, errors,
+    course progress and celebration. Never in a hero, pricing, services, contact
+    or the CV.
+    **And not in every empty state either**: `EmptyState variant="inline"` is the
+    hole inside a table page or a dashboard widget, and it carries no face — the
+    type does not accept one. `page`, the default, is the one that IS the screen,
+    and there `expression` stays mandatory. A dozen mascots on one admin screen is
+    not the humour contract. See `docs/decisions.md` § 27.
+12. **The fin is not a free parameter**: `foam` on a dark background, `color` on a
+    light one. The components already choose it from the background.
+
+## What the library does NOT do, on purpose
+
+These are the confusions people run into most often when consuming it.
+
+- **It does not ship Shiki.** It publishes the *theme*, not the highlighter.
+  `CodeBlock` receives the code **already highlighted** by the project's tool.
+- **It does not format dates.** `ArticleCard`, `TalkCard` and company receive the
+  date already formatted by the project: the library imposes no locale.
+  `dateTime` is separate, in ISO, for the `<time>` attribute.
+- **`NewsletterForm` does not do the POST.** It is presentational: it takes
+  `state` and emits `onSubmitEmail`. The call is made by the project with its own
+  provider.
+- **It ships no router.** The components with links accept `asChild` to wrap the
+  framework's `Link`.
+- **It ships no `data-testid`.** A composed part your test suite has to reach is
+  reached with a slot: `ArticleCard`'s `tagAsChild`, `Breadcrumb`'s and
+  `TableOfContents`'s `linkAsChild`. They hand you the element and its
+  attributes and keep the classes. Do NOT select by structure or by a style
+  class — a style class is not a contract and it changes when the style does.
+- **It does not load fonts.** It declares them by name.
+- **There is no Tailwind v3 preset.**
+
+## Usage patterns
 
 ```tsx
 import { Text, Button, Badge, cn } from '@eduardoalvarez/arrecife';
@@ -264,12 +568,12 @@ import type { TextProps } from '@eduardoalvarez/arrecife';
 
 <Text variant="eyebrow" tone="muted">charlas</Text>
 <Text as="h2" variant="h1">Escalar con criterio</Text>
-<Text variant="body">Se corta solo a 68ch.</Text>
-<Text variant="ui" measure={false}>Sin corte, para una celda estrecha.</Text>
+<Text variant="body">Clamps itself to 68ch.</Text>
+<Text variant="ui" measure={false}>No clamp, for a narrow cell.</Text>
 ```
 
-`asChild` renderiza el hijo en vez del elemento propio. Es como se envuelve el
-enlace del framework sin perder los estilos:
+`asChild` renders the child instead of the component's own element. It is how the
+framework's link gets wrapped without losing the styles:
 
 ```tsx
 <Button asChild>
@@ -277,23 +581,23 @@ enlace del framework sin perder los estilos:
 </Button>
 ```
 
-`cn` es `clsx` + `tailwind-merge`. Se usa para componer `className` sin que dos
-utilidades del mismo grupo peleen.
+`cn` is `clsx` + `tailwind-merge`. It is used to compose `className` without two
+utilities from the same group fighting each other.
 
-Open Graph, sin React:
+Open Graph, without React:
 
 ```ts
 import satori from 'satori';
-import { plantillaArticulo, OG } from '@eduardoalvarez/arrecife/og';
+import { articleTemplate, OG } from '@eduardoalvarez/arrecife/og';
 
-const svg = await satori(plantillaArticulo({ title, date, readingMinutes }), {
+const svg = await satori(articleTemplate({ title, date, readingMinutes }), {
   width: OG.width,   // 1200
   height: OG.height, // 630
   fonts: [...],
 });
 ```
 
-Resaltado de sintaxis, desde la configuración del sitio:
+Syntax highlighting, from the site's configuration:
 
 ```ts
 import { arrecife } from '@eduardoalvarez/arrecife/shiki';
@@ -303,1253 +607,1348 @@ export default defineConfig({
 });
 ```
 
-# Inventario
+# Inventory
 
-Lo que sigue sale del compilador de TypeScript en cada build. Solo se listan los
-props **declarados por la librería**: los heredados de un elemento HTML o de una
-primitiva de Radix se resumen en la línea `Extiende`, y son los de siempre.
+What follows comes out of the TypeScript compiler on every build. Only the props
+**declared by the library** are listed: the ones inherited from an HTML element
+or from a Radix primitive are summarised in the `Extends` line, and they are the
+usual ones.
 
-## Primitivos
+## Primitives
 
-Se importan de `@eduardoalvarez/arrecife`. 110 exportaciones.
+Imported from `@eduardoalvarez/arrecife`. 110 exports.
 
 ### Accordion, AccordionItem, AccordionTrigger, AccordionContent
 
-Fuente: `src/primitives/accordion.tsx`
+Source: `src/primitives/accordion.tsx`
 
 **Accordion**
-El plegable. Lo pedían dos proyectos: el FAQ del portafolio y el temario de cursos, que es literalmente una lista de secciones que se abren.
+The disclosure. Two projects asked for it: the portfolio FAQ and the course syllabus, which is literally a list of sections that open.
 
-- Extiende: `ComponentPropsWithoutRef<typeof AccordionPrimitive.Root>`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<typeof AccordionPrimitive.Root>`
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AccordionItem**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AccordionTrigger**
-El disparador es el encabezado, así que va DENTRO de un `<h3>`: Radix envuelve el botón en `AccordionPrimitive.Header`, que renderiza el elemento que se le pida. Sin eso, un lector de pantalla ve una lista de botones sueltos y pierde la estructura de la página, que es justo lo que un FAQ necesita conservar.
+The trigger IS the heading, so it goes INSIDE an `<h3>`: Radix wraps the button in `AccordionPrimitive.Header`, which renders whichever element you ask of it. Without that, a screen reader sees a list of loose buttons and loses the page structure, which is precisely what a FAQ needs to keep.
 
-- Extiende: `ComponentPropsWithoutRef< typeof AccordionPrimitive.Trigger >`
+- Extends: `ComponentPropsWithoutRef< typeof AccordionPrimitive.Trigger >`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `headingLevel` | `4 \| 2 \| 3` |  | `3` | Nivel del encabezado que envuelve al disparador. |
+| `headingLevel` | `4 \| 2 \| 3` |  | `3` | The level of the heading wrapping the trigger. |
 
 **AccordionContent**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### AlertDialogOverlay, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogCancel, AlertDialogAction, AlertDialog, AlertDialogTrigger
 
-Fuente: `src/primitives/alert-dialog.tsx`
+Source: `src/primitives/alert-dialog.tsx`
 
 **AlertDialogOverlay**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AlertDialogContent**
-Sin entrada animada, igual que `Dialog`: aparece donde va a quedarse.
+No entrance animation, same as `Dialog`: it appears where it will stay.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AlertDialogHeader**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AlertDialogFooter**
-Cancelar a la IZQUIERDA de confirmar en escritorio y ABAJO en móvil, que es lo que da `flex-col-reverse`: el orden del DOM pone cancelar primero —es donde va el foco— y en columna el dedo lo encuentra donde toca sin cambiar la tabulación.
+Cancel to the LEFT of confirm on desktop and BELOW it on mobile, which is what `flex-col-reverse` gives: the DOM order puts cancel first — that is where focus goes — and in a column the thumb finds it where it should be without changing the tab order.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AlertDialogTitle**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AlertDialogDescription**
-Lo que se pierde, dicho entero. Es lo que el rol `alertdialog` hace que se anuncie de entrada, así que aquí no va «esta acción no se puede deshacer» suelto: va qué se borra y qué se lleva por delante.
+What is lost, spelled out. The `alertdialog` role makes this get announced up front, so «this action cannot be undone» does not go here on its own: what goes here is what gets deleted and what it takes down with it.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AlertDialogCancel**
-El que se lleva el foco al abrir.
+The one that takes focus on open.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AlertDialogAction**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AlertDialog**
-La confirmación destructiva. NO es un `Dialog` con otro texto, y por eso está en su propio archivo y sobre su propia primitiva de Radix.
+The destructive confirmation. It is NOT a `Dialog` with different text, which is why it lives in its own file and on its own Radix primitive.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AlertDialogTrigger**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Alert
 
-Fuente: `src/primitives/alert.tsx`
+Source: `src/primitives/alert.tsx`
 
-El aviso lleva el color en el fondo, no solo en el borde.
+- Extends: `Omit<ComponentPropsWithoutRef<'div'>, 'title'> & VariantProps<typeof alert>`
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'div'>, 'title'> & VariantProps<typeof alert>`
-
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `enfasis` | `"sutil" \| "fuerte"` |  | `sutil` |  |
-| `icon` | `ReactNode` |  |  | Sustituye el glifo mono de la variante. Nunca un emoji: si necesitas otra cosa, es un SVG de `glyphs`. |
+| `emphasis` | `"subtle" \| "strong"` |  |  |  |
+| `icon` | `ReactNode` |  |  | Replaces the variant's mono glyph. Never an emoji: if you need something else, it is an SVG from `glyphs`. |
 | `title` | `ReactNode` |  |  |  |
-| `variant` | `"accent" \| "success" \| "warning" \| "error"` |  | `accent` |  |
+| `variant` | `"accent" \| "success" \| "warning" \| "error"` |  |  |  |
 
 ### Avatar, AvatarImage, AvatarFallback, AvatarUpload
 
-Fuente: `src/primitives/avatar.tsx`
+Source: `src/primitives/avatar.tsx`
 
 **Avatar**
-Uno solo para todo: la foto del autor y la de cualquier persona del sistema. No hay un `brand/Avatar` aparte — una foto de perfil con la piel de la marca es exactamente esto con un `src` distinto.
+One for everything: the author's photo and anyone else's in the system. There is no separate `brand/Avatar` — a profile photo wearing the brand's skin is exactly this with a different `src`.
 
-- Extiende: `ComponentPropsWithoutRef<typeof AvatarPrimitive.Root> & VariantProps<typeof avatar>`
+- Extends: `ComponentPropsWithoutRef<typeof AvatarPrimitive.Root> & VariantProps<typeof avatar>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `size` | `"sm" \| "md" \| "lg" \| "xl"` |  | `md` |  |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` |  |  |  |
 
 **AvatarImage**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AvatarFallback**
-Iniciales mientras la imagen carga, o cuando no hay imagen.
+Initials while the image loads, or when there is no image.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **AvatarUpload**
-El avatar que se puede cambiar. `Avatar` muestra; este además deja elegir.
+The avatar you can change. `Avatar` displays; this one also lets you pick.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'div'>, 'onSelect' \| 'children'> & VariantProps<typeof avatar>`
+- Extends: `Omit<ComponentPropsWithoutRef<'div'>, 'onSelect' \| 'children'> & VariantProps<typeof avatar>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `accept` | `string` |  | `image/*` | Qué acepta el diálogo del sistema. |
+| `accept` | `string` |  | `image/*` | What the system dialog accepts. |
 | `disabled` | `boolean \| undefined` |  | `false` |  |
-| `fallback` | `ReactNode` |  |  | Iniciales mientras no hay imagen. |
-| `label` | `string` |  | `Cambiar la foto` | Nombre accesible del control. Es lo único que lo nombra: no hay texto visible. |
-| `onSelectFile` | `(archivo: File) => void` |  |  | Se dispara con el archivo elegido. La subida la hace el proyecto. |
+| `fallback` | `ReactNode` |  |  | Initials while there is no image. |
+| `label` | `string` |  | `Cambiar la foto` | The control's accessible name. It is the only thing naming it: there is no visible text. |
+| `onSelectFile` | `(file: File) => void` |  |  | Fires with the chosen file. The upload is the project's job. |
 | `size` | `"sm" \| "md" \| "lg" \| "xl"` |  |  |  |
-| `src` | `string` |  |  | La imagen actual, ya subida. La previsualización local la gana mientras dure. |
+| `src` | `string` |  |  | The current image, already uploaded. The local preview beats it while it lasts. |
 
 ### Badge, CategoryBadge, MetricBadge
 
-Fuente: `src/primitives/badge.tsx`
+Source: `src/primitives/badge.tsx`
 
 **Badge**
-Semáforo. Cuadrada r6, sans 12.5/500 y fondo al 8 % del semántico — la receta del aviso en tamaño de palabra: un estado es un aviso de una sola palabra.
+Three badge families, three components. Why there are three shapes and not one is in `variants/badge.ts`, next to the classes that make them.
 
-- Extiende: `ComponentPropsWithoutRef<'span'> & VariantProps<typeof badge>`
+- Extends: `ComponentPropsWithoutRef<'span'> & VariantProps<typeof badge>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `variant` | `"accent" \| "success" \| "warning" \| "error" \| "neutral" \| "warm"` |  | `neutral` |  |
+| `variant` | `"neutral" \| "accent" \| "warm" \| "success" \| "warning" \| "error"` |  |  |  |
 
 **CategoryBadge**
-Un slug, en arena. Sin transformar: los slugs ya vienen en minúscula y forzarla sería el mismo error que forzaba el `uppercase`.
+- Extends: `ComponentPropsWithoutRef<'span'>`
 
-- Extiende: `ComponentPropsWithoutRef<'span'>`
-
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `active` | `boolean \| undefined` |  | `false` | Filtro seleccionado: arena sólido con tinta encima. |
+| `active` | `boolean \| undefined` |  | `false` | Selected filter: solid sand with ink on top. |
 
 **MetricBadge**
-- Extiende: `ComponentPropsWithoutRef<'span'>`
+- Extends: `ComponentPropsWithoutRef<'span'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `boxed` | `boolean \| undefined` |  | `false` | Añade el aro de hairline. Por defecto la métrica va sin caja. |
+| `boxed` | `boolean \| undefined` |  | `false` | Adds the hairline ring. By default a metric carries no box. |
 
 ### Button
 
-Fuente: `src/primitives/button.tsx`
-
-Las CUATRO variantes del sistema, y solo esas cuatro.
+Source: `src/primitives/button.tsx`
 
-- Extiende: `ComponentPropsWithoutRef<'button'> & VariantProps<typeof button>`
+- Extends: `ComponentPropsWithoutRef<'button'> & VariantProps<typeof button>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `asChild` | `boolean` |  | `false` | Renderiza el hijo en vez de un `<button>`, para envolver un enlace. |
-| `icon` | `ReactNode` |  |  | Glifo SVG antes del texto. Se oculta mientras carga. |
-| `loading` | `boolean` |  | `false` | Deshabilita y anuncia `aria-busy`. Incompatible con `asChild`. |
-| `size` | `"sm" \| "md" \| "lg" \| "icon"` |  | `md` |  |
-| `variant` | `"primary" \| "conversion" \| "secondary" \| "tertiary"` |  | `primary` |  |
+| `asChild` | `boolean` |  | `false` | Renders the child instead of a `<button>`, to wrap a link. |
+| `icon` | `ReactNode` |  |  | SVG glyph before the text. Hidden while loading. |
+| `loading` | `boolean` |  | `false` | Disables and announces `aria-busy`. Incompatible with `asChild`. |
+| `size` | `"sm" \| "md" \| "lg" \| "icon" \| "icon-sm"` |  |  |  |
+| `variant` | `"primary" \| "conversion" \| "secondary" \| "tertiary" \| "destructive" \| "destructiveOutline"` |  |  |  |
 
 ### Calendar
 
-Fuente: `src/primitives/calendar.tsx`
+Source: `src/primitives/calendar.tsx`
 
-Calendario mensual navegable, sobre `react-day-picker`.
+A navigable month calendar, on top of `react-day-picker`.
 
-- Extiende: `ComponentProps<typeof DayPicker>`
+- Extends: `ComponentProps<typeof DayPicker>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `fullWidth` | `boolean \| undefined` |  | `false` | Estira el calendario hasta ocupar todo el ancho de su contenedor, con las celdas repartiéndoselo a partes iguales. |
+| `fullWidth` | `boolean \| undefined` |  | `false` | Stretches the calendar to fill its container's whole width, with the cells splitting it evenly. |
 
 ### Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter
 
-Fuente: `src/primitives/card.tsx`
+Source: `src/primitives/card.tsx`
 
 **Card**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **CardHeader**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **CardTitle**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **CardDescription**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **CardContent**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **CardFooter**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Checkbox
 
-Fuente: `src/primitives/checkbox.tsx`
+Source: `src/primitives/checkbox.tsx`
 
-- Extiende: `ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>`
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Code
 
-Fuente: `src/primitives/code.tsx`
+Source: `src/primitives/code.tsx`
 
-Código en línea, dentro de prosa.
+Inline code, inside prose.
 
-- Extiende: `ComponentPropsWithoutRef<'code'>`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<'code'>`
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### DateField
 
-Fuente: `src/primitives/date-field.tsx`
+Source: `src/primitives/date-field.tsx`
 
-Un campo de fecha sobre el control nativo, no sobre un calendario propio.
+A date field on the native control, not on a calendar of our own.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'input'>, 'type'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'input'>, 'type'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `invalid` | `boolean \| undefined` |  | `false` |  |
-| `withTime` | `boolean \| undefined` |  | `false` | Añade la hora al campo. Es el `datetime-local` nativo. |
+| `withTime` | `boolean \| undefined` |  | `false` | Adds the time to the field. It is the native `datetime-local`. |
 
 ### DialogOverlay, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, Dialog, DialogTrigger, DialogClose
 
-Fuente: `src/primitives/dialog.tsx`
+Source: `src/primitives/dialog.tsx`
 
 **DialogOverlay**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DialogContent**
-Sin entrada animada: no hay escala ni desplazamiento en el sistema.
+No entrance animation: there is no scale or displacement in the system.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DialogHeader**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DialogFooter**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DialogTitle**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DialogDescription**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **Dialog**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DialogTrigger**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DialogClose**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuSubTrigger, DropdownMenuSubContent, DropdownMenu, DropdownMenuTrigger, DropdownMenuGroup, DropdownMenuRadioGroup, DropdownMenuSub
 
-Fuente: `src/primitives/dropdown-menu.tsx`
+Source: `src/primitives/dropdown-menu.tsx`
 
 **DropdownMenuContent**
-Sin animación de entrada: el menú aparece, no se despliega.
+No entrance animation: the menu appears, it does not unfold.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuItem**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuCheckboxItem**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuRadioItem**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuLabel**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuSeparator**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuSubTrigger**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuSubContent**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenu**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuTrigger**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuGroup**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuRadioGroup**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **DropdownMenuSub**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Input
 
-Fuente: `src/primitives/input.tsx`
+Source: `src/primitives/input.tsx`
 
-- Extiende: `ComponentPropsWithoutRef<'input'>`
+- Extends: `ComponentPropsWithoutRef<'input'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `invalid` | `boolean` |  | `false` | Marca el control como inválido y tiñe el borde. |
+| `invalid` | `boolean` |  | `false` | Marks the control as invalid and tints the border. |
 
 ### Label
 
-Fuente: `src/primitives/label.tsx`
+Source: `src/primitives/label.tsx`
 
-La escala `label`: 13px, que es el mínimo absoluto en pantalla del sistema.
+The `label` scale: 13px, which is the system's absolute minimum on screen.
 
-- Extiende: `ComponentPropsWithoutRef<typeof LabelPrimitive.Root>`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<typeof LabelPrimitive.Root>`
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis
 
-Fuente: `src/primitives/pagination.tsx`
+Source: `src/primitives/pagination.tsx`
 
 **Pagination**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **PaginationContent**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **PaginationItem**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **PaginationLink**
-- Extiende: `ComponentPropsWithoutRef<'a'>`
+- Extends: `ComponentPropsWithoutRef<'a'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `isActive` | `boolean` |  | `false` |  |
 
 **PaginationPrevious**
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `isActive` | `boolean` |  |  |  |
 
 **PaginationNext**
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `isActive` | `boolean` |  |  |  |
 
 **PaginationEllipsis**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### PopoverContent, Popover, PopoverTrigger, PopoverAnchor
 
-Fuente: `src/primitives/popover.tsx`
+Source: `src/primitives/popover.tsx`
 
 **PopoverContent**
-Sin animación de entrada: aparece donde va a quedarse, como el resto.
+No entrance animation: it appears where it will stay, like the rest.
 
-- Extiende: `ComponentPropsWithoutRef<typeof PopoverPrimitive.Content> & Etiquetado`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<typeof PopoverPrimitive.Content> & Labelled`
+- No own props: it passes through those of the element or primitive it wraps.
 
 **Popover**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **PopoverTrigger**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **PopoverAnchor**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Progress
 
-Fuente: `src/primitives/progress.tsx`
+Source: `src/primitives/progress.tsx`
 
-El ancho del indicador cambia, no se anima: el sistema no anima escala ni desplazamiento. `transition-standard` solo cubre color y borde, así que el salto de ancho es inmediato aunque la clase esté puesta.
+The indicator's width changes, it is not animated: the system animates neither scale nor displacement. `transition-standard` only covers color and border, so the width jump is immediate even with the class in place.
 
-- Extiende: `ComponentPropsWithoutRef<typeof ProgressPrimitive.Root>`
+- Extends: `ComponentPropsWithoutRef<typeof ProgressPrimitive.Root>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `label` | `string` | sí |  | Nombre accesible de la barra. Es obligatorio a propósito: una barra de progreso sin nombre no dice de qué es el progreso, y ninguna otra parte del componente puede deducirlo. |
-| `tone` | `"accent" \| "warm"` |  | `accent` | Arena en vez de bioluz, para progreso de curso. |
+| `label` | `string` | yes |  | The bar's accessible name. It is mandatory on purpose: a progress bar with no name does not say what the progress is about, and no other part of the component can deduce it. |
+| `tone` | `"accent" \| "warm"` |  | `accent` | Sand instead of biolume, for course progress. |
 
 ### RadioGroup, RadioGroupItem
 
-Fuente: `src/primitives/radio-group.tsx`
+Source: `src/primitives/radio-group.tsx`
 
 **RadioGroup**
-- Extiende: `ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>`
+- No own props: it passes through those of the element or primitive it wraps.
 
 **RadioGroupItem**
-- Extiende: `ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>`
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### SelectTrigger, SelectContent, SelectLabel, SelectItem, SelectSeparator, Select, SelectGroup, SelectValue
 
-Fuente: `src/primitives/select.tsx`
+Source: `src/primitives/select.tsx`
 
 **SelectTrigger**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SelectContent**
-Sin animación de entrada: el menú aparece, no se despliega.
+No entrance animation: the menu appears, it does not unfold.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SelectLabel**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SelectItem**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SelectSeparator**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **Select**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SelectGroup**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SelectValue**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Separator
 
-Fuente: `src/primitives/separator.tsx`
+Source: `src/primitives/separator.tsx`
 
-`hairline`, no `border`: una división entre contenidos es sutil por definición. Para delimitar un control existe `border`, que es otro token.
+`hairline`, not `border`: a division between pieces of content is subtle by definition. To delimit a control there is `border`, which is another token.
 
-- Extiende: `ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>`
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### SheetContent, SheetHeader, SheetBody, SheetFooter, SheetTitle, SheetDescription, Sheet, SheetTrigger, SheetClose
 
-Fuente: `src/primitives/sheet.tsx`
+Source: `src/primitives/sheet.tsx`
 
 **SheetContent**
-La segunda y última excepción a «nada de desplazamiento», aprobada a sabiendas: un panel que entra desde un borde se desliza por definición, y quieto sería un modal descentrado.
+The second and last exception to «no displacement», approved knowingly: a panel entering from an edge slides by definition, and held still it would be an off-centre modal.
 
-- Extiende: `ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & VariantProps<typeof panel>`
+- Extends: `ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & VariantProps<typeof panel>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `side` | `"right" \| "left" \| "top" \| "bottom"` |  | `right` |  |
 
 **SheetHeader**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SheetBody**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SheetFooter**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SheetTitle**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SheetDescription**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **Sheet**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SheetTrigger**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **SheetClose**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Skeleton
 
-Fuente: `src/primitives/skeleton.tsx`
+Source: `src/primitives/skeleton.tsx`
 
-Barrido de 1.4s lineal, del documento.
+A 1.4s linear sweep, from the document.
 
-- Extiende: `ComponentPropsWithoutRef<'div'>`
+- Extends: `ComponentPropsWithoutRef<'div'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `still` | `boolean \| undefined` |  | `false` | Apaga el barrido. Para listas largas, donde muchas a la vez marean. |
+| `still` | `boolean \| undefined` |  | `false` | Turns the sweep off. For long lists, where many at once are dizzying. |
 
 ### Switch
 
-Fuente: `src/primitives/switch.tsx`
+Source: `src/primitives/switch.tsx`
 
-La perilla cambia de posición, pero no se anima al hacerlo: la posición es el estado, no una transición. Lo único que transiciona es el color de la vía.
+The knob changes position, but is not animated while doing so: the position IS the state, not a transition. The only thing that transitions is the track's color.
 
-- Extiende: `ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>`
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption
 
-Fuente: `src/primitives/table.tsx`
+Source: `src/primitives/table.tsx`
 
 **Table**
-El contenedor scrollea en horizontal: la página nunca lo hace.
+The container scrolls horizontally: the page never does.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TableHeader**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TableBody**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TableFooter**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TableRow**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TableHead**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TableCell**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TableCaption**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Tabs, TabsList, TabsTrigger, TabsContent
 
-Fuente: `src/primitives/tabs.tsx`
+Source: `src/primitives/tabs.tsx`
 
 **Tabs**
-- Extiende: `ComponentPropsWithoutRef<typeof TabsPrimitive.Root>`
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- Extends: `ComponentPropsWithoutRef<typeof TabsPrimitive.Root>`
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TabsList**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TabsTrigger**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TabsContent**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Textarea
 
-Fuente: `src/primitives/textarea.tsx`
+Source: `src/primitives/textarea.tsx`
 
-- Extiende: `ComponentPropsWithoutRef<'textarea'>`
+- Extends: `ComponentPropsWithoutRef<'textarea'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `invalid` | `boolean` |  | `false` |  |
 
 ### Toaster
 
-Fuente: `src/primitives/toaster.tsx`
+Source: `src/primitives/toaster.tsx`
 
-Va UNA vez, lo más arriba posible del árbol. Dos `Toaster` montados pintan cada aviso dos veces: la lista es del módulo, no de la instancia.
+Mount it ONCE, as high in the tree as possible. Two mounted `Toaster`s paint every notice twice: the list belongs to the module, not to the instance.
 
-- Extiende: `{ /** Cuánto dura un aviso que no dice lo contrario. */ duration?: number; /** * Nombre del landmark que Radix crea para la región de avisos. Se traduce * porque lo lee un lector de pantalla, y el default de Radix está en inglés. */ label?: string; }`
+- Extends: `{ /** How long a notice lasts when it does not say otherwise. */ duration?: number; /** * The name of the landmark Radix creates for the notices region. It is * translated because a screen reader reads it, and Radix's default is in * English. */ label?: string; }`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `duration` | `number` |  | `5000` | Cuánto dura un aviso que no dice lo contrario. |
-| `label` | `string` |  | `Avisos` | Nombre del landmark que Radix crea para la región de avisos. Se traduce porque lo lee un lector de pantalla, y el default de Radix está en inglés. |
+| `duration` | `number` |  | `5000` | How long a notice lasts when it does not say otherwise. |
+| `label` | `string` |  | `Avisos` | The name of the landmark Radix creates for the notices region. It is translated because a screen reader reads it, and Radix's default is in English. |
 
 ### TooltipContent, TooltipProvider, Tooltip, TooltipTrigger
 
-Fuente: `src/primitives/tooltip.tsx`
+Source: `src/primitives/tooltip.tsx`
 
 **TooltipContent**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TooltipProvider**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **Tooltip**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **TooltipTrigger**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 ### Text
 
-Fuente: `src/primitives/typography.tsx`
+Source: `src/primitives/typography.tsx`
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'p'>, 'color'> & VariantProps<typeof texto>`
+- Extends: `Omit<ComponentPropsWithoutRef<'p'>, 'color'> & VariantProps<typeof text>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `as` | `"h2" \| "h3" \| "li" \| "p" \| "span" \| "caption" \| "dd" \| "dt" \| "em" \| "figcaption" \| "h1" \| "h4" \| "legend" \| "strong"` |  |  | Etiqueta HTML. Por defecto, la que corresponde a la escala. |
-| `asChild` | `boolean` |  | `false` | Renderiza el hijo en vez de crear un elemento, para envolver un enlace. |
-| `measure` | `boolean` |  |  | Corta la línea a 68ch. Activo por defecto en `body`, que es la única escala pensada para leerse en párrafos largos. |
-| `tone` | `"accent" \| "success" \| "warning" \| "error" \| "warm" \| "primary" \| "secondary" \| "muted"` |  | `primary` |  |
-| `variant` | `"display" \| "h2" \| "h3" \| "label" \| "body" \| "h1" \| "meta" \| "stat" \| "lead" \| "ui" \| "tag" \| "chip" \| "eyebrow"` |  | `body` |  |
+| `as` | `"h1" \| "h2" \| "h3" \| "strong" \| "li" \| "p" \| "span" \| "caption" \| "dd" \| "dt" \| "em" \| "figcaption" \| "h4" \| "legend"` |  |  | HTML tag. Defaults to whichever one matches the scale. |
+| `asChild` | `boolean` |  | `false` | Renders the child instead of creating an element, to wrap a link. |
+| `measure` | `boolean` |  |  | Clamps the line to 68ch. On by default for `body`, the only scale meant to be read in long paragraphs. |
+| `tone` | `"primary" \| "secondary" \| "accent" \| "warm" \| "success" \| "warning" \| "error" \| "muted"` |  |  |  |
+| `variant` | `"display" \| "stat" \| "h1" \| "h2" \| "h3" \| "body" \| "lead" \| "ui" \| "label" \| "tag" \| "chip" \| "meta" \| "eyebrow"` |  |  |  |
 
-## Componentes
+## Components
 
-Se importan de `@eduardoalvarez/arrecife`. 24 exportaciones.
+Imported from `@eduardoalvarez/arrecife`. 25 exports.
 
 ### ArticleCard
 
-Fuente: `src/components/article-card/index.tsx`
+Source: `src/components/article-card/index.tsx`
 
-La línea de metadatos va en `meta` y no en `eyebrow`: `18 ago 2026 · 8 min de lectura` es un dato, no un antetítulo, y en versalitas no era ninguna de las dos cosas.
+The metadata line uses `meta` and not `eyebrow`: `18 ago 2026 · 8 min de lectura` is a datum, not an overline, and in small caps it was neither.
 
-- Extiende: `Omit<TarjetaProps, 'children' \| 'title'>`
+- Extends: `Omit<CardShellProps, 'children' \| 'title'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `asChild` | `boolean \| undefined` |  |  | Renderiza el hijo en vez de un `<a>`. Es como se enchufa el `Link` de Next o de Astro sin que la librería dependa de ningún enrutador. |
-| `date` | `ReactNode` |  |  | Fecha ya formateada por el proyecto: la librería no impone locale. |
-| `dateTime` | `string` |  |  | Valor de `datetime` del `<time>`, en ISO. |
-| `excerpt` | `ReactNode` |  |  | Entradilla. Se corta a dos líneas para que la rejilla no se desalinee. |
-| `headingLevel` | `2 \| 3` |  | `3` | Nivel del titular. `h3` por defecto: una tarjeta suelta en una rejilla no gana el nivel que su posición no le da. |
+| `asChild` | `boolean \| undefined` |  |  | Renders the child instead of an `<a>`. It is how Next's or Astro's `Link` plugs in without the library depending on any router. |
+| `date` | `ReactNode` |  |  | Date already formatted by the project: the library imposes no locale. |
+| `dateTime` | `string` |  |  | The `<time>` element's `datetime` value, in ISO. |
+| `excerpt` | `ReactNode` |  |  | Standfirst. Clamped to two lines so the grid does not fall out of line. |
+| `headingLevel` | `2 \| 3` |  | `3` | The headline level. `h3` by default: a lone card in a grid does not earn a level its position does not give it. |
 | `readingMinutes` | `number` |  |  |  |
+| `tagAsChild` | `(props: { tag: string; children: ReactNode; }) => ReactNode` |  |  | Renders each tag through the child, so an E2E suite can reach it. |
 | `tags` | `readonly string[]` |  |  |  |
-| `title` | `ReactNode` | sí |  |  |
+| `title` | `ReactNode` | yes |  |  |
 
 ### AudioPlayer
 
-Fuente: `src/components/audio-player/index.tsx`
+Source: `src/components/audio-player/index.tsx`
 
-- Extiende: `{ src: string; title?: string; /** * `full` para páginas de podcast, `compact` para barras laterales y `banner` * para artículos con narración. `compact` y `banner` traen además el * reproductor flotante cuando el estático sale de vista. */ mode?: AudioPlayerMode \| undefined; /** * Se llama una sola vez por carga, la primera vez que el audio arranca. * Aquí es donde el proyecto engancha su analítica; la librería no la trae. */ onFirstPlay?: ((title?: string) => void) \| undefined; }`
+- Extends: `{ src: string; title?: string; /** * `full` for podcast pages, `compact` for sidebars and `banner` for articles * with narration. `compact` and `banner` also bring the floating player when * the static one leaves the viewport. */ mode?: AudioPlayerMode \| undefined; /** * Called once per load, the first time the audio starts. * This is where the project hooks up its analytics; the library ships none. */ onFirstPlay?: ((title?: string) => void) \| undefined; }`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `mode` | `"banner" \| "full" \| "compact"` |  | `full` | `full` para páginas de podcast, `compact` para barras laterales y `banner` para artículos con narración. `compact` y `banner` traen además el reproductor flotante cuando el estático sale de vista. |
-| `onFirstPlay` | `(title?: string \| undefined) => void` |  |  | Se llama una sola vez por carga, la primera vez que el audio arranca. Aquí es donde el proyecto engancha su analítica; la librería no la trae. |
-| `src` | `string` | sí |  |  |
+| `mode` | `"banner" \| "full" \| "compact"` |  | `full` | `full` for podcast pages, `compact` for sidebars and `banner` for articles with narration. `compact` and `banner` also bring the floating player when the static one leaves the viewport. |
+| `onFirstPlay` | `(title?: string \| undefined) => void` |  |  | Called once per load, the first time the audio starts. This is where the project hooks up its analytics; the library ships none. |
+| `src` | `string` | yes |  |  |
 | `title` | `string` |  |  |  |
 
 ### AuthorCard
 
-Fuente: `src/components/author-card/index.tsx`
+Source: `src/components/author-card/index.tsx`
 
-La firma al pie del artículo: avatar 52px, nombre 15/500 y el rol en mono muted. Tres datos, ni uno más.
+The byline at the foot of the article: 52px avatar, 15/500 name and the role in muted mono. Three data points, not one more.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'div'>, 'role'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'div'>, 'role'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `action` | `ReactNode` |  |  | Enlaces o botón de contacto. |
-| `bio` | `ReactNode` |  |  | Una o dos frases. Se corta a 68ch sola. |
-| `name` | `string` | sí |  |  |
-| `role` | `ReactNode` |  |  | El rol. Va en mono: es un dato, no una frase. |
-| `src` | `string` |  |  | URL del avatar. Sin ella se muestran las iniciales. |
+| `action` | `ReactNode` |  |  | Links or a contact button. |
+| `bio` | `ReactNode` |  |  | One or two sentences. It clamps itself to 68ch. |
+| `name` | `string` | yes |  |  |
+| `role` | `ReactNode` |  |  | The role. It goes in mono: it is a datum, not a sentence. |
+| `src` | `string` |  |  | The avatar's URL. Without it the initials are shown. |
 
 ### Blockquote
 
-Fuente: `src/components/blockquote/index.tsx`
+Source: `src/components/blockquote/index.tsx`
 
-La barra lateral es `accent`, que es el color interactivo, porque una cita es la voz de otro entrando en el texto. No lleva comillas decorativas: los glifos del sistema son SVG y una comilla de adorno no aporta nada que el borde y la sangría no digan ya.
+The side bar is `accent`, the interactive color, because a quotation is somebody else's voice entering the text. It carries no decorative quote marks: the system's glyphs are SVG, and an ornamental quote adds nothing the border and the indent do not already say.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'blockquote'>, 'cite'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'blockquote'>, 'cite'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `author` | `ReactNode` |  |  | Quién lo dijo. Se marca como `<cite>`. |
-| `source` | `ReactNode` |  |  | Dónde lo dijo: charla, artículo, conversación. |
+| `author` | `ReactNode` |  |  | Who said it. Marked up as `<cite>`. |
+| `source` | `ReactNode` |  |  | Where they said it: a talk, an article, a conversation. |
 
 ### Breadcrumb
 
-Fuente: `src/components/breadcrumb/index.tsx`
+Source: `src/components/breadcrumb/index.tsx`
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'nav'>, 'children'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'nav'>, 'children'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `homeHref` | `string` |  | `/` | Destino del `~`. Por defecto, la raíz del sitio. |
-| `homeLabel` | `string` |  | `Inicio` | Etiqueta accesible del `~`, que si no se lee como una tilde suelta. |
-| `items` | `readonly Migaja[]` | sí |  |  |
-| `linkAsChild` | `(props: { href: string; children: ReactNode; }) => ReactNode` |  |  | Renderiza los enlaces con el hijo, para enchufar el `Link` de Next o Astro. Recibe cada `href` en el `props` del Slot. |
+| `homeHref` | `string` |  | `/` | Where the `~` goes. The site root by default. |
+| `homeLabel` | `string` |  | `Inicio` | Accessible label for the `~`, which otherwise reads as a stray tilde. |
+| `items` | `readonly Crumb[]` | yes |  |  |
+| `linkAsChild` | `(props: { href: string; children: ReactNode; }) => ReactNode` |  |  | Renders the links through the child, to plug in Next's or Astro's `Link`. It receives each `href` in the Slot's `props`. |
 
 ### CodeBlock
 
-Fuente: `src/components/code-block/index.tsx`
+Source: `src/components/code-block/index.tsx`
 
-`brand.hull` es «casco · contorno y fondo de bloques de código», así que un bloque de código es oscuro también en modo claro. Por eso la raíz declara `data-theme="dark"`: todo lo de dentro — tinta, hairline, acento — pasa a la paleta oscura sin importar el tema de la página. Es la única isla de tema invertido del sistema, y es deliberada.
+`brand.hull` is «hull · outline and the background of code blocks», so a code block is dark in light mode too. That is why the root declares `data-theme="dark"`: everything inside — ink, hairline, accent — switches to the dark palette regardless of the page's theme. It is the system's only island of inverted theme, and it is deliberate.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'div'>, 'children'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'div'>, 'children'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `children` | `ReactNode` | sí |  | El código ya resaltado, o texto plano. |
-| `copyText` | `string` |  |  | Texto que se copia al portapapeles. Sin esto, no se muestra el botón. |
-| `language` | `string` |  |  | Etiqueta del lenguaje. Se muestra en la barra superior. |
+| `children` | `ReactNode` | yes |  | The already-highlighted code, or flat text. |
+| `copyText` | `string` |  |  | The text copied to the clipboard. Without it, the button is not shown. |
+| `language` | `string` |  |  | The language label. Shown in the top bar. |
 
 ### CourseCard
 
-Fuente: `src/components/course-card/index.tsx`
+Source: `src/components/course-card/index.tsx`
 
-- Extiende: `Omit<TarjetaProps, 'children' \| 'title'>`
+- Extends: `Omit<CardShellProps, 'children' \| 'title'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `asChild` | `boolean \| undefined` |  |  | Renderiza el hijo en vez de un `<a>`. Es como se enchufa el `Link` de Next o de Astro sin que la librería dependa de ningún enrutador. |
-| `meta` | `readonly ReactNode[]` |  |  | Nivel, duración, número de lecciones: lo que el proyecto quiera listar. |
-| `progress` | `number` |  |  | Porcentaje cursado. Solo tiene sentido para quien ya está inscrito; cuando se pasa, la barra va en arena, que es el color del progreso de curso. |
-| `status` | `ReactNode` |  |  | Etiqueta de estado: «próximamente», «gratis», «nuevo». |
+| `asChild` | `boolean \| undefined` |  |  | Renders the child instead of an `<a>`. It is how Next's or Astro's `Link` plugs in without the library depending on any router. |
+| `meta` | `readonly ReactNode[]` |  |  | Level, duration, number of lessons: whatever the project wants to list. |
+| `progress` | `number` |  |  | Percentage completed. It only makes sense for someone already enrolled; when passed, the bar goes in sand, which is the color of course progress. |
+| `status` | `ReactNode` |  |  | Status label: «próximamente», «gratis», «nuevo». |
 | `summary` | `ReactNode` |  |  |  |
-| `title` | `ReactNode` | sí |  |  |
+| `title` | `ReactNode` | yes |  |  |
 
 ### EmptyState
 
-Fuente: `src/components/empty-state/index.tsx`
+Source: `src/components/empty-state/index.tsx`
 
-La regla más importante de la mascota, por fin como código.
+- Extends: `EmptyStateBase & ( \| { /** `page`, the default: the empty state IS the screen or the section, and it carries the face. */ variant?: 'page' \| undefined; /** * The face. Mandatory on `page` and impossible on `inline` — the props * are a union, so the generated table cannot show a per-variant «req.» * and the sentence has to carry it. Without it, `page` is a centred * paragraph. */ expression: Face; /** Where the brand PNGs are served from. */ basePath?: string \| undefined; icon?: never; } \| { /** `inline`: the hole inside a table or a widget. No face, and no way to pass one. */ variant: 'inline'; /** * A glyph above the line. It measures 1em and inherits `currentColor`, * like `Stat`'s: the project passes its own and sizes it, because the * system has no icon library and is not getting one. */ icon?: ReactNode; expression?: never; basePath?: never; } )`
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'div'>, 'title'>`
-
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `action` | `ReactNode` |  |  | La acción que saca del estado vacío. Normalmente un botón terciario. |
-| `basePath` | `string` |  |  | Dónde se sirven los PNG de la marca. |
-| `description` | `ReactNode` |  |  | Una línea explicando qué falta o qué hacer. |
-| `expresion` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` | sí |  | La cara. Obligatoria: sin ella esto es un párrafo centrado. |
-| `title` | `ReactNode` | sí |  |  |
+| `action` | `ReactNode` |  |  | The action that gets you out of the empty state. Usually a tertiary button. |
+| `basePath` | `string` |  |  | Where the brand PNGs are served from. |
+| `description` | `ReactNode` |  |  | One line explaining what is missing or what to do. |
+| `expression` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` |  |  | The face. Mandatory on `page` and impossible on `inline` — the props are a union, so the generated table cannot show a per-variant «req.» and the sentence has to carry it. Without it, `page` is a centred paragraph. |
+| `icon` | `ReactNode` |  |  | A glyph above the line. It measures 1em and inherits `currentColor`, like `Stat`'s: the project passes its own and sizes it, because the system has no icon library and is not getting one. |
+| `title` | `ReactNode` | yes |  |  |
+| `variant` | `"inline" \| "page"` |  |  | `page`, the default: the empty state IS the screen or the section, and it carries the face. `inline`: the hole inside a table or a widget. No face, and no way to pass one. |
 
 ### EventCalendar
 
-Fuente: `src/components/event-calendar/index.tsx`
+Source: `src/components/event-calendar/index.tsx`
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'div'>, 'onSelect' \| 'children'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'div'>, 'onSelect' \| 'children'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `emptyMessage` | `ReactNode` |  | `Nada en este día.` | Texto del panel cuando el día elegido no tiene nada. |
-| `events` | `readonly EventoCalendario[]` | sí |  |  |
-| `formatDay` | `(dia: Date) => string` |  | `(dia) => format(dia, "EEEE d de MMMM", { locale: es })` | Encabezado del panel. Por defecto, `es` de date-fns, como `Calendar`. |
-| `formatTime` | `(fecha: Date) => string` |  | `(fecha) => format(fecha, HH:mm, { locale: es })` |  |
-| `onCreateEvent` | `(evento: Omit<EventoCalendario, "id">) => void` |  |  | Sin él, la agenda es de solo lectura y no se pinta el formulario. |
+| `emptyMessage` | `ReactNode` |  | `Nada en este día.` | The panel's text when the chosen day has nothing on it. |
+| `events` | `readonly CalendarEvent[]` | yes |  |  |
+| `formatDay` | `(day: Date) => string` |  | `(day) => format(day, "EEEE d de MMMM", { locale: es })` | The panel's heading. Defaults to date-fns' `es`, like `Calendar`. |
+| `formatTime` | `(date: Date) => string` |  | `(date) => format(date, HH:mm, { locale: es })` |  |
+| `onCreateEvent` | `(event: Omit<CalendarEvent, "id">) => void` |  |  | Without it, the schedule is read-only and the form is not painted. |
 | `onDeleteEvent` | `(id: string) => void` |  |  |  |
-| `onSelectDay` | `(dia: Date) => void` |  |  |  |
-| `onUpdateEvent` | `(evento: EventoCalendario) => void` |  |  |  |
-| `selected` | `Date` |  |  | Día seleccionado, si el proyecto lo controla. Sin él, empieza en hoy. |
+| `onSelectDay` | `(day: Date) => void` |  |  |  |
+| `onUpdateEvent` | `(event: CalendarEvent) => void` |  |  |  |
+| `selected` | `Date` |  |  | Selected day, if the project controls it. Without it, it starts on today. |
 
 ### Footer, FooterLink
 
-Fuente: `src/components/footer/index.tsx`
+Source: `src/components/footer/index.tsx`
 
 **Footer**
-- Extiende: `ComponentPropsWithoutRef<'footer'>`
+- Extends: `ComponentPropsWithoutRef<'footer'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `brand` | `ReactNode` |  |  | La fila de marca: la aleta y el wordmark, arriba del todo. |
-| `social` | `readonly Red[]` |  |  |  |
-| `year` | `number` |  | `new Date().getFullYear()` | Año de la firma. |
+| `brand` | `ReactNode` |  |  | The brand row: the fin and the wordmark, at the very top. |
+| `social` | `readonly SocialLink[]` |  |  |  |
+| `year` | `number` |  | `new Date().getFullYear()` | The signature's year. |
 
 **FooterLink**
-- Extiende: `ComponentPropsWithoutRef<'a'>`
+- Extends: `ComponentPropsWithoutRef<'a'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `asChild` | `boolean \| undefined` |  | `false` |  |
 
 ### Hero
 
-Fuente: `src/components/hero/index.tsx`
+Source: `src/components/hero/index.tsx`
 
-UNO por sitio. Es la única pieza del sistema que se gasta como el botón de conversión, y por la misma razón: si hay dos, no hay ninguno.
+ONE per site. It is the only piece in the system that is spent like the conversion button, and for the same reason: if there are two, there are none.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'section'>, 'title'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'section'>, 'title'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `action` | `ReactNode` |  |  | Los botones. Aquí va el único `conversion` de la pantalla. |
+| `action` | `ReactNode` |  |  | The buttons. The screen's only `conversion` goes here. |
 | `basePath` | `string` |  |  |  |
 | `description` | `ReactNode` |  |  |  |
-| `eyebrow` | `ReactNode` |  |  | Mono, versalitas, en acento. |
-| `pose` | `"desk" \| "laptop-coffee" \| "peek" \| "surf"` |  |  | La pose de Tiburoncín. Sin ella el hero es un panel con texto. |
-| `title` | `ReactNode` | sí |  |  |
-| `variant` | `"cabecera" \| "centrado"` |  | `cabecera` | `cabecera` sangra la pose por la esquina; `centrado` la pone arriba y centra el texto, para una página que es solo esto. |
+| `eyebrow` | `ReactNode` |  |  | Mono, small caps, in accent. |
+| `pose` | `"desk" \| "laptop-coffee" \| "peek" \| "surf"` |  |  | Tiburoncín's pose. Without it the hero is a panel with text. |
+| `title` | `ReactNode` | yes |  |  |
+| `variant` | `"header" \| "centered"` |  | `header` | `header` bleeds the pose off the corner; `centered` puts it on top and centres the text, for a page that is only this. |
 
 ### LinkRow
 
-Fuente: `src/components/link-row/index.tsx`
+Source: `src/components/link-row/index.tsx`
 
-Migrado desde `links/src/components/Card.astro`. El original escalaba la tarjeta al 102 %, subía el título un píxel y giraba y agrandaba el icono en hover — cuatro movimientos que el sistema no permite. Aquí el hover cambia el borde y el color del icono, y nada más.
+Migrated from `links/src/components/Card.astro`. The original scaled the card to 102 %, lifted the title by a pixel and rotated and enlarged the icon on hover — four movements the system does not allow. Here the hover changes the border and the icon's color, and nothing else.
 
-- Extiende: `Omit<TarjetaProps, 'children'>`
+- Extends: `Omit<CardShellProps, 'children'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `asChild` | `boolean \| undefined` |  |  | Renderiza el hijo en vez de un `<a>`. Es como se enchufa el `Link` de Next o de Astro sin que la librería dependa de ningún enrutador. |
+| `asChild` | `boolean \| undefined` |  |  | Renders the child instead of an `<a>`. It is how Next's or Astro's `Link` plugs in without the library depending on any router. |
 | `description` | `ReactNode` |  |  |  |
-| `external` | `boolean \| undefined` |  | `false` | Marca el enlace como externo: añade la flecha y el `rel` seguro. |
-| `icon` | `ReactNode` |  |  | Glifo SVG del destino. Nunca un emoji. |
-| `name` | `ReactNode` | sí |  |  |
+| `external` | `boolean \| undefined` |  | `false` | Marks the link as external: adds the arrow and the safe `rel`. |
+| `icon` | `ReactNode` |  |  | The target's SVG glyph. Never an emoji. |
+| `name` | `ReactNode` | yes |  |  |
 
 ### Nav, NavItem
 
-Fuente: `src/components/nav/index.tsx`
+Source: `src/components/nav/index.tsx`
 
 **Nav**
-La barra del sitio: 64px, abismo al 86 % y desenfoque de 14px detrás.
+The site bar: 64px, abyss at 86 % and a 14px blur behind it — 56 when it shares the screen with a sidebar.
 
-- Extiende: `ComponentPropsWithoutRef<'header'>`
+- Extends: `ComponentPropsWithoutRef<'header'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `actions` | `ReactNode` |  |  | Acciones a la derecha: conversión, cambio de tema, buscar. |
-| `brand` | `ReactNode` |  |  | El logo, a la izquierda. |
+| `actions` | `ReactNode` |  |  | Actions on the right: conversion, theme switch, search. |
+| `brand` | `ReactNode` |  |  | The logo, on the left. |
+| `size` | `"compact" \| "default"` |  | `default` | `compact` is 56px instead of 64, for a bar that shares the screen with a sidebar: at 64 the two compete for the same corner and together they eat the top of the content area. |
 
 **NavItem**
-El `./` lo pone el componente, no quien lo usa.
+The `./` is put there by the component, not by whoever uses it.
 
-- Extiende: `ComponentPropsWithoutRef<'a'>`
+- Extends: `ComponentPropsWithoutRef<'a'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `active` | `boolean \| undefined` |  | `false` | Sección actual: bioluz con subrayado de 1px. |
-| `asChild` | `boolean \| undefined` |  | `false` | Renderiza el hijo en vez de un `<a>`, para el `Link` del enrutador. |
+| `active` | `boolean \| undefined` |  | `false` | Current section: biolume with a 1px underline. |
+| `asChild` | `boolean \| undefined` |  | `false` | Renders the child instead of an `<a>`, for the router's `Link`. |
 
 ### NewsletterForm
 
-Fuente: `src/components/newsletter-form/index.tsx`
+Source: `src/components/newsletter-form/index.tsx`
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'section'>, 'title' \| 'onSubmit'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'section'>, 'title' \| 'onSubmit'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
+| `aside` | `ReactNode` |  |  | The illustration, as a second column inside the panel. |
 | `basePath` | `string` |  |  |  |
 | `description` | `ReactNode` |  |  |  |
-| `disclaimer` | `ReactNode` |  |  | La letra pequeña. Es el «sin spam», y por eso admite cara. |
+| `disclaimer` | `ReactNode` |  |  | The small print. It is the «sin spam», which is why it accepts a face. |
 | `errorMessage` | `ReactNode` |  | `No se pudo suscribir ese correo. Revísalo y vuelve a intentar.` |  |
-| `expresion` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` |  |  |  |
+| `expression` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` |  |  |  |
+| `fieldErrors` | `{ name?: ReactNode; email?: ReactNode; }` |  |  | A message under one specific field, instead of the single alert. |
 | `fieldLabel` | `string` |  | `Correo electrónico` |  |
-| `nameField` | `boolean` |  | `false` | Añade el campo de nombre delante del correo. |
-| `nameInputProps` | `Omit<InputProps, "id" \| "disabled" \| "name">` |  |  | Lo que el proyecto necesite colgar del campo de nombre: `minLength`, `maxLength`, `pattern`. La librería no impone ninguna de las tres. |
+| `nameField` | `boolean` |  | `false` | Adds the name field ahead of the email one. |
+| `nameInputProps` | `Omit<InputProps, "id" \| "disabled" \| "name">` |  |  | Whatever the project needs to hang off the name field: `minLength`, `maxLength`, `pattern`. The library imposes none of the three. |
 | `nameLabel` | `string` |  | `Nombre` |  |
 | `namePlaceholder` | `string` |  | `Cómo te llamas` |  |
-| `onSubmitEmail` | `(email: string, name?: string \| undefined) => void` |  |  | Se dispara con el correo ya leído del campo, y con el nombre si el campo está puesto. |
-| `placeholder` | `string` |  | `tu@correo.dev` |  |
-| `state` | `"error" \| "reposo" \| "enviando" \| "exito"` |  | `reposo` |  |
+| `onFieldChange` | `(field: "email" \| "name", value: string) => void` |  |  | Fires when either field changes. It is where the project clears its error. |
+| `onSubmitEmail` | `(email: string, name?: string \| undefined) => void` |  |  | Fires with the email already read from the field, and with the name if that field is enabled. |
+| `placeholder` | `string` |  | `tu@email.dev` |  |
+| `resetOnSuccess` | `boolean` |  | `true` | Empties the fields after a successful subscription. On by default. |
+| `state` | `"success" \| "error" \| "idle" \| "sending"` |  | `idle` |  |
 | `submitLabel` | `string` |  | `Suscribirme` |  |
 | `successMessage` | `ReactNode` |  | `Ya estás dentro. Te llega un correo cada dos semanas, y nada más.` |  |
-| `title` | `ReactNode` | sí |  |  |
+| `title` | `ReactNode` | yes |  |  |
 
 ### PageHeader
 
-Fuente: `src/components/page-header/index.tsx`
+Source: `src/components/page-header/index.tsx`
 
-Una sola cabecera en dos escalas, no dos componentes.
+One header at two scales, not two components.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'header'>, 'title'> & VariantProps<typeof cabecera>`
+- Extends: `Omit<ComponentPropsWithoutRef<'header'>, 'title'> & VariantProps<typeof header>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `action` | `ReactNode` |  |  | Ranura para las llamadas a la acción. Si aquí va un botón de conversión, es el único de la pantalla. |
-| `as` | `"h2" \| "h1"` |  | `h1` | Nivel del titular. `h1` salvo que la página ya tenga uno. |
+| `action` | `ReactNode` |  |  | Slot for the calls to action. If a conversion button goes here, it is the only one on the screen. |
+| `as` | `"h1" \| "h2"` |  | `h1` | The headline's level. `h1` unless the page already has one. |
 | `description` | `ReactNode` |  |  |  |
-| `eyebrow` | `ReactNode` |  |  | Mono, versalitas, en acento. Es la sección a la que pertenece la página. |
+| `eyebrow` | `ReactNode` |  |  | Mono, small caps, in accent. It is the section the page belongs to. |
 | `size` | `"display" \| "page"` |  | `page` |  |
-| `title` | `ReactNode` | sí |  |  |
+| `title` | `ReactNode` | yes |  |  |
 
 ### ScrollingProgressBar
 
-Fuente: `src/components/scrolling-progress-bar/index.tsx`
+Source: `src/components/scrolling-progress-bar/index.tsx`
 
-Cuánto llevas leído. NO es `Progress` con otro nombre.
+How much you have read. It is NOT `Progress` under another name.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'div'>, 'children'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'div'>, 'children'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `sticky` | `boolean` |  | `true` | Pega la barra al borde superior de la ventana. |
-| `target` | `RefObject<HTMLElement \| null>` |  |  | El elemento que se mide. Sin él, el documento entero. |
-| `tone` | `"accent" \| "warm"` |  | `accent` | Arena en vez de bioluz, para igualar el progreso de curso. |
+| `sticky` | `boolean` |  | `true` | Pins the bar to the top edge of the window. |
+| `target` | `RefObject<HTMLElement \| null>` |  |  | The element being measured. Without it, the whole document. |
+| `tone` | `"accent" \| "warm"` |  | `accent` | Sand instead of biolume, to match course progress. |
 
-### SidebarItem, SidebarNav
+### SidebarItem, SidebarGroup, SidebarNav
 
-Fuente: `src/components/sidebar-nav/index.tsx`
+Source: `src/components/sidebar-nav/index.tsx`
 
 **SidebarItem**
-La barra lateral del admin del blog.
+The blog admin's sidebar.
 
-- Extiende: `ComponentPropsWithoutRef<'a'>`
+- Extends: `ComponentPropsWithoutRef<'a'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `active` | `boolean \| undefined` |  | `false` |  |
 | `asChild` | `boolean \| undefined` |  | `false` |  |
-| `badge` | `ReactNode` |  |  | Contador a la derecha: borradores pendientes, media sin usar. |
+| `badge` | `ReactNode` |  |  | Counter on the right: pending drafts, unused media. |
+| `icon` | `ReactNode` |  |  | The section's glyph, on the left. It REPLACES the `▸` rather than joining it, and it inherits `currentColor`, so it follows the item's state without being tinted separately. |
+
+**SidebarGroup**
+A labelled block of items — «Contenido», «Alumnos», «Ventas».
+
+- Extends: `Omit<ComponentPropsWithoutRef<'li'>, 'title'>`
+
+| prop | type | req. | default | what it does |
+| --- | --- | --- | --- | --- |
+| `label` | `ReactNode` | yes |  | The block's name. Sentence case, not a section title. |
 
 **SidebarNav**
-- Extiende: `ComponentPropsWithoutRef<'nav'>`
+- Extends: `ComponentPropsWithoutRef<'nav'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `branch` | `ReactNode` |  |  |  |
-| `version` | `ReactNode` |  |  | Versión y rama, al pie. |
+| `brand` | `ReactNode` |  |  | The row at the top: isotype and wordmark, `cursos · admin`. It is a slot and not a `logo`/`name` pair because every panel spells its own name differently, and the part that IS the system — the rhythm, the hairline under it — is here. |
+| `collapsed` | `boolean \| undefined` |  | `false` | Turns the sidebar into a rail: icons only, and the widths become the library's — `w-sidebar` and `w-sidebar-rail`. It is CONTROLLED and there is no uncontrolled mode, because this state is almost always persisted in a cookie or in `localStorage`, and an internal state would fight the one the project already keeps. |
+| `collapseLabel` | `string` |  | `Plegar el panel` | The toggle's accessible name, in the two directions. |
+| `expandLabel` | `string` |  | `Desplegar el panel` |  |
+| `mark` | `ReactNode` |  |  | What `brand` becomes in the rail. Usually the isotype with no wordmark. |
+| `onCollapsedChange` | `(collapsed: boolean) => void` |  |  | Called with what the state should become. With it, the toggle appears; with `collapsed` alone the sidebar is a rail with no way out of it, which is a legitimate layout and not an accident. |
+| `user` | `ReactNode` |  |  | Who is signed in, at the bottom above the version. A slot, because an avatar needs a session and a sign-out route and the library takes no project infrastructure — the same reason `Nav`'s user menu goes in `actions`. |
+| `version` | `ReactNode` |  |  | Version and branch, at the bottom. |
 
 ### Stat
 
-Fuente: `src/components/stat/index.tsx`
+Source: `src/components/stat/index.tsx`
 
-Una métrica grande: el número en la escala `stat` y su nombre debajo.
+A large metric: the number in the `stat` scale and its name underneath.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'div'>, 'title'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'div'>, 'title'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `description` | `ReactNode` |  |  | La bajada: el matiz que el número solo no da. «12 aplicaciones» no dice si son muchas, y aquí es donde se dice. |
-| `icon` | `ReactNode` |  |  | Glifo al lado del título, a 1em. Hereda `currentColor`, así que sigue al tono del título y no hay que teñirlo aparte. |
-| `label` | `ReactNode` | sí |  | Qué se está contando. Va en mono versalitas. |
-| `progress` | `number` |  |  | Con `progress`, la métrica se lee como avance y añade la barra. |
-| `tone` | `"neutral" \| "alerta"` |  | `neutral` | `alerta` solo cuando el número ES el problema. |
-| `value` | `ReactNode` | sí |  | El número, ya formateado. La librería no impone locale. |
+| `delta` | `StatDelta` |  |  | How the number moved since last time. |
+| `description` | `ReactNode` |  |  | The standfirst: the nuance the number alone does not give. «12 aplicaciones» does not say whether that is a lot, and this is where that gets said. |
+| `icon` | `ReactNode` |  |  | Glyph in a tinted circle, in the corner opposite the title. At 1em, and it inherits `currentColor` from the badge, so it takes the tone without being tinted separately. |
+| `label` | `ReactNode` | yes |  | What is being counted. It goes in mono small caps. |
+| `progress` | `number` |  |  | With `progress`, the metric reads as progress and adds the bar. |
+| `spark` | `ReactNode` |  |  | The number's shape over time, under it. A `ReactNode` and not a data prop: a sparkline needs a charting library, and this component lives in the barrel that four projects install. The one project that draws them passes its own, exactly like `icon`. |
+| `tone` | `"neutral" \| "alert" \| "achievement"` |  | `neutral` | `alert` ONLY when the number is the problem, and `achievement` when it is the opposite — the diplomas issued, the modules finished. The two paint the same sand today and they are still two names: a system that names by meaning cannot make «this is bad» the only way to say «this stands out». See `docs/decisions.md` § 28. |
+| `value` | `ReactNode` | yes |  | The number, already formatted. The library imposes no locale. |
 
 ### TalkCard
 
-Fuente: `src/components/talk-card/index.tsx`
+Source: `src/components/talk-card/index.tsx`
+
+A talk has more than one destination, and that is what shapes this type.
 
-- Extiende: `Omit<TarjetaProps, 'children' \| 'title'>`
+- Extends: `\| (Omit<CardShellProps, 'children' \| 'title'> & TalkContent & { /** The card is the link. Do not pass resources with this. */ resources?: never; }) \| (Omit<ComponentPropsWithoutRef<'article'>, 'title'> & TalkContent & { /** * Slides, repo, recording. They are the links, so the card stops being * one. */ resources: ReactNode; })`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `asChild` | `boolean \| undefined` |  |  | Renderiza el hijo en vez de un `<a>`. Es como se enchufa el `Link` de Next o de Astro sin que la librería dependa de ningún enrutador. |
 | `date` | `ReactNode` |  |  |  |
 | `dateTime` | `string` |  |  |  |
-| `description` | `ReactNode` |  |  | De qué iba la charla. Se corta a dos líneas, igual que el `excerpt` de `ArticleCard`, para que la rejilla no se desalinee. |
-| `event` | `ReactNode` | sí |  | Dónde se dio: la conferencia, el meetup, el equipo. |
+| `description` | `ReactNode` |  |  | What the talk was about. Clamped to two lines, same as `ArticleCard`'s `excerpt`, so the grid does not fall out of line. |
+| `event` | `ReactNode` | yes |  | Where it was given: the conference, the meetup, the team. |
 | `location` | `ReactNode` |  |  |  |
-| `status` | `ReactNode` |  |  | Etiqueta corta de estado: «con vídeo», «próxima», «solo audio». |
-| `title` | `ReactNode` | sí |  |  |
+| `resources` | `ReactNode` |  |  | The card is the link. Do not pass resources with this. Slides, repo, recording. They are the links, so the card stops being one. |
+| `status` | `ReactNode` |  |  | Short status label: «con vídeo», «próxima», «solo audio». |
+| `title` | `ReactNode` | yes |  |  |
 
 ### ThemeToggle
 
-Fuente: `src/components/theme-toggle/index.tsx`
+Source: `src/components/theme-toggle/index.tsx`
 
-El control que faltaba. La librería definía todo el sistema de temas y no exponía lo que lo cambia, así que dos proyectos lo reimplementaban.
+The control that was missing. The library defined the whole theming system and exposed nothing that changes it, so two projects were reimplementing it.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'button'>, 'onClick'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'button'>, 'onClick'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `label` | `string` |  | `Cambiar de tema` | Nombre accesible. El botón no tiene texto visible, así que es lo único que lo nombra. |
-| `onThemeChange` | `(tema: Tema) => void` |  |  | Se dispara con el tema que quedó puesto, por si el proyecto quiere anotarlo. |
-| `size` | `"sm" \| "md" \| "lg" \| "icon"` |  | `icon` |  |
-| `variant` | `"primary" \| "conversion" \| "secondary" \| "tertiary"` |  | `secondary` |  |
+| `label` | `string` |  | `Cambiar de tema` | Accessible name. The button has no visible text, so it is the only thing naming it. |
+| `onThemeChange` | `(theme: Theme) => void` |  |  | Fires with whichever theme ended up set, in case the project wants to record it. |
+| `size` | `"sm" \| "md" \| "lg" \| "icon" \| "icon-sm"` |  | `icon` |  |
+| `variant` | `"primary" \| "conversion" \| "secondary" \| "tertiary" \| "destructive" \| "destructiveOutline"` |  | `secondary` |  |
 
 ### TableOfContents
 
-Fuente: `src/components/toc/index.tsx`
+Source: `src/components/toc/index.tsx`
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'nav'>, 'children'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'nav'>, 'children'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `activeHref` | `string` |  |  | Ancla de la sección visible. |
-| `items` | `readonly Entrada[]` | sí |  |  |
+| `activeHref` | `string` |  |  | The anchor of the visible section. |
+| `items` | `readonly TocEntry[]` | yes |  |  |
 | `linkAsChild` | `(props: { href: string; children: ReactNode; }) => ReactNode` |  |  |  |
 
-## Marca
+## Brand
 
-Se importan de `@eduardoalvarez/arrecife` o `@eduardoalvarez/arrecife/brand`. 4 exportaciones.
+Imported from `@eduardoalvarez/arrecife` or `@eduardoalvarez/arrecife/brand`. 4 exports.
 
-### Isotipo
+### Isotype
 
-Fuente: `src/brand/isotipo.tsx`
+Source: `src/brand/isotype.tsx`
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'img'>, 'src' \| 'alt'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'img'>, 'src' \| 'alt'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `alt` | `string` |  |  | Texto alternativo. Vacío cuando el isotipo acompaña a un texto que ya lo nombra. |
-| `basePath` | `string` |  | `RUTA_ASSETS` |  |
-| `sobre` | `"oscuro" \| "claro"` |  | `oscuro` | Sobre qué fondo se monta. Es obligatorio decidirlo, aunque tenga default: el cuerpo de la aleta es casi negro, así que la variante de dos azules desaparece sobre abismo. Al ser una prop, la regla deja de ser algo que recordar. |
+| `alt` | `string` |  |  | Alt text. Empty when the isotype accompanies text that already names it. |
+| `background` | `"dark" \| "light"` |  | `dark` | Which background it sits on. Deciding is mandatory even though it has a default: the fin's body is nearly black, so the two-blue variant disappears over abyss. Being a prop, the rule stops being something to remember. |
+| `basePath` | `string` |  | `ASSETS_PATH` |  |
 
 ### Logo
 
-Fuente: `src/brand/logo.tsx`
+Source: `src/brand/logo.tsx`
 
-El wordmark sale de `naming.wordmark`, no de una cadena escrita a mano, y siempre dice «Eduardo Álvarez». La mascota se llama Tiburoncín y no aparece escrita dentro del logo: no hay ninguna prop que permita cambiar el texto.
+The wordmark comes from `naming.wordmark`, not from a hand-written string, and it always reads «Eduardo Álvarez». The mascot is called Tiburoncín and its name never appears inside the logo: there is no prop that changes the text.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'span'>, 'children'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'span'>, 'children'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `basePath` | `string` |  | `RUTA_ASSETS` |  |
-| `conLema` | `boolean \| undefined` |  | `false` | Añade el lema bajo el wordmark, separado de la aleta por una divisoria. |
-| `sobre` | `"oscuro" \| "claro"` |  | `oscuro` |  |
-| `soloIsotipo` | `boolean \| undefined` |  | `false` | Oculta el wordmark y deja solo la aleta, para barras muy estrechas. |
+| `background` | `"dark" \| "light"` |  | `dark` |  |
+| `basePath` | `string` |  | `ASSETS_PATH` |  |
+| `isotypeOnly` | `boolean \| undefined` |  | `false` | Hides the wordmark and leaves only the fin, for very narrow bars. |
+| `withTagline` | `boolean \| undefined` |  | `false` | Adds the tagline under the wordmark, separated from the fin by a divider. |
 
-### Mascota, CaraDeMascota
+### Mascot, MascotFace
 
-Fuente: `src/brand/mascota.tsx`
+Source: `src/brand/mascot.tsx`
+
+**Mascot**
+Full-body Tiburoncín.
+
+- Extends: `Base`
+
+| prop | type | req. | default | what it does |
+| --- | --- | --- | --- | --- |
+| `alt` | `string` |  |  | Alt text. Empty by default: the mascot is illustration and the text beside it already says what there is to know. Fill it in only when the image carries information that is not written next to it. |
+| `basePath` | `string` |  | `ASSETS_PATH` |  |
+| `pose` | `"desk" \| "laptop-coffee" \| "peek" \| "surf"` | yes |  |  |
 
-**Mascota**
-Tiburoncín de cuerpo entero.
+**MascotFace**
+Tiburoncín's head, with an expression.
 
-- Extiende: `Base`
+- Extends: `Base`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `alt` | `string` |  |  | Texto alternativo. Vacío por defecto: la mascota es ilustración y el texto que la acompaña ya dice lo que hay que saber. Se rellena solo cuando la imagen aporta información que no está escrita al lado. |
-| `basePath` | `string` |  | `RUTA_ASSETS` |  |
-| `pose` | `"desk" \| "laptop-coffee" \| "peek" \| "surf"` | sí |  |  |
+| `alt` | `string` |  |  | Alt text. Empty by default: the mascot is illustration and the text beside it already says what there is to know. Fill it in only when the image carries information that is not written next to it. |
+| `basePath` | `string` |  | `ASSETS_PATH` |  |
+| `expression` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` | yes |  |  |
+
+## Social icons
+
+Imported from `@eduardoalvarez/arrecife/social` · or grouped as `social` from the root. 9 exports.
+
+### GitHub, LinkedIn, X, Instagram, Discord, YouTube, Rss, Email, Newsletter
+
+Source: `src/social/index.tsx`
+
+**GitHub**
+- No own props: it passes through those of the element or primitive it wraps.
+
+**LinkedIn**
+- No own props: it passes through those of the element or primitive it wraps.
+
+**X**
+- No own props: it passes through those of the element or primitive it wraps.
 
-**CaraDeMascota**
-La cabeza de Tiburoncín, con expresión.
+**Instagram**
+- No own props: it passes through those of the element or primitive it wraps.
 
-- Extiende: `Base`
+**Discord**
+- No own props: it passes through those of the element or primitive it wraps.
 
-| prop | tipo | req. | defecto | qué hace |
+**YouTube**
+- No own props: it passes through those of the element or primitive it wraps.
+
+**Rss**
+- No own props: it passes through those of the element or primitive it wraps.
+
+**Email**
+- No own props: it passes through those of the element or primitive it wraps.
+
+**Newsletter**
+The newsletter. It plays the same role as `Rss` — a way to follow, not a social network — which is why it belongs in this catalogue and does not open the door to an icon library.
+
+- No own props: it passes through those of the element or primitive it wraps.
+
+## Icons
+
+Imported from `@eduardoalvarez/arrecife/icons` · requires `@phosphor-icons/react`. 1 exports.
+
+### Icon
+
+Source: `src/icons/index.tsx`
+
+- Extends: `Omit<PhosphorIconProps, 'size' \| 'weight' \| 'ref'>`
+
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `alt` | `string` |  |  | Texto alternativo. Vacío por defecto: la mascota es ilustración y el texto que la acompaña ya dice lo que hay que saber. Se rellena solo cuando la imagen aporta información que no está escrita al lado. |
-| `basePath` | `string` |  | `RUTA_ASSETS` |  |
-| `expresion` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` | sí |  |  |
+| `as` | `Icon` | yes |  | The Phosphor icon itself, passed as a component: `<Icon as={Books} />`. |
+| `label` | `string` |  |  | The accessible name. WITHOUT it the icon is decorative and gets `aria-hidden`, which is the right default: most icons sit beside their own label and announcing them twice is noise. |
+| `tone` | `"action" \| "current" \| "quiet"` |  | `action` | WHAT THE ICON IS DOING, which is what picks the weight. Three values, and there is no fourth: `action` is the default and the system's line, `current` is the one of a set you are on, `quiet` is furniture that is not a control. `weight` is deliberately not a prop — see `TONE_WEIGHT`. |
 
-## Formularios
+## Forms
 
-Se importan de `@eduardoalvarez/arrecife/form` · pide `react-hook-form`. 7 exportaciones.
+Imported from `@eduardoalvarez/arrecife/form` · requires `react-hook-form`. 7 exports.
 
 ### FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage, Form
 
-Fuente: `src/form/index.tsx`
+Source: `src/form/index.tsx`
 
 **FormField**
-Un campo controlado. Envuelve el `Controller` de RHF y además publica el nombre en contexto, que es de donde lo leen la etiqueta y el mensaje sin que haya que repetirlo tres veces.
+A controlled field. It wraps RHF's `Controller` and also publishes the name into context, which is where the label and the message read it from without having to repeat it three times.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **FormItem**
-La caja del campo: etiqueta, control, ayuda y mensaje, en columna.
+The field's box: label, control, help and message, in a column.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **FormLabel**
-La etiqueta NO se tiñe de rojo cuando el campo falla.
+The label is NOT tinted red when the field fails.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **FormControl**
-Envuelve al control y le cablea los atributos: el `id` que la etiqueta apunta, el `aria-describedby` con la ayuda y el mensaje, y el `aria-invalid`.
+Wraps the control and wires its attributes: the `id` the label points at, the `aria-describedby` with the help and the message, and the `aria-invalid`.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **FormDescription**
-La ayuda del campo. Se anuncia siempre, haya error o no.
+The field's help text. It is always announced, error or not.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **FormMessage**
-El mensaje de validación. Sin error no renderiza nada: un hueco reservado para el fallo desplaza el resto del formulario cada vez que aparece.
+The validation message. With no error it renders nothing: a gap reserved for the failure shifts the rest of the form every time it appears.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **Form**
-La capa que ata los controles a un formulario con validación y mensajes.
+The layer that ties the controls to a form with validation and messages.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
-## Gráficas
+## Charts
 
-Se importan de `@eduardoalvarez/arrecife/chart` · pide `recharts`. 5 exportaciones.
+Imported from `@eduardoalvarez/arrecife/chart` · requires `recharts`. 5 exports.
 
 ### ChartContainer, ChartTooltip, ChartLegend, ChartTooltipContent, ChartLegendContent
 
-Fuente: `src/chart/index.tsx`
+Source: `src/chart/index.tsx`
 
 **ChartContainer**
-Envuelve la gráfica en un `<figure>` con nombre accesible y le da a Recharts el alto concreto que necesita para medirse.
+Wraps the chart in a `<figure>` with an accessible name and gives Recharts the concrete height it needs to measure itself.
 
-- Extiende: `Omit<ComponentPropsWithoutRef<'figure'>, 'title'>`
+- Extends: `Omit<ComponentPropsWithoutRef<'figure'>, 'title'>`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `height` | `number` |  | `320` | Alto en píxeles. Recharts necesita uno concreto para medir. |
-| `label` | `string` | sí |  | Qué muestra la gráfica, en una frase. Obligatorio, como el `label` de `Progress`: un `<svg>` de barras sin nombre accesible no es «una gráfica sin etiqueta», es una región vacía. |
-| `summary` | `ReactNode` |  |  | Lo que la gráfica dice, en palabras. Va en un `figcaption` oculto visualmente. |
+| `height` | `number` |  | `320` | Height in pixels. Recharts needs a concrete one to measure itself. |
+| `label` | `string` | yes |  | What the chart shows, in one sentence. Mandatory, like `Progress`'s `label`: a bar `<svg>` with no accessible name is not «a chart without a label», it is an empty region. |
+| `summary` | `ReactNode` |  |  | What the chart says, in words. It goes in a visually hidden `figcaption`. |
 
 **ChartTooltip**
-El `Tooltip` de Recharts con los defectos del sistema: sin animación y con el cursor teñido de `surfaceRaised`.
+Recharts' `Tooltip` with the system's defaults: no animation, and the cursor tinted `surfaceRaised`.
 
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **ChartLegend**
-- Sin props propios: pasa los del elemento o la primitiva que envuelve.
+- No own props: it passes through those of the element or primitive it wraps.
 
 **ChartTooltipContent**
-La caja del tooltip. Es una tarjeta del sistema —`surface`, borde de control, sombra estándar— y no la caja blanca de Recharts, que en modo oscuro es un rectángulo blanco encima de un panel oscuro.
+The tooltip's box. It is a system card — `surface`, control border, standard shadow — and not Recharts' white box, which in dark mode is a white rectangle on top of a dark panel.
 
-- Extiende: `{ active?: boolean \| undefined; payload?: readonly ChartPayloadItem[] \| undefined; label?: ReactNode; /** Formatea el valor. Sin ella se imprime tal cual: la librería no impone locale. */ formatter?: ((valor: unknown, item: ChartPayloadItem) => ReactNode) \| undefined; /** Oculta el encabezado, para una gráfica de una sola categoría. */ hideLabel?: boolean; className?: string; }`
+- Extends: `{ active?: boolean \| undefined; payload?: readonly ChartPayloadItem[] \| undefined; label?: ReactNode; /** Formats the value. Without it, it is printed as is: the library imposes no locale. */ formatter?: ((value: unknown, item: ChartPayloadItem) => ReactNode) \| undefined; /** Hides the header, for a single-category chart. */ hideLabel?: boolean; className?: string; }`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `active` | `boolean \| undefined` |  |  |  |
 | `className` | `string` |  |  |  |
-| `formatter` | `(valor: unknown, item: ChartPayloadItem) => ReactNode` |  |  | Formatea el valor. Sin ella se imprime tal cual: la librería no impone locale. |
-| `hideLabel` | `boolean` |  | `false` | Oculta el encabezado, para una gráfica de una sola categoría. |
+| `formatter` | `(value: unknown, item: ChartPayloadItem) => ReactNode` |  |  | Formats the value. Without it, it is printed as is: the library imposes no locale. |
+| `hideLabel` | `boolean` |  | `false` | Hides the header, for a single-category chart. |
 | `label` | `ReactNode` |  |  |  |
 | `payload` | `readonly ChartPayloadItem[]` |  |  |  |
 
 **ChartLegendContent**
-La leyenda con la misma marca cuadrada del tooltip y la escala `label`.
+The legend, with the tooltip's same square swatch and the `label` scale.
 
-- Extiende: `{ payload?: readonly ChartPayloadItem[] \| undefined; className?: string; }`
+- Extends: `{ payload?: readonly ChartPayloadItem[] \| undefined; className?: string; }`
 
-| prop | tipo | req. | defecto | qué hace |
+| prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `className` | `string` |  |  |  |
 | `payload` | `readonly ChartPayloadItem[]` |  |  |  |
 
-## Exportaciones que no son componentes
+## Exports that are not components
 
-La raíz reexporta todo lo de `./tokens` y `./brand` por conveniencia. Cada uno
-aparece una sola vez, en la subruta más específica que lo publica: si el código
-no monta React, esa subruta es la que hay que importar.
+The root re-exports everything from `./tokens` and `./brand` for convenience.
+Each one appears exactly once, under the most specific subpath that publishes
+it: if the code does not mount React, that subpath is the one to import.
+
+### `@eduardoalvarez/arrecife/variants`
+
+| export | type | what it is |
+| --- | --- | --- |
+| `alertVariants` | `(props?: (ConfigVariants<{ variant: { accent: string; success: string; warning: string; error: string; }; emphasis: { subtle: string; strong: string; }; }> & ClassProp) \| undefined): string` |  |
+| `avatarVariants` | `(props?: (ConfigVariants<{ size: { sm: string; md: string; lg: string; xl: string; }; }> & ClassProp) \| undefined): string` |  |
+| `badgeVariants` | `(props?: (ConfigVariants<{ variant: { neutral: string; accent: string; warm: string; success: string; warning: string; error: string; }; }> & ClassProp) \| undefined): string` |  |
+| `buttonVariants` | `(props?: (ConfigVariants<{ variant: { primary: string[]; conversion: string; secondary: string[]; tertiary: string[]; destructive: string; destructiveOutline: string[]; }; size: { sm: string; md: string; lg: string; icon: string; 'icon-sm': string; }; }> & ClassProp) \| undefined): string` |  |
+| `CARD` | `string[]` |  |
+| `CARD_HOVER` | `"transition-standard hover:border-hairline-hover"` |  |
+| `CARD_SURFACE` | `"rounded-card border-hairline bg-surface border"` |  |
+| `categoryBadgeVariants` | `(props?: (ConfigVariants<{ active: { false: string; true: string; }; }> & ClassProp) \| undefined): string` |  |
+| `metricBadgeVariants` | `string[]` |  |
+| `textVariants` | `(props?: (ConfigVariants<{ variant: { display: string; stat: string; h1: string; h2: string; h3: string; body: string; lead: string; ui: string; label: string; tag: string; chip: string; meta: string; eyebrow: string; }; tone: { ...; }; }> & ClassProp) \| undefined): string` |  |
 
 ### `@eduardoalvarez/arrecife/tokens`
 
-| export | tipo | qué es |
+| export | type | what it is |
 | --- | --- | --- |
-| `brand` | `{ readonly body: "#3E7CB1"; readonly spots: "#C2D7E7"; readonly hull: "#0B1524"; }` | Marca — iguales en los dos modos. |
+| `brand` | `{ readonly body: "#3E7CB1"; readonly spots: "#C2D7E7"; readonly hull: "#0B1524"; }` | Brand — identical in both modes. |
 | `colors` | `{ dark, light }` |  |
-| `control` | `{ readonly sm: 14; readonly md: 22; readonly lg: 30; readonly icon: 42; }` | Controles, del documento: `sm 8/14 · md 12/22 · lg 15/30 · icono 42×42`. |
-| `dark` | `{ background, surface, surfaceRaised, border, hairline, hairlineHover, textPrimary, textSecondary, textMuted, accent, accentHover, accentOn, warm, warmHover, warmOn, success, warning, error }` | Modo oscuro (primario). Contrastes medidos sobre `background` #091319. |
+| `control` | `{ readonly sm: 14; readonly md: 22; readonly lg: 30; readonly icon: 42; readonly iconSm: 32; }` | Controls, from the document: `sm 8/14 · md 12/22 · lg 15/30 · icon 42×42`. |
+| `dark` | `{ background, surface, surfaceRaised, border, hairline, hairlineHover, textPrimary, textSecondary, textMuted, accent, accentHover, accentOn, warm, warmHover, warmOn, success, warning, error, danger, dangerHover, dangerOn }` | Dark mode (primary). Contrast measured against `background` #091319. |
 | `fonts` | `{ display, sans, mono }` |  |
 | `gradient` | `{ dark, light }` |  |
-| `light` | `{ background, surface, surfaceRaised, border, hairline, hairlineHover, textPrimary, textSecondary, textMuted, accent, accentHover, accentOn, warm, warmHover, warmOn, success, warning, error }` | Modo claro. Contrastes medidos sobre `background` #F6F2EA. `background` es blanco CÁLIDO: nunca #FFF como fondo de página. |
-| `limits` | `{ readonly minScreenPx: 13; readonly minPrintPt: 12; readonly measure: "68ch"; }` | Límites duros de legibilidad. |
-| `motion` | `{ readonly duration: "150ms"; readonly easing: "ease-out"; readonly properties: "color, background-color, border-color, fill, stroke"; }` | 150ms ease-out — solo color y borde. El sistema no anima posición ni escala: los estados se comunican con borde y color, no con movimiento. |
-| `naming` | `{ readonly wordmark: "Eduardo Álvarez"; readonly mascot: "Tiburoncín"; readonly domain: "eduardoalvarez.dev"; }` | El wordmark siempre dice «Eduardo Álvarez». La mascota se llama Tiburoncín y nunca aparece escrita dentro del logo. |
+| `light` | `{ background, surface, surfaceRaised, border, hairline, hairlineHover, textPrimary, textSecondary, textMuted, accent, accentHover, accentOn, warm, warmHover, warmOn, success, warning, error, danger, dangerHover, dangerOn }` | Light mode. Contrast measured against `background` #F6F2EA. `background` is WARM white: never #FFF as the page background. |
+| `limits` | `{ readonly minScreenPx: 13; readonly minPrintPt: 12; readonly measure: "68ch"; }` | Hard legibility limits. |
+| `motion` | `{ readonly duration: "150ms"; readonly easing: "ease-out"; readonly properties: "color, background-color, border-color, fill, stroke"; }` | 150ms ease-out — color and border only. The system animates neither position nor scale: states are communicated with border and color, not with movement. |
+| `naming` | `{ readonly wordmark: "Eduardo Álvarez"; readonly mascot: "Tiburoncín"; readonly domain: "eduardoalvarez.dev"; }` | The wordmark always reads «Eduardo Álvarez». The mascot is called Tiburoncín and its name never appears inside the logo. |
 | `radius` | `{ readonly chip: 6; readonly control: 10; readonly card: 14; readonly panel: 16; readonly pill: 999; }` |  |
-| `series` | `{ readonly dark: readonly ["#35D6C0", "#F2A65A", "#3E7CB1", "#71919C"]; readonly light: readonly ["#0D7C6F", "#A65B27", "#3E7CB1", "#626A75"]; }` | La paleta de series de las gráficas. CUATRO, por el mismo motivo que la de sintaxis: el sistema se comunica con color y borde, no con ruido cromático. |
-| `shadow` | `{ readonly standard: "0 1px 2px rgba(0, 0, 0, 0.35)"; }` | Un solo nivel. No hay escala de elevación. |
-| `sintaxis` | `{ fondo, identificador, literal, palabraClave, comentario, invalido }` | La paleta del resaltado de sintaxis. |
-| `size` | `{ readonly nav: 64; readonly content: 760; readonly wide: 1180; }` |  |
-| `spacing` | `{ readonly stepXs: 8; readonly stepSm: 12; readonly stepMd: 16; readonly stepLg: 26; readonly stepXl: 40; readonly section: 96; }` | El ritmo de página. Los cinco escalones llevan `step` en el nombre, y no es decoración: es la corrección de un bug que no dio la cara en ningún sitio. |
-| `tagline` | `{ largo, corto, en }` |  |
-| `tokens` | `{ colors, brand, fonts, typeScale, limits, radius, control, spacing, size, gradient, sintaxis, series, shadow, motion, tagline, naming }` | Todos los tokens en un solo objeto, para plantillas Satori y generadores. |
+| `series` | `{ readonly dark: readonly ["#35D6C0", "#F2A65A", "#3E7CB1", "#71919C"]; readonly light: readonly ["#0D7C6F", "#A65B27", "#3E7CB1", "#626A75"]; }` | The chart series palette. FOUR, for the same reason as the syntax palette: the system communicates with color and border, not with chromatic noise. |
+| `shadow` | `{ readonly standard: "0 1px 2px rgba(0, 0, 0, 0.35)"; }` | A single level. There is no elevation scale. |
+| `size` | `{ readonly nav: 64; readonly navCompact: 56; readonly sidebar: 256; readonly sidebarRail: 56; readonly content: 760; readonly wide: 1180; }` |  |
+| `spacing` | `{ readonly stepXs: 8; readonly stepSm: 12; readonly stepMd: 16; readonly stepLg: 26; readonly stepXl: 40; readonly section: 96; }` | Page rhythm. All five steps carry `step` in the name, and that is not decoration: it is the fix for a bug that never surfaced anywhere. |
+| `syntax` | `{ background, identifier, literal, keyword, comment, invalid }` | The syntax highlighting palette. |
+| `tagline` | `{ long, short, en }` |  |
+| `tokens` | `{ colors, brand, fonts, typeScale, limits, radius, control, spacing, size, gradient, syntax, series, shadow, motion, tagline, naming }` | Every token in a single object, for Satori templates and generators. |
 | `typeScale` | `{ display, stat, h1, h2, h3, body, lead, ui, label, tag, chip, meta, eyebrow }` |  |
 
-Tipos (13): `BrandToken`, `ColorMode`, `ColorToken`, `ControlToken`, `FontToken`, `GradientToken`, `RadiusToken`, `SeriesToken`, `SintaxisToken`, `SizeToken`, `SpacingToken`, `Tokens`, `TypeScaleToken`.
+Types (13): `BrandToken`, `ColorMode`, `ColorToken`, `ControlToken`, `FontToken`, `GradientToken`, `RadiusToken`, `SeriesToken`, `SizeToken`, `SpacingToken`, `SyntaxToken`, `Tokens`, `TypeScaleToken`.
+
+### `@eduardoalvarez/arrecife/social`
+
+Types (1): `SocialIconProps`.
+
+### `@eduardoalvarez/arrecife/theme`
+
+| export | type | what it is |
+| --- | --- | --- |
+| `applyTheme` | `(theme: Theme, persist?: boolean): void` | Sets the theme on `<html>` and persists it. |
+| `currentTheme` | `(): Theme` | The theme currently in place, read from the DOM. |
+| `preferredTheme` | `({ base }?: ThemeOptions): Theme` | The theme that applies: whatever was chosen, and with no choice, `base` if the site declared one, else whatever the system asks for. With no `prefers-color-scheme` declared, dark, which is primary. |
+| `storedTheme` | `(): Theme \| null` | The stored preference, if any. `null` means «nobody has chosen», which is not the same as «chose dark»: with no choice, the system decides. |
+| `THEME_ATTRIBUTE` | `"data-theme"` | The attribute the `[data-theme]` blocks in `theme.css` read. |
+| `THEME_EVENT` | `"arrecife:theme"` | The event emitted when the theme changes. |
+| `THEME_KEY` | `"arrecife-theme"` | The `localStorage` key. |
+| `themeScript` | `({ base }?: ThemeOptions): string` | The script that goes INLINE in the `<head>`, before any stylesheet. |
+| `toggleTheme` | `(): Theme` | Switches to the opposite one and returns whichever stuck. |
+| `watchTheme` | `(onChange: (theme: Theme) => void, options?: ThemeOptions): () => void` | Subscribes to theme changes and returns the function that cancels it. |
+
+Types (2): `Theme`, `ThemeOptions`.
 
 ### `@eduardoalvarez/arrecife/brand`
 
-| export | tipo | qué es |
+| export | type | what it is |
 | --- | --- | --- |
-| `aletas` | `{ readonly color: "fin.png"; readonly espuma: "fin-foam.png"; }` | La aleta, en sus dos variantes. |
-| `caras` | `{ annoyed, confused, hearts, laughing, shades, waiting, wink }` | Las caras. Solo se usan en estados vacíos, confirmaciones, errores, progreso de curso y celebración — nunca en hero, precios, servicios, contacto ni CV. Por eso `EmptyState` recibe una cara y `PageHeader` no. |
-| `listaCaras` | `readonly ("annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink")[]` |  |
-| `listaPoses` | `readonly ("desk" \| "laptop-coffee" \| "peek" \| "surf")[]` |  |
-| `poses` | `{ readonly desk: "pose-desk.png"; readonly 'laptop-coffee': "pose-laptop-coffee.png"; readonly peek: "pose-peek.png"; readonly surf: "pose-surf.png"; }` | Poses de cuerpo entero. |
-| `RUTA_ASSETS` | `"/brand"` | Dónde se sirven los PNG. Por defecto `/brand`, que es donde ya viven en los cinco proyectos (`public/brand/`), así que no hay nada que configurar. |
-| `usoDeCara` | `{ wink, waiting, laughing, shades, hearts, confused, annoyed }` | El uso asignado de cada cara, del inventario del manual. |
+| `ASSETS_PATH` | `"/brand"` | Where the PNGs are served from. `/brand` by default, which is where they already live in all five projects (`public/brand/`), so there is nothing to configure. |
+| `faceList` | `readonly ("annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink")[]` |  |
+| `faces` | `{ annoyed, confused, hearts, laughing, shades, waiting, wink }` | The faces. They are used only in empty states, confirmations, errors, course progress and celebration — never in a hero, pricing, services, contact or CV. That is why `EmptyState` takes a face and `PageHeader` does not. |
+| `faceUsage` | `{ wink, waiting, laughing, shades, hearts, confused, annoyed }` | The assigned use of each face, from the manual's inventory. |
+| `fins` | `{ readonly color: "fin.png"; readonly foam: "fin-foam.png"; }` | The fin, in its two variants. |
+| `poseList` | `readonly ("desk" \| "laptop-coffee" \| "peek" \| "surf")[]` |  |
+| `poses` | `{ readonly desk: "pose-desk.png"; readonly 'laptop-coffee': "pose-laptop-coffee.png"; readonly peek: "pose-peek.png"; readonly surf: "pose-surf.png"; }` | Full-body poses. |
 
-Tipos (8): `Aleta`, `Cara`, `CaraDeMascotaProps`, `Fondo`, `IsotipoProps`, `LogoProps`, `MascotaProps`, `Pose`.
+Types (8): `Background`, `Face`, `Fin`, `IsotypeProps`, `LogoProps`, `MascotFaceProps`, `MascotProps`, `Pose`.
 
-### `@eduardoalvarez/arrecife/shiki`
+### `@eduardoalvarez/arrecife/icons`
 
-| export | tipo | qué es |
+| export | type | what it is |
 | --- | --- | --- |
-| `arrecife` | `TemaShiki` |  |
+| `ICON_WEIGHT` | `"light" \| "fill" \| "thin" \| "regular" \| "bold" \| "duotone"` | Phosphor's own name for the system's line. It is what `tone="action"` resolves to. |
+| `TONE_WEIGHT` | `Record<IconTone, IconWeight>` | The three roles, and the weight each one is drawn at. This is the whole of the weight axis: Phosphor ships six and this system reads three, because the other three — `thin`, `bold`, `duotone` — have no role behind them here. |
 
-Tipos (1): `TemaShiki`.
+Types (2): `IconProps`, `IconTone`.
 
-### `@eduardoalvarez/arrecife/chart`
+### `@eduardoalvarez/arrecife/shiki`
 
-| export | tipo | qué es |
+| export | type | what it is |
 | --- | --- | --- |
-| `colorDeSerie` | `(indice: number): string` | El color de la serie `indice`, como custom property. |
-| `COLORES_DE_SERIE` | `string[]` | Las cuatro, en orden, para pasárselas de golpe a un `Pie` con `Cell`. |
+| `arrecife` | `ShikiTheme` |  |
 
-Tipos (4): `ChartContainerProps`, `ChartLegendContentProps`, `ChartPayloadItem`, `ChartTooltipContentProps`.
+Types (1): `ShikiTheme`.
 
-### `@eduardoalvarez/arrecife/tema`
+### `@eduardoalvarez/arrecife/chart`
 
-| export | tipo | qué es |
+| export | type | what it is |
 | --- | --- | --- |
-| `alternarTema` | `(): Tema` | Cambia al contrario y devuelve el que quedó. |
-| `aplicarTema` | `(tema: Tema, persistir?: boolean): void` | Pone el tema en el `<html>` y lo persiste. |
-| `escucharTema` | `(alCambiar: (tema: Tema) => void): () => void` | Se suscribe a los cambios de tema y devuelve la función que cancela. |
-| `scriptTema` | `string` | El script que va INLINE en el `<head>`, antes de cualquier hoja de estilo. |
-| `TEMA_ATRIBUTO` | `"data-theme"` | El atributo que leen los bloques `[data-theme]` de `theme.css`. |
-| `TEMA_CLAVE` | `"arrecife-tema"` | La clave de `localStorage`. |
-| `TEMA_EVENTO` | `"arrecife:tema"` | El evento que se emite cuando el tema cambia. |
-| `temaActual` | `(): Tema` | El tema que hay puesto ahora mismo, leído del DOM. |
-| `temaGuardado` | `(): Tema \| null` | La preferencia guardada, si la hay. `null` significa «nadie ha elegido», que no es lo mismo que «eligió oscuro»: sin elección manda el sistema. |
-| `temaPreferido` | `(): Tema` | El tema que corresponde: lo elegido, y si no hay elección, lo que pida el sistema. Sin `prefers-color-scheme` declarado, oscuro, que es el primario. |
-
-Tipos (1): `Tema`.
+| `SERIES_COLORS` | `string[]` | All four, in order, to hand to a `Pie` with `Cell` in one go. |
+| `seriesColor` | `(index: number): string` | The color of series `index`, as a custom property. |
+
+Types (4): `ChartContainerProps`, `ChartLegendContentProps`, `ChartPayloadItem`, `ChartTooltipContentProps`.
 
 ### `@eduardoalvarez/arrecife/form`
 
-| export | tipo | qué es |
+| export | type | what it is |
 | --- | --- | --- |
-| `useFormField` | `(): { invalid: boolean; isDirty: boolean; isTouched: boolean; isValidating: boolean; error?: FieldError; name: string; id: string; idDescripcion: string; idMensaje: string; }` | Lo que necesita cualquier pieza del campo: el nombre, los tres ids y el estado de validación. |
+| `useFormField` | `(): { invalid: boolean; isDirty: boolean; isTouched: boolean; isValidating: boolean; error?: FieldError; name: string; id: string; descriptionId: string; messageId: string; }` | What any piece of the field needs: the name, the three ids and the validation state. |
 
 ### `@eduardoalvarez/arrecife/og`
 
-| export | tipo | qué es |
+| export | type | what it is |
 | --- | --- | --- |
-| `OG` | `{ readonly width: 1200; readonly height: 630; readonly margen: 64; readonly mascota: 430; readonly aletaFirma: 34; readonly reservaMascota: 560; }` | El lienzo y la retícula. Son las medidas de producción. |
-| `plantillaArticulo` | `(datos: DatosArticulo): NodoSatori` | Artículo · degradado 145° sobre abismo, categoría y lectura en arena. |
-| `plantillaBase` | `(opciones: { modo: "oscuro" \| "claro"; fondo: string; eyebrow: { texto: string; color: string; }; title: string; bajada?: string \| undefined; firma: string; firmaColor: string; base: string; mascota?: NodoSatori \| null \| undefined; mascotaIzquierda?: boolean \| undefined; tinta: string; tintaSecundaria: string; }): NodoSatori` |  |
-| `plantillaCharla` | `(datos: DatosCharla): NodoSatori` | Charla · eyebrow en bioluz con evento y año, pose sangrando por la esquina. |
-| `plantillaCurso` | `(datos: DatosCurso): NodoSatori` | Curso · LA ÚNICA PLANTILLA EN CLARO. |
-| `plantillaDefecto` | `(datos?: DatosDefecto): NodoSatori` | Por defecto · la excepción declarada del documento. |
+| `articleTemplate` | `(data: ArticleData): SatoriNode` | Article · 145° gradient over abyss, category and reading time in sand. |
+| `courseTemplate` | `(data: CourseData): SatoriNode` | Course · THE ONLY LIGHT TEMPLATE. |
+| `defaultTemplate` | `(data?: DefaultData): SatoriNode` | Default · the document's declared exception. |
+| `OG` | `{ readonly width: 1200; readonly height: 630; readonly margin: 64; readonly mascot: 430; readonly signatureFin: 34; readonly mascotReserve: 560; }` | The canvas and the grid. These are the production measurements. |
+| `plantillaBase` | `(options: { mode: "dark" \| "light"; background: string; eyebrow: { text: string; color: string; }; title: string; bajada?: string \| undefined; signature: string; firmaColor: string; base: string; mascot?: SatoriNode \| ... 1 more ... \| undefined; mascotaIzquierda?: boolean \| undefined; tinta: string; tintaSecundaria: string; }): SatoriNode` |  |
+| `talkTemplate` | `(data: TalkData): SatoriNode` | Talk · eyebrow in biolume with the event and year, pose bleeding off the corner. |
 
-Tipos (6): `DatosArticulo`, `DatosBase`, `DatosCharla`, `DatosCurso`, `DatosDefecto`, `NodoSatori`.
+Types (6): `ArticleData`, `BaseData`, `CourseData`, `DefaultData`, `SatoriNode`, `TalkData`.
 
 ### `@eduardoalvarez/arrecife`
 
-| export | tipo | qué es |
+| export | type | what it is |
 | --- | --- | --- |
-| `alertVariants` | `(props?: (ConfigVariants<{ variant: { accent: string; success: string; warning: string; error: string; }; enfasis: { sutil: string; fuerte: string; }; }> & ClassProp) \| undefined): string` |  |
-| `avatarVariants` | `(props?: (ConfigVariants<{ size: { sm: string; md: string; lg: string; xl: string; }; }> & ClassProp) \| undefined): string` |  |
-| `badgeVariants` | `(props?: (ConfigVariants<{ variant: { neutral: string; accent: string; warm: string; success: string; warning: string; error: string; }; }> & ClassProp) \| undefined): string` |  |
-| `buttonVariants` | `(props?: (ConfigVariants<{ variant: { primary: string[]; conversion: string; secondary: string[]; tertiary: string[]; }; size: { sm: string; md: string; lg: string; icon: string; }; }> & ClassProp) \| undefined): string` |  |
-| `categoryBadgeVariants` | `(props?: (ConfigVariants<{ active: { false: string; true: string; }; }> & ClassProp) \| undefined): string` |  |
 | `cn` | `(...inputs: ClassValue[]): string` |  |
-| `HOVER_TARJETA` | `"transition-standard hover:border-hairline-hover"` | El hover de la regla 6: solo el borde. Se aplica donde la tarjeta es pulsable. |
-| `social` | `typeof import("src/lib/social")` |  |
-| `SUPERFICIE_TARJETA` | `"rounded-card border-hairline bg-surface border"` | El contenedor de superficie del sistema, y la única definición de lo que es una tarjeta: `surface`, borde `hairline`, radio de tarjeta. |
-| `textVariants` | `(props?: (ConfigVariants<{ variant: { display: string; stat: string; h1: string; h2: string; h3: string; body: string; lead: string; ui: string; label: string; tag: string; chip: string; meta: string; eyebrow: string; }; tone: { ...; }; }> & ClassProp) \| undefined): string` |  |
-| `toast` | `(mensaje: ReactNode, opciones?: ToastOptions \| undefined): string` | Lanza un aviso. Devuelve su id, que es lo que hay que guardar para cerrarlo a mano —el caso de «guardando…» que se reemplaza cuando termina la petición. |
-| `useTema` | `(): Tema` | El tema puesto ahora mismo, para un proyecto que necesite ramificar en React —un logo distinto por modo, una imagen que no tiene versión clara—. |
-
-Tipos (60): `AccordionProps`, `AccordionTriggerProps`, `AlertProps`, `ArticleCardProps`, `AudioPlayerMode`, `AudioPlayerProps`, `AuthorCardProps`, `AvatarProps`, `AvatarUploadProps`, `BadgeProps`, `BlockquoteProps`, `BreadcrumbProps`, `ButtonProps`, `CalendarProps`, `CategoryBadgeProps`, `CheckboxProps`, `CodeBlockProps`, `CodeProps`, `CourseCardProps`, `DateFieldProps`, `EmptyStateProps`, `Entrada`, `EventCalendarProps`, `EventoCalendario`, `FooterLinkProps`, `FooterProps`, `HeroProps`, `InputProps`, `LabelProps`, `LinkRowProps`, `MetricBadgeProps`, `Migaja`, `NavItemProps`, `NavProps`, `NewsletterFormProps`, `NewsletterState`, `PageHeaderProps`, `PaginationLinkProps`, `PopoverContentProps`, `ProgressProps`, `RadioGroupItemProps`, `RadioGroupProps`, `Red`, `ScrollingProgressBarProps`, `SeparatorProps`, `SheetContentProps`, `SidebarItemProps`, `SidebarNavProps`, `SkeletonProps`, `StatProps`, `SwitchProps`, `TableOfContentsProps`, `TabsProps`, `TalkCardProps`, `TextProps`, `TextareaProps`, `ThemeToggleProps`, `ToastOptions`, `ToastVariant`, `ToasterProps`.
-
-# Dónde mirar si esto no basta
-
-- Storybook publica cada componente con sus stories y la tabla de props generada
-  desde los tipos.
-- `README.md` del repo: el porqué de cada decisión, la tabla de correcciones de
-  contraste y el ciclo de publicación.
-- `docs/design-system.md` y `docs/manual-de-marca.md`: los documentos de
-  identidad, consultables con `grep`.
-- `docs/decisiones.md`: los quince puntos donde el código y el documento no
-  decían lo mismo, con la resolución de cada uno.
-- `AGENTS.md`: para trabajar dentro del repo de la librería.
+| `social` | `typeof import("src/social/index")` |  |
+| `toast` | `(message: ReactNode, options?: ToastOptions \| undefined): string` | Fires a notice. It returns its id, which is what you keep in order to close it by hand — the «guardando…» case that gets replaced when the request finishes. |
+| `useTheme` | `(): Theme` | The theme set right now, for a project that needs to branch in React — a different logo per mode, an image with no light version. |
+
+Types (62): `AccordionProps`, `AccordionTriggerProps`, `AlertProps`, `ArticleCardProps`, `AudioPlayerMode`, `AudioPlayerProps`, `AuthorCardProps`, `AvatarProps`, `AvatarUploadProps`, `BadgeProps`, `BlockquoteProps`, `BreadcrumbProps`, `ButtonProps`, `CalendarEvent`, `CalendarProps`, `CategoryBadgeProps`, `CheckboxProps`, `CodeBlockProps`, `CodeProps`, `CourseCardProps`, `Crumb`, `DateFieldProps`, `EmptyStateProps`, `EventCalendarProps`, `FooterLinkProps`, `FooterProps`, `HeroProps`, `InputProps`, `LabelProps`, `LinkRowProps`, `MetricBadgeProps`, `NavItemProps`, `NavProps`, `NewsletterFormProps`, `NewsletterState`, `PageHeaderProps`, `PaginationLinkProps`, `PopoverContentProps`, `ProgressProps`, `RadioGroupItemProps`, `RadioGroupProps`, `ScrollingProgressBarProps`, `SeparatorProps`, `SheetContentProps`, `SidebarGroupProps`, `SidebarItemProps`, `SidebarNavProps`, `SkeletonProps`, `SocialLink`, `StatDelta`, `StatProps`, `SwitchProps`, `TableOfContentsProps`, `TabsProps`, `TalkCardProps`, `TextProps`, `TextareaProps`, `ThemeToggleProps`, `ToastOptions`, `ToastVariant`, `ToasterProps`, `TocEntry`.
+
+# Where to look if this is not enough
+
+- Storybook publishes every component with its stories and the props table
+  generated from the types.
+- The repo's `README.md`: the reasoning behind each decision, the contrast
+  correction table and the release cycle.
+- `docs/design-system.md` and `docs/brand-manual.md`: the identity documents,
+  greppable.
+- `docs/decisions.md`: the points where the code and the document did not say the
+  same thing, each with its resolution.
+- `AGENTS.md`: for working inside the library's repo.