@eduardoalvarez/arrecife 0.10.0 → 0.12.0

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';
 
@@ -48,7 +48,7 @@ import '@radix-ui/react-label';
  * `--ease-standard`, so it introduces neither a new timing nor a new curve.
  * Whoever asked for less motion still sees the panel appear where it will stay.
  *
- * See `docs/decisions/0.6.md` § 20.
+ * See `docs/decisions/` § 20.
  *
  * The chevron, by contrast, rotates with no transition: `transition-standard`
  * only covers color and border, so `rotate` snaps even with the class in place.
@@ -111,7 +111,7 @@ declare function Alert({ className, variant, emphasis, title, icon, children, ..
  * «Borrar el artículo», not «Aceptar».
  *
  * `destructive` is for the destructive button that has none of that around it:
- * a table row, a toolbar. See `docs/decisions/0.6.md` § 21.
+ * a table row, a toolbar. See `docs/decisions/` § 21.
  */
 declare const AlertDialog: react.FC<AlertDialogPrimitive.AlertDialogProps>;
 declare const AlertDialogTrigger: react.ForwardRefExoticComponent<AlertDialogPrimitive.AlertDialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
@@ -497,7 +497,7 @@ declare function Switch({ className, ...props }: SwitchProps): react.JSX.Element
  * `Nav`'s `size` documents: a `rounded-none` passed from the call site does
  * nothing, silently. There is one shape on purpose — fourteen call sites wanted
  * the same one — and a second gets a prop when a second consumer exists, not
- * before. See `docs/decisions/0.8.md` § 39.
+ * before. See `docs/decisions/` § 39.
  *
  * THE `tabIndex` IS NOT DECORATION and it is not new behaviour dressed up as
  * markup. A region you can pan with a mouse has to be reachable with a keyboard
@@ -771,7 +771,7 @@ declare function AuthorCard({ name, role, src, bio, action, className, ...props
  *   paths this file used to carry verbatim from the portfolio are gone with
  *   `lib/glyphs.tsx`; `Play`, `Pause`, `SpeakerHigh` and `SpeakerSlash` are the
  *   same symbols in Phosphor's hand, and the ±15s skips are `ArrowCounterClockwise`
- *   and `ArrowClockwise`. See `docs/decisions/0.10.md` § 51.
+ *   and `ArrowClockwise`. See `docs/decisions/` § 51.
  * - analytics' `trackEvent` → the `onFirstPlay` prop, which the consumer wires
  *   to whatever they use. It still fires exactly once per load.
  *
@@ -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/` § 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.
@@ -901,7 +941,7 @@ declare function CourseCard({ title, summary, meta, status, progress, className,
  * smaller one: the hole inside a table page or a dashboard widget, competing with
  * a dozen elements around it. An admin panel has twenty of those on one screen,
  * and twenty faces is not the humour contract, it is a zoo. The variant carries
- * no face, and the type does not let one through. See `docs/decisions/0.7.md` § 27.
+ * no face, and the type does not let one through. See `docs/decisions/` § 27.
  */
 type EmptyStateBase = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
     title: ReactNode;
@@ -990,7 +1030,7 @@ declare function EventCalendar({ events, onCreateEvent, onUpdateEvent, onDeleteE
  * The domain defaults to `naming.domain` and not to a hand-written string, for
  * the same reason as the wordmark: if it changes, it changes in all five
  * projects at once. A project that lives on its OWN domain passes `domain` —
- * see `docs/decisions/0.9.md` § 49.
+ * see `docs/decisions/` § 49.
  *
  * The social links are icons with NO visible text, so `aria-label` is not an
  * improvement: it is the only thing that makes them legible. Which is why it is
@@ -1006,7 +1046,7 @@ declare function EventCalendar({ events, onCreateEvent, onUpdateEvent, onDeleteE
  * answer has not moved: `EmptyState` is a discriminated union where `page` is
  * the default and `inline` cannot be handed a face; `Nav` takes a `size` where
  * `default` is the bar it always was. Both left what was written before exactly
- * where it was. See `docs/decisions/0.8.md` § 44.
+ * where it was. See `docs/decisions/` § 44.
  *
  * The union is what holds the rule up. `columns`, `description` and `action`
  * exist only on `full`, and the default form cannot be handed one. As loose
@@ -1054,7 +1094,7 @@ type FooterColumn = {
  * `./aviso-legal` — and that row is what `variant="full"`'s columns replace. A
  * flat row cannot say which block a link belongs to, cannot carry a heading a
  * screen reader can jump to, and made whoever wrote the label type the `./`
- * themselves, which the columns put there. See docs/decisions/0.8.md § 47.
+ * themselves, which the columns put there. See docs/decisions/ § 47.
  */
 type FooterBase = Omit<ComponentPropsWithoutRef<'footer'>, 'children'> & {
     social?: readonly SocialLink[];
@@ -1089,10 +1129,25 @@ type FooterBase = Omit<ComponentPropsWithoutRef<'footer'>, 'children'> & {
      * have warned about.
      *
      * It is a domain and not a whole signature: the `$`, the `cd ~/` and the year
-     * are the identity's and stay the component's. See `docs/decisions/0.9.md`
+     * are the identity's and stay the component's. See `docs/decisions/`
      * § 49.
      */
     domain?: string | undefined;
+    /**
+     * Adds «Creado con Arrecife ♥», linking to the library's Storybook.
+     *
+     * OFF BY DEFAULT, and that is the decision rather than the default. No
+     * consuming project credits the library today — the four were read before
+     * this was written — so turning it on for everybody would be the library
+     * putting a line into five production footers that none of them asked for.
+     * That is the move § 45 is about, and it does not get made twice.
+     *
+     * A site that wants it passes `builtWith`. It is a boolean and not a slot: the
+     * string and the destination are the library's, and a slot would be an
+     * invitation to write «Hecho con Arrecife» on one site and «Creado con» on the
+     * next, which is the drift this package exists to remove.
+     */
+    builtWith?: boolean | undefined;
 };
 type FooterProps = FooterBase & ({
     /** The shape the library has always had: stacked rows and the signature at the top right. */
@@ -1128,7 +1183,7 @@ type FooterProps = FooterBase & ({
         children: ReactNode;
     }) => ReactNode) | undefined;
 });
-declare function Footer({ variant, columns, description, action, linkAsChild, social, brand, year, signatureHref, domain, className, ...rest }: FooterProps): react.JSX.Element;
+declare function Footer({ variant, columns, description, action, linkAsChild, social, brand, builtWith, year, signatureHref, domain, className, ...rest }: FooterProps): react.JSX.Element;
 
 /**
  * ONE per site. It is the only piece in the system that is spent like the
@@ -1262,7 +1317,7 @@ type NavItemProps = ComponentPropsWithoutRef<'a'> & {
  * impossible to call. It passed `tsc` and it passed the build, because the shape
  * of the children is not something either one looks at. `Slottable` is Radix's
  * answer to exactly this: it marks which child the router's `Link` replaces and
- * leaves the decoration where it is. See `docs/decisions/0.8.md` § 40.
+ * leaves the decoration where it is. See `docs/decisions/` § 40.
  */
 declare function NavItem({ active, asChild, className, children, ...props }: NavItemProps): react.JSX.Element;
 
@@ -1392,6 +1447,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/` § 57.
+ *
  * It takes no mascot face, at either scale: faces go in empty states,
  * confirmations, errors, course progress and celebration.
  *
@@ -1416,8 +1480,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.
@@ -1481,7 +1558,7 @@ declare function ScrollingProgressBar({ target, tone, sticky, className, ...prop
  * eyebrow is the same length in none of them, so an inline icon puts the only
  * coloured mark on a different x in every card; pinned to the corner it lands on
  * a grid. The circle is the tint pattern the system already has — `bg-accent/10`
- * as a surface and the colour on the GLYPH, per `docs/decisions/0.6.md` § 4b — and a
+ * as a surface and the colour on the GLYPH, per `docs/decisions/` § 4b — and a
  * glyph clears the 3:1 graphical threshold where text would not clear 4.5.
  *
  * WHICH IS WHY A NEUTRAL NUMBER IS PRIMARY INK AND NOT BIOLUME. With a biolume
@@ -1489,7 +1566,7 @@ declare function ScrollingProgressBar({ target, tone, sticky, className, ...prop
  * the size of a postcard, and the thing you came to read stops being the loudest
  * thing in it. `alert` and `achievement` DO still paint the number sand, so the
  * document's rule survives exactly where it matters: sand when the number is not
- * just a number. See `docs/decisions/0.7.md` § 31.
+ * just a number. See `docs/decisions/` § 31.
  */
 type StatProps = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
     /** The number, already formatted. The library imposes no locale. */
@@ -1501,7 +1578,7 @@ type StatProps = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
      * 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.
+     * `docs/decisions/` § 28.
      */
     tone?: 'neutral' | 'alert' | 'achievement';
     /** With `progress`, the metric reads as progress and adds the bar. */

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';
 
@@ -48,7 +48,7 @@ import '@radix-ui/react-label';
  * `--ease-standard`, so it introduces neither a new timing nor a new curve.
  * Whoever asked for less motion still sees the panel appear where it will stay.
  *
- * See `docs/decisions/0.6.md` § 20.
+ * See `docs/decisions/` § 20.
  *
  * The chevron, by contrast, rotates with no transition: `transition-standard`
  * only covers color and border, so `rotate` snaps even with the class in place.
@@ -111,7 +111,7 @@ declare function Alert({ className, variant, emphasis, title, icon, children, ..
  * «Borrar el artículo», not «Aceptar».
  *
  * `destructive` is for the destructive button that has none of that around it:
- * a table row, a toolbar. See `docs/decisions/0.6.md` § 21.
+ * a table row, a toolbar. See `docs/decisions/` § 21.
  */
 declare const AlertDialog: react.FC<AlertDialogPrimitive.AlertDialogProps>;
 declare const AlertDialogTrigger: react.ForwardRefExoticComponent<AlertDialogPrimitive.AlertDialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
@@ -497,7 +497,7 @@ declare function Switch({ className, ...props }: SwitchProps): react.JSX.Element
  * `Nav`'s `size` documents: a `rounded-none` passed from the call site does
  * nothing, silently. There is one shape on purpose — fourteen call sites wanted
  * the same one — and a second gets a prop when a second consumer exists, not
- * before. See `docs/decisions/0.8.md` § 39.
+ * before. See `docs/decisions/` § 39.
  *
  * THE `tabIndex` IS NOT DECORATION and it is not new behaviour dressed up as
  * markup. A region you can pan with a mouse has to be reachable with a keyboard
@@ -771,7 +771,7 @@ declare function AuthorCard({ name, role, src, bio, action, className, ...props
  *   paths this file used to carry verbatim from the portfolio are gone with
  *   `lib/glyphs.tsx`; `Play`, `Pause`, `SpeakerHigh` and `SpeakerSlash` are the
  *   same symbols in Phosphor's hand, and the ±15s skips are `ArrowCounterClockwise`
- *   and `ArrowClockwise`. See `docs/decisions/0.10.md` § 51.
+ *   and `ArrowClockwise`. See `docs/decisions/` § 51.
  * - analytics' `trackEvent` → the `onFirstPlay` prop, which the consumer wires
  *   to whatever they use. It still fires exactly once per load.
  *
@@ -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/` § 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.
@@ -901,7 +941,7 @@ declare function CourseCard({ title, summary, meta, status, progress, className,
  * smaller one: the hole inside a table page or a dashboard widget, competing with
  * a dozen elements around it. An admin panel has twenty of those on one screen,
  * and twenty faces is not the humour contract, it is a zoo. The variant carries
- * no face, and the type does not let one through. See `docs/decisions/0.7.md` § 27.
+ * no face, and the type does not let one through. See `docs/decisions/` § 27.
  */
 type EmptyStateBase = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
     title: ReactNode;
@@ -990,7 +1030,7 @@ declare function EventCalendar({ events, onCreateEvent, onUpdateEvent, onDeleteE
  * The domain defaults to `naming.domain` and not to a hand-written string, for
  * the same reason as the wordmark: if it changes, it changes in all five
  * projects at once. A project that lives on its OWN domain passes `domain` —
- * see `docs/decisions/0.9.md` § 49.
+ * see `docs/decisions/` § 49.
  *
  * The social links are icons with NO visible text, so `aria-label` is not an
  * improvement: it is the only thing that makes them legible. Which is why it is
@@ -1006,7 +1046,7 @@ declare function EventCalendar({ events, onCreateEvent, onUpdateEvent, onDeleteE
  * answer has not moved: `EmptyState` is a discriminated union where `page` is
  * the default and `inline` cannot be handed a face; `Nav` takes a `size` where
  * `default` is the bar it always was. Both left what was written before exactly
- * where it was. See `docs/decisions/0.8.md` § 44.
+ * where it was. See `docs/decisions/` § 44.
  *
  * The union is what holds the rule up. `columns`, `description` and `action`
  * exist only on `full`, and the default form cannot be handed one. As loose
@@ -1054,7 +1094,7 @@ type FooterColumn = {
  * `./aviso-legal` — and that row is what `variant="full"`'s columns replace. A
  * flat row cannot say which block a link belongs to, cannot carry a heading a
  * screen reader can jump to, and made whoever wrote the label type the `./`
- * themselves, which the columns put there. See docs/decisions/0.8.md § 47.
+ * themselves, which the columns put there. See docs/decisions/ § 47.
  */
 type FooterBase = Omit<ComponentPropsWithoutRef<'footer'>, 'children'> & {
     social?: readonly SocialLink[];
@@ -1089,10 +1129,25 @@ type FooterBase = Omit<ComponentPropsWithoutRef<'footer'>, 'children'> & {
      * have warned about.
      *
      * It is a domain and not a whole signature: the `$`, the `cd ~/` and the year
-     * are the identity's and stay the component's. See `docs/decisions/0.9.md`
+     * are the identity's and stay the component's. See `docs/decisions/`
      * § 49.
      */
     domain?: string | undefined;
+    /**
+     * Adds «Creado con Arrecife ♥», linking to the library's Storybook.
+     *
+     * OFF BY DEFAULT, and that is the decision rather than the default. No
+     * consuming project credits the library today — the four were read before
+     * this was written — so turning it on for everybody would be the library
+     * putting a line into five production footers that none of them asked for.
+     * That is the move § 45 is about, and it does not get made twice.
+     *
+     * A site that wants it passes `builtWith`. It is a boolean and not a slot: the
+     * string and the destination are the library's, and a slot would be an
+     * invitation to write «Hecho con Arrecife» on one site and «Creado con» on the
+     * next, which is the drift this package exists to remove.
+     */
+    builtWith?: boolean | undefined;
 };
 type FooterProps = FooterBase & ({
     /** The shape the library has always had: stacked rows and the signature at the top right. */
@@ -1128,7 +1183,7 @@ type FooterProps = FooterBase & ({
         children: ReactNode;
     }) => ReactNode) | undefined;
 });
-declare function Footer({ variant, columns, description, action, linkAsChild, social, brand, year, signatureHref, domain, className, ...rest }: FooterProps): react.JSX.Element;
+declare function Footer({ variant, columns, description, action, linkAsChild, social, brand, builtWith, year, signatureHref, domain, className, ...rest }: FooterProps): react.JSX.Element;
 
 /**
  * ONE per site. It is the only piece in the system that is spent like the
@@ -1262,7 +1317,7 @@ type NavItemProps = ComponentPropsWithoutRef<'a'> & {
  * impossible to call. It passed `tsc` and it passed the build, because the shape
  * of the children is not something either one looks at. `Slottable` is Radix's
  * answer to exactly this: it marks which child the router's `Link` replaces and
- * leaves the decoration where it is. See `docs/decisions/0.8.md` § 40.
+ * leaves the decoration where it is. See `docs/decisions/` § 40.
  */
 declare function NavItem({ active, asChild, className, children, ...props }: NavItemProps): react.JSX.Element;
 
@@ -1392,6 +1447,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/` § 57.
+ *
  * It takes no mascot face, at either scale: faces go in empty states,
  * confirmations, errors, course progress and celebration.
  *
@@ -1416,8 +1480,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.
@@ -1481,7 +1558,7 @@ declare function ScrollingProgressBar({ target, tone, sticky, className, ...prop
  * eyebrow is the same length in none of them, so an inline icon puts the only
  * coloured mark on a different x in every card; pinned to the corner it lands on
  * a grid. The circle is the tint pattern the system already has — `bg-accent/10`
- * as a surface and the colour on the GLYPH, per `docs/decisions/0.6.md` § 4b — and a
+ * as a surface and the colour on the GLYPH, per `docs/decisions/` § 4b — and a
  * glyph clears the 3:1 graphical threshold where text would not clear 4.5.
  *
  * WHICH IS WHY A NEUTRAL NUMBER IS PRIMARY INK AND NOT BIOLUME. With a biolume
@@ -1489,7 +1566,7 @@ declare function ScrollingProgressBar({ target, tone, sticky, className, ...prop
  * the size of a postcard, and the thing you came to read stops being the loudest
  * thing in it. `alert` and `achievement` DO still paint the number sand, so the
  * document's rule survives exactly where it matters: sand when the number is not
- * just a number. See `docs/decisions/0.7.md` § 31.
+ * just a number. See `docs/decisions/` § 31.
  */
 type StatProps = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
     /** The number, already formatted. The library imposes no locale. */
@@ -1501,7 +1578,7 @@ type StatProps = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
      * 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.
+     * `docs/decisions/` § 28.
      */
     tone?: 'neutral' | 'alert' | 'achievement';
     /** With `progress`, the metric reads as progress and adds the bar. */