@eduardoalvarez/arrecife 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # Changelog
 
+## [0.8.0](https://github.com/Proskynete/arrecife/compare/v0.7.0...v0.8.0) (2026-09-06)
+
+
+### ⚠ BREAKING CHANGES
+
+* **components:** `SidebarNav`, `SidebarGroup` and `SidebarItem` are removed. A project that wants a sidebar builds one from `Nav` and `Sheet`, which is what both admin projects already did. Migration in docs/migration-0.8.md.
+* **components:** `Footer` no longer accepts `children`, and `FooterLink` is removed. A row of loose text links becomes `variant="full"` with `columns`. Migration in docs/migration-0.8.md.
+* **tokens:** the `caret` utility is removed. If you wrote `motion-safe:caret` by hand, Tailwind now drops it silently and your mark goes still with no error: use `pulse-accent` on a thin shape. Migration in docs/migration-0.8.md.
+* **primitives:** `Table` draws its own radius, border and clip, so the wrapper `div` around it has to lose its `rounded-*`, `border` and `overflow-hidden` or you get two borders. Nothing fails at compile time. Migration in docs/migration-0.8.md.
+
+### 🚀 Novedades
+
+* **chart:** AreaChart, BarChart and LineChart on the chassis ([780c976](https://github.com/Proskynete/arrecife/commit/780c97633b1d245f9de42cc42a333e0b7baf679c))
+* **components:** Footer gets a full shape, and its signature draws the halo ([88c5af3](https://github.com/Proskynete/arrecife/commit/88c5af362ff2ee44e50e534259014d1a3f19c253))
+* **components:** SidebarNav goes, and so does the recipe built on it ([27f6a3e](https://github.com/Proskynete/arrecife/commit/27f6a3e65c4f67dfd1531992b436965bc591bdf6))
+* **components:** the footer stops taking loose links, and the columns are the answer ([5d4495e](https://github.com/Proskynete/arrecife/commit/5d4495eb8f9928dfea0605026b8e99a91922ee27))
+* **primitives:** Table draws its own surface, and its scroll region is reachable ([ca07f2c](https://github.com/Proskynete/arrecife/commit/ca07f2c5a04f9db45819a9d3f0d69e32e3d112c6))
+* **social:** the glyphs come out as portable data, and Website joins them ([bb62292](https://github.com/Proskynete/arrecife/commit/bb62292c16d4a9c4953b4a83deab61db0f07afcf))
+* **tokens:** pulse-accent, the halo both sites already drew ([28d1c49](https://github.com/Proskynete/arrecife/commit/28d1c49fa9c7f48077391e2462ace69053c1377e))
+* **tokens:** the caret goes, and the motion rule is one criterion again ([46f03ff](https://github.com/Proskynete/arrecife/commit/46f03ff26c5568b38a1a0633f2ed1f1ac34bcaa7))
+
+
+### 🐛 Correcciones
+
+* **components:** NavItem asChild reaches its child ([f0556d5](https://github.com/Proskynete/arrecife/commit/f0556d5a7e36af188e7c7cac8df82258310c5205))
+* **primitives:** ref is in the type of the four form controls ([f219d32](https://github.com/Proskynete/arrecife/commit/f219d3253fbddf35f004cb5f88015ad25cedde90))
+* the llms generator stops interpreting $ in the inventory ([e0f5309](https://github.com/Proskynete/arrecife/commit/e0f5309b6620c9b8e6ed07d77bc08a5164b977fd))
+* **tokens:** the doctor stops asking a React-less project for [@source](https://github.com/source) ([7bf6e8f](https://github.com/Proskynete/arrecife/commit/7bf6e8fe97e444ed60547265cceda1bd960511c4))
+
+
+### 📚 Documentación
+
+* §§ 47 and 48, and the two removals in the migration guide ([424933e](https://github.com/Proskynete/arrecife/commit/424933e7a419398e755ccd49019f00e54bcc8abf))
+* docs/ splits into architecture, decisions and runbooks ([db5a9b4](https://github.com/Proskynete/arrecife/commit/db5a9b4621100bbf1b77b83894f43caea99c56c1))
+* **readme:** the 0.8.0 callout, and SidebarNav comes off the Phase 5 list ([a5af2f0](https://github.com/Proskynete/arrecife/commit/a5af2f0c2f838432d4a9c815d2127c35146c88bd))
+* **readme:** the table's surface, the halo, and the caret that goes with it ([a30b8b6](https://github.com/Proskynete/arrecife/commit/a30b8b601b30fb133cd1876c1139f88142c83d8a))
+* the reference documents for 0.8.0 ([e4521e2](https://github.com/Proskynete/arrecife/commit/e4521e2b1492132baa3849d8b73e36425ff40f4c))
+
+
+### 🚀 CI/CD
+
+* the templates and the size labeler follow docs/ into its folders ([ea037a1](https://github.com/Proskynete/arrecife/commit/ea037a16517e379ec7bf6544caa96239fae2a491))
+
+## [0.7.0](https://github.com/Proskynete/arrecife/compare/v0.6.0...v0.7.0) (2026-09-04)
+
+
+### ⚠ BREAKING CHANGES
+
+* **icons:** `Icon` no longer accepts `weight`. Pass `tone` instead — `action` is the old default, `current` is `fill` and `quiet` is `light`. The version it changes in has not been published, so nothing on npm carries the old shape.
+* **components:** `Stat`'s `tone="alerta"` becomes `tone="alert"`. Nothing else changes — same colour, same rule, same default. Migration in docs/migration-0.7.md.
+
+### 🚀 Novedades
+
+* **components:** EmptyState gains the shape that carries no face ([7292ec0](https://github.com/Proskynete/arrecife/commit/7292ec07cc3332442335325c49bbc0f3473267fc))
+* **components:** Nav gains the one thing of the three it was missing ([1d2ec5b](https://github.com/Proskynete/arrecife/commit/1d2ec5b0a39d46bf17ee91f2a756c3fa7e8e1cd8))
+* **components:** Stat gains delta, spark and the achievement tone ([0cf4348](https://github.com/Proskynete/arrecife/commit/0cf4348f4efd16c49ab54a5c205bb06c4f04ffd6))
+* **components:** Stat's tone stops being called alerta ([43ffa43](https://github.com/Proskynete/arrecife/commit/43ffa431ac6f675ab27be2a8096e0acbad758711))
+* **components:** the sidebar collapses to a rail, and takes who is signed in ([6fae58f](https://github.com/Proskynete/arrecife/commit/6fae58f3e6bc9cf975a78ca1aeab484421386f51))
+* **components:** the sidebar gets blocks, and the icon replaces the prompt ([1d910a3](https://github.com/Proskynete/arrecife/commit/1d910a38d56000d955bc317fc4566fb7038864f0))
+* **components:** the Stat card as it goes in the panel ([50e47f1](https://github.com/Proskynete/arrecife/commit/50e47f1b898afe207011d00f983af260e623a970))
+* **icons:** the system adopts Phosphor, and it still ships no icons ([8a89c4e](https://github.com/Proskynete/arrecife/commit/8a89c4ef3e2292b8cb5d3c0a287fa59ceb635679))
+* **icons:** the weight is an axis with three roles, and none of them is bold ([a8a9bed](https://github.com/Proskynete/arrecife/commit/a8a9bed9df6dea6c48b63dfd5e4af8f44368befa))
+* npx arrecife, for the two failures that produce no error ([1b2160f](https://github.com/Proskynete/arrecife/commit/1b2160f378a53d433851b4c7995d164f3b93edd1))
+* **social:** the nine icons get a subpath that crosses the RSC boundary ([bfa239f](https://github.com/Proskynete/arrecife/commit/bfa239f6c75c8cd99b7c9fa0bad155fdc68b7d98))
+* **tokens:** a second bar height, for a shell that also has a sidebar ([2277afb](https://github.com/Proskynete/arrecife/commit/2277afb6bc2a2674d7722d69a989259634b74cbd))
+* **tokens:** the sidebar's two widths, because a collapsible one needs both ([8b04bc0](https://github.com/Proskynete/arrecife/commit/8b04bc0dcc065d408b40d2076cb61d5bbe19dbc6))
+
+
+### 🐛 Correcciones
+
+* **a11y:** the focus ring is one utility, at the offset the document gives ([66519b9](https://github.com/Proskynete/arrecife/commit/66519b9ab9834608aae7098b127d1789ad932579))
+* **a11y:** the two accessible names the English sweep took with it ([dea2b8c](https://github.com/Proskynete/arrecife/commit/dea2b8cf17b5ee4a449d92c4805e89c528aa4021))
+* **components:** the default copy goes back to Spanish ([1b0121e](https://github.com/Proskynete/arrecife/commit/1b0121e284b3a5fd244ba63704adf35de06937d5))
+* **components:** the story taught a face map that `faceUsage` denies ([98c46ff](https://github.com/Proskynete/arrecife/commit/98c46ff337e90eb4acb6e90b38a00b54be4805e3))
+* **components:** thirteen more strings the sweep corrupted, in the demo copy ([d6dd7fc](https://github.com/Proskynete/arrecife/commit/d6dd7fcc84a205dba562c8e1f1559328bac73e76))
+* **tokens:** no light gradient ends on surfaceRaised, where accent is 4.21 ([802fdd0](https://github.com/Proskynete/arrecife/commit/802fdd09e6841ea29c384e5f8f99866c1b30bb81))
+
+
+### 🔧 Mantenimiento
+
+* **components:** the AudioPlayer's internals finish the move to English ([db566d7](https://github.com/Proskynete/arrecife/commit/db566d7223c04db928e925ef0fb4edc462c240f8))
+
+
+### 📚 Documentación
+
+* § 35 and § 36, the weight axis and the two actions nobody carried over ([dc72b1d](https://github.com/Proskynete/arrecife/commit/dc72b1d70fe5344b34473fb1a6ae8bb22dca29e6))
+* § 37, the focus ring, and the one half of it that is an interpretation ([6084787](https://github.com/Proskynete/arrecife/commit/6084787068bbd5882574aae323d42581d7ccdbd7))
+* § 9 is ratified and § 38 answers the number nobody looked up ([cd301fc](https://github.com/Proskynete/arrecife/commit/cd301fc8bcba06a4df3928de83fa8eee573cc261))
+* an icon is not illustration, and the version that says so is 0.7.0 ([5d5a88c](https://github.com/Proskynete/arrecife/commit/5d5a88c162fe8ec747602cff7c09476650cab2b8))
+* **components:** the delta says direction, and the document says so first ([ad39c6f](https://github.com/Proskynete/arrecife/commit/ad39c6f9776817f745cca82b1c93fab6287eec31))
+* the ban on icon libraries is lifted, and the set was picked by measurement ([b313b64](https://github.com/Proskynete/arrecife/commit/b313b64b69e0db6a75001a888d95be7c71d5b211))
+* the contrast rule for surfaceRaised covers gradients too ([e5e92d5](https://github.com/Proskynete/arrecife/commit/e5e92d5efc7a0610d06b09b6a757def4fb88dce8))
+* the focus ring is a utility now, and AGENTS said to write it out by hand ([1943567](https://github.com/Proskynete/arrecife/commit/1943567070e30aed733b08c1ca66fd18287221ff))
+* the neutral number stops being biolume, and where the tone went ([9f3fffb](https://github.com/Proskynete/arrecife/commit/9f3fffbd1f6e65f8797a140f6be71268a2f62d38))
+* the rail gets in, and the entry says which premise expired ([86d7b04](https://github.com/Proskynete/arrecife/commit/86d7b044432120d2b29eb3295c1958075a6109c1))
+* the second shape of the empty state, and where it bends the document ([612e7a8](https://github.com/Proskynete/arrecife/commit/612e7a8c78b49a03a6db8f787b90ae13bc60a6eb))
+* the sidebar's blocks, and why the label is not a heading ([dc030f1](https://github.com/Proskynete/arrecife/commit/dc030f1ae707e4ee8596b4b6659716c3debd0fa0))
+* the third tone, and the fourth breaking change ([abb6dfc](https://github.com/Proskynete/arrecife/commit/abb6dfce7cf93f2167dbff29c32c8d6b399c440c))
+* the two forms of the social icons, and which one crosses the boundary ([9b90a82](https://github.com/Proskynete/arrecife/commit/9b90a829201de857462c80cf846dde46d628597b))
+* the two silent failures get a command, and the README stops being the guard ([4b40bb6](https://github.com/Proskynete/arrecife/commit/4b40bb6359e79100544da3ba8cb0586dfc82bd03))
+* the weight is three values, and the README and AGENTS said it was one ([05f3351](https://github.com/Proskynete/arrecife/commit/05f33513c4332ab4651b0a256ad8cbecfe810e34))
+* this is two releases, not one — the guide splits back ([16fdf94](https://github.com/Proskynete/arrecife/commit/16fdf9494092f0b77f7397d891637d130407555b))
+* two of the three things Nav was missing were already there ([f77b712](https://github.com/Proskynete/arrecife/commit/f77b7125d500122b26bf22f79f5983be483e3df4))
+
+
+### 🚀 CI/CD
+
+* a check for the copy, because «nothing catches this» was the wrong answer ([74169c3](https://github.com/Proskynete/arrecife/commit/74169c3803f753a61800de130184ec0a2043d821))
+* icons joins the scope list ([783acc4](https://github.com/Proskynete/arrecife/commit/783acc432cea7f947e3dbd8fc3590be9617c5102))
+* social joins the scope list, by the rule that was already written ([d805a37](https://github.com/Proskynete/arrecife/commit/d805a37e0206ff3f6f71718d69d8db93e2e70f75))
+* the actions decisions.md owes a canvas get printed, because § 22's was not ([c5dc751](https://github.com/Proskynete/arrecife/commit/c5dc751aa01be82c3429239afb6372fa8471acc6))
+
 ## [0.6.0](https://github.com/Proskynete/arrecife/compare/v0.5.1...v0.6.0) (2026-09-02)
 
 

package/README.md

@@ -7,7 +7,7 @@ Published Storybook: [arrecife.eduardoalvarez.dev](https://arrecife.eduardoalvar
 
 ## The identity documents
 
-`docs/design-system.md` and `docs/brand-manual.md` are the extraction of the two
+`docs/architecture/design-system.md` and `docs/architecture/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.
 
@@ -15,7 +15,7 @@ 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.
 
-`docs/decisions.md` is the other half: the points where the code and the document
+`docs/decisions/` 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.
 
 ## The two documents for agents
@@ -86,6 +86,77 @@ 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.)
+
+```
+arrecife · 2 thing(s) that fail without saying so:
+
+  src/styles/globals.css
+    imports @eduardoalvarez/arrecife/tokens/theme.css and has no @source.
+    Every class the components emit is being purged — silently. Add:
+
+      @source "../../node_modules/@eduardoalvarez/arrecife/dist";
+
+  src/styles/globals.css
+    redefines --color-accent, which @eduardoalvarez/arrecife owns.
+      yours:    var(--accent)   ← points at another property, so it wins silently
+      arrecife: #35D6C0
+```
+
+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.7.0.** Four breaks, and three of them are things the library
+> takes back OUT because nothing in the four projects drew them: the `caret`
+> utility, the footer's row of loose text links, and `SidebarNav`.
+>
+> Only one fails at compile time — `Footer` no longer takes `children` — and that
+> is the one to look at first. The other three fail silently or not at all: the
+> `Table` wrapper you no longer need gives you two borders, and a hand-written
+> `motion-safe:caret` just stops animating.
+>
+> Everything else is additive: `Footer variant="full"` with columns, three chart
+> shapes, `./social/data` for a project that mounts no React, and a `Website`
+> glyph.
+>
+> Run `npx arrecife` first, then read
+> [`docs/runbooks/migration-0.8.md`](docs/runbooks/migration-0.8.md).
+
+> **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, and
+> `npx arrecife` catches two failures that produce no error at all.
+>
+> Run `npx arrecife` first, then read
+> [`docs/runbooks/migration-0.7.md`](docs/runbooks/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.
 >
@@ -98,19 +169,19 @@ tests caught it, not the build, and until 0.3.0 this was only written in
 > 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).
+> **delete**: [`docs/runbooks/migration-0.6.md`](docs/runbooks/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).
+> and the examples, is in [`docs/runbooks/migration-0.5.md`](docs/runbooks/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).
+> [`docs/runbooks/migration-0.3.md`](docs/runbooks/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.
@@ -275,32 +346,53 @@ 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.
 
-### The social icons are namespaced
-
-It is the first thing anyone consuming the library trips over, because the
-natural form does not work:
+### The social icons come from `./social`
 
 ```tsx
-// ❌ does not exist
+// ❌ 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 />
 ```
 
-All nine are `GitHub`, `LinkedIn`, `X`, `Instagram`, `Discord`, `YouTube`, `Rss`,
-`Email` and `Newsletter`. They live under a namespace for a concrete reason:
-**one of them is called `X`**.
+All ten are `GitHub`, `LinkedIn`, `X`, `Instagram`, `Discord`, `YouTube`, `Rss`,
+`Email`, `Newsletter` and `Website`. The last one is «my other site» — the
+personal domain in a footer full of networks — and it exists so that footer stops
+borrowing a globe from an icon set, which brings its own stroke weight and its
+own margins with it.
+
+**And the shapes are published a second time, without React.** `./social/data`
+imports nothing: it holds every glyph as structured shapes plus `socialSvg`,
+which returns a complete `<svg>` as a string. It is for the consumer that mounts
+no React and used to paste the `<path>` into its own template — `links` had four
+of them and `cursos` had six. The React components above are drawn from that same
+file, so a `d` that changes changes in both or in neither. See
+`docs/decisions/0.8.md` § 42.
+
+**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. 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.
+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.
@@ -309,6 +401,77 @@ 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.
+
+```tsx
+import { GraduationCap } from '@phosphor-icons/react';
+import { Icon } from '@eduardoalvarez/arrecife/icons';
+
+<Icon as={GraduationCap} />
+```
+
+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:
+
+| | 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/0.7.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/0.7.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
@@ -320,18 +483,24 @@ It blocked `cursos` for a whole version, and the workaround there was a
 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.
+`./variants`, `./social/data`, `./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 ten `<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/0.7.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 the portable ones.
+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
@@ -354,9 +523,11 @@ 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 `#EFE9DE`, and nothing compared
-them.
+`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>`,
@@ -382,10 +553,21 @@ import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage }
 
 import { ChartContainer, ChartTooltip, ChartTooltipContent, seriesColor }
   from '@eduardoalvarez/arrecife/chart';
+
+// And the three chart types, which are what a project actually reaches for.
+import { AreaChart, BarChart, LineChart } from '@eduardoalvarez/arrecife/chart';
 ```
 
-`check:exports` verifies that the five portable ones — `./tokens`, `./theme`,
-`./variants`, `./og` and `./shiki` — bring no React into the published `dist/`,
+`AreaChart`, `BarChart` and `LineChart` take `data`, `series` and `xKey` and draw
+the whole thing. **They are not Recharts' components of the same name**, and the
+collision is deliberate: what they replace is not an import, it is sixty lines of
+composition — a `linearGradient` with a hardcoded id, a `CartesianGrid
+vertical={false}`, two axes with the line and the tick off, a `type="natural"`
+and a `strokeWidth` — which `cursos` wrote four times, once per chart. None of
+that is a decision the project made. See `docs/decisions/0.8.md` § 43.
+
+`check:exports` verifies that the six portable ones — `./tokens`, `./theme`,
+`./variants`, `./social/data`, `./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
@@ -442,6 +624,20 @@ contrast ratio, which overshoots near white.
 `textMuted` never goes over `surfaceRaised`: in dark it gives 4.07. Menus use
 `textSecondary`, which gives 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.
+
+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/0.6.md` § 9 has the measurements, including the two other things the first composition
+got wrong.
+
 ### The third correction: a semantic color is not a text color over its own tint
 
 It came up while implementing the document's alert recipe — background at 8 % of
@@ -632,8 +828,13 @@ run summary.
 - **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/` and `shiki/`.
+  `Nav`, `TableOfContents`, `Stat`, `Footer`, `Hero`, `NewsletterForm`, `og/` and
+  `shiki/`.
+
+  `SidebarNav` was on that list and came off it in 0.8.0. It met the rule below
+  on the identity half and never on the consumer half: the two admin projects it
+  was built for each wrote their own and never imported it. See
+  `docs/decisions/0.8.md` § 48.
 
   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
@@ -668,9 +869,13 @@ about as library pieces. They get in anyway: the CLI aesthetic — the bar's
 
 ### Phase 3 decisions
 
-- **No `lucide-react`.** The eight glyphs the primitives need are inline in
-  `src/lib/glyphs.tsx`, inherit `currentColor` and measure 1em. An icon library
-  as a dependency is something each of the five projects pays for.
+- **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
@@ -694,6 +899,15 @@ about as library pieces. They get in anyway: the CLI aesthetic — the bar's
   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.
+- **`Table`'s scroll region is a focus stop.** A region you can pan with a mouse
+  has to be reachable with a keyboard — WCAG 2.1.1 — and a table of text holds
+  nothing focusable to land on, so the columns past the right edge were simply
+  unreadable without one. It had been true since the container started scrolling
+  and no story was ever narrow enough to say so; the first one with more columns
+  than width failed axe on `scrollable-region-focusable` immediately. It is
+  unconditional, because whether a table overflows depends on the viewport and
+  the only alternative is a ResizeObserver on every table in the system. See
+  `docs/decisions/0.8.md` § 39.
 
 ### The syntax palette
 
@@ -839,22 +1053,47 @@ maintain for nothing.
 `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 signature's mark: the halo, and the caret it removed
+
+The CLI signature ends in a 2px bar that stays solid and **radiates** — a
+`box-shadow` ring grows out to 5px and fades, 1.5s `ease-in-out`, behind
+`motion-safe`. It is the fifth declared motion exception and it lands on the
+one criterion the other four share, next to the button spinner: a prompt that
+radiates says the terminal is live, which is what a still mark cannot say.
+
+**It replaced a blink this library had invented.** The signature used to end in a
+half-em block blinking at `step-end`, argued from first principles: a prompt
+whose caret does not blink is a terminal that has hung. Every sentence of that
+argument is true, and it was answering a question the identity had already
+answered — `cursos` and `eduardoalvarez.dev` both shipped `@keyframes cursor-ping`,
+the same effect under the same name, written before this library had a `Footer`.
+The blog's copy is still in its `base.css` with nothing rendering it, because
+adopting the component replaced its mark. That is the drift this library exists
+to remove, arriving through the library.
+
+**`caret` is gone, not merely unused.** It arrived in 0.6.0 and it is removed
+here. A published utility is normally not withdrawn the day its one consumer
+changes its mind, but it never had a consumer to change its mind: no project ever
+wrote the class, and the argument that justified it was reasoned rather than
+read. Leaving it published leaves the invention in the package under a label that
+makes it look like a feature.
+
+**The halo is not that utility with a setting**, which is why it arrives under
+its own name. The caret's whole case rested on `step-end`: a real caret is on or
+off, and easing it turns a terminal into a pulsing dot. Folding a halo into that
+name would make the argument contradict itself.
+
+**And the rule gets its shape back.** The caret was the only member of the
+«legibility» criterion that was invented to admit it, so the five exceptions —
+the button spinner, the `Sheet` panel, the `Skeleton` shimmer, the `Accordion`
+height and this halo — are again all one thing: feedback about progress or about
+spatial continuity. A sixth lands on that or it does not exist.
+
+The bar is 2px and not a block because a halo needs something thin to radiate
+from, the colour is `var(--color-accent)` so it follows the mode, and
+`motion-safe` is the one thing not copied from `cursos` — whose span animates
+regardless of the setting. See `docs/decisions/0.8.md` § 45, and § 23 for the entry
+it reverses.
 
 ### The second motion exception
 
@@ -900,7 +1139,7 @@ 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.
+`docs/decisions/0.6.md` § 21.
 
 ### `icon-sm`, for the one admin app
 
@@ -911,7 +1150,7 @@ three actions per table row, and at 42 the row grows with them.
 `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.
+page's primary action stays at 42. See `docs/decisions/0.6.md` § 22.
 
 ### The theme script, and the mode a site already decided
 

package/dist/brand/index.cjs

@@ -75,7 +75,7 @@ var typeScale = {
    * (plankton 5.57:1 over abyss), which is the part that is not negotiable.
    *
    * At 13 the three badge families grew past the size of a small button and
-   * outweighed the title they accompany. See `docs/decisions.md`.
+   * outweighed the title they accompany. See `docs/decisions/`.
    */
   chip: { family: "mono", size: 11.5, lineHeight: 1.4, weight: 400 },
   /**
@@ -121,7 +121,7 @@ var control = {
    * baseline; 28 would have been a fifth height that matches nothing.
    *
    * It does not replace `icon`. A page's primary action stays at 42; this is for
-   * a row of a table. See `docs/decisions.md` § 22.
+   * a row of a table. See `docs/decisions/0.6.md` § 22.
    */
   iconSm: 32
 };

package/dist/brand/index.js

@@ -1,6 +1,6 @@
 'use client';
-export { Isotype, Logo, Mascot, MascotFace } from '../chunk-6O3KWB6P.js';
+export { Isotype, Logo, Mascot, MascotFace } from '../chunk-MPZBF2TZ.js';
 export { ASSETS_PATH, faceList, faceUsage, faces, fins, poseList, poses } from '../chunk-CKRSQPTX.js';
-import '../chunk-XKYHTOUJ.js';
-import '../chunk-O4TAH7YJ.js';
+import '../chunk-FAAGZG7A.js';
+import '../chunk-FGFNK72B.js';
 import '../chunk-MLKGABMK.js';