shelving 1.236.2 → 1.237.0

package/ui/block/Card.md

@@ -0,0 +1,85 @@
+# Card
+
+A boxed surface that groups a self-contained piece of content. Rendered as an `<article>`, painted from the tint ladder (surface, border, text) and styled with rounded corners and padding by default.
+
+**Things to know:**
+
+- Set `href` or `onClick` to make the whole card navigable — a stretched, visually-hidden overlay `<a>` / `<button>` covers the card while the children render normally inside. Real interactive elements inside the card (inline links, buttons) stay clickable and keyboard-focusable.
+- `color=` and `status=` move the tint anchor for the card's scope, so the surface, border, text, and hover shade all re-derive together — and nested components (`Tag`, `Preformatted`, `Button`) inherit the same tint.
+- A card styles only the box. Lay out its contents with the usual block components (`Subheading`, `Paragraph`, `Row`, …).
+- Composes the standard styling variants: `color`, `status`, `padding`, `space`, `width`, plus typography.
+
+## Usage
+
+### Static card
+
+```tsx
+import { Card, Subheading, Paragraph } from "shelving/ui";
+
+<Card>
+  <Subheading>Storage</Subheading>
+  <Paragraph>1.2 GB of 5 GB used.</Paragraph>
+</Card>
+```
+
+### Navigable card
+
+```tsx
+import { Card, Subheading, Paragraph } from "shelving/ui";
+
+// The entire card is a link; `title` labels the overlay for screen readers.
+<Card href="/projects/shelving" title="Open Shelving">
+  <Subheading>Shelving</Subheading>
+  <Paragraph>TypeScript data toolkit.</Paragraph>
+</Card>
+```
+
+### Status and colour
+
+```tsx
+import { Card, Subheading } from "shelving/ui";
+
+<Card status="error"><Subheading>Couldn't load</Subheading></Card>
+<Card color="purple" padding="large" space="none"><Subheading>Featured</Subheading></Card>
+```
+
+## Styling
+
+`Card` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Move `--card-tint` to recolour everything at once; reach for a per-property hook for a single surgical change.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--card-tint` | Tint anchor for the card scope — recolours surface, border, text and hover together | `inherit` (flows from `color=` / `status=` / parent) |
+| `--card-background` | Surface fill | `var(--tint-90)` |
+| `--card-hover-background` | Surface fill when a navigable card is hovered | `var(--tint-95)` |
+| `--card-color` | Text colour | `var(--tint-00)` |
+| `--card-border` | Border shorthand | `var(--card-stroke) solid var(--tint-80)` |
+| `--card-stroke` | Border / outline thickness | `var(--stroke-normal)` (2px) |
+| `--card-radius` | Corner radius | `var(--radius-normal)` (16px) |
+| `--card-padding` | Inner padding | `var(--space-normal)` (16px) |
+| `--card-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
+| `--card-shadow` | Drop shadow | `none` |
+| `--card-transition` | Transition | `all var(--duration-fast)` (150ms) |
+| `--card-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
+
+**Global tokens it reads** — move these to retheme broadly rather than overriding ladder steps directly: the tint ladder `--tint-00` / `--tint-80` / `--tint-90` / `--tint-95`, plus `--space-normal`, `--space-paragraph`, `--radius-normal`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, and `--duration-fast`.
+
+```css
+/* Theme: borderless cards with a soft shadow and tighter corners. */
+:root {
+  --card-border: none;
+  --card-shadow: var(--shadow-small);
+  --card-radius: var(--radius-small);
+}
+
+/* Retint every card purple — surface, border, text and hover all follow. */
+:root {
+  --card-tint: var(--color-purple);
+}
+```
+
+## See also
+
+- [`Panel`](/ui/Panel) — a card-like grouping for stacked sections rather than standalone content.
+- [`Section`](/ui/Section) — a titled block; cards often hold one or more sections.
+- [`ui`](/ui) — the styling system: tint ladder, cascade layers, and theming.

package/ui/block/Card.tsx

@@ -29,6 +29,7 @@ export interface CardProps
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
  *
+ * @kind component
  * @example <Card><Subheading>Static</Subheading></Card>
  * @example <Card href="/foo" title="Open foo"><Subheading>Clickable</Subheading></Card>
  * @example <Card status="error"><Subheading>Not found</Subheading></Card>

package/ui/block/Heading.d.ts

@@ -31,6 +31,7 @@ export interface HeadingProps extends ColorVariants, SpaceVariants, TypographyVa
  * Section heading — renders an `<h2>`.
  * - Sits between `Title` (`<h1>`) and `Subheading` (`<h3>`) in the heading hierarchy.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
  * @returns Rendered `<h2>` heading element.
  * @example <Heading>Section title</Heading>

package/ui/block/Heading.js

@@ -20,6 +20,7 @@ export const HEADING_PROSE_CLASS = getModuleClass(HEADING_CSS, "prose");
  * Section heading — renders an `<h2>`.
  * - Sits between `Title` (`<h1>`) and `Subheading` (`<h3>`) in the heading hierarchy.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
  * @returns Rendered `<h2>` heading element.
  * @example <Heading>Section title</Heading>

package/ui/block/Heading.md

@@ -0,0 +1,70 @@
+# Heading
+
+A section heading — renders an `<h2>`. It sits in the middle of the three-level heading family: `Title` (`<h1>`), `Heading` (`<h2>`), `Subheading` (`<h3>`).
+
+**Things to know:**
+
+- Pick the component that matches the level rather than overriding `level`. Choosing `Title` / `Heading` / `Subheading` keeps the visual size and the document outline in step, which matters for accessibility and the docs-site table of contents.
+- The `level` prop (`1`–`6`) is an escape hatch for the rare case where the outline level must differ from the visual size — avoid it in normal use.
+- Inside `Prose`, an `<h2>` is styled by the same rules (`HEADING_PROSE_CLASS`), so Markdown-rendered headings match component ones.
+- Accepts `color=` and the typography variants; like all block components it collapses its outer margin when it's the first/last child of its container.
+
+## Usage
+
+### Section heading
+
+```tsx
+import { Heading, Paragraph } from "shelving/ui";
+
+<Heading>Billing</Heading>
+<Paragraph>Manage your plan and payment method.</Paragraph>
+```
+
+### The heading family together
+
+```tsx
+import { Title, Heading, Subheading } from "shelving/ui";
+
+<Title>Account</Title>        {/* <h1> */}
+<Heading>Security</Heading>   {/* <h2> */}
+<Subheading>Sessions</Subheading> {/* <h3> */}
+```
+
+### Coloured heading
+
+```tsx
+import { Heading } from "shelving/ui";
+
+<Heading color="red">Danger zone</Heading>
+```
+
+## Styling
+
+`Heading` exposes hooks for its rhythm and type. It inherits text colour by default (so it picks up the surrounding tint); set `--heading-color` only to override that.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--heading-tint` | Tint anchor for the heading scope | `inherit` (flows from `color=` / parent) |
+| `--heading-color` | Text colour | `inherit` |
+| `--heading-space-before` | Top margin | `var(--space-section)` (2rem) |
+| `--heading-space` | Bottom margin | `var(--space-paragraph)` (16px) |
+| `--heading-font` | Font family | `var(--font-title)` |
+| `--heading-weight` | Font weight | `var(--weight-strong)` (700) |
+| `--heading-size` | Font size | `var(--size-xxlarge)` |
+| `--heading-leading` | Line height | `var(--leading)` |
+
+**Global tokens it reads:** `--space-section`, `--space-paragraph`, `--font-title`, `--weight-strong`, `--size-xxlarge`, and `--leading`. (`Title` and `Subheading` share this component and expose the parallel `--title-*` / `--subheading-*` hooks.)
+
+```css
+/* Theme: serif headings, a touch larger. */
+:root {
+  --heading-font: var(--font-serif);
+  --heading-size: var(--size-xxxlarge);
+}
+```
+
+## See also
+
+- [`Title`](/ui/Title) — the top-level page heading that pairs with `Heading`.
+- [`Section`](/ui/Section) — wraps a heading and its content as a titled section.
+- [`ui`](/ui) — the styling system: tint ladder, typography variants, and theming.

package/ui/block/Heading.tsx

@@ -37,6 +37,7 @@ export interface HeadingProps extends ColorVariants, SpaceVariants, TypographyVa
  * Section heading — renders an `<h2>`.
  * - Sits between `Title` (`<h1>`) and `Subheading` (`<h3>`) in the heading hierarchy.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
  * @returns Rendered `<h2>` heading element.
  * @example <Heading>Section title</Heading>

package/ui/block/List.d.ts

@@ -34,6 +34,7 @@ export interface ListProps extends ColorVariants, GapVariants, SpaceVariants, Ty
  * List block — wraps each child in an `<li>` and renders an `<ul>` or `<ol>`.
  * - Pass `ordered` to render an ordered `<ol>` instead of the default unordered `<ul>`.
  *
+ * @kind component
  * @param props Colour, gap, space, and typography variants plus the `children` items and `ordered` toggle.
  * @returns Rendered `<ul>` or `<ol>` list element.
  * @example <List>{["One", "Two", "Three"]}</List>

package/ui/block/List.js

@@ -27,6 +27,7 @@ export const LIST_PROSE_CLASS = getModuleClass(LIST_CSS, "prose");
  * List block — wraps each child in an `<li>` and renders an `<ul>` or `<ol>`.
  * - Pass `ordered` to render an ordered `<ol>` instead of the default unordered `<ul>`.
  *
+ * @kind component
  * @param props Colour, gap, space, and typography variants plus the `children` items and `ordered` toggle.
  * @returns Rendered `<ul>` or `<ol>` list element.
  * @example <List>{["One", "Two", "Three"]}</List>

package/ui/block/List.md

@@ -0,0 +1,51 @@
+# List
+
+A bulleted or numbered list. Renders a `<ul>` by default (or an `<ol>` when `ordered` is set) and wraps each child in its own `<li>`, so you pass the items as children rather than writing the `<li>` markup yourself.
+
+**Things to know:**
+
+- Pass `ordered` to render an `<ol>` with numbered markers; the default is an unordered `<ul>`.
+- Each child becomes one list item — give it plain content, not an `<li>`.
+- Items are laid out as a flex column; tune the spacing between them with the `gap` variant (`<List gap="small">`).
+- Like the other block components it carries its own outer block margin and collapses it when it is the first or last child of its container.
+- Inside [`Prose`](/ui/Prose) a raw `<ul>` / `<ol>` picks up the same styling, so Markdown-rendered lists match component ones.
+
+## Usage
+
+### Unordered and ordered lists
+
+```tsx
+import { List } from "shelving/ui";
+
+<List>{["Apples", "Oranges", "Pears"]}</List>
+<List ordered>{["First", "Second", "Third"]}</List>
+```
+
+### Tighter spacing
+
+```tsx
+import { List } from "shelving/ui";
+
+<List gap="small">{items.map(item => item.label)}</List>
+```
+
+## Styling
+
+`List` paints from the [tint ladder](/ui/TINT_CLASS) for its markers only; rebind `--list-tint` to recolour the scope, or reach for a per-property hook for a single change.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--list-tint` | Tint anchor for the list scope | `inherit` (flows from `color=` / parent) |
+| `--list-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
+| `--list-gap` | Space between items | `var(--space-xsmall)` |
+| `--list-indent` | Inline start padding (marker gutter) | `1.125em` unordered / `1.8em` ordered |
+| `--list-marker-color` | Bullet / number colour | `var(--tint-80)` |
+
+**Global tokens it reads:** `--space-paragraph`, `--space-xsmall`, and the tint-ladder step `--tint-80`. The `gap` variant comes from the shared [`ui`](/ui) styling system.
+
+## See also
+
+- [`Definitions`](/ui/Definitions) — term/value pairs in a styled `<dl>` when a key/value list is needed.
+- [`Paragraph`](/ui/Paragraph) — body text that sits alongside lists.
+- [`Prose`](/ui/Prose) — styles raw `<ul>` / `<ol>` inside longform content.
+- [`ui`](/ui) — the styling system: gap and tint variants, and theming.

package/ui/block/List.tsx

@@ -41,6 +41,7 @@ export interface ListProps extends ColorVariants, GapVariants, SpaceVariants, Ty
  * List block — wraps each child in an `<li>` and renders an `<ul>` or `<ol>`.
  * - Pass `ordered` to render an ordered `<ol>` instead of the default unordered `<ul>`.
  *
+ * @kind component
  * @param props Colour, gap, space, and typography variants plus the `children` items and `ordered` toggle.
  * @returns Rendered `<ul>` or `<ol>` list element.
  * @example <List>{["One", "Two", "Three"]}</List>

package/ui/block/Panel.d.ts

@@ -23,6 +23,7 @@ export interface PanelProps extends ColorVariants, StatusVariants, TypographyVar
  *
  * Renders as a `<section>` by default; pass `as="header"` etc. for other semantic elements.
  *
+ * @kind component
  * @param props Colour, status, and typography variants plus `children`.
  * @returns Rendered full-width panel region.
  * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>

package/ui/block/Panel.js

@@ -12,6 +12,7 @@ const PANEL_CLASS = getModuleClass(PANEL_CSS, "panel");
  *
  * Renders as a `<section>` by default; pass `as="header"` etc. for other semantic elements.
  *
+ * @kind component
  * @param props Colour, status, and typography variants plus `children`.
  * @returns Rendered full-width panel region.
  * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>

package/ui/block/Panel.md

@@ -0,0 +1,50 @@
+# Panel
+
+A full-width vertical region that paints the current surface colour. Use panels to break a page into stacked bands: each one butts against its neighbours (zero block margin) but carries generous vertical padding, so a page becomes a sequence of coloured sections.
+
+**Things to know:**
+
+- A panel always spans the full width of its container. To constrain the content inside, compose a [`Block`](/ui/Block) `narrow` (or `wide`) within it.
+- Block margin is always zero so panels stack flush; control the vertical breathing room with the `padding` variant (`<Panel padding="large">`, `<Panel padding="none">`). Inline padding is fixed.
+- `color=` / `status=` move the tint anchor for the whole panel scope, so the surface, border, and text re-derive together and cascade into nested content.
+- The top and bottom borders are dropped on the first and last panel so the page doesn't gain stray edge lines.
+
+## Usage
+
+### Page banded into panels
+
+```tsx
+import { Panel, Block, Title, Paragraph } from "shelving/ui";
+
+<Panel as="header" color="primary">
+  <Block narrow>
+    <Title>Welcome</Title>
+  </Block>
+</Panel>
+<Panel padding="large">
+  <Block narrow>
+    <Paragraph>Each panel is a full-width band; the inner block constrains the content.</Paragraph>
+  </Block>
+</Panel>
+```
+
+## Styling
+
+`Panel` paints from the [tint ladder](/ui/TINT_CLASS); rebind `--panel-tint` to recolour the whole scope at once, or reach for a per-property hook for a single change.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--panel-tint` | Tint anchor for the panel scope — recolours surface, border, and text together | `inherit` (flows from `color=` / `status=` / parent) |
+| `--panel-background` | Surface fill | `var(--tint-90)` |
+| `--panel-color` | Text colour | `var(--tint-00)` |
+| `--panel-border` | Top/bottom border shorthand | `var(--panel-stroke) solid var(--tint-80)` |
+| `--panel-stroke` | Border thickness | `var(--stroke-normal)` (2px) |
+
+**Global tokens it reads:** the tint-ladder steps `--tint-00` / `--tint-80` / `--tint-90`, plus `--stroke-normal`. Vertical padding comes from the shared `padding` variant.
+
+## See also
+
+- [`Card`](/ui/Card) — a boxed surface for standalone content rather than a full-width band.
+- [`Block`](/ui/Block) — the inner width-constraining wrapper for panel content.
+- [`Section`](/ui/Section) — a landmark region that sits inside a panel's inner block.
+- [`ui`](/ui) — the styling system: tint ladder, padding variants, and theming.

package/ui/block/Panel.tsx

@@ -29,6 +29,7 @@ export interface PanelProps extends ColorVariants, StatusVariants, TypographyVar
  *
  * Renders as a `<section>` by default; pass `as="header"` etc. for other semantic elements.
  *
+ * @kind component
  * @param props Colour, status, and typography variants plus `children`.
  * @returns Rendered full-width panel region.
  * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>

package/ui/block/Paragraph.d.ts

@@ -25,6 +25,7 @@ export interface ParagraphProps extends ColorVariants, SpaceVariants, Typography
 /**
  * Paragraph block of body text — rendered as `<p>`.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus `children`.
  * @returns Rendered `<p>` paragraph element.
  * @example <Paragraph>Hello world.</Paragraph>

package/ui/block/Paragraph.js

@@ -19,6 +19,7 @@ export const PARAGRAPH_PROSE_CLASS = getModuleClass(PARAGRAPH_CSS, "prose");
 /**
  * Paragraph block of body text — rendered as `<p>`.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus `children`.
  * @returns Rendered `<p>` paragraph element.
  * @example <Paragraph>Hello world.</Paragraph>

package/ui/block/Paragraph.md

@@ -0,0 +1,48 @@
+# Paragraph
+
+A block of body text — renders a `<p>`. The default container for running prose between headings, lists, and other blocks.
+
+**Things to know:**
+
+- Carries its own outer block margin and collapses it when it is the first or last child of its container, so stacked paragraphs space evenly without doubling up at the edges.
+- Accepts `color=` and the typography variants (`size`, `serif`, `center`, …) to retint or restyle the text.
+- Fill it with inline annotations such as [`Strong`](/ui/Strong), [`Emphasis`](/ui/Emphasis), [`Code`](/ui/Code), [`Mark`](/ui/Mark), and [`Link`](/ui/Link).
+- Inside [`Prose`](/ui/Prose) a raw `<p>` picks up the same styling, so Markdown-rendered paragraphs match component ones.
+
+## Usage
+
+### Body text
+
+```tsx
+import { Paragraph } from "shelving/ui";
+
+<Paragraph>The best widget on the market.</Paragraph>
+```
+
+### With inline annotations
+
+```tsx
+import { Paragraph, Strong, Link } from "shelving/ui";
+
+<Paragraph>
+  <Strong>Note:</Strong> read our <Link href="/privacy">privacy policy</Link> first.
+</Paragraph>
+```
+
+## Styling
+
+`Paragraph` exposes a single hook for its own block margin and rebinds the tint anchor for its scope; it paints no colour of its own, so it inherits the surrounding text colour.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--paragraph-tint` | Tint anchor for the paragraph scope | `inherit` (flows from `color=` / parent) |
+| `--paragraph-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
+
+**Global tokens it reads:** `--space-paragraph`.
+
+## See also
+
+- [`Prose`](/ui/Prose) — wrap mixed content to style raw `<p>` and friends in one step.
+- [`Heading`](/ui/Heading) — the section heading that usually precedes a paragraph.
+- [`List`](/ui/List) — bulleted or numbered content alongside paragraphs.
+- [`ui`](/ui) — the styling system: tint ladder, typography variants, and theming.

package/ui/block/Paragraph.tsx

@@ -30,6 +30,7 @@ export interface ParagraphProps extends ColorVariants, SpaceVariants, Typography
 /**
  * Paragraph block of body text — rendered as `<p>`.
  *
+ * @kind component
  * @param props Colour, space, and typography variants plus `children`.
  * @returns Rendered `<p>` paragraph element.
  * @example <Paragraph>Hello world.</Paragraph>

package/ui/block/Prose.d.ts

@@ -11,6 +11,7 @@ export interface ProseProps extends OptionalChildProps {
  * A section of longform text containing lots of `<p>` or `<ul>` style elements.
  * - Applies the prose variant of every block and inline component so nested content picks up the right longform spacing and typography.
  *
+ * @kind component
  * @param props The longform `children` to render inside the prose container.
  * @returns Rendered `<div>` wrapping the prose content.
  * @example <Prose><Paragraph>First.</Paragraph><Paragraph>Second.</Paragraph></Prose>

package/ui/block/Prose.js

@@ -29,6 +29,7 @@ const PROSE_STYLES = getClass(PARAGRAPH_PROSE_CLASS, HEADING_PROSE_CLASS, SUBHEA
  * A section of longform text containing lots of `<p>` or `<ul>` style elements.
  * - Applies the prose variant of every block and inline component so nested content picks up the right longform spacing and typography.
  *
+ * @kind component
  * @param props The longform `children` to render inside the prose container.
  * @returns Rendered `<div>` wrapping the prose content.
  * @example <Prose><Paragraph>First.</Paragraph><Paragraph>Second.</Paragraph></Prose>

package/ui/block/Prose.md

@@ -0,0 +1,49 @@
+# Prose
+
+A wrapper that applies cohesive longform typography to a subtree of mixed HTML content. Wrap any block of paragraphs, lists, headings, code, tables, and inline annotations in `<Prose>` and they pick up the right spacing and type in one step — including raw HTML elements emitted by a markup renderer.
+
+**Things to know:**
+
+- `Prose` applies the "prose" variant of *every* block and inline component as a single compound class, so raw `<p>`, `<ul>`, `<h2>`, `<code>`, `<a>`, etc. are styled to match their component counterparts ([`Paragraph`](/ui/Paragraph), [`List`](/ui/List), [`Heading`](/ui/Heading), [`Code`](/ui/Code), [`Link`](/ui/Link), …).
+- This is the bridge for markup: wrap [`Markup`](/markup) output (or anything that emits raw HTML) in `<Prose>` and it just works — no per-element component wrapping needed.
+- It only sets up typography and its own outer margin; it paints no colour and adds no box of its own.
+
+## Usage
+
+### Prose content from a renderer
+
+```tsx
+import { Prose, Markup } from "shelving/ui";
+
+<Prose>
+  <Markup>{article.body}</Markup>
+</Prose>
+```
+
+### Hand-written longform
+
+```tsx
+import { Prose, Paragraph } from "shelving/ui";
+
+<Prose>
+  <Paragraph>First.</Paragraph>
+  <Paragraph>Second.</Paragraph>
+</Prose>
+```
+
+## Styling
+
+`Prose` exposes a single hook for its own block margin. The longform typography of nested content is themed through each block/inline component's own hooks (e.g. `--paragraph-space`, `--heading-size`), not through `Prose` itself.
+
+| Variable | Styles | Default |
+|---|---|---|
+| `--prose-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
+
+**Global tokens it reads:** `--space-paragraph`.
+
+## See also
+
+- [`Paragraph`](/ui/Paragraph) — body text; its prose variant styles raw `<p>` inside `Prose`.
+- [`List`](/ui/List) — its prose variant styles raw `<ul>` / `<ol>` inside `Prose`.
+- [`Markup`](/markup) — renders a markup string into the raw HTML that `Prose` styles.
+- [`ui`](/ui) — the styling system and per-component theming hooks.

package/ui/block/Prose.tsx

@@ -64,6 +64,7 @@ export interface ProseProps extends OptionalChildProps {}
  * A section of longform text containing lots of `<p>` or `<ul>` style elements.
  * - Applies the prose variant of every block and inline component so nested content picks up the right longform spacing and typography.
  *
+ * @kind component
  * @param props The longform `children` to render inside the prose container.
  * @returns Rendered `<div>` wrapping the prose content.
  * @example <Prose><Paragraph>First.</Paragraph><Paragraph>Second.</Paragraph></Prose>

package/ui/block/Section.d.ts

@@ -34,6 +34,7 @@ export interface SectionProps extends ColorVariants, SpaceVariants, TypographyVa
  * `<section>` block with block-level spacing.
  * - Pass `as` to render a different semantic element.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<section>` element.
  * @example <Section><Heading>About</Heading></Section>
@@ -43,6 +44,7 @@ export declare function Section(props: SectionProps): ReactElement;
 /**
  * `<header>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<header>` element.
  * @example <Header><Title>Welcome</Title></Header>
@@ -52,6 +54,7 @@ export declare function Header(props: SectionProps): ReactElement;
 /**
  * `<footer>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<footer>` element.
  * @example <Footer><Small>© 2026</Small></Footer>
@@ -61,6 +64,7 @@ export declare function Footer(props: SectionProps): ReactElement;
 /**
  * `<nav>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<nav>` element.
  * @example <Nav><Link href="/">Home</Link></Nav>
@@ -70,6 +74,7 @@ export declare function Nav(props: SectionProps): ReactElement;
 /**
  * `<aside>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<aside>` element.
  * @example <Aside narrow><Paragraph>Sidebar</Paragraph></Aside>
@@ -79,6 +84,7 @@ export declare function Aside(props: SectionProps): ReactElement;
 /**
  * `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<figure>` element.
  * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>

package/ui/block/Section.js

@@ -24,6 +24,7 @@ function renderSection(defaultComponent, { as: Component = defaultComponent, chi
  * `<section>` block with block-level spacing.
  * - Pass `as` to render a different semantic element.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<section>` element.
  * @example <Section><Heading>About</Heading></Section>
@@ -35,6 +36,7 @@ export function Section(props) {
 /**
  * `<header>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<header>` element.
  * @example <Header><Title>Welcome</Title></Header>
@@ -46,6 +48,7 @@ export function Header(props) {
 /**
  * `<footer>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<footer>` element.
  * @example <Footer><Small>© 2026</Small></Footer>
@@ -57,6 +60,7 @@ export function Footer(props) {
 /**
  * `<nav>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<nav>` element.
  * @example <Nav><Link href="/">Home</Link></Nav>
@@ -68,6 +72,7 @@ export function Nav(props) {
 /**
  * `<aside>` block with block-level spacing.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<aside>` element.
  * @example <Aside narrow><Paragraph>Sidebar</Paragraph></Aside>
@@ -79,6 +84,7 @@ export function Aside(props) {
 /**
  * `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content.
  *
+ * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<figure>` element.
  * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>