@eduardoalvarez/arrecife 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.11.0](https://github.com/Proskynete/arrecife/compare/v0.10.0...v0.11.0) (2026-09-11)
+
+
+### 🚀 Novedades
+
+* **brand:** the fin can follow the theme with background="auto" ([3021f24](https://github.com/Proskynete/arrecife/commit/3021f24575c6f9422b7f322bf825a878a735306d))
+* **chart:** valueMax sets the top of the value axis ([ccebe24](https://github.com/Proskynete/arrecife/commit/ccebe24361ce4004916b433819ddf7f53f89907a))
+* **components:** CourseCard takes a cover and a closing row ([a3c73d0](https://github.com/Proskynete/arrecife/commit/a3c73d0b21edffc16c2965475fce9de6e1502926))
+* **components:** PageHeader lets the screen pick the title scale ([99bd553](https://github.com/Proskynete/arrecife/commit/99bd55376992109ea90c8eaedc435ffcadffdb0e))
+
+
+### 📚 Documentación
+
+* four decisions from cursos adopting the whole library ([2a712b8](https://github.com/Proskynete/arrecife/commit/2a712b871edd73f63fddfd2733279bf3e2834e07))
+* **readme:** background="auto", valueMax, and the story count ([149442c](https://github.com/Proskynete/arrecife/commit/149442cb2748da9cb06b3df23254cba46aae378a))
+
 ## [0.10.0](https://github.com/Proskynete/arrecife/compare/v0.9.0...v0.10.0) (2026-09-09)
 
 

package/README.md

@@ -588,6 +588,11 @@ 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.
 
+A chart of a quantity with a ceiling passes it: `valueMax={100}` on a percentage.
+Without it the value axis ends at the largest datum, and a horizontal ranking —
+whose value axis is hidden — draws a course watched to 40 % as a full bar. See
+`docs/decisions/0.11.md` § 58.
+
 `check:exports` verifies that the five portable ones — `./tokens`, `./theme`,
 `./variants`, `./og` and `./shiki` — bring no React into the published `dist/`,
 **by following the relative imports**. Without that the check was worthless: with `treeshake`
@@ -603,7 +608,7 @@ chunk imports it.
 | `pnpm typecheck` | `tsc --noEmit` |
 | `pnpm lint` | ESLint, including the ban on literal hexes outside `tokens.ts` |
 | `pnpm check:tokens` | fails if `src/tokens/` imports anything from outside |
-| `pnpm test` | compiles Tailwind and runs axe over the 208 stories, in both modes |
+| `pnpm test` | compiles Tailwind and runs axe over the 248 stories, in both modes |
 | `pnpm check:exports` | verifies that `dist/` holds what `exports` promises |
 | `pnpm check:release` | validates `release-please-config.json` against the official schema |
 | `pnpm storybook` | generates the tokens and serves Storybook on 6006 |
@@ -1047,6 +1052,12 @@ adding a line to the catalog.
 Pixel analysis confirms it — 94 % of `fin-foam.png` is `#EDF4F3`, which is the
 foam token.
 
+On a site that switches theme, `background="auto"` renders both and the `light:`
+variant shows the one that reads, so no call site has to know which theme is on.
+A background that does not follow the theme — a dark panel on a light page —
+still names itself: `auto` reads the page, not the panel. See
+`docs/decisions/0.11.md` § 60.
+
 **Rule 5 as API.** The wordmark comes from `naming.wordmark` and always reads
 «Eduardo Álvarez». There is no prop that changes that text, and Tiburoncín never
 appears written inside the logo.

package/dist/brand/index.cjs

@@ -168,18 +168,24 @@ function Isotype({
   className,
   ...props
 }) {
-  const file = background === "dark" ? fins.foam : fins.color;
-  return /* @__PURE__ */ jsxRuntime.jsx(
+  const fin = (file, mode) => /* @__PURE__ */ jsxRuntime.jsx(
     "img",
     {
       src: `${basePath}/${file}`,
       alt,
       width: 147,
       height: 111,
-      className: cn("h-8 w-auto select-none", className),
+      className: cn("h-8 w-auto select-none", className, mode),
       ...props
     }
   );
+  if (background === "auto") {
+    return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      fin(fins.foam, "light:hidden"),
+      fin(fins.color, "not-light:hidden")
+    ] });
+  }
+  return fin(background === "dark" ? fins.foam : fins.color);
 }
 function Logo({
   background = "dark",

package/dist/brand/index.d.cts

@@ -3,21 +3,60 @@ export { A as ASSETS_PATH, a as Fin, f as faceList, b as faceUsage, c as faces,
 import * as react from 'react';
 import { ComponentPropsWithoutRef } from 'react';
 
+/**
+ * Which background the fin sits on, or `auto` to let the theme decide.
+ *
+ * It is its own type and not a third member of `Background`, because
+ * `Background` is also what the OG templates read, and Satori has no CSS to
+ * resolve `auto` with: a template knows its mode and has to say it.
+ */
+type IsotypeBackground = Background | 'auto';
 type IsotypeProps = Omit<ComponentPropsWithoutRef<'img'>, 'src' | 'alt'> & {
     /**
-     * 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.
+     * 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.
+     *
+     * Use `dark` or `light` when the background does not follow the theme. A
+     * panel that stays dark in both modes is a fixed background, and `auto` would
+     * pick the page's fin instead of the panel's.
      */
-    background?: Background | undefined;
+    background?: IsotypeBackground | undefined;
     basePath?: string | undefined;
     /** Alt text. Empty when the isotype accompanies text that already names it. */
     alt?: string | undefined;
 };
+/**
+ * The fin, in the variant its background asks for.
+ *
+ * `auto` renders both and lets the `light:` variant choose, which is what
+ * `ThemeToggle` already does with its two icons and for the same reason: the
+ * server does not know the theme, and a fin picked in JavaScript would be wrong
+ * on the first paint half the time. `cursos` had written exactly this by hand
+ * after a surface changed mode and its fin vanished — not looked wrong: vanished,
+ * with no error and no gap in the layout. See `docs/decisions/0.11.md` § 60.
+ *
+ * Dark is the system default, so the foam fin is the one shown unless
+ * `data-theme="light"` says otherwise, and the two-blue one hides everywhere
+ * else. `not-light:hidden` rather than `hidden light:block`: the visible fin
+ * keeps whatever `display` the call site gave it.
+ *
+ * What it costs: the hidden image is still downloaded, 14 or 21 KB. And with
+ * `auto` the props land on BOTH `<img>` — an `id` or a `ref` included — so a
+ * call site that needs to reach the one image passes the background it is on.
+ * The `alt` does not double: an image with `display: none` is out of the
+ * accessibility tree.
+ */
 declare function Isotype({ background, basePath, alt, className, ...props }: IsotypeProps): react.JSX.Element;
 
 type LogoProps = Omit<ComponentPropsWithoutRef<'span'>, 'children'> & {
-    background?: Background | undefined;
+    /**
+     * 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.
+     */
+    background?: IsotypeBackground | undefined;
     basePath?: string | undefined;
     /** Hides the wordmark and leaves only the fin, for very narrow bars. */
     isotypeOnly?: boolean | undefined;
@@ -69,4 +108,4 @@ type MascotFaceProps = Base & {
  */
 declare function MascotFace({ expression, basePath, alt, className, ...props }: MascotFaceProps): react.JSX.Element;
 
-export { Background, Face, Isotype, type IsotypeProps, Logo, type LogoProps, Mascot, MascotFace, type MascotFaceProps, type MascotProps, Pose };
+export { Background, Face, Isotype, type IsotypeBackground, type IsotypeProps, Logo, type LogoProps, Mascot, MascotFace, type MascotFaceProps, type MascotProps, Pose };

package/dist/brand/index.d.ts

@@ -3,21 +3,60 @@ export { A as ASSETS_PATH, a as Fin, f as faceList, b as faceUsage, c as faces,
 import * as react from 'react';
 import { ComponentPropsWithoutRef } from 'react';
 
+/**
+ * Which background the fin sits on, or `auto` to let the theme decide.
+ *
+ * It is its own type and not a third member of `Background`, because
+ * `Background` is also what the OG templates read, and Satori has no CSS to
+ * resolve `auto` with: a template knows its mode and has to say it.
+ */
+type IsotypeBackground = Background | 'auto';
 type IsotypeProps = Omit<ComponentPropsWithoutRef<'img'>, 'src' | 'alt'> & {
     /**
-     * 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.
+     * 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.
+     *
+     * Use `dark` or `light` when the background does not follow the theme. A
+     * panel that stays dark in both modes is a fixed background, and `auto` would
+     * pick the page's fin instead of the panel's.
      */
-    background?: Background | undefined;
+    background?: IsotypeBackground | undefined;
     basePath?: string | undefined;
     /** Alt text. Empty when the isotype accompanies text that already names it. */
     alt?: string | undefined;
 };
+/**
+ * The fin, in the variant its background asks for.
+ *
+ * `auto` renders both and lets the `light:` variant choose, which is what
+ * `ThemeToggle` already does with its two icons and for the same reason: the
+ * server does not know the theme, and a fin picked in JavaScript would be wrong
+ * on the first paint half the time. `cursos` had written exactly this by hand
+ * after a surface changed mode and its fin vanished — not looked wrong: vanished,
+ * with no error and no gap in the layout. See `docs/decisions/0.11.md` § 60.
+ *
+ * Dark is the system default, so the foam fin is the one shown unless
+ * `data-theme="light"` says otherwise, and the two-blue one hides everywhere
+ * else. `not-light:hidden` rather than `hidden light:block`: the visible fin
+ * keeps whatever `display` the call site gave it.
+ *
+ * What it costs: the hidden image is still downloaded, 14 or 21 KB. And with
+ * `auto` the props land on BOTH `<img>` — an `id` or a `ref` included — so a
+ * call site that needs to reach the one image passes the background it is on.
+ * The `alt` does not double: an image with `display: none` is out of the
+ * accessibility tree.
+ */
 declare function Isotype({ background, basePath, alt, className, ...props }: IsotypeProps): react.JSX.Element;
 
 type LogoProps = Omit<ComponentPropsWithoutRef<'span'>, 'children'> & {
-    background?: Background | undefined;
+    /**
+     * 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.
+     */
+    background?: IsotypeBackground | undefined;
     basePath?: string | undefined;
     /** Hides the wordmark and leaves only the fin, for very narrow bars. */
     isotypeOnly?: boolean | undefined;
@@ -69,4 +108,4 @@ type MascotFaceProps = Base & {
  */
 declare function MascotFace({ expression, basePath, alt, className, ...props }: MascotFaceProps): react.JSX.Element;
 
-export { Background, Face, Isotype, type IsotypeProps, Logo, type LogoProps, Mascot, MascotFace, type MascotFaceProps, type MascotProps, Pose };
+export { Background, Face, Isotype, type IsotypeBackground, type IsotypeProps, Logo, type LogoProps, Mascot, MascotFace, type MascotFaceProps, type MascotProps, Pose };

package/dist/brand/index.js

@@ -1,5 +1,5 @@
 'use client';
-export { Isotype, Logo, Mascot, MascotFace } from '../chunk-IIT3YLYN.js';
+export { Isotype, Logo, Mascot, MascotFace } from '../chunk-RKGKO2TW.js';
 import '../chunk-FAAGZG7A.js';
 export { ASSETS_PATH, faceList, faceUsage, faces, fins, poseList, poses } from '../chunk-CKRSQPTX.js';
 import '../chunk-FGFNK72B.js';

package/dist/chart/index.cjs

@@ -300,6 +300,7 @@ var color = (series2, index) => series2.color ?? seriesColor(index);
 var MARGIN = { left: 0, right: 12, top: 8, bottom: 0 };
 var AXIS = { tickLine: false, axisLine: false };
 var tickOf = (format) => format ? { tickFormatter: format } : {};
+var domainOf = (max) => max === void 0 ? {} : { domain: [0, max] };
 var legendOf = (series2, legend) => legend ?? series2.length > 1 ? /* @__PURE__ */ jsxRuntime.jsx(ChartLegend, { content: /* @__PURE__ */ jsxRuntime.jsx(ChartLegendContent, {}) }, "legend") : null;
 var tooltipOf = (formatter) => /* @__PURE__ */ jsxRuntime.jsx(
   ChartTooltip,
@@ -316,6 +317,7 @@ function AreaChart({
   formatter,
   xTickFormatter,
   yTickFormatter,
+  valueMax,
   legend,
   stacked = false,
   ...container
@@ -328,7 +330,7 @@ function AreaChart({
     ] }, s.key)) }),
     /* @__PURE__ */ jsxRuntime.jsx(recharts.CartesianGrid, { vertical: false }),
     /* @__PURE__ */ jsxRuntime.jsx(recharts.XAxis, { dataKey: xKey, ...AXIS, tickMargin: 8, ...tickOf(xTickFormatter) }),
-    /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter) }),
+    /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter), ...domainOf(valueMax) }),
     tooltipOf(formatter),
     legendOf(series2, legend),
     series2.map((s, i) => /* @__PURE__ */ jsxRuntime.jsx(
@@ -354,6 +356,7 @@ function BarChart({
   formatter,
   xTickFormatter,
   yTickFormatter,
+  valueMax,
   legend,
   orientation = "vertical",
   stacked = false,
@@ -380,7 +383,16 @@ function BarChart({
             },
             "category"
           ),
-          /* @__PURE__ */ jsxRuntime.jsx(recharts.XAxis, { type: "number", hide: true, ...tickOf(yTickFormatter) }, "value")
+          /* @__PURE__ */ jsxRuntime.jsx(
+            recharts.XAxis,
+            {
+              type: "number",
+              hide: true,
+              ...tickOf(yTickFormatter),
+              ...domainOf(valueMax)
+            },
+            "value"
+          )
         ] : [
           /* @__PURE__ */ jsxRuntime.jsx(
             recharts.XAxis,
@@ -392,7 +404,16 @@ function BarChart({
             },
             "category"
           ),
-          /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter) }, "value")
+          /* @__PURE__ */ jsxRuntime.jsx(
+            recharts.YAxis,
+            {
+              ...AXIS,
+              width: 40,
+              ...tickOf(yTickFormatter),
+              ...domainOf(valueMax)
+            },
+            "value"
+          )
         ],
         tooltipOf(formatter),
         legendOf(series2, legend),
@@ -419,13 +440,14 @@ function LineChart({
   formatter,
   xTickFormatter,
   yTickFormatter,
+  valueMax,
   legend,
   ...container
 }) {
   return /* @__PURE__ */ jsxRuntime.jsx(ChartContainer, { ...container, children: /* @__PURE__ */ jsxRuntime.jsxs(recharts.LineChart, { data: rows(data), margin: MARGIN, children: [
     /* @__PURE__ */ jsxRuntime.jsx(recharts.CartesianGrid, { vertical: false }),
     /* @__PURE__ */ jsxRuntime.jsx(recharts.XAxis, { dataKey: xKey, ...AXIS, tickMargin: 8, ...tickOf(xTickFormatter) }),
-    /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter) }),
+    /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter), ...domainOf(valueMax) }),
     tooltipOf(formatter),
     legendOf(series2, legend),
     series2.map((s, i) => /* @__PURE__ */ jsxRuntime.jsx(

package/dist/chart/index.d.cts

@@ -187,6 +187,22 @@ type SeriesChartProps = Omit<ChartContainerProps, 'children'> & {
      * «$1200» in the tooltip, and the axis is the one you read while comparing.
      */
     yTickFormatter?: ((value: unknown) => string) | undefined;
+    /**
+     * The top of the value axis, when the scale has one that the data does not
+     * reach — 100 for a percentage.
+     *
+     * Without it the axis ends at the largest datum, and on a chart of «% visto»
+     * a course watched to 40 % draws as a full bar when it is the highest on the
+     * list. On `BarChart orientation="horizontal"` nothing gives that away: the
+     * value axis is hidden by design, so the chart says something false and
+     * looks exactly like one that does not.
+     *
+     * The bottom is always zero. A bar that does not start at zero is a
+     * different lie, and this prop is not a way into it. It is a floor for the
+     * top and not a clip either: a datum above it extends the axis instead of
+     * running off the edge. See `docs/decisions/0.11.md` § 58.
+     */
+    valueMax?: number | 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
@@ -217,7 +233,7 @@ type AreaChartProps = SeriesChartProps & {
     /** Adds the series up instead of overlaying them. */
     stacked?: boolean | undefined;
 };
-declare function AreaChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, stacked, ...container }: AreaChartProps): react.JSX.Element;
+declare function AreaChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, stacked, ...container }: AreaChartProps): react.JSX.Element;
 /**
  * Bars, upright or lying down.
  *
@@ -241,7 +257,7 @@ type BarChartProps = SeriesChartProps & {
     /** Stacks the series instead of putting them side by side. */
     stacked?: boolean | undefined;
 };
-declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, orientation, stacked, ...container }: BarChartProps): react.JSX.Element;
+declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, orientation, stacked, ...container }: BarChartProps): react.JSX.Element;
 /**
  * Lines, for comparing series against each other.
  *
@@ -254,6 +270,6 @@ declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTick
  * where it means «this one».
  */
 type LineChartProps = SeriesChartProps;
-declare function LineChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, ...container }: LineChartProps): react.JSX.Element;
+declare function LineChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, ...container }: LineChartProps): react.JSX.Element;
 
 export { AreaChart, type AreaChartProps, BarChart, type BarChartProps, ChartContainer, type ChartContainerProps, type ChartDatum, ChartLegend, ChartLegendContent, type ChartLegendContentProps, type ChartPayloadItem, type ChartSeries, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, LineChart, type LineChartProps, SERIES_COLORS, type SeriesChartProps, seriesColor };

package/dist/chart/index.d.ts

@@ -187,6 +187,22 @@ type SeriesChartProps = Omit<ChartContainerProps, 'children'> & {
      * «$1200» in the tooltip, and the axis is the one you read while comparing.
      */
     yTickFormatter?: ((value: unknown) => string) | undefined;
+    /**
+     * The top of the value axis, when the scale has one that the data does not
+     * reach — 100 for a percentage.
+     *
+     * Without it the axis ends at the largest datum, and on a chart of «% visto»
+     * a course watched to 40 % draws as a full bar when it is the highest on the
+     * list. On `BarChart orientation="horizontal"` nothing gives that away: the
+     * value axis is hidden by design, so the chart says something false and
+     * looks exactly like one that does not.
+     *
+     * The bottom is always zero. A bar that does not start at zero is a
+     * different lie, and this prop is not a way into it. It is a floor for the
+     * top and not a clip either: a datum above it extends the axis instead of
+     * running off the edge. See `docs/decisions/0.11.md` § 58.
+     */
+    valueMax?: number | 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
@@ -217,7 +233,7 @@ type AreaChartProps = SeriesChartProps & {
     /** Adds the series up instead of overlaying them. */
     stacked?: boolean | undefined;
 };
-declare function AreaChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, stacked, ...container }: AreaChartProps): react.JSX.Element;
+declare function AreaChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, stacked, ...container }: AreaChartProps): react.JSX.Element;
 /**
  * Bars, upright or lying down.
  *
@@ -241,7 +257,7 @@ type BarChartProps = SeriesChartProps & {
     /** Stacks the series instead of putting them side by side. */
     stacked?: boolean | undefined;
 };
-declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, orientation, stacked, ...container }: BarChartProps): react.JSX.Element;
+declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, orientation, stacked, ...container }: BarChartProps): react.JSX.Element;
 /**
  * Lines, for comparing series against each other.
  *
@@ -254,6 +270,6 @@ declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTick
  * where it means «this one».
  */
 type LineChartProps = SeriesChartProps;
-declare function LineChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, ...container }: LineChartProps): react.JSX.Element;
+declare function LineChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, ...container }: LineChartProps): react.JSX.Element;
 
 export { AreaChart, type AreaChartProps, BarChart, type BarChartProps, ChartContainer, type ChartContainerProps, type ChartDatum, ChartLegend, ChartLegendContent, type ChartLegendContentProps, type ChartPayloadItem, type ChartSeries, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, LineChart, type LineChartProps, SERIES_COLORS, type SeriesChartProps, seriesColor };

package/dist/chart/index.js

@@ -106,6 +106,7 @@ var color = (series, index) => series.color ?? seriesColor(index);
 var MARGIN = { left: 0, right: 12, top: 8, bottom: 0 };
 var AXIS = { tickLine: false, axisLine: false };
 var tickOf = (format) => format ? { tickFormatter: format } : {};
+var domainOf = (max) => max === void 0 ? {} : { domain: [0, max] };
 var legendOf = (series, legend) => legend ?? series.length > 1 ? /* @__PURE__ */ jsx(ChartLegend, { content: /* @__PURE__ */ jsx(ChartLegendContent, {}) }, "legend") : null;
 var tooltipOf = (formatter) => /* @__PURE__ */ jsx(
   ChartTooltip,
@@ -122,6 +123,7 @@ function AreaChart({
   formatter,
   xTickFormatter,
   yTickFormatter,
+  valueMax,
   legend,
   stacked = false,
   ...container
@@ -134,7 +136,7 @@ function AreaChart({
     ] }, s.key)) }),
     /* @__PURE__ */ jsx(CartesianGrid, { vertical: false }),
     /* @__PURE__ */ jsx(XAxis, { dataKey: xKey, ...AXIS, tickMargin: 8, ...tickOf(xTickFormatter) }),
-    /* @__PURE__ */ jsx(YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter) }),
+    /* @__PURE__ */ jsx(YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter), ...domainOf(valueMax) }),
     tooltipOf(formatter),
     legendOf(series, legend),
     series.map((s, i) => /* @__PURE__ */ jsx(
@@ -160,6 +162,7 @@ function BarChart({
   formatter,
   xTickFormatter,
   yTickFormatter,
+  valueMax,
   legend,
   orientation = "vertical",
   stacked = false,
@@ -186,7 +189,16 @@ function BarChart({
             },
             "category"
           ),
-          /* @__PURE__ */ jsx(XAxis, { type: "number", hide: true, ...tickOf(yTickFormatter) }, "value")
+          /* @__PURE__ */ jsx(
+            XAxis,
+            {
+              type: "number",
+              hide: true,
+              ...tickOf(yTickFormatter),
+              ...domainOf(valueMax)
+            },
+            "value"
+          )
         ] : [
           /* @__PURE__ */ jsx(
             XAxis,
@@ -198,7 +210,16 @@ function BarChart({
             },
             "category"
           ),
-          /* @__PURE__ */ jsx(YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter) }, "value")
+          /* @__PURE__ */ jsx(
+            YAxis,
+            {
+              ...AXIS,
+              width: 40,
+              ...tickOf(yTickFormatter),
+              ...domainOf(valueMax)
+            },
+            "value"
+          )
         ],
         tooltipOf(formatter),
         legendOf(series, legend),
@@ -225,13 +246,14 @@ function LineChart({
   formatter,
   xTickFormatter,
   yTickFormatter,
+  valueMax,
   legend,
   ...container
 }) {
   return /* @__PURE__ */ jsx(ChartContainer, { ...container, children: /* @__PURE__ */ jsxs(LineChart$1, { data: rows(data), margin: MARGIN, children: [
     /* @__PURE__ */ jsx(CartesianGrid, { vertical: false }),
     /* @__PURE__ */ jsx(XAxis, { dataKey: xKey, ...AXIS, tickMargin: 8, ...tickOf(xTickFormatter) }),
-    /* @__PURE__ */ jsx(YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter) }),
+    /* @__PURE__ */ jsx(YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter), ...domainOf(valueMax) }),
     tooltipOf(formatter),
     legendOf(series, legend),
     series.map((s, i) => /* @__PURE__ */ jsx(

package/dist/{chunk-IIT3YLYN.js → chunk-RKGKO2TW.js}

@@ -1,7 +1,7 @@
 import { cn } from './chunk-FAAGZG7A.js';
 import { fins, ASSETS_PATH, poses, faces } from './chunk-CKRSQPTX.js';
 import { naming, tagline } from './chunk-FGFNK72B.js';
-import { jsx, jsxs } from 'react/jsx-runtime';
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 
 function Isotype({
   background = "dark",
@@ -10,18 +10,24 @@ function Isotype({
   className,
   ...props
 }) {
-  const file = background === "dark" ? fins.foam : fins.color;
-  return /* @__PURE__ */ jsx(
+  const fin = (file, mode) => /* @__PURE__ */ jsx(
     "img",
     {
       src: `${basePath}/${file}`,
       alt,
       width: 147,
       height: 111,
-      className: cn("h-8 w-auto select-none", className),
+      className: cn("h-8 w-auto select-none", className, mode),
       ...props
     }
   );
+  if (background === "auto") {
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      fin(fins.foam, "light:hidden"),
+      fin(fins.color, "not-light:hidden")
+    ] });
+  }
+  return fin(background === "dark" ? fins.foam : fins.color);
 }
 function Logo({
   background = "dark",

package/dist/index.cjs

@@ -2874,25 +2874,62 @@ function CourseCard({
   meta,
   status,
   progress,
+  media,
+  footer,
   className,
   ...props
 }) {
-  return /* @__PURE__ */ jsxRuntime.jsx(CardShell, { className: cn("p-step-lg", className), ...props, children: /* @__PURE__ */ jsxRuntime.jsxs("article", { className: "gap-step-sm flex h-full flex-col", children: [
-    status ? /* @__PURE__ */ jsxRuntime.jsx("div", { children: /* @__PURE__ */ jsxRuntime.jsx(Badge, { variant: "warm", children: status }) }) : null,
-    /* @__PURE__ */ jsxRuntime.jsx(Text, { as: "h3", variant: "h3", className: "group-hover:text-accent transition-standard", children: title }),
-    summary ? /* @__PURE__ */ jsxRuntime.jsx(Text, { variant: "ui", tone: "secondary", className: "line-clamp-3", children: summary }) : null,
-    meta && meta.length > 0 ? /* @__PURE__ */ jsxRuntime.jsx(Text, { variant: "label", tone: "muted", as: "p", className: "gap-step-xs flex flex-wrap items-center", children: meta.map((m, i) => /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "gap-step-xs flex items-center", children: [
-      i > 0 ? /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\xB7" }) : null,
-      m
-    ] }, i)) }) : null,
-    typeof progress === "number" ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "gap-step-xs mt-auto flex flex-col pt-step-sm", children: [
-      /* @__PURE__ */ jsxRuntime.jsx(Progress, { value: progress, tone: "warm", label: `Progreso del curso: ${progress}%` }),
-      /* @__PURE__ */ jsxRuntime.jsxs(Text, { variant: "label", tone: "muted", as: "p", children: [
-        progress,
-        "% cursado"
-      ] })
-    ] }) : null
-  ] }) });
+  const hasProgress = typeof progress === "number";
+  return (
+    // `overflow-hidden` only with a cover: it is what rounds the cover's top
+    // corners to the card's. It clips the content and not the `<a>` itself, so
+    // the focus ring — an outline three pixels outside — still shows.
+    /* @__PURE__ */ jsxRuntime.jsx(
+      CardShell,
+      {
+        className: cn("p-step-lg", media ? "overflow-hidden" : null, className),
+        ...props,
+        children: /* @__PURE__ */ jsxRuntime.jsxs("article", { className: "gap-step-sm flex h-full flex-col", children: [
+          media ? (
+            // The bleed is the card's own padding, negated. A call site that
+            // changes the padding through `className` has to change this too, and
+            // that is the trade for keeping the padding on the shell like every
+            // other card instead of in a second place only when there is a cover.
+            /* @__PURE__ */ jsxRuntime.jsx("div", { className: "-mx-step-lg -mt-step-lg mb-step-xs", children: media })
+          ) : null,
+          status ? /* @__PURE__ */ jsxRuntime.jsx("div", { children: /* @__PURE__ */ jsxRuntime.jsx(Badge, { variant: "warm", children: status }) }) : null,
+          /* @__PURE__ */ jsxRuntime.jsx(Text, { as: "h3", variant: "h3", className: "group-hover:text-accent transition-standard", children: title }),
+          summary ? /* @__PURE__ */ jsxRuntime.jsx(Text, { variant: "ui", tone: "secondary", className: "line-clamp-3", children: summary }) : null,
+          meta && meta.length > 0 ? /* @__PURE__ */ jsxRuntime.jsx(Text, { variant: "label", tone: "muted", as: "p", className: "gap-step-xs flex flex-wrap items-center", children: meta.map((m, i) => /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "gap-step-xs flex items-center", children: [
+            i > 0 ? /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\xB7" }) : null,
+            m
+          ] }, i)) }) : null,
+          hasProgress ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "gap-step-xs mt-auto flex flex-col pt-step-sm", children: [
+            /* @__PURE__ */ jsxRuntime.jsx(Progress, { value: progress, tone: "warm", label: `Progreso del curso: ${progress}%` }),
+            /* @__PURE__ */ jsxRuntime.jsxs(Text, { variant: "label", tone: "muted", as: "p", children: [
+              progress,
+              "% cursado"
+            ] })
+          ] }) : null,
+          footer ? (
+            // Only one of the two takes `mt-auto`. Two auto margins in one column
+            // split the free space between them, and the progress bar would float
+            // halfway down the card.
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "div",
+              {
+                className: cn(
+                  "gap-step-sm pt-step-sm flex flex-wrap items-center justify-between",
+                  hasProgress ? null : "mt-auto"
+                ),
+                children: footer
+              }
+            )
+          ) : null
+        ] })
+      }
+    )
+  );
 }
 
 // src/brand/catalog.ts
@@ -3643,12 +3680,21 @@ function PageHeader({
   action,
   size: size2,
   as = "h1",
+  titleVariant,
   className,
   ...props
 }) {
   return /* @__PURE__ */ jsxRuntime.jsxs("header", { className: cn(header({ size: size2 }), className), ...props, children: [
     eyebrow ? /* @__PURE__ */ jsxRuntime.jsx(Text, { variant: "eyebrow", tone: "accent", as: "p", children: eyebrow }) : null,
-    /* @__PURE__ */ jsxRuntime.jsx(Text, { as, variant: size2 === "display" ? "display" : "h1", className: "max-w-measure", children: title }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      Text,
+      {
+        as,
+        variant: titleVariant ?? (size2 === "display" ? "display" : "h1"),
+        className: "max-w-measure",
+        children: title
+      }
+    ),
     description ? /* @__PURE__ */ jsxRuntime.jsx(Text, { variant: "body", tone: "secondary", children: description }) : null,
     action ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "gap-step-sm mt-step-sm flex flex-wrap items-center", children: action }) : null
   ] });
@@ -3895,18 +3941,24 @@ function Isotype({
   className,
   ...props
 }) {
-  const file = background === "dark" ? fins.foam : fins.color;
-  return /* @__PURE__ */ jsxRuntime.jsx(
+  const fin = (file, mode) => /* @__PURE__ */ jsxRuntime.jsx(
     "img",
     {
       src: `${basePath}/${file}`,
       alt,
       width: 147,
       height: 111,
-      className: cn("h-8 w-auto select-none", className),
+      className: cn("h-8 w-auto select-none", className, mode),
       ...props
     }
   );
+  if (background === "auto") {
+    return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      fin(fins.foam, "light:hidden"),
+      fin(fins.color, "not-light:hidden")
+    ] });
+  }
+  return fin(background === "dark" ? fins.foam : fins.color);
 }
 function Logo({
   background = "dark",

package/dist/index.d.cts

@@ -26,7 +26,7 @@ import * as ToastPrimitive from '@radix-ui/react-toast';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 import { F as Face, P as Pose } from './catalog-D13txprv.cjs';
 export { A as ASSETS_PATH, B as Background, a as Fin, f as faceList, b as faceUsage, c as faces, d as fins, p as poseList, e as poses } from './catalog-D13txprv.cjs';
-export { Isotype, IsotypeProps, Logo, LogoProps, Mascot, MascotFace, MascotFaceProps, MascotProps } from './brand/index.cjs';
+export { Isotype, IsotypeBackground, IsotypeProps, Logo, LogoProps, Mascot, MascotFace, MascotFaceProps, MascotProps } from './brand/index.cjs';
 import { ClassValue } from 'clsx';
 import '@radix-ui/react-label';
 
@@ -869,7 +869,13 @@ type CodeBlockProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'> & {
 };
 declare function CodeBlock({ children, language, copyText, className, ...props }: CodeBlockProps): react.JSX.Element;
 
-type CourseCardProps = Omit<CardShellProps, 'children' | 'title'> & {
+/**
+ * `media` is left out of the shell's props because `<a>` already has an
+ * attribute by that name — a media query for the linked resource, a string —
+ * and intersected with the slot it would make the slot accept only strings.
+ * No browser acts on it and no project was passing it.
+ */
+type CourseCardProps = Omit<CardShellProps, 'children' | 'title' | 'media'> & {
     title: ReactNode;
     summary?: ReactNode;
     /** Level, duration, number of lessons: whatever the project wants to list. */
@@ -881,8 +887,42 @@ type CourseCardProps = Omit<CardShellProps, 'children' | 'title'> & {
      * when passed, the bar goes in sand, which is the color of course progress.
      */
     progress?: number | undefined;
+    /**
+     * 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.
+     *
+     * The project owns the element — an `<img>`, a framework's `Image`, a
+     * generated cover — and its ratio; the card clips it to its own corners. An
+     * `alt` that repeats the title makes a screen reader say the course twice
+     * before anything else.
+     */
+    media?: 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.
+     */
+    footer?: ReactNode;
 };
-declare function CourseCard({ title, summary, meta, status, progress, className, ...props }: CourseCardProps): react.JSX.Element;
+/**
+ * The course, as a card that links to it.
+ *
+ * `media` and `footer` are slots rather than props for a cover URL, a rating
+ * and a price, because none of those three is the identity's. The price comes
+ * formatted in a currency the library does not know, the rating is drawn by a
+ * component the project already has, and the cover is an image pipeline. What
+ * IS the identity's stays here: the title's scale and its hover, the sand bar,
+ * the status badge. See `docs/decisions/0.11.md` § 59.
+ *
+ * The title does NOT go over the cover. It stays in the body at `h3`, with the
+ * hover every other card has. Text on a photograph needs a scrim, and a scrim's
+ * contrast depends on the photograph: it cannot be measured once and recorded,
+ * which is the only way contrast is decided in this system.
+ *
+ * And the cover does not move on hover. Rule 6 is the border and nothing else:
+ * no zoom, no scale, no displacement.
+ */
+declare function CourseCard({ title, summary, meta, status, progress, media, footer, className, ...props }: CourseCardProps): react.JSX.Element;
 
 /**
  * The mascot's most important rule, finally as code.
@@ -1392,6 +1432,15 @@ declare function NewsletterForm({ title, description, state, onSubmitEmail, succ
  *
  * `display` for covers, `page` for section headers.
  *
+ * The size picks the title's scale by default, and `titleVariant` lets the
+ * screen pick another one. The default is the document's — «h1 44/700» on the
+ * six interior pages of the reading site — and it is right there. It is not
+ * right in the two admin apps: `blog-content-manager` titles its twelve screens
+ * at 24px, and `cursos` titles 29 of its 32 at `h3` — every one in the panel —
+ * and the other three, the public catalog pages, at `h2`. Both are rungs the
+ * scale already has, and a third `size` could only have named one of them. See
+ * `docs/decisions/0.11.md` § 57.
+ *
  * It takes no mascot face, at either scale: faces go in empty states,
  * confirmations, errors, course progress and celebration.
  *
@@ -1416,8 +1465,21 @@ type PageHeaderProps = Omit<ComponentPropsWithoutRef<'header'>, 'title'> & Varia
     action?: ReactNode | undefined;
     /** The headline's level. `h1` unless the page already has one. */
     as?: 'h1' | 'h2' | undefined;
+    /**
+     * The headline's scale, when the screen needs a different one from what
+     * `size` gives — `display` for `display`, `h1` for `page`.
+     *
+     * It is the same split `Text` makes: `as` is the level, this is how big it
+     * looks. A panel's `<h1>` at `h3` is still the page's only `h1`. The padding
+     * stays with `size`, so a header inside a layout that already spaces its
+     * content passes `className="py-0"`.
+     *
+     * Only the four headline scales, all in the display family. `stat` is for
+     * numbers and `body` is not a headline.
+     */
+    titleVariant?: 'display' | 'h1' | 'h2' | 'h3' | undefined;
 };
-declare function PageHeader({ title, eyebrow, description, action, size, as, className, ...props }: PageHeaderProps): react.JSX.Element;
+declare function PageHeader({ title, eyebrow, description, action, size, as, titleVariant, className, ...props }: PageHeaderProps): react.JSX.Element;
 
 /**
  * How much you have read. It is NOT `Progress` under another name.

package/dist/index.d.ts

@@ -26,7 +26,7 @@ import * as ToastPrimitive from '@radix-ui/react-toast';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 import { F as Face, P as Pose } from './catalog-D13txprv.js';
 export { A as ASSETS_PATH, B as Background, a as Fin, f as faceList, b as faceUsage, c as faces, d as fins, p as poseList, e as poses } from './catalog-D13txprv.js';
-export { Isotype, IsotypeProps, Logo, LogoProps, Mascot, MascotFace, MascotFaceProps, MascotProps } from './brand/index.js';
+export { Isotype, IsotypeBackground, IsotypeProps, Logo, LogoProps, Mascot, MascotFace, MascotFaceProps, MascotProps } from './brand/index.js';
 import { ClassValue } from 'clsx';
 import '@radix-ui/react-label';
 
@@ -869,7 +869,13 @@ type CodeBlockProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'> & {
 };
 declare function CodeBlock({ children, language, copyText, className, ...props }: CodeBlockProps): react.JSX.Element;
 
-type CourseCardProps = Omit<CardShellProps, 'children' | 'title'> & {
+/**
+ * `media` is left out of the shell's props because `<a>` already has an
+ * attribute by that name — a media query for the linked resource, a string —
+ * and intersected with the slot it would make the slot accept only strings.
+ * No browser acts on it and no project was passing it.
+ */
+type CourseCardProps = Omit<CardShellProps, 'children' | 'title' | 'media'> & {
     title: ReactNode;
     summary?: ReactNode;
     /** Level, duration, number of lessons: whatever the project wants to list. */
@@ -881,8 +887,42 @@ type CourseCardProps = Omit<CardShellProps, 'children' | 'title'> & {
      * when passed, the bar goes in sand, which is the color of course progress.
      */
     progress?: number | undefined;
+    /**
+     * 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.
+     *
+     * The project owns the element — an `<img>`, a framework's `Image`, a
+     * generated cover — and its ratio; the card clips it to its own corners. An
+     * `alt` that repeats the title makes a screen reader say the course twice
+     * before anything else.
+     */
+    media?: 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.
+     */
+    footer?: ReactNode;
 };
-declare function CourseCard({ title, summary, meta, status, progress, className, ...props }: CourseCardProps): react.JSX.Element;
+/**
+ * The course, as a card that links to it.
+ *
+ * `media` and `footer` are slots rather than props for a cover URL, a rating
+ * and a price, because none of those three is the identity's. The price comes
+ * formatted in a currency the library does not know, the rating is drawn by a
+ * component the project already has, and the cover is an image pipeline. What
+ * IS the identity's stays here: the title's scale and its hover, the sand bar,
+ * the status badge. See `docs/decisions/0.11.md` § 59.
+ *
+ * The title does NOT go over the cover. It stays in the body at `h3`, with the
+ * hover every other card has. Text on a photograph needs a scrim, and a scrim's
+ * contrast depends on the photograph: it cannot be measured once and recorded,
+ * which is the only way contrast is decided in this system.
+ *
+ * And the cover does not move on hover. Rule 6 is the border and nothing else:
+ * no zoom, no scale, no displacement.
+ */
+declare function CourseCard({ title, summary, meta, status, progress, media, footer, className, ...props }: CourseCardProps): react.JSX.Element;
 
 /**
  * The mascot's most important rule, finally as code.
@@ -1392,6 +1432,15 @@ declare function NewsletterForm({ title, description, state, onSubmitEmail, succ
  *
  * `display` for covers, `page` for section headers.
  *
+ * The size picks the title's scale by default, and `titleVariant` lets the
+ * screen pick another one. The default is the document's — «h1 44/700» on the
+ * six interior pages of the reading site — and it is right there. It is not
+ * right in the two admin apps: `blog-content-manager` titles its twelve screens
+ * at 24px, and `cursos` titles 29 of its 32 at `h3` — every one in the panel —
+ * and the other three, the public catalog pages, at `h2`. Both are rungs the
+ * scale already has, and a third `size` could only have named one of them. See
+ * `docs/decisions/0.11.md` § 57.
+ *
  * It takes no mascot face, at either scale: faces go in empty states,
  * confirmations, errors, course progress and celebration.
  *
@@ -1416,8 +1465,21 @@ type PageHeaderProps = Omit<ComponentPropsWithoutRef<'header'>, 'title'> & Varia
     action?: ReactNode | undefined;
     /** The headline's level. `h1` unless the page already has one. */
     as?: 'h1' | 'h2' | undefined;
+    /**
+     * The headline's scale, when the screen needs a different one from what
+     * `size` gives — `display` for `display`, `h1` for `page`.
+     *
+     * It is the same split `Text` makes: `as` is the level, this is how big it
+     * looks. A panel's `<h1>` at `h3` is still the page's only `h1`. The padding
+     * stays with `size`, so a header inside a layout that already spaces its
+     * content passes `className="py-0"`.
+     *
+     * Only the four headline scales, all in the display family. `stat` is for
+     * numbers and `body` is not a headline.
+     */
+    titleVariant?: 'display' | 'h1' | 'h2' | 'h3' | undefined;
 };
-declare function PageHeader({ title, eyebrow, description, action, size, as, className, ...props }: PageHeaderProps): react.JSX.Element;
+declare function PageHeader({ title, eyebrow, description, action, size, as, titleVariant, className, ...props }: PageHeaderProps): react.JSX.Element;
 
 /**
  * How much you have read. It is NOT `Progress` under another name.

package/dist/index.js

@@ -9,8 +9,8 @@ export { THEME_ATTRIBUTE, THEME_EVENT, THEME_KEY, applyTheme, currentTheme, pref
 import { alert, button, avatar, badge, category, metric, CARD_SURFACE, CARD } from './chunk-XXDATT3A.js';
 export { CARD, CARD_HOVER, CARD_SURFACE, alert as alertVariants, avatar as avatarVariants, badge as badgeVariants, button as buttonVariants, category as categoryBadgeVariants, metric as metricBadgeVariants } from './chunk-XXDATT3A.js';
 export { text as textVariants } from './chunk-ODBFN44D.js';
-import { MascotFace, Mascot } from './chunk-IIT3YLYN.js';
-export { Isotype, Logo, Mascot, MascotFace } from './chunk-IIT3YLYN.js';
+import { MascotFace, Mascot } from './chunk-RKGKO2TW.js';
+export { Isotype, Logo, Mascot, MascotFace } from './chunk-RKGKO2TW.js';
 import { Icon } from './chunk-ZSCSKCTY.js';
 import { cn } from './chunk-FAAGZG7A.js';
 export { cn } from './chunk-FAAGZG7A.js';
@@ -2181,25 +2181,62 @@ function CourseCard({
   meta,
   status,
   progress,
+  media,
+  footer,
   className,
   ...props
 }) {
-  return /* @__PURE__ */ jsx(CardShell, { className: cn("p-step-lg", className), ...props, children: /* @__PURE__ */ jsxs("article", { className: "gap-step-sm flex h-full flex-col", children: [
-    status ? /* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(Badge, { variant: "warm", children: status }) }) : null,
-    /* @__PURE__ */ jsx(Text, { as: "h3", variant: "h3", className: "group-hover:text-accent transition-standard", children: title }),
-    summary ? /* @__PURE__ */ jsx(Text, { variant: "ui", tone: "secondary", className: "line-clamp-3", children: summary }) : null,
-    meta && meta.length > 0 ? /* @__PURE__ */ jsx(Text, { variant: "label", tone: "muted", as: "p", className: "gap-step-xs flex flex-wrap items-center", children: meta.map((m, i) => /* @__PURE__ */ jsxs("span", { className: "gap-step-xs flex items-center", children: [
-      i > 0 ? /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xB7" }) : null,
-      m
-    ] }, i)) }) : null,
-    typeof progress === "number" ? /* @__PURE__ */ jsxs("div", { className: "gap-step-xs mt-auto flex flex-col pt-step-sm", children: [
-      /* @__PURE__ */ jsx(Progress, { value: progress, tone: "warm", label: `Progreso del curso: ${progress}%` }),
-      /* @__PURE__ */ jsxs(Text, { variant: "label", tone: "muted", as: "p", children: [
-        progress,
-        "% cursado"
-      ] })
-    ] }) : null
-  ] }) });
+  const hasProgress = typeof progress === "number";
+  return (
+    // `overflow-hidden` only with a cover: it is what rounds the cover's top
+    // corners to the card's. It clips the content and not the `<a>` itself, so
+    // the focus ring — an outline three pixels outside — still shows.
+    /* @__PURE__ */ jsx(
+      CardShell,
+      {
+        className: cn("p-step-lg", media ? "overflow-hidden" : null, className),
+        ...props,
+        children: /* @__PURE__ */ jsxs("article", { className: "gap-step-sm flex h-full flex-col", children: [
+          media ? (
+            // The bleed is the card's own padding, negated. A call site that
+            // changes the padding through `className` has to change this too, and
+            // that is the trade for keeping the padding on the shell like every
+            // other card instead of in a second place only when there is a cover.
+            /* @__PURE__ */ jsx("div", { className: "-mx-step-lg -mt-step-lg mb-step-xs", children: media })
+          ) : null,
+          status ? /* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(Badge, { variant: "warm", children: status }) }) : null,
+          /* @__PURE__ */ jsx(Text, { as: "h3", variant: "h3", className: "group-hover:text-accent transition-standard", children: title }),
+          summary ? /* @__PURE__ */ jsx(Text, { variant: "ui", tone: "secondary", className: "line-clamp-3", children: summary }) : null,
+          meta && meta.length > 0 ? /* @__PURE__ */ jsx(Text, { variant: "label", tone: "muted", as: "p", className: "gap-step-xs flex flex-wrap items-center", children: meta.map((m, i) => /* @__PURE__ */ jsxs("span", { className: "gap-step-xs flex items-center", children: [
+            i > 0 ? /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xB7" }) : null,
+            m
+          ] }, i)) }) : null,
+          hasProgress ? /* @__PURE__ */ jsxs("div", { className: "gap-step-xs mt-auto flex flex-col pt-step-sm", children: [
+            /* @__PURE__ */ jsx(Progress, { value: progress, tone: "warm", label: `Progreso del curso: ${progress}%` }),
+            /* @__PURE__ */ jsxs(Text, { variant: "label", tone: "muted", as: "p", children: [
+              progress,
+              "% cursado"
+            ] })
+          ] }) : null,
+          footer ? (
+            // Only one of the two takes `mt-auto`. Two auto margins in one column
+            // split the free space between them, and the progress bar would float
+            // halfway down the card.
+            /* @__PURE__ */ jsx(
+              "div",
+              {
+                className: cn(
+                  "gap-step-sm pt-step-sm flex flex-wrap items-center justify-between",
+                  hasProgress ? null : "mt-auto"
+                ),
+                children: footer
+              }
+            )
+          ) : null
+        ] })
+      }
+    )
+  );
 }
 var FACE = "w-[66px] max-w-none";
 function EmptyState(props) {
@@ -2881,12 +2918,21 @@ function PageHeader({
   action,
   size: size2,
   as = "h1",
+  titleVariant,
   className,
   ...props
 }) {
   return /* @__PURE__ */ jsxs("header", { className: cn(header({ size: size2 }), className), ...props, children: [
     eyebrow ? /* @__PURE__ */ jsx(Text, { variant: "eyebrow", tone: "accent", as: "p", children: eyebrow }) : null,
-    /* @__PURE__ */ jsx(Text, { as, variant: size2 === "display" ? "display" : "h1", className: "max-w-measure", children: title }),
+    /* @__PURE__ */ jsx(
+      Text,
+      {
+        as,
+        variant: titleVariant ?? (size2 === "display" ? "display" : "h1"),
+        className: "max-w-measure",
+        children: title
+      }
+    ),
     description ? /* @__PURE__ */ jsx(Text, { variant: "body", tone: "secondary", children: description }) : null,
     action ? /* @__PURE__ */ jsx("div", { className: "gap-step-sm mt-step-sm flex flex-wrap items-center", children: action }) : null
   ] });

package/llms.txt

@@ -480,6 +480,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/0.11.md` § 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`.
@@ -590,6 +597,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/0.11.md` § 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**,
@@ -610,6 +621,11 @@ compiles and looks wrong, or that fails the project's accessibility audit.
     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.
+    **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/0.11.md` § 60.
 
 ## What the library does NOT do, on purpose
 
@@ -625,6 +641,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/0.11.md` § 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 +1411,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». |
@@ -1557,6 +1583,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
 
@@ -1645,12 +1672,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 +1692,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 +1848,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 +1869,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 +1888,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. |
@@ -1937,7 +1969,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`
 

package/package.json

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