@eduardoalvarez/arrecife 0.5.1 → 0.7.0

package/README.md

@@ -1,151 +1,224 @@
 # Arrecife
 
-Librería de componentes de la identidad visual de Eduardo Álvarez.
+The component library of Eduardo Álvarez's visual identity.
 `@eduardoalvarez/arrecife` · React 19 · TypeScript · shadcn/ui · Storybook · tsup.
 
-## Los documentos de identidad
+Published Storybook: [arrecife.eduardoalvarez.dev](https://arrecife.eduardoalvarez.dev).
 
-`docs/design-system.md` y `docs/manual-de-marca.md` son la extracción de los dos
-canvas de Claude Design, en el repo para poder hacer `grep` y para versionarlos.
-El canvas sigue siendo la fuente; esto es la copia consultable.
+## The identity documents
 
-Está aquí por un motivo concreto: la paleta de resaltado vivía escrita a mano en
-un proyecto con un `#E05252` que este README declara incorrecto desde hace
-meses, y nadie lo vio porque el documento no era `grep`-able desde el código.
+`docs/design-system.md` and `docs/brand-manual.md` are the extraction of the two
+Claude Design canvases, kept in the repo so they can be grepped and versioned.
+The canvas is still the source; this is the consultable copy.
 
-`docs/decisiones.md` es la otra mitad: los quince puntos donde el código y el
-documento no dicen lo mismo, con la resolución y el motivo de cada uno.
+They are here for a concrete reason: the highlighting palette lived hand-written
+in a project with a `#E05252` that this README has declared wrong for months, and
+nobody saw it because the document was not greppable from the code.
 
-## Los dos documentos para agentes
+`docs/decisions.md` is the other half: the points where the code and the document
+do not say the same thing, each with its resolution and its reason.
 
-`AGENTS.md` es para un agente que trabaja **en este repo**: cómo se crea un
-componente, qué reglas no puede romper y dónde se verifica cada una. `CLAUDE.md`
-es un symlink a ese archivo, así que Claude, Codex y Cursor leen el mismo texto.
+## The two documents for agents
 
-`llms.txt` es para un agente que trabaja en uno de los **cinco proyectos que
-consumen** la librería. Ese agente nunca ve este repo: ve
-`node_modules/@eduardoalvarez/arrecife/`, y por eso `llms.txt` viaja en el
-tarball y se declara en `exports`.
+`AGENTS.md` is for an agent working **in this repo**: how a component is created,
+which rules it cannot break and where each one is verified. `CLAUDE.md` is a
+symlink to that file, so Claude, Codex and Cursor all read the same text.
 
-El inventario de componentes y props de `llms.txt` no está escrito a mano: lo
-extrae `scripts/build-llms.mjs` del compilador de TypeScript, y `pnpm check:llms`
-falla en CI si alguien cambia un prop y no lo regenera. La prosa vive en
-`docs/llms.plantilla.md`. Es la misma decisión que los tokens: una fuente, una
-salida generada, y un check que impide que discrepen.
+`llms.txt` is for an agent working in one of the **five projects that consume**
+the library. That agent never sees this repo: it sees
+`node_modules/@eduardoalvarez/arrecife/`, which is why `llms.txt` travels in the
+tarball and is declared in `exports`.
 
-## La restricción que manda sobre todo lo demás
+The component and prop inventory in `llms.txt` is not written by hand:
+`scripts/build-llms.mjs` extracts it from the TypeScript compiler, and
+`pnpm check:llms` fails in CI if somebody changes a prop and does not regenerate
+it. The prose lives in `docs/llms.template.md`. It is the same decision as the
+tokens: one source, a generated output, and a check that stops them disagreeing.
 
-`src/tokens/` no importa nada: ni React, ni componentes, ni CSS de terceros. Es el
-único subpaquete que pueden consumir los cinco proyectos, incluido un generador
-de OG con Satori y un sitio Astro que no monta React. Si un token termina
-dependiendo de un componente, la librería dejó de ser portable.
+## The constraint that outranks everything else
 
-No es documentación: `pnpm check:tokens` lo verifica en cada build y ESLint lo
-dice en el editor.
+`src/tokens/` imports nothing: not React, not components, not third-party CSS. It
+is the only subpackage the five projects can all consume, including an OG
+generator running on Satori and an Astro site that mounts no React. The moment a
+token depends on a component, the library has stopped being portable.
 
-## Salida de Tailwind
+It is not documentation: `pnpm check:tokens` verifies it on every build and
+ESLint says so in the editor.
 
-Una sola fuente, `src/tokens/tokens.ts`. Una salida generada,
-`dist/tokens/theme.css`, con `@theme` para Tailwind v4. La genera
-`scripts/build-tokens.mjs`; no se edita a mano y se regenera en cada build.
+## Tailwind output
 
-Decisión de la Fase 0: **solo v4**. El portfolio (`eduardoalvarez.dev`) migra de
-Tailwind v3 a v4 antes de consumir Arrecife. Si esa migración se atrasa, volver a
-publicar el preset de v3 es añadir un emisor más a `build-tokens.mjs` que lea el
-mismo objeto `tokens`: la fuente no cambia.
+One source, `src/tokens/tokens.ts`. One generated output,
+`dist/tokens/theme.css`, with `@theme` for Tailwind v4. It is generated by
+`scripts/build-tokens.mjs`; it is not edited by hand and it is regenerated on
+every build.
 
-### Consumo
+Phase 0 decision: **v4 only**. The portfolio (`eduardoalvarez.dev`) migrates from
+Tailwind v3 to v4 before consuming Arrecife. If that migration slips, publishing
+the v3 preset again is one more emitter in `build-tokens.mjs` reading the same
+`tokens` object: the source does not change.
+
+### Consuming it
 
 ```css
 @import "tailwindcss";
 @import "@eduardoalvarez/arrecife/tokens/theme.css";
 ```
 
-El modo oscuro es el primario y es el default. Un proyecto en modo claro declara
-`data-theme="light"` en `<html>`; uno oscuro no necesita declarar nada.
+Dark mode is primary and it is the default. A project in light mode declares
+`data-theme="light"` on `<html>`; a dark one declares nothing.
 
-**Si además vas a usar componentes, falta una línea, y sin ella no falla nada.**
-Tailwind no escanea `node_modules`, así que purga todas las clases que emiten los
-componentes: `border-hairline`, `rounded-pill` y `p-step-lg` resuelven a la nada.
-No hay error en consola, no hay aviso en el build, no hay clase sin definir — la
-tarjeta simplemente sale con borde `currentColor` y la píldora, cuadrada.
+**If you are also going to use components, one line is missing, and without it
+nothing fails.** Tailwind does not scan `node_modules`, so it purges every class
+the components emit: `border-hairline`, `rounded-pill` and `p-step-lg` resolve to
+nothing. There is no console error, no build warning, no undefined class — the
+card simply comes out with a `currentColor` border and the pill comes out square.
 
 ```css
 @import "tailwindcss";
 @import "@eduardoalvarez/arrecife/tokens/theme.css";
 
-/* Sin esto, los componentes se montan sin ningún estilo del sistema. */
+/* Without this, the components mount with none of the system's styles. */
 @source "../node_modules/@eduardoalvarez/arrecife/dist";
 ```
 
-La ruta es relativa al archivo CSS donde va la directiva, así que en un proyecto
-con la hoja en `src/styles/` sube dos niveles y no uno. Lo detectaron los tests
-E2E del blog, no el build, y hasta la 0.3.0 esto solo estaba escrito en
-`llms.txt` — el archivo que lee un agente y no una persona.
+The path is relative to the CSS file the directive lives in, so in a project with
+the sheet in `src/styles/` it goes up two levels and not one. The blog's E2E
+tests caught it, not the build, and until 0.3.0 this was only written in
+`llms.txt` — the file an agent reads and a person does not.
+
+### `npx arrecife` — the two things that fail without saying so
+
+```
+npx arrecife
+```
+
+It reads your stylesheets and checks the two failures that produce no error, both
+of which cost real hours in the migration:
+
+**The missing `@source`**, above. It also works out the path for you, counted
+from the sheet and not from the project root, which is the part that gets written
+wrong.
+
+**A token of yours redefining one of ours.** A project coming from shadcn brings
+`@theme inline { --color-accent: var(--accent); }`, and the two are not the same
+colour: shadcn's `--accent` is the hover **surface**, `#17303E`, and this
+library's is the brand turquoise, `#35D6C0`. The result was **88 classes inside
+the library's own components** painting grey — 28 `text-accent`, 26 focus rings,
+15 `bg-accent`, 12 `border-accent`. Buttons, focus rings and badges came out the
+colour of a surface and it looked as though the migration had done nothing. (The
+twenty-six are one `focus-ring` utility now, which changes the count and not the
+failure: it reads `var(--color-accent)` like everything else here.)
 
-> **Vienes de la 0.4.0 o anterior.** `Toast`, `ToastProvider`, `ToastViewport`,
-> `ToastTitle` y `ToastDescription` dejaron de ser API pública en la 0.5.0: se
-> usa `Toaster` y `toast()`. `ToastAction` se queda. La migración, con el porqué
-> y los ejemplos, está en [`docs/migracion-0.5.md`](docs/migracion-0.5.md).
+```
+arrecife · 2 thing(s) that fail without saying so:
 
-> **Vienes de la 0.2.0 o anterior.** Los cinco escalones de espaciado se
-> renombraron: `p-md` es ahora `p-step-md`, `gap-sm` es `gap-step-sm`. Es un
-> cambio incompatible, y si tu proyecto usa `max-w-sm`, `max-w-md` o `max-w-lg`,
-> además te estaban valiendo 12, 16 y 26px sin que nada lo dijera. El porqué, el
-> patrón de migración y qué revisar después están en
-> [`docs/migracion-0.3.md`](docs/migracion-0.3.md).
+  src/styles/globals.css
+    imports @eduardoalvarez/arrecife/tokens/theme.css and has no @source.
+    Every class the components emit is being purged — silently. Add:
 
-Las familias tipográficas se declaran por nombre. Cada proyecto carga Bricolage
-Grotesque, Geist y JetBrains Mono como prefiera: la librería no impone cómo.
+      @source "../../node_modules/@eduardoalvarez/arrecife/dist";
 
-**Los nombres tienen que coincidir EXACTAMENTE**, y esto ya ha mordido dos veces.
-Los tokens declaran las familias así:
+  src/styles/globals.css
+    redefines --color-accent, which @eduardoalvarez/arrecife owns.
+      yours:    var(--accent)   ← points at another property, so it wins silently
+      arrecife: #35D6C0
+```
 
-| Token | `font-family` que declara | Utilidad |
+Five names collide with shadcn's — `background`, `border`, `warm`, `warm-hover`
+and `accent`. Four are harmless because both sides happen to agree on the value,
+so the command reports the value on each side and only fails on the ones that
+differ. A collision that agrees is worth knowing about and is not worth failing
+over.
+
+> **Coming from 0.6.0.** One break, and it is a find and replace the type checker
+> points at: `Stat`'s `tone="alerta"` is `tone="alert"`.
+>
+> Everything else is additive, and most of it lets a project delete something it
+> was maintaining by hand: `./social` and `./icons` are two new subpaths,
+> `EmptyState` has a shape with no face, `Stat` covers the KPI cards, `SidebarNav`
+> groups and collapses, and `npx arrecife` catches two failures that produce no
+> error at all.
+>
+> Run `npx arrecife` first, then read
+> [`docs/migration-0.7.md`](docs/migration-0.7.md).
+
+> **Coming from 0.5.x.** Two unrelated things landed in 0.6.0, and they ship
+> together because in `0.x` a breaking change bumps the minor.
+>
+> The whole public API moved to English: `./tema` is now `./theme`, `scriptTema`
+> is `themeScript`, `Red` is `SocialLink`, the `degradado-hero` utility is
+> `gradient-hero`, and `Hero`'s `variant="cabecera"` is `variant="header"`.
+>
+> And three things break on the API side: `themeScript` is a function, the root
+> ships `"use client"`, and `TalkCardProps` is a union. All three break loudly —
+> the type checker catches every one at the call site.
+>
+> Both halves, in order, with the full rename table and what each project can now
+> **delete**: [`docs/migration-0.6.md`](docs/migration-0.6.md).
+
+> **Coming from 0.4.0 or earlier.** `Toast`, `ToastProvider`, `ToastViewport`,
+> `ToastTitle` and `ToastDescription` stopped being public API in 0.5.0: you use
+> `Toaster` and `toast()`. `ToastAction` stays. The migration, with the reasoning
+> and the examples, is in [`docs/migration-0.5.md`](docs/migration-0.5.md).
+
+> **Coming from 0.2.0 or earlier.** The five spacing steps were renamed: `p-md`
+> is now `p-step-md`, `gap-sm` is `gap-step-sm`. It is a breaking change, and if
+> your project uses `max-w-sm`, `max-w-md` or `max-w-lg`, those were also worth
+> 12, 16 and 26px with nothing saying so. The reasoning, the migration pattern
+> and what to check afterwards are in
+> [`docs/migration-0.3.md`](docs/migration-0.3.md).
+
+The font families are declared by name. Each project loads Bricolage Grotesque,
+Geist and JetBrains Mono however it prefers: the library does not dictate how.
+
+**The names have to match EXACTLY**, and this has already bitten twice. The
+tokens declare the families like this:
+
+| Token | `font-family` it declares | Utility |
 | --- | --- | --- |
 | `fonts.display` | `"Bricolage Grotesque"` | `font-display` |
 | `fonts.sans` | `"Geist"` | `font-sans` |
 | `fonts.mono` | `"JetBrains Mono"` | `font-mono` |
 
-Un proyecto que registre su `@font-face` como `"Bricolage Grotesque Variable"` o
-`"Geist Variable"` —el nombre con el que las publican varios paquetes de fuentes—
-**no** está cargando lo que los tokens piden: la display y la mono caen a la
-fuente del sistema, en silencio y sin un aviso en consola. Es exactamente lo que
-pasó en dos de los cinco proyectos.
+A project registering its `@font-face` as `"Bricolage Grotesque Variable"` or
+`"Geist Variable"` — the name several font packages publish them under — is
+**not** loading what the tokens ask for: the display and the mono fall back to
+the system font, silently and with no console warning. It is exactly what
+happened in two of the five projects.
 
-El `family` del `@font-face` es un alias que elige el proyecto, así que la
-solución es declararlo con el nombre que pide el token:
+The `@font-face`'s `family` is an alias the project chooses, so the fix is to
+declare it with the name the token asks for:
 
 ```css
 @font-face {
-  font-family: "Bricolage Grotesque"; /* NO "Bricolage Grotesque Variable" */
-  src: url("/fuentes/bricolage-grotesque.woff2") format("woff2-variations");
+  font-family: "Bricolage Grotesque"; /* NOT "Bricolage Grotesque Variable" */
+  src: url("/fonts/bricolage-grotesque.woff2") format("woff2-variations");
   font-weight: 200 800;
   font-display: swap;
 }
 ```
 
-#### En Next, con `next/font`
+#### In Next, with `next/font`
 
-Es el mismo fallo por otra puerta, y muerde a los dos proyectos Next. `next/font`
-registra cada familia bajo un nombre GENERADO —`__Geist_a1b2c3`— y la expone como
-una custom property; el nombre literal `"Geist"` que declaran los tokens no
-existe en ningún `@font-face` de la página.
+It is the same failure through another door, and it bites both Next projects.
+`next/font` registers each family under a GENERATED name — `__Geist_a1b2c3` — and
+exposes it as a custom property; the literal `"Geist"` the tokens declare exists
+in no `@font-face` on the page.
 
-Importar `theme.css` sobrescribe `--font-sans` con ese literal, y las tres
-familias caen a la fuente del sistema. En silencio: no hay 404, porque la fuente
-sí se cargó — con otro nombre.
+Importing `theme.css` overwrites `--font-sans` with that literal, and all three
+families fall back to the system font. Silently: there is no 404, because the
+font did load — under another name.
 
-La solución es reafirmar las tres DESPUÉS del import, apuntando a las variables
-que genera `next/font`:
+The fix is to reassert all three AFTER the import, pointing at the variables
+`next/font` generates:
 
 ```ts
-// app/fuentes.ts
+// app/fonts.ts
 import { Geist, Bricolage_Grotesque, JetBrains_Mono } from 'next/font/google';
 
-export const sans = Geist({ subsets: ['latin'], variable: '--fuente-sans' });
-export const display = Bricolage_Grotesque({ subsets: ['latin'], variable: '--fuente-display' });
-export const mono = JetBrains_Mono({ subsets: ['latin'], variable: '--fuente-mono' });
+export const sans = Geist({ subsets: ['latin'], variable: '--project-sans' });
+export const display = Bricolage_Grotesque({ subsets: ['latin'], variable: '--project-display' });
+export const mono = JetBrains_Mono({ subsets: ['latin'], variable: '--project-mono' });
 ```
 
 ```css
@@ -153,52 +226,52 @@ export const mono = JetBrains_Mono({ subsets: ['latin'], variable: '--fuente-mon
 @import "@eduardoalvarez/arrecife/tokens/theme.css";
 @source "../node_modules/@eduardoalvarez/arrecife/dist";
 
-/* Después del import, o gana el literal que no está cargado. */
+/* After the import, or the literal that is not loaded wins. */
 @theme {
-  --font-sans: var(--fuente-sans), ui-sans-serif, system-ui, sans-serif;
-  --font-display: var(--fuente-display), ui-sans-serif, system-ui, sans-serif;
-  --font-mono: var(--fuente-mono), ui-monospace, SFMono-Regular, Menlo, monospace;
+  --font-sans: var(--project-sans), ui-sans-serif, system-ui, sans-serif;
+  --font-display: var(--project-display), ui-sans-serif, system-ui, sans-serif;
+  --font-mono: var(--project-mono), ui-monospace, SFMono-Regular, Menlo, monospace;
 }
 ```
 
-Las variables se llaman `--fuente-*` y no `--font-*` a propósito: `--font-sans`
-es el nombre que Tailwind usa para SU token, y dárselo a `next/font` deja las dos
-capas peleando por la misma propiedad.
+The variables are called `--project-*` and not `--font-*` on purpose:
+`--font-sans` is the name Tailwind uses for ITS token, and handing it to
+`next/font` leaves the two layers fighting over the same property.
 
-El `variable` de cada familia va en la clase del `<html>`, como pide Next:
+Each family's `variable` goes on the `<html>` class, as Next asks:
 `className={`${sans.variable} ${display.variable} ${mono.variable}`}`.
 
-### Mapa de tokens a utilidades
+### Token-to-utility map
 
-| Token | Custom property | Utilidad |
+| Token | Custom property | 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` (padding de botón) |
-| `control.icon` | `--spacing-control-icon` | `size-control-icon` (botón de icono 42×42) |
-| `gradient[modo].hero` | `--gradient-hero` | `degradado-hero` (utilidad, sigue el modo) |
+| `control.md` | `--spacing-control-md` | `px-control-md` (button padding) |
+| `control.icon` | `--spacing-control-icon` | `size-control-icon` (42×42 icon button) |
+| `gradient[mode].hero` | `--gradient-hero` | `gradient-hero` (a utility, follows the mode) |
 | `size.nav` | `--spacing-nav` | `h-nav` |
 | `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` |
 
-El variante `light:` está disponible para los casos del modo claro invertido.
+The `light:` variant is available for the inverted light-mode cases.
 
-También se puede consumir el objeto en JS, sin CSS y sin React — es lo que usan
-las plantillas de OG:
+The object can also be consumed in JS, with no CSS and no React — it is what the
+OG templates use:
 
 ```ts
 import { tokens } from '@eduardoalvarez/arrecife/tokens';
 ```
 
-El tema de resaltado va en otra subruta por la misma razón — se consume desde
-`astro.config.mjs`, no desde un componente:
+The highlighting theme lives in another subpath for the same reason — it is
+consumed from `astro.config.mjs`, not from a component:
 
 ```ts
 import { arrecife } from '@eduardoalvarez/arrecife/shiki';
@@ -208,30 +281,30 @@ export default defineConfig({
 });
 ```
 
-**La librería no trae Shiki.** Los proyectos ya resaltan en build con su propia
-herramienta; lo que les faltaba no era un resaltador, era el tema. `CodeBlock`
-sigue recibiendo el código ya resaltado, que es para lo que está escrito.
+**The library does not ship Shiki.** The projects already highlight at build time
+with their own tooling; what they were missing was not a highlighter, it was the
+theme. `CodeBlock` still receives the code already highlighted, which is what it
+is written for.
 
-Las plantillas de OG se publican en su propia subruta por la misma razón: un
-generador corre en un worker o en un script de build y no debe arrastrar React ni
-un solo componente.
+The OG templates are published in their own subpath for the same reason: a
+generator runs in a worker or in a build script and must not drag in React or a
+single component.
 
 ```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: [...],
 });
 ```
 
-Son funciones puras que devuelven el árbol que Satori pinta, construido solo con
-tokens. `dist/og/index.js` no menciona React en ninguna línea, y eso es
-comprobable con un `grep`.
+They are pure functions returning the tree Satori paints, built only from tokens.
+`dist/og/index.js` mentions React on no line, and that is checkable with a grep.
 
-## Cómo se usa desde un proyecto
+## How it is used from a project
 
 ```tsx
 import { Text, Button, Badge, cn } from '@eduardoalvarez/arrecife';
@@ -239,137 +312,307 @@ 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>
 ```
 
-Cada componente publica su página de documentación en Storybook con la tabla de
-props generada desde los tipos. Las de `Text`:
+Every component publishes its documentation page in Storybook with the props
+table generated from the types. `Text`'s:
 
-| prop | tipo | por defecto |
+| prop | type | default |
 | --- | --- | --- |
 | `variant` | `display · stat · h1 · h2 · h3 · body · lead · ui · label · tag · meta · chip · eyebrow` | `body` |
 | `tone` | `primary · secondary · muted · accent · warm · success · warning · error` | `primary` |
-| `as` | `h1 · h2 · h3 · h4 · p · span · strong · em · figcaption · caption · legend · dt · dd · li` | según `variant` |
-| `measure` | `boolean` — corta a 68ch | `true` en `body` |
-| `asChild` | `boolean` — renderiza el hijo, para envolver un enlace | `false` |
+| `as` | `h1 · h2 · h3 · h4 · p · span · strong · em · figcaption · caption · legend · dt · dd · li` | per `variant` |
+| `measure` | `boolean` — clamps to 68ch | `true` on `body` |
+| `asChild` | `boolean` — renders the child, to wrap a link | `false` |
 
-Comprobado empaquetando la librería con `pnpm pack` e instalándola en un proyecto
-aparte: los tipos resuelven desde `dist/`, `./tokens` carga sin arrastrar React y
-`./tokens/theme.css` se resuelve por subruta.
+Verified by packing the library with `pnpm pack` and installing it in a separate
+project: the types resolve from `dist/`, `./tokens` loads without dragging React
+in and `./tokens/theme.css` resolves by subpath.
 
-### Los iconos de redes van agrupados
-
-Es lo primero con lo que tropieza quien consume la librería, porque la forma
-natural no funciona:
+### The social icons come from `./social`
 
 ```tsx
-// ❌ no existe
+// ❌ does not exist: the root publishes them grouped, not loose
 import { GitHub, LinkedIn } from '@eduardoalvarez/arrecife';
 
-// ✅
-import { social } from '@eduardoalvarez/arrecife';
+// ✅ the normal form
+import { GitHub, LinkedIn } from '@eduardoalvarez/arrecife/social';
 
+// ✅ for iterating the catalogue
+import { social } from '@eduardoalvarez/arrecife';
 <social.GitHub />
-<social.LinkedIn />
 ```
 
-Los ocho son `GitHub`, `LinkedIn`, `X`, `Instagram`, `Discord`, `YouTube`, `Rss`
-y `Correo`. Van bajo un namespace por un motivo concreto: **uno se llama `X`**.
-Un `export const X` en la raíz de una librería de componentes colisiona con
-cualquier cosa —una variable de un genérico, un `import { X }` de otro sitio— y
-el fallo aparece lejos de aquí.
+All nine are `GitHub`, `LinkedIn`, `X`, `Instagram`, `Discord`, `YouTube`, `Rss`,
+`Email` and `Newsletter`.
+
+**The two forms are not taste, and in Next they are not interchangeable.** The
+root carries `"use client"`, and what crosses into a Server Component is a client
+reference **per export** — the properties of a plain object are not exports. So
+from a Server Component `social.LinkedIn` is `undefined`, and `undefined` as an
+element type kills the build at prerender. `./social` carries no directive: the
+icon renders on the server, ships no client JS, and pulls 5.6 KB instead of the
+root's 116 KB. Reach for the subpath by default; reach for `social` when you are
+mapping a list of link names onto icons.
+
+The namespace stays because **one of them is called `X`**. An `export const X` at
+the root of a component library collides with anything — a generic's type
+variable, an `import { X }` from somewhere else — and the failure shows up far
+from here. In the subpath you asked for icons, so the collision is yours to
+resolve and it takes one word: `import { X as XIcon }`.
+
+`Newsletter` is the bell, and it is named for what it means and not for what it
+draws — same as everything else in the system. It plays `Rss`'s role: a way to
+follow, not a social network. That is what keeps it inside this catalogue and
+keeps the catalogue from turning into an icon library.
+
+**The internal glyphs are NOT exported.** `Close`, `ChevronDown`, `Copy`, `Sun`
+and company are the minimum set the primitives need and they stay inside.
+Publishing them would turn `lib/glyphs.tsx` into the icon library the system
+decided not to have, and from there it grows on its own. A project that needs an
+icon passes its own: `Stat` receives `icon`, `Footer` receives each social link's
+`icon`.
+
+### The icons are yours, the way they are drawn is not
+
+That last sentence used to end there, and «its own what, drawn how» had no
+answer. The admin panel imports 89 distinct icons in 229 places — 77 of them
+domain icons for a course admin, which no design system was going to ship — and
+drew them at `size-4` twenty-six times, plus `size-3.5`, `size-3`, `size-6` and
+`size-7`, with no rule behind any of them.
 
-**Los glifos internos NO se exportan.** `Close`, `ChevronDown`, `Copy`, `Sol` y
-compañía son el juego mínimo que necesitan los primitivos y se quedan dentro.
-Publicarlos convertiría `lib/glyphs.tsx` en la librería de iconos que el sistema
-decidió no tener, y a partir de ahí crece sola. Un proyecto que necesite un icono
-pasa el suyo: `Stat` recibe `icon`, `Footer` recibe el `icon` de cada red.
+```tsx
+import { GraduationCap } from '@phosphor-icons/react';
+import { Icon } from '@eduardoalvarez/arrecife/icons';
 
-### Las dos subrutas que piden una dependencia
+<Icon as={GraduationCap} />
+```
 
-`./form` y `./chart` no cuelgan de la raíz, y es a propósito. Cada una pide una
-dependencia de pares **opcional** —`react-hook-form` y `recharts`—, y colgarlas
-del índice principal obligaría a los cinco proyectos a instalarlas para que su
-bundler resolviera un import que cuatro de ellos nunca ejecutan.
+1em, so the icon takes the size of the text it sits in and nobody picks a number.
+Weight `regular` by default, and **that is the whole reason the set is
+Phosphor**: it bakes the weight into the path instead of exposing a
+`strokeWidth`, and its regular lands on the one stroke the identity document
+names. Measured on the `Minus` path itself, whose regular form is a bar of radius
+8 on a 256 grid:
 
-Es la misma decisión que `./og` y `./shiki`, mirada desde el otro lado: allí se
-saca React del camino de quien no lo monta; aquí se saca Recharts del camino de
-quien no dibuja.
+| | Line | As a fraction of the rendered size |
+| --- | --- | --- |
+| phosphor `regular` | 16 on a 256 grid | **0.0625em** |
+| the document | 1.6 on a 24 grid | **0.0667em** |
+| `lib/glyphs.tsx` | 1.75 on a 16 grid | 0.109em |
+
+Six per cent apart, which is no pixel on any screen. Nothing had to be derived and
+no number had to be invented. The `Icons/Icon` → `regular IS the document's
+stroke` story alternates the bars so the claim can be checked instead of believed
+— and it also shows the third row, because **`glyphs.tsx` is the outlier**: at
+0.109em it is three quarters heavier than both, it was never argued anywhere, and
+aligning it would restyle every primitive in the library. That is a separate
+change and `docs/decisions.md` § 29 says so.
+
+**The weight is an axis with three values, and `tone` is how you name them.**
+`weight` is not a prop: Phosphor ships six and this system reads three, because
+`thin`, `bold` and `duotone` have no role behind them here.
+
+| `tone` | Weight | What it is |
+| --- | --- | --- |
+| `action` · the default | `regular` | An icon that is a control or names one |
+| `current` | `fill` | The one of a set you are on — the item carrying `aria-current` |
+| `quiet` | `light` | Furniture: a marker in a metadata row, not a control and not a state |
+
+`current` is the value that earns the axis, and the argument is not taste.
+An active sidebar item already says so in biolume, and **colour on its own is the
+one channel WCAG 1.4.1 says may not carry meaning** — the fill is the second
+channel, and it is the one that survives a forced-colours mode where the biolume
+does not. `quiet` is the opposite problem: in a metadata row the icon is not the
+point of the line, and at `regular` it draws as heavy as the date beside it.
+`docs/decisions.md` § 35 has the rest.
+
+`@phosphor-icons/react` is an **optional** peer dependency on its own subpath, by
+the same rule as `./form` and `./chart`: two of the five projects use no icons and
+install nothing.
+
+**An icon is not illustration.** Tiburoncín — the faces, the poses, the fin — is
+the mascot, it comes from `./brand`, and the manual doses it by surface: a face
+only in an empty state, a confirmation, an error, course progress or a
+celebration. An icon is functional vocabulary and goes wherever a control needs a
+label it cannot spell. Adopting a set changed nothing about the first, and
+neither stands in for the other in either direction.
+
+**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 — and it ships no `"use client"` to stop you, so the
+failure arrives at render. The `/ssr` entry is the same icons without the context
+read, and `Icon` works with either.
+
+### `"use client"` is in the published `dist`
+
+The root, `./brand`, `./form` and `./chart` carry the directive. They render
+React, and their Radix primitives call `createContext` at module scope: without
+it, a Next project with the App Router cannot import the library at all — it
+fails at build time with `TypeError: (0 , r.createContext) is not a function`.
+It blocked `cursos` for a whole version, and the workaround there was a
+`"use client"` in every one of that project's own adapters, including a `Badge`
+that is a `<span>` with no interaction. It cost 272 KB of client chunk.
+
+The five portable subpaths do NOT carry it — `./tokens`, `./theme`,
+`./variants`, `./og` and `./shiki` — and that is the half that matters more.
+Marking them client would be a lie with a cost: a Server Component importing
+`buttonVariants`, a function that returns a string, would pull a client boundary
+in with it.
+
+`./social` is the third case, and it is why the check stopped looking only at the
+portable ones. It renders React — it is nine `<svg>` — so it can never be
+portable, and it holds no state, so it must not be a client entry either. Listed
+in neither set, nothing would have noticed it being marked client by mistake, and
+that mistake undoes the only reason the subpath exists. See `docs/decisions.md`
+§ 26.
+
+It is stamped by `scripts/add-use-client.mjs` after tsup, and not by tsup's
+`banner`. That was tried first: esbuild writes the directive and the bundling
+pass strips it back out with a `Module level directives cause errors when
+bundled` warning. The build stayed green and the published package was broken for
+Next — the worst way to fail, because the failure surfaces in somebody else's
+project. `check:exports` now verifies it in both directions: present on the four
+client entries, absent from every other subpath.
+
+It is inert outside Next. In Astro and in plain Vite it is a string literal at
+the top of a module; Rollup may warn and nothing else happens. One `dist` serves
+the Next projects and the Astro ones, which is the constraint that decided the
+shape.
+
+### `./variants` — the class vocabulary without React
+
+```ts
+import { buttonVariants, badgeVariants, CARD_SURFACE }
+  from '@eduardoalvarez/arrecife/variants';
+```
+
+`buttonVariants`, `badgeVariants` and `categoryBadgeVariants` are not
+components: they are functions that return a string of classes. They touch
+neither React nor the DOM. They used to live inside the components, so importing
+one dragged the whole library along, and that had a cost measured in two of the
+five projects.
+
+In `cursos` it forced a `"use client"` on an adapter whose entire content was one
+call to CVA. In `links`, which depends on no React at all, it was not even an
+option: that project copied the class vocabulary by hand into `LinkRow.astro` and
+`Footer.astro`, and the copy had already drifted once: the hero gradient sat at
+`55%` and `#e9eeea` against the token's `60%` and, at the time, `#EFE9DE`, and
+nothing compared them. That light stop is `#FFFFFF` now — § 9 measured it — which
+is the same lesson seen from the other end. A copied value goes stale the moment
+the original moves, and only the original is ever right.
+
+The rule for what belongs in the subpath: if it returns classes, it goes there;
+if it returns markup, it stays in the component. `Button` renders a `<button>`,
+so it stays at the root; `buttonVariants` returns a string, so it is in
+`./variants`. The root re-exports all of it, so an existing
+`import { buttonVariants } from '@eduardoalvarez/arrecife'` keeps working — what
+the subpath buys is not the name, it is not paying for React to get it.
+
+### The two subpaths that ask for a dependency
+
+`./form` and `./chart` do not hang off the root, and that is deliberate. Each
+asks for an **optional** peer dependency — `react-hook-form` and `recharts` — and
+hanging them off the main index would force all five projects to install them so
+their bundler could resolve an import four of them never execute.
+
+It is the same decision as `./og` and `./shiki`, seen from the other side: there
+React is kept out of the way of whoever does not mount it; here Recharts is kept
+out of the way of whoever does not draw.
 
 ```tsx
 import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage }
   from '@eduardoalvarez/arrecife/form';
 
-import { ChartContainer, ChartTooltip, ChartTooltipContent, colorDeSerie }
+import { ChartContainer, ChartTooltip, ChartTooltipContent, seriesColor }
   from '@eduardoalvarez/arrecife/chart';
 ```
 
-`check:exports` verifica que las cuatro portables —`./tokens`, `./tema`, `./og` y
-`./shiki`— no traen React en el `dist/` publicado, **siguiendo los imports
-relativos**. Sin eso el check era papel mojado: con `treeshake` activo, cada
-entrada portable queda en dos líneas que reexportan de un `chunk-XXXX.js`, y un
-grep sobre esas dos líneas no encuentra React ni aunque el chunk lo importe.
+`check:exports` verifies that the five portable ones — `./tokens`, `./theme`,
+`./variants`, `./og` and `./shiki` — bring no React into the published `dist/`,
+**by following the relative imports**. Without that the check was worthless: with `treeshake`
+on, each portable entry ends up as two lines re-exporting from a
+`chunk-XXXX.js`, and a grep over those two lines finds no React even when the
+chunk imports it.
 
 ## Scripts
 
 | | |
 | --- | --- |
-| `pnpm build` | verifica la pureza de tokens, compila con tsup y genera `theme.css` |
+| `pnpm build` | verifies token purity, compiles with tsup and generates `theme.css` |
 | `pnpm typecheck` | `tsc --noEmit` |
-| `pnpm lint` | ESLint, incluido el veto a hex literales fuera de `tokens.ts` |
-| `pnpm check:tokens` | falla si `src/tokens/` importa algo de fuera |
-| `pnpm test` | compila Tailwind y corre axe sobre las 206 stories, en los dos modos |
-| `pnpm check:exports` | verifica que `dist/` tiene lo que `exports` promete |
-| `pnpm check:release` | valida `release-please-config.json` contra el esquema oficial |
-| `pnpm storybook` | genera los tokens y levanta Storybook en el 6006 |
+| `pnpm lint` | ESLint, including the ban on literal hexes outside `tokens.ts` |
+| `pnpm check:tokens` | fails if `src/tokens/` imports anything from outside |
+| `pnpm test` | compiles Tailwind and runs axe over the 208 stories, in both modes |
+| `pnpm check:exports` | verifies that `dist/` holds what `exports` promises |
+| `pnpm check:release` | validates `release-please-config.json` against the official schema |
+| `pnpm storybook` | generates the tokens and serves Storybook on 6006 |
 
-## El contraste como test, no como panel
+## Contrast as a test, not as a panel
 
-`pnpm test` monta cada story en un Chromium real y le pasa axe con
-`a11y: { test: 'error' }`. Corre dos veces, una por modo: un color solo falla en
-uno de los dos, así que pasar en oscuro no prueba nada sobre el claro.
+`pnpm test` mounts every story in a real Chromium and runs axe over it with
+`a11y: { test: 'error' }`. It runs twice, once per mode: a color only fails in
+one of the two, so passing in dark proves nothing about light.
 
-Está comprobado que no es decorativo: devolver `textMuted` claro a su valor
-anterior tira ocho stories con «insufficient color contrast of 4.24».
+It is demonstrably not decorative: putting light `textMuted` back to its previous
+value takes down eight stories with «insufficient color contrast of 4.24».
 
-Hay una sola regla desactivada, en dos stories concretas y con el motivo escrito
-al lado: `aria-hidden-focus` en `Select`/`DropdownMenu` abiertos. Radix marca
-`aria-hidden` todo lo que queda fuera del portal y deja el disparador dentro
-siendo focusable; el foco está atrapado por su `FocusScope`, así que no se puede
-tabular hasta él. Es un desacuerdo conocido entre axe y Radix.
+There is exactly one disabled rule, in two specific stories and with the reason
+written beside it: `aria-hidden-focus` on open `Select`/`DropdownMenu`. Radix
+marks everything outside the portal `aria-hidden` and leaves the trigger inside
+it still focusable; focus is trapped by its `FocusScope`, so it cannot be tabbed
+to. It is a known disagreement between axe and Radix.
 
-## Correcciones de contraste
+## Contrast corrections
 
-El documento de identidad medía todo contra `background`. Pero `surfaceRaised`
-es el peor caso en los **dos** modos: en claro es más oscuro que el fondo de
-página, en oscuro es más claro. Es donde viven menús y tabs activos.
+The identity document measured everything against `background`. But
+`surfaceRaised` is the worst case in **both** modes: in light it is darker than
+the page background, in dark it is lighter. It is where menus and active tabs
+live.
 
-| token | antes | ahora | motivo |
+| token | before | now | reason |
 | --- | --- | --- | --- |
-| `light.textMuted` | `#6B7480` | `#626A75` | 4.24 no llegaba a AA sobre papel |
-| `light.warning` | `#9A6A12` | `#8D6111` | 4.23 no llegaba a AA sobre papel |
-| `dark.error` | `#E05252` | `#E15757` | 4.35 sobre `surface`, que es donde va un error de formulario |
+| `light.textMuted` | `#6B7480` | `#626A75` | 4.24 did not reach AA over paper |
+| `light.warning` | `#9A6A12` | `#8D6111` | 4.23 did not reach AA over paper |
+| `dark.error` | `#E05252` | `#E15757` | 4.35 over `surface`, which is where a form error goes |
+
+All three keep their exact hue and saturation: only lightness moves, by one to
+four points. Light `accent` and `warm` are untouched.
 
-Los tres conservan tono y saturación exactos: solo cambia la luminosidad entre
-uno y cuatro puntos. `accent` y `warm` claros no se tocan.
+New token: `hairlineHover` — `#2C4D5D` in dark (rule 6's value) and `#D3C8B2` in
+light, derived by matching the perceptual step (ΔL\* 10.5) rather than the
+contrast ratio, which overshoots near white.
 
-Token nuevo: `hairlineHover` — `#2C4D5D` en oscuro (el valor de la regla 6) y
-`#D3C8B2` en claro, derivado de igualar el salto perceptual (ΔL\* 10.5) en vez
-de la razón de contraste, que cerca del blanco se pasa de frenada.
+`textMuted` never goes over `surfaceRaised`: in dark it gives 4.07. Menus use
+`textSecondary`, which gives 6.96.
 
-`textMuted` no va nunca sobre `surfaceRaised`: en oscuro da 4.07. Los menús usan
-`textSecondary`, que da 6.96.
+**And no gradient ends there either**, which is the same rule applied to a
+surface that moves. The light `hero` and `section` blocks used to sweep from the
+page down onto `surfaceRaised`, where light `accent` reads **4.21** and `warm`
+**4.19** — both under 4.5, and both of them fine at 4.55 and 4.53 on the page
+they started from. That makes a token's contrast a function of **where in the
+panel the text happens to sit**, which no token can guarantee and the suite
+cannot see: axe does not evaluate text over a gradient, so both modes passed it.
+`Hero` puts an `accent` eyebrow directly on that gradient.
 
-### La tercera corrección: el color semántico no es color de texto sobre su tinte
+The light blocks now sweep between `background` and `surface` and never touch
+`surfaceRaised`, so the darkest point of either one is the page itself — a token
+that passes on the page passes at every point of the sweep. `docs/decisions.md`
+§ 9 has the measurements, including the two other things the first composition
+got wrong.
 
-Salió al implementar la receta de avisos del documento — fondo al 8 % del color
-semántico — y la tiró la suite en modo claro, en cinco stories.
+### The third correction: a semantic color is not a text color over its own tint
 
-Los semánticos claros están calibrados para pasar **justo** sobre papel. Teñir el
-fondo con ellos los hunde por debajo de AA:
+It came up while implementing the document's alert recipe — background at 8 % of
+the semantic color — and the suite took it down in light mode, across five
+stories.
 
-| tono | sobre papel | sobre su propio tinte 8 % | `textPrimary` sobre el tinte |
+The light semantics are calibrated to pass **just** over paper. Tinting the
+background with them sinks them below AA:
+
+| tone | over paper | over its own 8 % tint | `textPrimary` over the tint |
 | --- | --- | --- | --- |
 | `accent` | 4.55 | **4.12** | 14.82 |
 | `warm` | 4.54 | **4.11** | 14.85 |
@@ -377,79 +620,83 @@ fondo con ellos los hunde por debajo de AA:
 | `warning` | 4.88 | **4.40** | 14.78 |
 | `error` | 4.87 | **4.35** | 14.64 |
 
-No hay alfa que lo arregle: el problema es poner el color encima de sí mismo. La
-resolución no toca la paleta — el tinte es una **superficie**, así que el texto
-que lleva encima es un token de texto. El color semántico se queda donde no es
-texto: el borde y el glifo.
+No alpha fixes it: the problem is putting the color on top of itself. The
+resolution does not touch the palette — the tint is a **surface**, so the text on
+top of it is a text token. The semantic color stays where it is not text: the
+border and the glyph.
 
-El 8 %, por cierto, aguanta igual o mejor sobre papel que sobre abismo (1.106 vs.
-1.149 en acento). La sospecha de que el modo claro necesitaba una segunda tabla
-iba al revés: el punto flojo del sistema es `error` sobre abismo, 1.067.
+The 8 %, incidentally, holds up as well as or better over paper than over abyss
+(1.106 vs. 1.149 in accent). The suspicion that light mode needed a second table
+ran the other way round: the system's weak point is `error` over abyss, 1.067.
 
-## Publicar una versión
+## Publishing a version
 
-**No hay pasos manuales.** El tag, el CHANGELOG y el bump de versión los hace
-release-please a partir de los commits convencionales que ya se escriben —y que
-`lint-pr-title` ya obliga a escribir bien.
+**There are no manual steps.** The tag, the CHANGELOG and the version bump are
+done by release-please from the conventional commits that already get written —
+and that `lint-pr-title` already forces to be written correctly.
 
-El ciclo, entero, está en `.github/workflows/release.yml`:
+The whole cycle lives in `.github/workflows/release.yml`:
 
-1. Mergeas un PR a `main` con un título tipo `feat(badge): …`.
-2. release-please abre —o actualiza— un PR llamado `chore: versión X.Y.Z` con el
-   bump en `package.json` y la entrada nueva del `CHANGELOG.md`. Ese PR se queda
-   abierto y se va acumulando con cada merge, así que puedes juntar varios
-   cambios en una versión.
-3. Cuando lo mergeas, corta el tag, crea el release y dispara la publicación.
-4. Antes de subir nada, el workflow comprueba que el tag y `package.json`
-   coinciden, y corre lint, tipos, build, la verificación de `exports` y la
-   suite completa en los dos modos.
+1. You merge a PR to `main` with a title like `feat(badge): …`.
+2. release-please opens — or updates — a PR called `chore: release X.Y.Z` with
+   the bump in `package.json` and the new `CHANGELOG.md` entry. That PR stays
+   open and accumulates with every merge, so you can group several changes into
+   one version.
+3. When you merge it, it cuts the tag, creates the release and triggers the
+   publish.
+4. Before uploading anything, the workflow checks that the tag and `package.json`
+   match, and runs lint, types, build, the `exports` verification and the full
+   suite in both modes.
+5. With the package already on npm, it builds Storybook and deploys it to
+   [arrecife.eduardoalvarez.dev](https://arrecife.eduardoalvarez.dev).
 
-`feat:` sube la minor y `fix:` la patch. Mientras la versión sea `0.x`, un
-cambio que rompe sube la **minor** y no la major: eso es lo que significa el
-`0.` — que la API todavía se puede mover sin gastar la 1.0. Está en
-`release-please-config.json`, y ahí también está `initial-version` con el `0.1.0`
-de la primera versión.
+`feat:` bumps the minor and `fix:` the patch. While the version is `0.x`, a
+breaking change bumps the **minor** and not the major: that is what the `0.`
+means — that the API can still move without spending 1.0. It is in
+`release-please-config.json`, and `initial-version` with the first release's
+`0.1.0` is there too.
 
-Cuando la API se estabilice, se sube a `1.0.0` a mano una vez y a partir de ahí
-un `BREAKING CHANGE:` sube la major como en cualquier paquete.
+When the API stabilises, it goes up to `1.0.0` by hand once, and from then on a
+`BREAKING CHANGE:` bumps the major like in any other package.
 
-### Cómo release-please decide qué cortar
+### How release-please decides what to cut
 
-Dos datos, y salen de sitios distintos. Saberlo evita el único fallo que deja el
-release atascado:
+Two pieces of information, and they come from different places. Knowing this
+avoids the one failure that leaves the release stuck:
 
-| Dato | De dónde sale |
+| Datum | Where it comes from |
 | --- | --- |
-| La **versión** | Del **título** del PR — `chore(main): release 0.2.0` |
-| El **componente** | Del **nombre de la rama** — `release-please--branches--main--components--arrecife` |
+| The **version** | From the PR **title** — `chore(main): release 0.2.0` |
+| The **component** | From the **branch name** — `release-please--branches--main--components--arrecife` |
 
-El componente lo deriva de `package.json` y **no se puede fijar por
-configuración**: no existe una clave `component` en el
-[esquema oficial](https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json).
-`include-component-in-tag: false` es lo que hace que el tag sea `v0.2.0` y no
+The component is derived from `package.json` and **cannot be pinned by
+configuration**: there is no `component` key in the
+[official schema](https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json).
+`include-component-in-tag: false` is what makes the tag `v0.2.0` and not
 `arrecife-v0.2.0`.
 
-Si el título o la rama se editan a mano y dejan de casar, release-please no crea
-el release y cada run termina en `There are untagged, merged release PRs
-outstanding - aborting`. De ahí no se sale con configuración: hay que cortar el
-tag y el release a mano y reetiquetar el PR a `autorelease: tagged`.
+If the title or the branch are edited by hand and stop matching, release-please
+does not create the release and every run ends in `There are untagged, merged
+release PRs outstanding - aborting`. There is no way out of that through
+configuration: the tag and the release have to be cut by hand and the PR
+relabelled `autorelease: tagged`.
 
-`pnpm check:release` valida la configuración contra ese esquema en cada CI.
-Existe porque release-please **ignora en silencio** las claves que no conoce: una
-opción inventada no da error, no sale en el log y no hace nada.
+`pnpm check:release` validates the configuration against that schema on every CI
+run. It exists because release-please **silently ignores** keys it does not know:
+an invented option raises no error, shows in no log and does nothing.
 
-### La publicación de confianza
+### Trusted publishing
 
-El workflow publica con **OIDC**: GitHub emite un token que prueba «este build
-salió de este repo y de este workflow», y npm lo cambia por permiso de
-publicación. No hay ningún secreto de larga vida que robar, ni que rotar. De
-paso genera la **procedencia**, que firma el paquete con un enlace verificable a
-ese commit exacto.
+The workflow publishes with **OIDC**: GitHub issues a token proving «this build
+came out of this repo and this workflow», and npm exchanges it for permission to
+publish. There is no long-lived secret to steal, or to rotate. It also generates
+**provenance**, which signs the package with a verifiable link to that exact
+commit.
 
-Se configura una vez, en npmjs.com → el paquete → *Settings* → *Trusted
+It is configured once, on npmjs.com → the package → *Settings* → *Trusted
 publisher*:
 
-| Campo | Valor |
+| Field | Value |
 | --- | --- |
 | Publisher | GitHub Actions |
 | Organization or user | `Proskynete` |
@@ -457,262 +704,416 @@ publisher*:
 | Workflow filename | `release.yml` |
 | Environment | `npm` |
 
-Ese *Workflow filename* es la razón de que el release y la publicación vivan en
-un solo archivo en vez de en un workflow reutilizable: npm casa el token contra
-un nombre, y con `workflow_call` hay dos candidatos.
-
-**El huevo y la gallina.** No se puede configurar un publicador de confianza en
-un paquete que todavía no existe, así que la primera versión necesita token:
-
-1. Crea el entorno `npm` en la configuración del repo con el secreto
-   `NPM_TOKEN` (un token de tipo *automation*).
-2. Sube la versión y publica la primera vez. El workflow avisa en el log de que
-   está usando token.
-3. Configura la publicación de confianza con la tabla de arriba.
-4. **Borra el secreto `NPM_TOKEN`.** El paso que lo usa se salta solo cuando no
-   está, y OIDC toma el relevo sin tocar ni una línea del workflow.
-
-Para probar sin gastar una versión: *Actions → Release y publicación → Run
-workflow* con el ensayo activado. Hace todo menos publicar, no necesita token, y
-el resumen del run lista qué archivos viajarían y cuánto pesa el tarball.
-
-## Estado
-
-- **Fase 1** · andamiaje, tokens y Storybook con el switch de tema. Completa.
-- **Fase 2** · `brand/`. Completa con los PNG que ya existían.
-- **Fase 3** · los 18 primitivos sobre shadcn/Radix, más `Text` y ocho añadidos
-  después de medir el uso real en los cinco proyectos. Completa.
-- **Fase 4** · `AudioPlayer`, migrado. Completa.
-- **Fase 5** · completa. `ArticleCard`, `AuthorCard`, `TalkCard`, `CourseCard`,
+That *Workflow filename* is the reason the release and the publish live in a
+single file rather than in a reusable workflow: npm matches the token against a
+name, and with `workflow_call` there are two candidates.
+
+**The chicken and the egg.** You cannot configure a trusted publisher on a
+package that does not exist yet, so the first version needs a token:
+
+1. Create the `npm` environment in the repo settings with the `NPM_TOKEN` secret
+   (an *automation* token).
+2. Bump the version and publish for the first time. The workflow says in the log
+   that it is using a token.
+3. Configure trusted publishing with the table above.
+4. **Delete the `NPM_TOKEN` secret.** The step that uses it skips itself when it
+   is absent, and OIDC takes over without touching a line of the workflow.
+
+To test without spending a version: *Actions → Release y publicación → Run
+workflow* with the dry run enabled. It does everything but publish, needs no
+token, and the run summary lists which files would travel and how big the tarball
+is.
+
+The dry run **does deploy Storybook**, to a Vercel preview and not to the public
+domain. That is deliberate: a dry run that skips a job cannot tell you whether
+that job works, and the deploy was the only step in the workflow that could not
+be tested without spending a version.
+
+One detail of the dry run that is confusing the first time: `npm publish
+--dry-run` queries the registry, and `package.json` points at an **already
+published** version except in the window between release-please bumping the
+number and the workflow publishing. So the dry run runs into `cannot publish over
+the previously published versions` over the one thing that cannot be right in a
+dry run. That specific message is forgiven with a notice; any other failure still
+fails.
+
+### Storybook is deployed with the version
+
+The published Storybook is the library's documentation: every story is both the
+example and the test that verifies it. It lives at
+[arrecife.eduardoalvarez.dev](https://arrecife.eduardoalvarez.dev) and it is
+uploaded by `release.yml`'s `deploy` job, **after** npm has published.
+
+That order is not an implementation detail. The site and the package have to tell
+the same version: a Storybook ahead of npm shows components nobody can install
+yet, and that is exactly the failure this repo exists because of — one source of
+truth drifting from another.
+
+Hence the decision that surprises people: **the Vercel project is not connected
+to GitHub.** With the Git integration, Vercel builds on its own on every push to
+`main` and there is no way to ask it to wait for the tag. The only thing that
+deploys is the workflow, and it uploads Storybook **already built**: with the
+Build Output API and `--prebuilt`, Vercel executes nothing, it serves what is in
+`.vercel/output/static`. That way it is built by the same Node and the same
+lockfile that just verified the library.
+
+It is configured once, with `vercel link` in a local clone to create the project
+and get the two ids out of `.vercel/project.json`. **Careful with one extra
+step:** `vercel link` connects the GitHub repository to the project on its own
+and without asking, which is exactly what you do not want. It is undone with
+`vercel git disconnect`, and it is worth checking before calling the project
+configured.
+
+| Where | Name | What it is |
+| --- | --- | --- |
+| *Secrets* | `VERCEL_TOKEN` | A Vercel account token |
+| *Variables* | `VERCEL_ORG_ID` | The `orgId` from `.vercel/project.json` |
+| *Variables* | `VERCEL_PROJECT_ID` | The `projectId` from `.vercel/project.json` |
+
+The two ids go in as **variables** and not as secrets on purpose: they are not
+secret — they come out of any clone that runs `vercel link` — and as variables
+they are readable in the log when something does not add up.
+
+The team's deployment protection is `all_except_custom_domains`: each deploy's
+unique URL asks for a team session and returns a 302 to the login, and the public
+one is the custom domain. It is not a misconfiguration, it is Vercel's default
+and it is the one we want.
+
+**If they are missing, the job warns and does not break.** By the time it runs,
+npm has published and the tag has been cut: a red there would read as «the
+release failed», which is the opposite of what happened. The warning stays in the
+run summary.
+
+## Status
+
+- **Phase 1** · scaffolding, tokens and Storybook with the theme switch. Done.
+- **Phase 2** · `brand/`. Done, with the PNGs that already existed.
+- **Phase 3** · the 18 primitives on shadcn/Radix, plus `Text` and eight more
+  added after measuring real usage across the five projects. Done.
+- **Phase 4** · `AudioPlayer`, migrated. Done.
+- **Phase 5** · done. `ArticleCard`, `AuthorCard`, `TalkCard`, `CourseCard`,
   `LinkRow`, `CodeBlock`, `Blockquote`, `PageHeader`, `EmptyState`, `Breadcrumb`,
   `Nav`, `SidebarNav`, `TableOfContents`, `Stat`, `Footer`, `Hero`,
-  `NewsletterForm`, `og/` y `shiki/`.
-
-  El criterio para decidir qué entra sigue siendo el mismo: **codifica una regla
-  de identidad, tiene dos o más consumidores, y no arrastra infraestructura del
-  proyecto.**
-
-### `Hero` y `NewsletterForm` volvieron a entrar
-
-Estaban fuera de la lista con un argumento escrito, y el argumento se revisó.
-
-**`Hero`.** Se había descartado porque «el hero del portafolio y el de cursos son
-el mismo esqueleto que una cabecera de sección, y `PageHeader` los cubre con una
-prop de escala». Eso vale para el texto y solo para el texto. El hero del
-documento tiene además degradado, radio de panel, texto acotado al 62 % del ancho
-y la pose sangrando por la esquina inferior derecha — nada de lo cual cabe en una
-prop de escala de `PageHeader`, y todo lo cual son reglas de identidad que si no
-viven aquí se reimplementan cinco veces. Son dos piezas distintas: `PageHeader`
-sigue siendo la cabecera de sección y va dentro de `<main>`; `Hero` es la portada
-y va uno por sitio.
-
-**`NewsletterForm`.** Se había descartado porque «la mitad de su código es un
-`POST` a un endpoint que solo vive ahí: eso es infraestructura». Correcto, y por
-eso el `POST` no está aquí. El componente es presentacional: recibe `state` y
-emite `onSubmitEmail`, y el proyecto hace la llamada con su proveedor. Lo que sí
-es identidad son los cuatro estados y, sobre todo, que el aviso vaya **debajo**
-del formulario en vez de reemplazarlo — reemplazarlo es lo que rompe el caso real
-de quien se suscribe con el correo equivocado.
-
-`Nav`, `Footer`, `Breadcrumb` y `Hero` son composición de página y se pueden
-discutir como piezas de librería. Entran igual: la estética CLI —el `./sección`
-de la barra, el `~ / artículos / slug` de la ruta, la firma `$ cd ~/…` del pie—
-es lo primero que se desincroniza cuando cinco proyectos la escriben cada uno por
-su cuenta.
-
-### Decisiones de la Fase 3
-
-- **Sin `lucide-react`.** Los ocho glifos que los primitivos necesitan están
-  inline en `src/lib/glyphs.tsx`, heredan `currentColor` y miden 1em. Una
-  librería de iconos como dependencia se la come cada uno de los cinco proyectos.
-- **Sin animaciones de entrada.** Modales, menús, tooltips y toasts aparecen
-  donde van a quedarse. La perilla del `Switch` cambia de posición sin deslizarse.
-  La única transición del sistema es `transition-standard`, que solo puede animar
-  color y borde porque así está escrita la utilidad.
-- **Una excepción, documentada:** el spinner de `Button loading` gira. Un botón
-  cargando sin movimiento es indistinguible de uno deshabilitado; es
-  realimentación de progreso, no de estado, y va envuelto en `motion-safe`.
-- **`Progress` exige `label`.** Una barra sin nombre accesible no dice de qué es
-  el progreso, y ninguna otra parte del componente puede deducirlo.
-- **Cero hex literales**, incluido `Button`. La regla 2 sale con
-  `light:bg-brand-hull`, porque el casco ya era un token.
-- **`cursor-pointer` explícito** en todo lo que se pulsa. Tailwind v4 quitó del
-  preflight el `cursor: pointer` de `button`, así que un botón sin la clase se
-  queda con la flecha del sistema. Lo llevan `Button`, `Checkbox`,
-  `RadioGroupItem`, `Switch`, `TabsTrigger`, el disparador de `Select`, los
-  cerrar de `Dialog`/`Sheet`/`Toast`, `PaginationLink`, el casco de las tarjetas
-  pulsables y los enlaces de `Nav`, `Footer` y `Breadcrumb` — que renderizan
-  `<a>` sin `href` cuando se les enchufa el `Link` de un enrutador.
-
-  Dos excepciones deliberadas. `Label` apunta a un control pero no es el control.
-  Y los **ítems de menú** de `Select` y `DropdownMenu` se quedan en
-  `cursor-default`: un menú nativo no muestra la manito, y el highlight de la
-  fila ya dice que la fila responde.
-
-### La paleta de sintaxis
-
-Del documento, literal: «keywords arena, strings bioluz, comments plancton,
-identifiers espuma», sobre casco. Cuatro colores a propósito — funciones,
-variables y tipos caen los tres en espuma, porque el sistema se comunica con
-color y borde y no con ruido cromático. Los números y booleanos van con las
-cadenas: el documento no los asigna, y agruparlos por «son literales» es más
-coherente que estrenar un quinto color.
-
-Medido sobre `brand.hull` #0B1524, todo AA:
-
-| rol | token | contraste |
+  `NewsletterForm`, `og/` and `shiki/`.
+
+  The criterion for deciding what gets in is still the same: **it encodes an
+  identity rule, it has two or more consumers, and it drags in no project
+  infrastructure.**
+
+### `Hero` and `NewsletterForm` came back in
+
+They were off the list with a written argument, and the argument was revisited.
+
+**`Hero`.** It had been ruled out because «the portfolio's hero and the courses
+one are the same skeleton as a section header, and `PageHeader` covers them with
+a scale prop». That holds for the text and only for the text. The document's hero
+also has a gradient, a panel radius, text clamped to 62 % of the width and the
+pose bleeding off the bottom-right corner — none of which fits in a `PageHeader`
+scale prop, and all of which are identity rules that get reimplemented five times
+if they do not live here. They are two different pieces: `PageHeader` is still
+the section header and goes inside `<main>`; `Hero` is the cover and there is one
+per site.
+
+**`NewsletterForm`.** It had been ruled out because «half its code is a `POST` to
+an endpoint that only lives there: that is infrastructure». Correct, and that is
+why the `POST` is not here. The component is presentational: it takes `state` and
+emits `onSubmitEmail`, and the project makes the call with its own provider. What
+IS identity are the four states and, above all, that the notice goes **below**
+the form instead of replacing it — replacing it is what breaks the real case of
+somebody who subscribes with the wrong email.
+
+`Nav`, `Footer`, `Breadcrumb` and `Hero` are page composition and can be argued
+about as library pieces. They get in anyway: the CLI aesthetic — the bar's
+`./section`, the path's `~ / artículos / slug`, the footer's `$ cd ~/…` signature
+— is the first thing that drifts when five projects each write it on their own.
+
+### Phase 3 decisions
+
+- **It ships no icon set**, and that has not changed. The eight glyphs the
+  primitives need are inline in `src/lib/glyphs.tsx`, inherit `currentColor` and
+  measure 1em, and they are not exported. What DID change is that
+  `@phosphor-icons/react` is now an optional peer on `./icons`, so the set a
+  project chooses is drawn at the system's weight — see «The icons are yours»
+  above. Optional and on a subpath is the point: the two projects that use no
+  icons install nothing.
+- **No entrance animations.** Modals, menus, tooltips and toasts appear where
+  they will stay. The `Switch` knob changes position without sliding. The
+  system's only transition is `transition-standard`, which can only animate color
+  and border because that is how the utility is written.
+- **One exception, documented:** the `Button loading` spinner spins. A loading
+  button with no movement is indistinguishable from a disabled one; it is
+  feedback about progress, not about state, and it is wrapped in `motion-safe`.
+- **`Progress` requires `label`.** A bar with no accessible name does not say
+  what the progress is about, and no other part of the component can deduce it.
+- **Zero literal hexes**, `Button` included. Rule 2 comes out as
+  `light:bg-brand-hull`, because the hull was already a token.
+- **Explicit `cursor-pointer`** on everything you press. Tailwind v4 removed
+  `cursor: pointer` for `button` from the preflight, so a button without the
+  class keeps the system arrow. It is carried by `Button`, `Checkbox`,
+  `RadioGroupItem`, `Switch`, `TabsTrigger`, `Select`'s trigger, the close
+  buttons of `Dialog`/`Sheet`/`Toast`, `PaginationLink`, the shell of the
+  clickable cards and the links in `Nav`, `Footer` and `Breadcrumb` — which
+  render an `<a>` with no `href` when a router's `Link` is plugged into them.
+
+  Two deliberate exceptions. `Label` points at a control but is not the control.
+  And the **menu items** of `Select` and `DropdownMenu` stay on `cursor-default`:
+  a native menu does not show the pointing hand, and the row highlight already
+  says the row responds.
+
+### The syntax palette
+
+Straight from the document: «keywords sand, strings biolume, comments plankton,
+identifiers foam», over hull. Four colors on purpose — functions, variables and
+types all land on foam, because the system communicates with color and border and
+not with chromatic noise. Numbers and booleans ride with strings: the document
+does not assign them, and grouping them under «they are literals» is more
+coherent than introducing a fifth color.
+
+Measured over `brand.hull` #0B1524, all AA:
+
+| role | token | contrast |
 | --- | --- | --- |
-| identificador | `textPrimary` | 16.42:1 |
+| identifier | `textPrimary` | 16.42:1 |
 | literal | `accent` | 10.05:1 |
-| palabra clave | `warm` | 9.05:1 |
-| comentario | `textMuted` | 5.43:1 |
-| invalidez | `error` | 4.97:1 |
+| keyword | `warm` | 9.05:1 |
+| comment | `textMuted` | 5.43:1 |
+| invalid | `error` | 4.97:1 |
 
-`brand.body` (#3E7CB1) no entra: el sistema lo restringe a relleno y aquí mide
-4.2:1.
+`brand.body` (#3E7CB1) is not in it: the system restricts it to fill and here it
+measures 4.2:1.
 
-Vivía escrita a mano en `eduardoalvarez.dev/src/settings/shiki-reef.ts`, y ahí
-dentro se había quedado un `#E05252` — justo el hex que este README dice que está
-mal. Es el caso de libro de por qué la paleta no puede vivir dentro de un
-proyecto: el tema se genera desde `tokens.sintaxis` y el rojo sale corregido solo.
+It used to live hand-written in
+`eduardoalvarez.dev/src/settings/shiki-reef.ts`, and a `#E05252` had been left
+inside it — precisely the hex this README says is wrong. It is the textbook case
+for why the palette cannot live inside a project: the theme is generated from
+`tokens.syntax` and the red comes out corrected on its own.
 
-### Temas anidables
+### Nestable themes
 
-`theme.css` emite un bloque por modo, no solo el claro. Así un subárbol puede
-declarar el modo contrario al de la página y todo lo de dentro lo respeta.
+`theme.css` emits one block per mode, not just the light one. That way a subtree
+can declare the opposite mode to the page and everything inside honours it.
 
-Lo usa `CodeBlock`: `brand.hull` es «fondo de bloques de código», así que un
-bloque es oscuro también en modo claro — y ahí `textPrimary` es casi negro. La
-raíz del bloque declara `data-theme="dark"` y la tinta se resuelve sola. Es la
-única isla de tema invertido del sistema, y es deliberada.
+`CodeBlock` uses it: `brand.hull` is «the background of code blocks», so a block
+is dark in light mode too — and there `textPrimary` is nearly black. The block's
+root declares `data-theme="dark"` and the ink resolves itself. It is the system's
+only island of inverted theme, and it is deliberate.
 
-### Las tarjetas y la regla 6
+### The cards and rule 6
 
-`ArticleCard`, `TalkCard`, `CourseCard` y `LinkRow` comparten un casco interno
-que no se publica, para que la regla 6 viva en un solo sitio: el hover cambia el
-borde de `hairline` a `hairlineHover` y tiñe el título de acento. Nada más.
+`ArticleCard`, `TalkCard`, `CourseCard` and `LinkRow` share an internal shell
+that is not published, so rule 6 lives in exactly one place: the hover changes
+the border from `hairline` to `hairlineHover` and tints the title with accent.
+Nothing else.
 
-`LinkRow` viene de `links/src/components/Card.astro`, que escalaba la tarjeta al
-102 %, subía el título un píxel y giraba y agrandaba el icono — cuatro
-movimientos que el sistema no permite.
+`LinkRow` comes from `links/src/components/Card.astro`, which scaled the card to
+102 %, lifted the title by a pixel and rotated and enlarged the icon — four
+movements the system does not allow.
 
-Ninguna tarjeta depende de un enrutador: por defecto renderizan un `<a href>`, y
-`asChild` deja enchufar el `Link` de Next o de Astro.
+No card depends on a router: by default they render an `<a href>`, and `asChild`
+lets Next's or Astro's `Link` be plugged in.
 
-### `AudioPlayer` — qué cambió al migrarlo
+### `AudioPlayer` — what changed on migration
 
-La lógica no se reescribió. Los tres modos, el reproductor flotante, los saltos
-de ±15s, el ciclo de velocidad 1 → 1.25 → 1.5 → 1.75 → 2 y el volumen con mute
-son los del portafolio. Lo que cambió:
+The logic was not rewritten. The three modes, the floating player, the ±15s
+skips, the 1 → 1.25 → 1.5 → 1.75 → 2 speed cycle and the volume with mute are the
+portfolio's. What changed:
 
-**Dos dependencias que un paquete no puede tener.** `Icon` del portafolio pasó a
-`src/lib/glyphs.tsx` con los trazados idénticos; `trackEvent` pasó a la prop
-`onFirstPlay`, que sigue disparándose una sola vez por carga.
+**Two dependencies a package cannot have.** The portfolio's `Icon` became
+`src/lib/glyphs.tsx` with identical paths; `trackEvent` became the `onFirstPlay`
+prop, which still fires exactly once per load.
 
-**Un cambio de API.** `compact`/`banner` como dos booleanos pasaron a
-`mode="full" | "compact" | "banner"`, que es el vocabulario con el que ya se
-describían los tres modos. Hay que tocar las llamadas del portafolio en la Fase 6.
+**One API change.** `compact`/`banner` as two booleans became
+`mode="full" | "compact" | "banner"`, which is the vocabulary the three modes were
+already described with. The portfolio's call sites need touching in Phase 6.
 
-**Tres animaciones que el sistema no permite.** La onda ya no anima `scaleY` — las
-barras siguen distinguiendo reproducción de pausa por opacidad. El flotante
-aparece y desaparece en vez de deslizarse. La barra de progreso ya no interpola
-el ancho, que además la hacía ir por detrás del audio. El giro del spinner de
-carga se queda, con la misma justificación que en `Button`.
+**Three animations the system does not allow.** The waveform no longer animates
+`scaleY` — the bars still tell playback from pause by opacity. The floating
+player appears and disappears instead of sliding. The progress bar no longer
+interpolates its width, which also made it lag behind the audio. The loading
+spinner's spin stays, with the same justification as in `Button`.
 
-**Un fallo de contraste heredado.** El botón de velocidad ponía `textMuted` sobre
-`surfaceRaised`: 4.07:1 en oscuro. Pasó a `textSecondary`. El original arrastra
-ese fallo.
+**An inherited contrast failure.** The speed button put `textMuted` over
+`surfaceRaised`: 4.07:1 in dark. It moved to `textSecondary`. The original still
+carries that failure.
 
-**Un `bug` latente.** Las piezas del reproductor viven a nivel de módulo, no
-dentro del componente. Declaradas dentro, cambian de identidad en cada render y
-React las remonta: con `timeupdate` disparando cuatro veces por segundo, el
-arrastre de la barra perdía el pointer capture.
+**A latent bug.** The player's pieces live at module level, not inside the
+component. Declared inside, they change identity on every render and React
+remounts them: with `timeupdate` firing four times a second, dragging the bar
+lost pointer capture.
 
-### La marca
+### The brand
 
-Las trece piezas de Tiburoncín estaban repartidas por los cinco proyectos, byte
-a byte idénticas. Se consolidaron en `assets/brand/` y se publican en el
-paquete; se sirven en `/brand`, que es la misma ruta que todos usan ya desde su
-`public/`, así que el valor por defecto de `basePath` funciona sin configurar
-nada.
+Tiburoncín's thirteen pieces were scattered across the five projects,
+byte-for-byte identical. They were consolidated into `assets/brand/` and are
+published in the package; they are served at `/brand`, the same path everyone
+already uses from their `public/`, so `basePath`'s default works with nothing to
+configure.
 
 ```tsx
-import { Logo, Mascota, CaraDeMascota, listaCaras } from '@eduardoalvarez/arrecife/brand';
+import { Logo, Mascot, MascotFace, faceList } from '@eduardoalvarez/arrecife/brand';
 ```
 
 | | |
 | --- | --- |
-| aletas | `fin.png` (dos azules) y `fin-foam.png` (silueta espuma) |
-| caras | annoyed · confused · hearts · laughing · shades · waiting · wink |
+| fins | `fin.png` (two blues) and `fin-foam.png` (foam silhouette) |
+| faces | annoyed · confused · hearts · laughing · shades · waiting · wink |
 | poses | desk · laptop-coffee · peek · surf |
 
-Los nombres son un tipo: una cara que no existe no compila, y el autocompletado
-ofrece las que hay. Añadir una es soltar el PNG y añadir una línea al catálogo.
+The names are a type: a face that does not exist will not compile, and
+autocomplete offers the ones that do. Adding one means dropping the PNG in and
+adding a line to the catalog.
 
-**Regla 1 como API.** `sobre="oscuro"` usa la silueta a una tinta y
-`sobre="claro"` la de dos azules. No es una nota en una guía: es una prop. El
-análisis de píxeles lo confirma — el 94 % de `fin-foam.png` es `#EDF4F3`, o sea
-el token espuma.
+**Rule 1 as API.** `background="dark"` uses the single-ink silhouette and
+`background="light"` the two-blue one. It is not a note in a guide: it is a prop.
+Pixel analysis confirms it — 94 % of `fin-foam.png` is `#EDF4F3`, which is the
+foam token.
 
-**Regla 5 como API.** El wordmark sale de `naming.wordmark` y siempre dice
-«Eduardo Álvarez». No hay ninguna prop que permita cambiar ese texto, y
-Tiburoncín no aparece escrito dentro del logo.
+**Rule 5 as API.** The wordmark comes from `naming.wordmark` and always reads
+«Eduardo Álvarez». There is no prop that changes that text, and Tiburoncín never
+appears written inside the logo.
 
-**Regla 4 como API.** Las caras van solo en estados vacíos, confirmaciones,
-errores, progreso de curso y celebración. La regla vive en qué componentes
-aceptan una cara, no en la documentación.
+**Rule 4 as API.** The faces only go in empty states, confirmations, errors,
+course progress and celebration. The rule lives in which components accept a
+face, not in the documentation.
 
-El formato es un detalle de implementación: cuando lleguen los SVG, se
-reemplazan los archivos y no cambia una línea de código.
+The format is an implementation detail: when the SVGs arrive, the files get
+replaced and not a line of code changes.
 
-### Los ocho que se añadieron después
+### The eight added afterwards
 
-No estaban en la lista original. Entraron midiendo en cuántos de los cinco
-proyectos se usa cada uno, con el mismo criterio que sacó a `Hero` y
-`NewsletterSection`.
+They were not on the original list. They got in by measuring how many of the five
+projects use each one, with the same criterion that took `Hero` and
+`NewsletterSection` out.
 
-| | archivos que lo usan | por qué |
+| | files using it | why |
 | --- | --- | --- |
-| `Card` | 34, en 4 proyectos | Es la única definición de qué es una superficie de tarjeta. Las cuatro tarjetas con dominio reutilizan sus clases. |
-| `Label` | 21, en 2 | Había siete controles de formulario y ninguna etiqueta. |
-| `Avatar` | 19, en 3 | Uno solo para todo: no hay un `brand/Avatar` aparte, porque una foto de perfil es esto con otro `src`. |
-| `Sheet` | 6, en 3 | Es `Dialog` con variante de lado. |
-| `Separator` | 8, en 2 | `hairline` era un token sin componente. |
-| `Popover` | 5, en 3 | Base de cualquier selector desplegable. |
-| `DateField` | — | El control nativo, sin dependencias, para elegir fecha en un formulario. |
-| `Calendar` | 6, en 3 | Calendario mensual navegable, para el planificador de contenido. `fullWidth` lo estira al ancho del contenedor. |
+| `Card` | 34, across 4 projects | It is the only definition of what a card surface is. All four cards with a domain reuse its classes. |
+| `Label` | 21, across 2 | There were seven form controls and no label. |
+| `Avatar` | 19, across 3 | One for everything: there is no separate `brand/Avatar`, because a profile photo is this with a different `src`. |
+| `Sheet` | 6, across 3 | It is `Dialog` with a side variant. |
+| `Separator` | 8, across 2 | `hairline` was a token with no component. |
+| `Popover` | 5, across 3 | The base of any dropdown selector. |
+| `DateField` | — | The native control, dependency-free, for picking a date in a form. |
+| `Calendar` | 6, across 3 | A navigable month calendar, for the content planner. `fullWidth` stretches it to the container's width. |
+
+There is no `DatePicker`: it is `Popover` plus `Calendar` and it is five lines. A
+third component that only glues together two that already exist is API surface to
+maintain for nothing.
+
+`Popover` requires `aria-label` or `aria-labelledby` in the type. Radix puts
+`role="dialog"` on the content, and a dialog with no accessible name says nothing
+to a screen reader: now it cannot be forgotten because it does not compile.
+
+### The fifth motion exception: the footer's caret
+
+The CLI signature ends in a block caret that blinks, behind `motion-safe`. It is
+the first exception that is not feedback about progress, so it needed a different
+argument.
+
+The signature is a **prompt** — that is why it is mono, why the `$` is in accent
+and why it sits in a footer instead of a `<p>` saying «© 2026». A prompt whose
+caret does not blink is a terminal that has hung, and a still block at the end of
+a line reads as a stray character.
+
+So the criterion splits in two. The first four exceptions are feedback about
+progress or spatial continuity; this one is legibility: it is not decoration, it
+is what makes the piece readable as what it is. `step-end` and not a fade,
+because a real caret is on or off and easing it turns a terminal into a pulsing
+dot. See `docs/decisions.md` § 23.
+
+### The second motion exception
+
+`Sheet` slides. It is the second and last exception to «no displacement»,
+approved knowingly: a panel entering from an edge, held still, would be an
+off-centre modal. It lasts `--duration-standard` with `--ease-standard` — the
+same time and the same curve as any color change — so it introduces no new
+timing, and it sits behind `motion-safe`.
+
+`Calendar` does **not** animate the month change: react-day-picker's `animate`
+stays on its default, which is off.
+
+### The danger variant, and where it does not go
+
+`Button` has `destructive` and `destructiveOutline` since 0.6.0. For four
+versions it had neither, on an argument that is still half right: inside an
+`AlertDialog` the confirm button is **not** red, because a title explains what is
+about to happen, focus starts on cancel and clicking outside does not close it.
+The context does the work and a red button on top of it is shouting.
+
+What broke the argument is the table row. `cursos` has eight destructive buttons
+in row actions and toolbars, next to «Editar» and «Duplicar», with nothing around
+them doing that work — and rendered as `secondary`, «Eliminar curso» looked
+exactly like «Cancelar».
+
+The palette is not `error`, and the reason is the role. `error` is a text color:
+it reads against a dark surface, so it sits mid-red. `danger` is a fill: what
+reads is the ink on top of it, so it goes lighter. Same split as `accent` and
+`accentOn`. In light mode both land on `#C0392B`, because over paper a red dark
+enough to carry white ink is also the red that reads as text.
+
+| | dark | light |
+| --- | --- | --- |
+| ink over fill | 6.53 | 5.11 |
+| ink over hover | 7.92 | 6.61 |
+| fill over background | 6.71 | 4.87 |
+| fill over surfaceRaised | 4.91 | **4.50** |
+
+That last cell is exactly on the AA line, which is where every light semantic in
+this palette sits. It matters because it is the outline variant's border and
+text, and `surfaceRaised` is where a toolbar lives.
+
+`destructiveOutline` fills on hover, and that is a declared exception to
+«secondary is never filled» — a destructive that looks identical to a secondary
+until you read it is the problem the variant exists to fix. See
+`docs/decisions.md` § 21.
+
+### `icon-sm`, for the one admin app
 
-No hay `DatePicker`: son `Popover` más `Calendar` y son cinco líneas. Un tercer
-componente que solo pega dos que ya existen es superficie de API que mantener sin
-ganar nada.
+42×42 is the right measure for a control you hit with a thumb, and four of the
+five projects are reading sites where that fits. `cursos` is the odd one out:
+three actions per table row, and at 42 the row grows with them.
 
-`Popover` exige `aria-label` o `aria-labelledby` en el tipo. Radix le pone
-`role="dialog"` al contenido, y un diálogo sin nombre accesible no le dice nada a
-un lector de pantalla: ahora no se puede olvidar porque no compila.
+`size="icon-sm"` is 32×32, and it is 32 and not the 28 that project actually had:
+32 is `sm`'s height, so a dense icon button lines up with a small text button and
+a toolbar mixing the two stays on one baseline. It does not replace `icon` — a
+page's primary action stays at 42. See `docs/decisions.md` § 22.
+
+### The theme script, and the mode a site already decided
+
+```astro
+<script is:inline set:html={themeScript({ base: 'dark' })} />
+```
 
-### La segunda excepción de movimiento
+Until 0.6.0 `themeScript` was a fixed string and resolved stored choice →
+`prefers-color-scheme` → dark. That is the right default for a library, and it
+was wrong for all five of these projects: they are dark BY DECISION, and
+`eduardoalvarez.dev`'s own script said so out loud — «dark is the brand's PRIMARY
+mode, so it's the default and doesn't follow the OS setting». With the OS in
+charge, a reader whose machine is in light mode saw the blog in light.
 
-`Sheet` se desliza. Es la segunda y última excepción a «nada de desplazamiento»,
-aprobada a sabiendas: un panel que entra desde un borde quieto sería un modal
-descentrado. Dura `--duration-standard` con `--ease-standard` —lo mismo y con la
-misma curva que cualquier cambio de color— así que no introduce un tiempo nuevo,
-y va detrás de `motion-safe`.
+There was no way to say otherwise, so those projects kept their own
+`public/theme.js` and the library published the hard part for nobody. Migrating
+just the button did not help either: `ThemeToggle` persists under
+`arrecife-theme` and their script read `theme`, so the two would have gone out of
+step.
 
-`Calendar` **no** anima el cambio de mes: `animate` de react-day-picker se queda
-en su valor por defecto, que es apagado.
+`base` stops the OS from being consulted at all. A stored choice still wins over
+it — it sets what happens when nobody has chosen yet, not what happens instead of
+choosing, so the toggle keeps working.
 
-### `Text` — la escala como API
+### `Text` — the scale as API
 
-`Text` no estaba en la lista original y se añadió después, porque sin él la
-escala solo existía como clases sueltas y nada impedía poner `text-display` en un
-párrafo. Tres reglas del sistema viven dentro del componente:
+`Text` was not on the original list and was added later, because without it the
+scale only existed as loose classes and nothing stopped anyone putting
+`text-display` on a paragraph. Three of the system's rules live inside the
+component:
 
-| regla | cómo se aplica |
+| rule | how it is applied |
 | --- | --- |
-| display solo para titulares, nunca cuerpo | la familia va atada a la escala; no existe una prop `font` |
-| el peso y el tracking son de la escala | vienen del token `--text-*` y no se exponen |
-| medida máxima de cuerpo 68ch | `body` la aplica solo; `measure={false}` la quita |
+| display for headlines only, never body | the family is bound to the scale; no `font` prop exists |
+| weight and tracking belong to the scale | they come from the `--text-*` token and are not exposed |
+| maximum body measure 68ch | `body` applies it on its own; `measure={false}` removes it |
 
-`as` y `variant` son independientes a propósito: un encabezado de segundo nivel
-que tiene que verse más pequeño es `<Text as="h2" variant="h3">`, no un `h3` que
-miente sobre la jerarquía de la página.
+`as` and `variant` are independent on purpose: a second-level heading that has to
+look smaller is `<Text as="h2" variant="h3">`, not an `h3` that lies about the
+page hierarchy.