@eduardoalvarez/arrecife 0.10.0 → 0.12.0

package/llms.txt

@@ -72,6 +72,15 @@ project declares `@source`, include the package:
 @source "../node_modules/@eduardoalvarez/arrecife/dist";
 ```
 
+**Every token is in `:root`, and you may read it with `var()`.** The block is
+`@theme static`, so a token is emitted whether or not a utility asks for it:
+`style={{ fill: 'var(--color-series-1)' }}` or `var(--radius-card)` from your own
+JavaScript resolves. Do not write a fallback hexadecimal next to it — that is a
+second copy of a value this package exists to keep in one place. Before that fix
+Tailwind dropped the four `--color-series-*` as unused, because they are read by
+`var()` and requested by no class, and the charts drew black. See
+`decisions/` § 61.
+
 ### Light mode and dark mode
 
 **Dark mode is primary and it is the default.** A dark project declares nothing.
@@ -263,7 +272,7 @@ 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.
+inside `<main>` and is not a landmark. See `decisions/` § 30.
 
 ### Icons are yours, the way they are drawn is not
 
@@ -332,7 +341,7 @@ a Server Component throws. It ships no `"use client"` to stop you, so the failur
 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.
+See `decisions/` § 29 and § 35.
 
 ### `Stat`'s delta says direction, not judgement
 
@@ -349,7 +358,7 @@ errores» point the same way and mean opposite things, so whether a number is go
 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.
+implementation. See `decisions/` § 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
@@ -359,7 +368,7 @@ no sparkline — pass your own, exactly like `icon`.
 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.
+number» is said. See `decisions/` § 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
@@ -433,6 +442,13 @@ 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.
 
+**`builtWith` adds «Creado con Arrecife ♥» under the signature**, linking to the
+library's Storybook. It works on both shapes and it is OFF by default:
+the credit is the site's to give, so the library does not put it in a footer
+that did not ask. Do not hand-write that line instead — the heart is Phosphor's
+filled `Heart` and never the emoji, and the URL is checked against the package's
+`homepage` on every build. See `decisions/` § 62.
+
 ### `Table` brings its own surface
 
 ```tsx
@@ -480,6 +496,13 @@ re-exported, because they are unchanged and wrapping them buys nothing.
 down for a ranking. Recharts calls that same thing `layout="vertical"` — if you
 are porting code, the value flips.
 
+**A percentage passes `valueMax={100}`.** Without it the value axis ends at the
+largest datum, and on a horizontal ranking — whose value axis is hidden — a
+course watched to 40 % draws as a full bar when it is the highest on the list.
+The bottom is always zero, and it is a floor rather than a clip: a datum above
+`valueMax` widens the axis instead of running off the edge. It is on all three
+types. See `decisions/` § 58.
+
 `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`.
@@ -487,6 +510,13 @@ 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 series palette comes from `seriesColor(i)` and `SERIES_COLORS`, and both
+return `var(--color-series-N)`** rather than a hexadecimal, so the colors follow
+the mode instead of freezing to the one that was live when the chart mounted. You
+do not need `data-theme` on `<html>` for that to resolve, and you do not need a
+fallback: the tokens are in `:root` on every page. Pass `color` per series only
+to override the palette on purpose — a semantic red for a failure count, say.
+
 ### The social icons are yours, and they come from Phosphor
 
 Until 0.10.0 the library shipped ten of them at `./social` — `GitHub`,
@@ -578,7 +608,7 @@ 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 `decisions/0.6.md` § 21.
+   already carry the weight. See `decisions/` § 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. There are five declared exceptions, all behind `motion-safe`
@@ -590,6 +620,10 @@ compiles and looks wrong, or that fails the project's accessibility audit.
    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.
+   `PageHeader` makes the same split: `as` is the level and `titleVariant` the
+   scale. An admin panel's title is `<PageHeader title="Ventas"
+   titleVariant="h3" />` — still the page's only `h1`, at 25px instead of 44. See
+   `decisions/` § 57.
 7. **`textMuted` never goes over `surfaceRaised`**: it gives 4.07 in dark. Over a
    raised surface — menus, active tabs — the token is `textSecondary`.
 8. **A background tinted with a semantic color carries text from a text token**,
@@ -607,9 +641,14 @@ compiles and looks wrong, or that fails the project's accessibility audit.
     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.
+    not the humour contract. See `decisions/` § 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.
+    **On a site that switches theme, pass `background="auto"`** to `Isotype` or
+    `Logo`: both fins are rendered and the `light:` variant shows the one that
+    reads, so no call site has to know the theme. A surface that keeps one mode
+    whatever the page does — a dark panel on a light page — is a fixed
+    background, and it still says `dark`. See `decisions/` § 60.
 
 ## What the library does NOT do, on purpose
 
@@ -625,6 +664,12 @@ These are the confusions people run into most often when consuming it.
   provider.
 - **It ships no router.** The components with links accept `asChild` to wrap the
   framework's `Link`.
+- **It does not know your prices, ratings or images.** `CourseCard` takes
+  `media` — the cover, bleeding to the edges, with `alt=""` because the title
+  already names the card — and `footer`, the closing row where a project puts the
+  rating and the price. Both are nodes the project draws; the card keeps the
+  title, its hover and the sand progress bar. The title does not go over the
+  cover. See `decisions/` § 59.
 - **It ships no `data-testid`.** A composed part your test suite has to reach is
   reached with a slot: `ArticleCard`'s `tagAsChild`, `Breadcrumb`'s and
   `TableOfContents`'s `linkAsChild`. They hand you the element and its
@@ -1389,11 +1434,15 @@ Source: `src/components/code-block/index.tsx`
 
 Source: `src/components/course-card/index.tsx`
 
-- Extends: `Omit<CardShellProps, 'children' \| 'title'>`
+The course, as a card that links to it.
+
+- Extends: `Omit<CardShellProps, 'children' \| 'title' \| 'media'>`
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `asChild` | `boolean \| undefined` |  |  | Renders the child instead of an `<a>`. It is how Next's or Astro's `Link` plugs in without the library depending on any router. |
+| `footer` | `ReactNode` |  |  | The closing row, under `meta`: the rating, the price, whatever the project sells the course with. It sits at the bottom of the card, so the rows of a grid line up whatever the length of each summary. |
+| `media` | `ReactNode` |  |  | The cover, at the top and bleeding to the card's edges, with `alt=""`: the whole card is one link and `title` already names it. |
 | `meta` | `readonly ReactNode[]` |  |  | Level, duration, number of lessons: whatever the project wants to list. |
 | `progress` | `number` |  |  | Percentage completed. It only makes sense for someone already enrolled; when passed, the bar goes in sand, which is the color of course progress. |
 | `status` | `ReactNode` |  |  | Status label: «próximamente», «gratis», «nuevo». |
@@ -1444,6 +1493,7 @@ Source: `src/components/footer/index.tsx`
 | --- | --- | --- | --- | --- |
 | `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. |
+| `builtWith` | `boolean \| undefined` |  |  | Adds «Creado con Arrecife ♥», linking to the library's Storybook. |
 | `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. |
 | `domain` | `string` |  |  | The domain the signature prints, defaulting to the identity's own. |
@@ -1557,6 +1607,7 @@ One header at two scales, not two components.
 | `eyebrow` | `ReactNode` |  |  | Mono, small caps, in accent. It is the section the page belongs to. |
 | `size` | `"display" \| "page"` |  | `page` |  |
 | `title` | `ReactNode` | yes |  |  |
+| `titleVariant` | `"display" \| "h1" \| "h2" \| "h3"` |  |  | The headline's scale, when the screen needs a different one from what `size` gives — `display` for `display`, `h1` for `page`. |
 
 ### ScrollingProgressBar
 
@@ -1588,7 +1639,7 @@ A large metric: the number in the `stat` scale and its name underneath.
 | `label` | `ReactNode` | yes |  | What is being counted. It goes in mono small caps. |
 | `progress` | `number` |  |  | With `progress`, the metric reads as progress and adds the bar. |
 | `spark` | `ReactNode` |  |  | The number's shape over time, under it. A `ReactNode` and not a data prop: a sparkline needs a charting library, and this component lives in the barrel that four projects install. The one project that draws them passes its own, exactly like `icon`. |
-| `tone` | `"neutral" \| "alert" \| "achievement"` |  | `neutral` | `alert` ONLY when the number is the problem, and `achievement` when it is the opposite — the diplomas issued, the modules finished. The two paint the same sand today and they are still two names: a system that names by meaning cannot make «this is bad» the only way to say «this stands out». See `docs/decisions/0.7.md` § 28. |
+| `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/` § 28. |
 | `value` | `ReactNode` | yes |  | The number, already formatted. The library imposes no locale. |
 
 ### TalkCard
@@ -1645,12 +1696,14 @@ Imported from `@eduardoalvarez/arrecife` or `@eduardoalvarez/arrecife/brand`. 4
 
 Source: `src/brand/isotype.tsx`
 
+The fin, in the variant its background asks for.
+
 - Extends: `Omit<ComponentPropsWithoutRef<'img'>, 'src' \| 'alt'>`
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `alt` | `string` |  |  | Alt text. Empty when the isotype accompanies text that already names it. |
-| `background` | `"dark" \| "light"` |  | `dark` | Which background it sits on. Deciding is mandatory even though it has a default: the fin's body is nearly black, so the two-blue variant disappears over abyss. Being a prop, the rule stops being something to remember. |
+| `background` | `"dark" \| "light" \| "auto"` |  | `dark` | Which background it sits on, or `auto` on a site that switches theme: both fins are rendered and CSS shows the one that reads. Deciding is mandatory even though it has a default: the fin's body is nearly black, so the two-blue variant disappears over abyss. |
 | `basePath` | `string` |  | `ASSETS_PATH` |  |
 
 ### Logo
@@ -1663,7 +1716,7 @@ The wordmark comes from `naming.wordmark`, not from a hand-written string, and i
 
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `background` | `"dark" \| "light"` |  | `dark` |  |
+| `background` | `"dark" \| "light" \| "auto"` |  | `dark` | The background the logo sits on, handed to its fin. `auto` follows the theme — see `Isotype`. The wordmark needs no help: it is `textPrimary`, which already follows the mode. |
 | `basePath` | `string` |  | `ASSETS_PATH` |  |
 | `isotypeOnly` | `boolean \| undefined` |  | `false` | Hides the wordmark and leaves only the fin, for very narrow bars. |
 | `withTagline` | `boolean \| undefined` |  | `false` | Adds the tagline under the wordmark, separated from the fin by a divider. |
@@ -1819,6 +1872,7 @@ A series over time, with the fill fading out underneath it.
 | `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`. |
+| `valueMax` | `number` |  |  | The top of the value axis, when the scale has one that the data does not reach — 100 for a percentage. |
 | `xKey` | `string` | yes |  | The key on the category axis: the day, the month, the course. |
 | `xTickFormatter` | `(value: unknown) => string` |  |  | Formats the TICK on the category axis. Returns a string, because an axis tick is an SVG `<text>` and not a place a node can go. |
 | `yTickFormatter` | `(value: unknown) => string` |  |  | Formats the tick on the VALUE axis — the currency symbol, the thousands separator, the percent sign. |
@@ -1839,6 +1893,7 @@ Bars, upright or lying down.
 | `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`. |
+| `valueMax` | `number` |  |  | The top of the value axis, when the scale has one that the data does not reach — 100 for a percentage. |
 | `xKey` | `string` | yes |  | The key on the category axis: the day, the month, the course. |
 | `xTickFormatter` | `(value: unknown) => string` |  |  | Formats the TICK on the category axis. Returns a string, because an axis tick is an SVG `<text>` and not a place a node can go. |
 | `yTickFormatter` | `(value: unknown) => string` |  |  | Formats the tick on the VALUE axis — the currency symbol, the thousands separator, the percent sign. |
@@ -1857,6 +1912,7 @@ Lines, for comparing series against each other.
 | `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`. |
+| `valueMax` | `number` |  |  | The top of the value axis, when the scale has one that the data does not reach — 100 for a percentage. |
 | `xKey` | `string` | yes |  | The key on the category axis: the day, the month, the course. |
 | `xTickFormatter` | `(value: unknown) => string` |  |  | Formats the TICK on the category axis. Returns a string, because an axis tick is an SVG `<text>` and not a place a node can go. |
 | `yTickFormatter` | `(value: unknown) => string` |  |  | Formats the tick on the VALUE axis — the currency symbol, the thousands separator, the percent sign. |
@@ -1895,7 +1951,7 @@ it: if the code does not mount React, that subpath is the one to import.
 | `light` | `{ background, surface, surfaceRaised, border, hairline, hairlineHover, textPrimary, textSecondary, textMuted, accent, accentHover, accentOn, warm, warmHover, warmOn, success, warning, error, danger, dangerHover, dangerOn }` | Light mode. Contrast measured against `background` #F6F2EA. `background` is WARM white: never #FFF as the page background. |
 | `limits` | `{ readonly minScreenPx: 13; readonly minPrintPt: 12; readonly measure: "68ch"; }` | Hard legibility limits. |
 | `motion` | `{ readonly duration: "150ms"; readonly easing: "ease-out"; readonly properties: "color, background-color, border-color, fill, stroke"; }` | 150ms ease-out — color and border only. The system animates neither position nor scale: states are communicated with border and color, not with movement. |
-| `naming` | `{ readonly wordmark: "Eduardo Álvarez"; readonly mascot: "Tiburoncín"; readonly domain: "eduardoalvarez.dev"; }` | The wordmark always reads «Eduardo Álvarez». The mascot is called Tiburoncín and its name never appears inside the logo. |
+| `naming` | `{ wordmark, mascot, domain, library, libraryUrl }` | The wordmark always reads «Eduardo Álvarez». The mascot is called Tiburoncín and its name never appears inside the logo. |
 | `radius` | `{ readonly chip: 6; readonly control: 10; readonly card: 14; readonly panel: 16; readonly pill: 999; }` |  |
 | `series` | `{ readonly dark: readonly ["#35D6C0", "#F2A65A", "#3E7CB1", "#71919C"]; readonly light: readonly ["#0D7C6F", "#A65B27", "#3E7CB1", "#626A75"]; }` | 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. |
@@ -1937,7 +1993,7 @@ Types (2): `Theme`, `ThemeOptions`.
 | `poseList` | `readonly ("desk" \| "laptop-coffee" \| "peek" \| "surf")[]` |  |
 | `poses` | `{ readonly desk: "pose-desk.png"; readonly 'laptop-coffee': "pose-laptop-coffee.png"; readonly peek: "pose-peek.png"; readonly surf: "pose-surf.png"; }` | Full-body poses. |
 
-Types (8): `Background`, `Face`, `Fin`, `IsotypeProps`, `LogoProps`, `MascotFaceProps`, `MascotProps`, `Pose`.
+Types (9): `Background`, `Face`, `Fin`, `IsotypeBackground`, `IsotypeProps`, `LogoProps`, `MascotFaceProps`, `MascotProps`, `Pose`.
 
 ### `@eduardoalvarez/arrecife/icons`
 
@@ -2003,5 +2059,7 @@ Types (60): `AccordionProps`, `AccordionTriggerProps`, `AlertProps`, `ArticleCar
 - `architecture/design-system.md` and `architecture/brand-manual.md`: the identity documents,
   greppable.
 - `decisions/`: the points where the code and the document did not say the
-  same thing, each with its resolution.
+  same thing, each with its resolution. One file per decision, named for its
+  number, so «§ 45» is `decisions/045-*.md` — which is how every `§ N` in this
+  file resolves.
 - `AGENTS.md`: for working inside the library's repo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eduardoalvarez/arrecife",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "The component library of Eduardo Álvarez’s visual identity",
   "license": "MIT",
   "author": "Eduardo Esteban Álvarez Castañeda <soy@eduardoalvarez.dev>",