@eduardoalvarez/arrecife 0.6.0 → 0.8.0

package/llms.txt

@@ -41,7 +41,7 @@ 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.
 
-**It ships no `lucide-react` and no icon library.** The glyphs the components
+**It ships no icon set.** The glyphs the components
 need are inline, inherit `currentColor` and measure 1em.
 
 ## Tailwind configuration
@@ -116,23 +116,27 @@ that only whoever uses them installs.
 | `@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 ten social icons, loose. No `"use client"` |
+| `@eduardoalvarez/arrecife/social/data` | **no** | — | The same ten as shapes, plus `socialSvg`. For a template that mounts no React |
+| `@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/chart` | yes | `recharts` | The chart chassis, the series palette and the three chart types |
 | `@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` and `./chart` sit outside the root for the symmetric reason: if they
-hung off the main index, the projects that draw no charts and use no React Hook
-Form would have to install those dependencies anyway so their bundler could
-resolve an import they never execute.
+`./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/`. They render React and their Radix primitives call `createContext` at
+`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`.
@@ -143,9 +147,13 @@ import in an adapter of your own marked `"use client"` — that was the workarou
 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. If all you need are classes — for a `<div>`, an
+The six portable subpaths do NOT carry the directive, and that is the half that
+matters in a Server Component: `./tokens`, `./theme`, `./variants`, `./social/data`,
+`./og` and `./shiki` stay on the server. Neither does `./social`, which is a third
+case: it renders React — it is ten `<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:
 
@@ -202,21 +210,324 @@ 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>`.
 
-### The social icons are namespaced
+### `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.
+
+### `Nav` is two slots and one height
+
+Almost everything an app shell wants from a site bar is already a slot:
+
+```tsx
+<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 `decisions/0.7.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 nav item carrying `aria-current` |
+| `quiet` | `light` | Furniture: a marker in a metadata row, not a control and not a state |
+
+```tsx
+<NavItem href="/cursos" active icon={<Icon as={GraduationCap} tone="current" />}>
+  cursos
+</NavItem>
+```
+
+`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 `decisions/0.7.md` § 29 and § 35.
+
+### `Stat`'s delta says direction, not judgement
 
 ```tsx
-// ❌ does not exist
+<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 `decisions/0.7.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 `decisions/0.7.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 two shapes of `Footer`
+
+```tsx
+// The default. Stacked rows, signature level with the first one.
+<Footer brand={<Logo />} social={SOCIAL} />
+
+// `full`. Brand and description on the left, link columns on the right,
+// signature closing the piece behind a hairline.
+<Footer
+  variant="full"
+  brand={<Logo />}
+  description="Cursos para construir con IA, directos y al grano."
+  columns={[
+    { title: 'Aprendizaje', links: [{ label: 'Cursos', href: '/cursos' }] },
+    { title: 'Legal', links: [{ label: 'Términos', href: '/terminos' }] },
+  ]}
+  social={SOCIAL}
+  action={<Button variant="tertiary" size="sm">Reportar un problema</Button>}
+  linkAsChild={({ href, children }) => <Link href={href}>{children}</Link>}
+/>
+```
+
+**Passing no `variant` is the default shape, and it is not a fallback**: two of
+the three sites that draw a footer want exactly that, and it has not changed.
+
+`columns`, `description`, `action` and `linkAsChild` exist ONLY on `full`. The
+props are a discriminated union, like `EmptyState`'s, so the default form cannot
+be handed one — if `tsc` rejects a `columns` you passed, you meant to pass
+`variant="full"` as well.
+
+Reach for `full` whenever the footer has links at all. **There is no other
+place to put them**: `Footer` takes no `children`, so a row of loose text links
+does not compile. That row existed until 0.8.0 and no project ever passed it —
+and columns are also the only way to say «this block changes with who is
+looking», an admin block against an account block, because they are data you
+build and not markup the library walks.
+
+The `./` in front of each column link is the component's, like `NavItem`'s, and
+it is `aria-hidden`. The column titles render as `<h3>`. Pass `linkAsChild` to
+plug in the router's `Link`; without it the columns are plain `<a>` and every
+navigation costs a page load.
+
+### `Table` brings its own surface
+
+```tsx
+// ✅ this is the whole thing
+<Table>…</Table>
+
+// ❌ two borders. The radius, the border and the clip are the component's
+<div className="rounded-lg border border-border bg-card overflow-hidden">
+  <Table>…</Table>
+</div>
+```
+
+`Table` draws `rounded-card`, `border-hairline` and the clip on the same
+container that scrolls it horizontally. Do not wrap it in a surface of your own,
+and do not add `overflow-hidden`: `TableRow`'s hover tint is already clipped by
+the corners, which is what the wrapper used to be for.
+
+`className` reaches the `<table>`, not the container, so a `rounded-none` from
+the call site does nothing.
+
+### The three chart types, and the names they took
+
+```tsx
+import { AreaChart, BarChart, LineChart } from '@eduardoalvarez/arrecife/chart';
+
+<AreaChart
+  label="Registros nuevos por día"
+  summary="Sube de 24 a 52 con una caída en mayo."
+  height={200}
+  data={data}
+  series={[{ key: 'count', label: 'Registros' }]}
+  xKey="day"
+/>
+```
+
+`data`, `series` and `xKey`, plus the mandatory `label`. The gradient, the grid,
+the axes and the tooltip belong to the component — that composition is the system
+drawing, and writing it at the call site is how it drifts.
+
+**These are NOT Recharts' components of the same name.** Import ours; do not
+import both in one file. Recharts' `Area`, `Line` and `XAxis` are still not
+re-exported, because they are unchanged and wrapping them buys nothing.
+
+`BarChart`'s `orientation` is named for what you see: `horizontal` lays the bars
+down for a ranking. Recharts calls that same thing `layout="vertical"` — if you
+are porting code, the value flips.
+
+`stacked` on `AreaChart` and `BarChart` adds the series up. Without it areas
+overlap, which is honest and rarely what you want with more than one series: to
+COMPARE rather than add up, the type is `LineChart`.
+
+Anything that is not a series over a category axis has no type and is not missing
+one. A doughnut is `ChartContainer` plus Recharts' `Pie` with `SERIES_COLORS`.
+
+### 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 />
 ```
 
-All nine: `GitHub`, `LinkedIn`, `X`, `Instagram`, `Discord`, `YouTube`, `Rss`,
-`Email`, `Newsletter`. They live under a namespace because one of them is called
-`X`, and loose it collides. `Newsletter` is the bell: a way to follow, like
-`Rss`, named for what it means.
+All ten: `GitHub`, `LinkedIn`, `X`, `Instagram`, `Discord`, `YouTube`, `Rss`,
+`Email`, `Newsletter`, `Website`. `Newsletter` is the bell: a way to follow, like
+`Rss`, named for what it means. `Website` is «my other site» — the personal
+domain in a footer full of networks — and it is what replaces borrowing a globe
+from an icon set, which brings its own stroke weight and its own margins.
+
+Six are brands and go SOLID, four are functional and use a 1.6 stroke. A row that
+mixes the two pens is the normal case, not a defect: a brand is somebody else's
+silhouette and cannot be outlined, and a symbol the system draws itself has no
+owner to be faithful to.
+
+**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 }`.
+
+**If you mount no React, the shapes are published too.** `./social/data` imports
+nothing, so an `.astro` that ships no framework JavaScript can draw the same
+glyph instead of pasting the `<path>` into the project:
+
+```astro
+---
+import { socialSvg } from '@eduardoalvarez/arrecife/social/data';
+---
+<Fragment set:html={socialSvg('GitHub', { class: 'size-[19px]' })} />
+```
+
+`socialGlyphs` is the catalogue keyed by name, `socialNames` is the ten names in
+order, and every glyph is exported on its own — `gitHubGlyph`, `websiteGlyph` —
+if you want the shapes rather than the markup. The React components are drawn
+from that same file, so the two renderings cannot disagree. Reaching for
+`socialGlyphs` or `socialSvg` names all ten, which is the price of iterating a
+catalogue; `import { LinkedIn }` still costs one shape.
 
 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
@@ -240,7 +551,7 @@ same value is available in both places and they cannot disagree.
 | `control.md` | `--spacing-control-md` | `px-control-md` |
 | `control.icon` | `--spacing-control-icon` | `size-control-icon` (42×42) |
 | `gradient[mode].hero` | `--gradient-hero` | `gradient-hero` |
-| `size.nav` | `--spacing-nav` | `h-nav` |
+| `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` |
@@ -256,7 +567,7 @@ 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>.
+<https://github.com/Proskynete/arrecife/blob/main/docs/runbooks/migration-0.3.md>.
 
 ## System rules the consuming code must not break
 
@@ -269,10 +580,16 @@ compiles and looks wrong, or that fails the project's accessibility audit.
 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.
+   already carry the weight. See `decisions/0.6.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.
+   they will stay. There are five declared exceptions, all behind `motion-safe`
+   and all with a reason written down: the `Button loading` spinner, `Sheet`'s
+   side panel, `Skeleton`'s shimmer, `Accordion`'s height and the `pulse-accent`
+   halo the footer signature ends in. All five are the same criterion — feedback
+   about progress or about spatial continuity — and a sixth lands on it or it
+   does not exist. The `caret` blink 0.6.0 shipped is removed in 0.8.0; it was
+   the only member of the second criterion § 23 opened for it.
 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
@@ -288,6 +605,11 @@ compiles and looks wrong, or that fails the project's accessibility audit.
 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 `decisions/0.7.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.
 
@@ -586,7 +908,7 @@ Source: `src/primitives/date-field.tsx`
 
 A date field on the native control, not on a calendar of our own.
 
-- Extends: `Omit<ComponentPropsWithoutRef<'input'>, 'type'>`
+- Extends: `Omit<ComponentProps<'input'>, 'type'>`
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
@@ -675,7 +997,9 @@ No entrance animation: the menu appears, it does not unfold.
 
 Source: `src/primitives/input.tsx`
 
-- Extends: `ComponentPropsWithoutRef<'input'>`
+`ComponentProps` and not `ComponentPropsWithoutRef`, and the difference is a bug and not a preference.
+
+- Extends: `ComponentProps<'input'>`
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
@@ -687,7 +1011,7 @@ Source: `src/primitives/label.tsx`
 
 The `label` scale: 13px, which is the system's absolute minimum on screen.
 
-- Extends: `ComponentPropsWithoutRef<typeof LabelPrimitive.Root>`
+- Extends: `ComponentProps<typeof LabelPrimitive.Root>`
 - No own props: it passes through those of the element or primitive it wraps.
 
 ### Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis
@@ -871,7 +1195,7 @@ The knob changes position, but is not animated while doing so: the position IS t
 Source: `src/primitives/table.tsx`
 
 **Table**
-The container scrolls horizontally: the page never does.
+The table, and the surface it sits on. The two are one piece.
 
 - No own props: it passes through those of the element or primitive it wraps.
 
@@ -894,6 +1218,8 @@ The container scrolls horizontally: the page never does.
 - No own props: it passes through those of the element or primitive it wraps.
 
 **TableCaption**
+The caption, at the bottom and INSIDE the surface.
+
 - No own props: it passes through those of the element or primitive it wraps.
 
 ### Tabs, TabsList, TabsTrigger, TabsContent
@@ -917,7 +1243,9 @@ Source: `src/primitives/tabs.tsx`
 
 Source: `src/primitives/textarea.tsx`
 
-- Extends: `ComponentPropsWithoutRef<'textarea'>`
+`ComponentProps` carries `ref`, which React 19 passes as a prop. See `InputProps`.
+
+- Extends: `ComponentProps<'textarea'>`
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
@@ -968,7 +1296,7 @@ Source: `src/primitives/typography.tsx`
 
 ## Components
 
-Imported from `@eduardoalvarez/arrecife`. 24 exports.
+Imported from `@eduardoalvarez/arrecife`. 21 exports.
 
 ### ArticleCard
 
@@ -976,7 +1304,7 @@ Source: `src/components/article-card/index.tsx`
 
 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.
 
-- Extends: `Omit<CardShellProps, 'children' \| 'title'>`
+- Extends: `Omit<CardShellProps, "children" \| "title">`
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
@@ -1078,17 +1406,17 @@ Source: `src/components/course-card/index.tsx`
 
 Source: `src/components/empty-state/index.tsx`
 
-The mascot's most important rule, finally as code.
-
-- Extends: `Omit<ComponentPropsWithoutRef<'div'>, 'title'>`
+- 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; } )`
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `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"` | yes |  | The face. Mandatory: without it this is a centred paragraph. |
+| `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
 
@@ -1108,26 +1436,24 @@ Source: `src/components/event-calendar/index.tsx`
 | `onUpdateEvent` | `(event: CalendarEvent) => void` |  |  |  |
 | `selected` | `Date` |  |  | Selected day, if the project controls it. Without it, it starts on today. |
 
-### Footer, FooterLink
+### Footer
 
 Source: `src/components/footer/index.tsx`
 
-**Footer**
-- Extends: `ComponentPropsWithoutRef<'footer'>`
+- Extends: `FooterBase & ( \| { /** The shape the library has always had: stacked rows and the signature at the top right. */ variant?: 'default' \| undefined; columns?: never; description?: never; action?: never; linkAsChild?: never; } \| { /** `full`: brand and description on the left, link columns on the right, signature closing it. */ variant: 'full'; /** The link columns. Mandatory: without them `full` is the default form with extra steps. */ columns: readonly FooterColumn[]; /** One line under the brand, saying what the site is. */ description?: ReactNode; /** An action under the row of icons — «Reportar un problema». Usually a tertiary button. */ action?: ReactNode; /** * Renders the column links through the child, to plug in the framework's * `Link`. It receives each `href` in the Slot's `props`. * * It is § 24's rule applied where it now bites: a column turns data into * markup, so without a slot the only way to reach one of those links * from a project is to select it by structure or by a style class, and * neither is a contract. `Breadcrumb` and `ArticleCard` have the same * signature on purpose. * * It is also what a client-side transition needs: `cursos` reached for * it the moment its columns stopped being `<a>` tags. */ linkAsChild?: ((props: { href: string; children: ReactNode }) => ReactNode) \| undefined; } )`
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
+| `action` | `ReactNode` |  |  | An action under the row of icons — «Reportar un problema». Usually a tertiary button. |
 | `brand` | `ReactNode` |  |  | The brand row: the fin and the wordmark, at the very top. |
+| `columns` | `readonly FooterColumn[]` |  |  | The link columns. Mandatory: without them `full` is the default form with extra steps. |
+| `description` | `ReactNode` |  |  | One line under the brand, saying what the site is. |
+| `linkAsChild` | `(props: { href: string; children: ReactNode; }) => ReactNode` |  |  | Renders the column links through the child, to plug in the framework's `Link`. It receives each `href` in the Slot's `props`. |
+| `signatureHref` | `string` |  |  | Makes the domain inside the signature a link, keeping the `$`, the path and the prompt's mark as text. |
 | `social` | `readonly SocialLink[]` |  |  |  |
+| `variant` | `"full" \| "default"` |  |  | The shape the library has always had: stacked rows and the signature at the top right. `full`: brand and description on the left, link columns on the right, signature closing it. |
 | `year` | `number` |  | `new Date().getFullYear()` | The signature's year. |
 
-**FooterLink**
-- Extends: `ComponentPropsWithoutRef<'a'>`
-
-| prop | type | req. | default | what it does |
-| --- | --- | --- | --- | --- |
-| `asChild` | `boolean \| undefined` |  | `false` |  |
-
 ### Hero
 
 Source: `src/components/hero/index.tsx`
@@ -1167,7 +1493,7 @@ Migrated from `links/src/components/Card.astro`. The original scaled the card to
 Source: `src/components/nav/index.tsx`
 
 **Nav**
-The site bar: 64px, abyss at 86 % and a 14px blur behind it.
+The site bar: 64px, abyss at 86 % and a 14px blur behind it — 56 when it shares the screen with a sidebar.
 
 - Extends: `ComponentPropsWithoutRef<'header'>`
 
@@ -1175,6 +1501,7 @@ The site bar: 64px, abyss at 86 % and a 14px blur behind it.
 | --- | --- | --- | --- | --- |
 | `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**
 The `./` is put there by the component, not by whoever uses it.
@@ -1198,10 +1525,10 @@ Source: `src/components/newsletter-form/index.tsx`
 | `basePath` | `string` |  |  |  |
 | `description` | `ReactNode` |  |  |  |
 | `disclaimer` | `ReactNode` |  |  | The small print. It is the «sin spam», which is why it accepts a face. |
-| `errorMessage` | `ReactNode` |  | `No se pudo suscribir ese email. Revísalo y vuelve a intentar.` |  |
+| `errorMessage` | `ReactNode` |  | `No se pudo suscribir ese correo. Revísalo y vuelve a intentar.` |  |
 | `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` |  | `Email electrónico` |  |
+| `fieldLabel` | `string` |  | `Correo electrónico` |  |
 | `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` |  |
@@ -1212,7 +1539,7 @@ Source: `src/components/newsletter-form/index.tsx`
 | `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 email cada dos semanas, y nada más.` |  |
+| `successMessage` | `ReactNode` |  | `Ya estás dentro. Te llega un correo cada dos semanas, y nada más.` |  |
 | `title` | `ReactNode` | yes |  |  |
 
 ### PageHeader
@@ -1246,29 +1573,6 @@ How much you have read. It is NOT `Progress` under another name.
 | `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
-
-Source: `src/components/sidebar-nav/index.tsx`
-
-**SidebarItem**
-The blog admin's sidebar.
-
-- Extends: `ComponentPropsWithoutRef<'a'>`
-
-| prop | type | req. | default | what it does |
-| --- | --- | --- | --- | --- |
-| `active` | `boolean \| undefined` |  | `false` |  |
-| `asChild` | `boolean \| undefined` |  | `false` |  |
-| `badge` | `ReactNode` |  |  | Counter on the right: pending drafts, unused media. |
-
-**SidebarNav**
-- Extends: `ComponentPropsWithoutRef<'nav'>`
-
-| prop | type | req. | default | what it does |
-| --- | --- | --- | --- | --- |
-| `branch` | `ReactNode` |  |  |  |
-| `version` | `ReactNode` |  |  | Version and branch, at the bottom. |
-
 ### Stat
 
 Source: `src/components/stat/index.tsx`
@@ -1279,11 +1583,13 @@ A large metric: the number in the `stat` scale and its name underneath.
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
+| `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 beside the title, at 1em. It inherits `currentColor`, so it follows the title's tone and does not have to be tinted separately. |
+| `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. |
-| `tone` | `"neutral" \| "alerta"` |  | `neutral` | `alerta` only when the number IS the problem. |
+| `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/0.7.md` § 28. |
 | `value` | `ReactNode` | yes |  | The number, already formatted. The library imposes no locale. |
 
 ### TalkCard
@@ -1315,7 +1621,7 @@ The control that was missing. The library defined the whole theming system and e
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `label` | `string` |  | `Cambiar de theme` | Accessible name. The button has no visible text, so it is the only thing naming it. |
+| `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` |  |
@@ -1389,6 +1695,64 @@ Tiburoncín's head, with an expression.
 | `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. 10 exports.
+
+### GitHub, LinkedIn, X, Instagram, Discord, YouTube, Rss, Email, Newsletter, Website
+
+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.
+
+**Instagram**
+- No own props: it passes through those of the element or primitive it wraps.
+
+**Discord**
+- No own props: it passes through those of the element or primitive it wraps.
+
+**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.
+
+**Website**
+«My other site»: the personal domain in a footer full of social networks.
+
+- 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 |
+| --- | --- | --- | --- | --- |
+| `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`. |
+
 ## Forms
 
 Imported from `@eduardoalvarez/arrecife/form` · requires `react-hook-form`. 7 exports.
@@ -1434,9 +1798,9 @@ The layer that ties the controls to a form with validation and messages.
 
 ## Charts
 
-Imported from `@eduardoalvarez/arrecife/chart` · requires `recharts`. 5 exports.
+Imported from `@eduardoalvarez/arrecife/chart` · requires `recharts`. 8 exports.
 
-### ChartContainer, ChartTooltip, ChartLegend, ChartTooltipContent, ChartLegendContent
+### ChartContainer, ChartTooltip, ChartLegend, ChartTooltipContent, ChartLegendContent, AreaChart, BarChart, LineChart
 
 Source: `src/chart/index.tsx`
 
@@ -1483,12 +1847,85 @@ The legend, with the tooltip's same square swatch and the `label` scale.
 | `className` | `string` |  |  |  |
 | `payload` | `readonly ChartPayloadItem[]` |  |  |  |
 
+**AreaChart**
+A series over time, with the fill fading out underneath it.
+
+- Extends: `SeriesChartProps`
+
+| prop | type | req. | default | what it does |
+| --- | --- | --- | --- | --- |
+| `data` | `readonly ChartDatum[]` | yes |  |  |
+| `formatter` | `(value: unknown) => ReactNode` |  |  | Formats the value in the tooltip. The library imposes no locale. |
+| `height` | `number` |  |  | 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. |
+| `legend` | `boolean \| undefined` |  |  | Shows the legend. It defaults to «only when there is more than one series»: a legend naming the one line already named by the chart's own heading is a row of pixels that says nothing. |
+| `series` | `readonly ChartSeries[]` | yes |  |  |
+| `stacked` | `boolean \| undefined` |  | `false` | Adds the series up instead of overlaying them. |
+| `summary` | `ReactNode` |  |  | What the chart says, in words. It goes in a visually hidden `figcaption`. |
+| `xKey` | `string` | yes |  | The key on the category axis: the day, the month, the course. |
+
+**BarChart**
+Bars, upright or lying down.
+
+- Extends: `SeriesChartProps`
+
+| prop | type | req. | default | what it does |
+| --- | --- | --- | --- | --- |
+| `data` | `readonly ChartDatum[]` | yes |  |  |
+| `formatter` | `(value: unknown) => ReactNode` |  |  | Formats the value in the tooltip. The library imposes no locale. |
+| `height` | `number` |  |  | 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. |
+| `legend` | `boolean \| undefined` |  |  | Shows the legend. It defaults to «only when there is more than one series»: a legend naming the one line already named by the chart's own heading is a row of pixels that says nothing. |
+| `orientation` | `"horizontal" \| "vertical"` |  | `vertical` | `vertical` grows the bars upwards, which is the default. `horizontal` is a ranking. |
+| `series` | `readonly ChartSeries[]` | yes |  |  |
+| `stacked` | `boolean \| undefined` |  | `false` | Stacks the series instead of putting them side by side. |
+| `summary` | `ReactNode` |  |  | What the chart says, in words. It goes in a visually hidden `figcaption`. |
+| `xKey` | `string` | yes |  | The key on the category axis: the day, the month, the course. |
+
+**LineChart**
+Lines, for comparing series against each other.
+
+- Extends: `SeriesChartProps`
+
+| prop | type | req. | default | what it does |
+| --- | --- | --- | --- | --- |
+| `data` | `readonly ChartDatum[]` | yes |  |  |
+| `formatter` | `(value: unknown) => ReactNode` |  |  | Formats the value in the tooltip. The library imposes no locale. |
+| `height` | `number` |  |  | 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. |
+| `legend` | `boolean \| undefined` |  |  | Shows the legend. It defaults to «only when there is more than one series»: a legend naming the one line already named by the chart's own heading is a row of pixels that says nothing. |
+| `series` | `readonly ChartSeries[]` | yes |  |  |
+| `summary` | `ReactNode` |  |  | What the chart says, in words. It goes in a visually hidden `figcaption`. |
+| `xKey` | `string` | yes |  | The key on the category axis: the day, the month, the course. |
+
 ## Exports that are not components
 
 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/social/data`
+
+| export | type | what it is |
+| --- | --- | --- |
+| `discordGlyph` | `SocialGlyph` | Discord's mark. Brand, so it is a solid silhouette. |
+| `emailGlyph` | `SocialGlyph` | The envelope. Functional, so it is a 1.6 stroke. |
+| `gitHubGlyph` | `SocialGlyph` | GitHub's mark. Brand, so it is a solid silhouette. |
+| `instagramGlyph` | `SocialGlyph` | Instagram's mark. Brand, so it is a solid silhouette. |
+| `linkedInGlyph` | `SocialGlyph` | LinkedIn's mark. Brand, so it is a solid silhouette. |
+| `newsletterGlyph` | `SocialGlyph` |  |
+| `rssGlyph` | `SocialGlyph` | The feed. Functional, so it is a 1.6 stroke — with one filled dot, because a ring that small reads as a smudge. |
+| `SOCIAL_STROKE_WIDTH` | `1.6` | The stroke width of a functional glyph, from the document. |
+| `SOCIAL_VIEW_BOX` | `"0 0 24 24"` | The grid every glyph is drawn on. |
+| `socialGlyphs` | `{ Discord, Email, GitHub, Instagram, LinkedIn, Newsletter, Rss, Website, X, YouTube }` | The whole catalogue, keyed by the name each glyph is exported under in `./social`. |
+| `socialNames` | `readonly ("Discord" \| "Email" \| "GitHub" \| "Instagram" \| "LinkedIn" \| "Newsletter" \| "Rss" \| "Website" \| "X" \| "YouTube")[]` | The ten names, in the order the catalogue declares them. |
+| `socialSvg` | `(name: "Discord" \| "Email" \| "GitHub" \| "Instagram" \| "LinkedIn" \| "Newsletter" \| "Rss" \| "Website" \| "X" \| "YouTube", extra?: Readonly<Record<string, string \| number>>): string` | One glyph as a complete `<svg>` string, for a template that cannot mount React. |
+| `websiteGlyph` | `SocialGlyph` | «My other site», and the reason it is here rather than borrowed. |
+| `xGlyph` | `SocialGlyph` | X's mark. Brand, so it is a solid silhouette. |
+| `youTubeGlyph` | `SocialGlyph` | YouTube's mark. Brand, so it is a solid silhouette. |
+
+Types (3): `SocialGlyph`, `SocialGlyphShape`, `SocialName`.
+
 ### `@eduardoalvarez/arrecife/variants`
 
 | export | type | what it is |
@@ -1521,7 +1958,7 @@ it: if the code does not mount React, that subpath is the one to import.
 | `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"]; }` | 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 content: 760; readonly wide: 1180; }` |  |
+| `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 }` |  |
@@ -1530,6 +1967,10 @@ it: if the code does not mount React, that subpath is the one to import.
 
 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 |
@@ -1561,6 +2002,15 @@ Types (2): `Theme`, `ThemeOptions`.
 
 Types (8): `Background`, `Face`, `Fin`, `IsotypeProps`, `LogoProps`, `MascotFaceProps`, `MascotProps`, `Pose`.
 
+### `@eduardoalvarez/arrecife/icons`
+
+| export | type | what it is |
+| --- | --- | --- |
+| `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. |
+
+Types (2): `IconProps`, `IconTone`.
+
 ### `@eduardoalvarez/arrecife/shiki`
 
 | export | type | what it is |
@@ -1576,7 +2026,7 @@ Types (1): `ShikiTheme`.
 | `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`.
+Types (10): `AreaChartProps`, `BarChartProps`, `ChartContainerProps`, `ChartDatum`, `ChartLegendContentProps`, `ChartPayloadItem`, `ChartSeries`, `ChartTooltipContentProps`, `LineChartProps`, `SeriesChartProps`.
 
 ### `@eduardoalvarez/arrecife/form`
 
@@ -1602,11 +2052,11 @@ Types (6): `ArticleData`, `BaseData`, `CourseData`, `DefaultData`, `SatoriNode`,
 | export | type | what it is |
 | --- | --- | --- |
 | `cn` | `(...inputs: ClassValue[]): string` |  |
-| `social` | `typeof import("src/lib/social")` |  |
+| `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 (60): `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`, `SidebarItemProps`, `SidebarNavProps`, `SkeletonProps`, `SocialLink`, `StatProps`, `SwitchProps`, `TableOfContentsProps`, `TabsProps`, `TalkCardProps`, `TextProps`, `TextareaProps`, `ThemeToggleProps`, `ToastOptions`, `ToastVariant`, `ToasterProps`, `TocEntry`.
+Types (60): `AccordionProps`, `AccordionTriggerProps`, `AlertProps`, `ArticleCardProps`, `AudioPlayerMode`, `AudioPlayerProps`, `AuthorCardProps`, `AvatarProps`, `AvatarUploadProps`, `BadgeProps`, `BlockquoteProps`, `BreadcrumbProps`, `ButtonProps`, `CalendarEvent`, `CalendarProps`, `CategoryBadgeProps`, `CheckboxProps`, `CodeBlockProps`, `CodeProps`, `CourseCardProps`, `Crumb`, `DateFieldProps`, `EmptyStateProps`, `EventCalendarProps`, `FooterColumn`, `FooterColumnLink`, `FooterProps`, `HeroProps`, `InputProps`, `LabelProps`, `LinkRowProps`, `MetricBadgeProps`, `NavItemProps`, `NavProps`, `NewsletterFormProps`, `NewsletterState`, `PageHeaderProps`, `PaginationLinkProps`, `PopoverContentProps`, `ProgressProps`, `RadioGroupItemProps`, `RadioGroupProps`, `ScrollingProgressBarProps`, `SeparatorProps`, `SheetContentProps`, `SkeletonProps`, `SocialLink`, `StatDelta`, `StatProps`, `SwitchProps`, `TableOfContentsProps`, `TabsProps`, `TalkCardProps`, `TextProps`, `TextareaProps`, `ThemeToggleProps`, `ToastOptions`, `ToastVariant`, `ToasterProps`, `TocEntry`.
 
 # Where to look if this is not enough
 
@@ -1614,8 +2064,8 @@ Types (60): `AccordionProps`, `AccordionTriggerProps`, `AlertProps`, `ArticleCar
   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,
+- `architecture/design-system.md` and `architecture/brand-manual.md`: the identity documents,
   greppable.
-- `docs/decisions.md`: the points where the code and the document did not say the
+- `decisions/`: 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.