# Catalog

Every unit of the system, from block to script, with when to use it, its inputs, its sizes, how its text is shortened and an example.

Each unit carries a spec beside its code. The catalog collects them, the MCP tools `catalog_list` and `catalog_get` serve them, and this page is generated from them. 173 units.

A block takes `size`: `compact`, `normal` or `expanded`. Unset, it picks from the width of its container; set, it is forced. Compact drops secondary detail before it shrinks type. A text prop that can be long takes a string or `{ full, short }`; with no short form the block applies the behaviour in its spec: `clamp` (cut at a line count on a word boundary, full text kept in the document), `drop`, `abbreviate` (a stated rule) or `require` (compact needs a short form; the audit warns).

## Blocks

Components usable in any piece without an import. Each takes `size`; text that can be long takes a short form.

| Id                | Summary                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `block:Prose`     | Running text; bare Markdown inside a Section is wrapped in one.                                                                            |
| `block:Lead`      | The paragraph that opens a part, one size up from body.                                                                                    |
| `block:Kicker`    | A short marker set above a heading, such as a part number.                                                                                 |
| `block:Segue`     | The sentence that hands one part to the next.                                                                                              |
| `block:Colophon`  | Method and provenance, set small in mono.                                                                                                  |
| `block:Figure`    | An image or drawing with an optional title, caption and credit; an image opens in a viewer.                                                |
| `block:Ref`       | An inline reference to a numbered figure: renders Figure 3 and links to it.                                                                |
| `block:Sidebar`   | A boxed aside for a self-contained explanation, set off by a tone and space, not a border.                                                 |
| `block:PieceCard` | A piece as a chip, a card or a lead, read from its frontmatter; never shown on the piece itself.                                           |
| `block:Live`      | An interactive figure: a client component with a heading and caption.                                                                      |
| `block:Stat`      | One headline number with its label and the condition it holds under.                                                                       |
| `block:PullQuote` | A line lifted from the text, set large.                                                                                                    |
| `block:Note`      | A margin note, set beside the paragraph it follows.                                                                                        |
| `block:Table`     | A table on the wide column that scrolls sideways when it cannot fit.                                                                       |
| `block:Panels`    | A row of short definitions, as many columns as fit.                                                                                        |
| `block:Panel`     | One term and its definition inside Panels.                                                                                                 |
| `block:Formula`   | A display formula in TeX, set by KaTeX; it scrolls inside its own box rather than widening the page.                                       |
| `block:Section`   | The unit of an article: reads its children and picks a layout.                                                                             |
| `block:Chapter`   | A run of sections that belong together, set a break apart.                                                                                 |
| `block:Article`   | The grid every section sits on, where the rhythm rules run.                                                                                |
| `block:Printout`  | A tractor-feed listing: dot-matrix type on banded stock with a perforated margin, for tables, logs and ledgers.                            |
| `block:Plotter`   | A frame that sets a figure on plotter paper: registration marks at the corners and a legend of the pens that drew it.                      |
| `block:Console`   | A terminal frame in phosphor ink for transcripts and interactives; the same screen in light and dark.                                      |
| `block:Dialogue`  | A recorded exchange between two parties, set as a transcript on the console screen, with the two sides in columns when they spoke at once. |
| `block:Window`    | A grey title-bar frame in the early-Macintosh manner, for content that is an interface: a form, a readout, a small panel.                  |
| `block:Player`    | The one frame of everything that plays or responds: a stage, three floating bars (top, bottom, left) and panels below.                     |
| `block:Frame`     | The figure frame under every interactive: a heading, the media, a caption and a credit, sized by the block contract.                       |

### Prose

Running text; bare Markdown inside a Section is wrapped in one.

**Use** Paragraphs, lists and headings that belong to one passage.

**Avoid** Captions, notes or quotes; they have their own blocks.

**Minimum width** `--lk-min-prose`

| Input      | Type                                |          | Meaning                                                                                                                                                                                      |
| ---------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width.                                                                                                                             |
| `children` | ReactNode                           | optional | Markdown.                                                                                                                                                                                    |
| `dropcap`  | boolean                             | optional | Set the first paragraph with a three-line initial. The letter stays in the word for screen readers and copy and paste. A feature piece sets one on each chapter's first paragraph by itself. |

| Size       | Shows                                                                           |
| ---------- | ------------------------------------------------------------------------------- |
| `compact`  | Hyphenation on; all text kept.                                                  |
| `normal`   | Shows everything; nothing in it is secondary, so only type hyphenation changes. |
| `expanded` | Shows everything; nothing in it is secondary, so only type hyphenation changes. |

```mdx
<Prose>

A paragraph.

</Prose>
```

### Lead

The paragraph that opens a part, one size up from body.

**Use** The question or claim a part opens with; two paragraphs give a dateline and an answer.

**Avoid** More than two paragraphs; it stops reading as a lead.

**Minimum width** `--lk-min-prose`

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `children` | ReactNode                           | optional | One or two paragraphs.                                           |

| Size       | Shows                                 |
| ---------- | ------------------------------------- |
| `compact`  | First paragraph only; hyphenation on. |
| `normal`   | Every paragraph.                      |
| `expanded` | Every paragraph.                      |

| Text       | Short form | Without one                                                |
| ---------- | ---------- | ---------------------------------------------------------- |
| `children` | none       | `drop`: Paragraphs after the first are dropped in compact. |

```mdx
<Lead>

One pulse or two? The answer is in the wire states.

</Lead>
```

### Kicker

A short marker set above a heading, such as a part number.

**Use** Numbering parts of a long piece.

**Avoid** Labels glued to a sentence; the prose lint rejects them.

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `children` | ReactNode                           | optional | The marker.                                                      |

| Size       | Shows                                                                           |
| ---------- | ------------------------------------------------------------------------------- |
| `compact`  | Shows everything; nothing in it is secondary, so only type hyphenation changes. |
| `normal`   | Shows everything; nothing in it is secondary, so only type hyphenation changes. |
| `expanded` | Shows everything; nothing in it is secondary, so only type hyphenation changes. |

```mdx
<Kicker>Part 2</Kicker>
```

### Segue

The sentence that hands one part to the next.

**Use** Closing a part with the question the next one answers.

**Avoid** A summary of what came before.

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `short`    | ReactNode                           | optional | A shorter hand-off for compact.                                  |
| `children` | ReactNode                           | optional | One sentence.                                                    |

| Size       | Shows                              |
| ---------- | ---------------------------------- |
| `compact`  | Short form, else cut at two lines. |
| `normal`   | Full text.                         |
| `expanded` | Full text.                         |

| Text       | Short form | Without one      |
| ---------- | ---------- | ---------------- |
| `children` | accepted   | `clamp`, 2 lines |

```mdx
<Segue>Which readout fails first?</Segue>
```

### Colophon

Method and provenance, set small in mono.

**Use** How a result was produced, at the end of a piece.

**Avoid** Findings; they belong in the body.

**Minimum width** `--lk-min-prose`

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `short`    | ReactNode                           | optional | A shorter statement of method for compact.                       |
| `children` | ReactNode                           | optional | Method and sources.                                              |

| Size       | Shows                                |
| ---------- | ------------------------------------ |
| `compact`  | Short form, else cut at three lines. |
| `normal`   | Full text.                           |
| `expanded` | Full text.                           |

| Text       | Short form | Without one      |
| ---------- | ---------- | ---------------- |
| `children` | accepted   | `clamp`, 3 lines |

```mdx
<Colophon>

Three runs, seeds 1 to 3.

</Colophon>
```

### Figure

An image or drawing with an optional title, caption and credit; an image opens in a viewer.

**Use** Any still figure: a chart, an SVG, a photograph.

**Avoid** Interactive figures (Live); tables (Table).

**Minimum width** `--lk-min-figure`

| Input       | Type                                                 |          | Meaning                                                                                                                                                                                                                           |
| ----------- | ---------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`      | 'compact' \| 'normal' \| 'expanded'                  | optional | Force a size. Unset, the block picks from its container's width.                                                                                                                                                                  |
| `src`       | string                                               | optional | Image source.                                                                                                                                                                                                                     |
| `alt`       | string                                               | optional | Alt text.                                                                                                                                                                                                                         |
| `title`     | string \| { full, short }                            | optional | A statement of what the figure shows, set above the media.                                                                                                                                                                        |
| `caption`   | string \| { full, short }                            | optional | What to see; one or two sentences.                                                                                                                                                                                                |
| `credit`    | ReactNode                                            | optional | Provenance; dropped in compact.                                                                                                                                                                                                   |
| `ratio`     | 'square' \| 'tall' \| 'classic' \| 'wide' \| 'plate' | optional | Aspect ratio of the media box.                                                                                                                                                                                                    |
| `zoom`      | boolean                                              | optional | Open the image in a full-window viewer (click, Enter or Space; Esc closes and focus returns). On by default for an image given as `src` (photographs, raster or SVG plates); off for custom media. `zoom=\{false\}` turns it off. |
| `children`  | ReactNode                                            | optional | Custom media; it sets its own height.                                                                                                                                                                                             |
| `id`        | string                                               | optional | Anchor, so a Ref can point at the figure.                                                                                                                                                                                         |
| `captionAt` | 'below' \| 'margin'                                  | optional | Where the caption sits. A margin caption needs a wide column section with room beside the figure; otherwise it goes below. A Section can set it for all its figures with captions.                                                |
| `number`    | number \| string                                     | optional | Set at compile time from the figure's place among the captioned figures of the piece; do not write it.                                                                                                                            |

| Size       | Shows                                               |
| ---------- | --------------------------------------------------- |
| `compact`  | Media and a short title or caption; credit dropped. |
| `normal`   | Title, media, caption and credit.                   |
| `expanded` | As normal, with title and caption one step larger.  |

| Text      | Short form | Without one      |
| --------- | ---------- | ---------------- |
| `title`   | accepted   | `clamp`, 2 lines |
| `caption` | accepted   | `clamp`, 3 lines |
| `credit`  | none       | `drop`           |

```mdx
<Figure title={{ full: "One pulse or two", short: "Pulses" }} caption="What to see." />
```

### Ref

An inline reference to a numbered figure: renders Figure 3 and links to it.

**Use** In running text, where the text points at a figure: see \<Ref to="drift" />. Give the figure an id and a caption.

**Avoid** A figure with no caption (it has no number; the build fails). Do not write the number by hand.

| Input      | Type             |          | Meaning                               |
| ---------- | ---------------- | -------- | ------------------------------------- |
| `to`       | string           | required | The id of the Figure.                 |
| `number`   | number \| string | optional | Set at compile time; do not write it. |
| `children` | ReactNode        | optional | Replaces the default text.            |

```mdx
See <Ref to="drift" />.

<Figure id="drift" caption="Drift over a day." />
```

### Sidebar

A boxed aside for a self-contained explanation, set off by a tone and space, not a border.

**Use** A definition, a method or a worked example that a reader can skip without losing the argument. Alone with its text in a section it sits beside it; with other blocks, between paragraphs.

**Avoid** The argument itself, or more than a few short paragraphs; a long aside is a section.

**Minimum width** `--lk-min-prose`

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `title`    | string \| { full, short }           | optional | What the box explains; cut at two lines.                         |
| `children` | ReactNode                           | optional | A few short paragraphs.                                          |

| Size       | Shows                                                |
| ---------- | ---------------------------------------------------- |
| `compact`  | Title and first paragraph; later paragraphs dropped. |
| `normal`   | Title and every paragraph.                           |
| `expanded` | As normal, with the title one step larger.           |

| Text       | Short form | Without one                                                |
| ---------- | ---------- | ---------------------------------------------------------- |
| `title`    | accepted   | `clamp`, 2 lines                                           |
| `children` | none       | `drop`: Paragraphs after the first are dropped in compact. |

```mdx
<Sidebar title="Reservoir computing">

A fixed, random system whose state a simple reader learns to interpret.

</Sidebar>
```

### PieceCard

A piece as a chip, a card or a lead, read from its frontmatter; never shown on the piece itself.

**Use** Another page points at a piece: a chip inside a sentence or a list, a card in a row, the lead at the top of an index.

**Avoid** On the piece's own page. Do not copy its title or deck by hand; the card reads them.

**Minimum width** `--lk-min-figure`

| Input   | Type                                |          | Meaning                                                                                                                                                                       |
| ------- | ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug`  | string                              | optional | The piece's slug, as in its path. Give this or `card`.                                                                                                                        |
| `card`  | CardData                            | optional | Instead of a slug: the card of an entry that still lives on the old site (content/home/elsewhere.ts), drawn the same with the tile for a picture and linking to its old path. |
| `size`  | 'compact' \| 'normal' \| 'expanded' | optional | compact is an inline chip, normal a card, expanded the lead. Unset, the card's container picks between a title and date, a card and a lead.                                   |
| `level` | 2 \| 3                              | optional | Heading level of the title: 2 under a page title, 3 inside a section (the default).                                                                                           |

| Size       | Shows                                                                                                        |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `compact`  | Chip: the short title (card.title, else title) and kind, linking to the piece; inline.                       |
| `normal`   | Card: thumbnail, kind and date, title, one line (card.line, else the deck), optional stat, up to three tags. |
| `expanded` | Lead: large thumbnail beside the title, the whole deck and the date.                                         |

| Text    | Short form | Without one                                                                                           |
| ------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| `title` | accepted   | `abbreviate`: A chip uses frontmatter card.title; without one, the title.                             |
| `line`  | accepted   | `abbreviate`: Normal uses frontmatter card.line, at most about 110 characters; without one, the deck. |

```mdx
<PieceCard slug="crosstalk" size="compact" />
```

### Live

An interactive figure: a client component with a heading and caption.

**Use** Anything the reader drives: a player, a simulator.

**Avoid** A still chart; use Figure.

**Minimum width** `--lk-min-live`

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `title`    | string \| { full, short }           | required | What the interaction is.                                         |
| `caption`  | string \| { full, short }           | optional | What to try.                                                     |
| `credit`   | ReactNode                           | optional | Provenance; dropped in compact.                                  |
| `children` | ReactNode                           | optional | The client component.                                            |

| Size       | Shows                                                   |
| ---------- | ------------------------------------------------------- |
| `compact`  | Media and the short title; caption cut, credit dropped. |
| `normal`   | Title, media, caption and credit.                       |
| `expanded` | As normal, with title and caption one step larger.      |

| Text      | Short form | Without one      |
| --------- | ---------- | ---------------- |
| `title`   | accepted   | `require`        |
| `caption` | accepted   | `clamp`, 3 lines |
| `credit`  | none       | `drop`           |

```mdx
<Live title={{ full: "Drive the reservoir", short: "Reservoir" }} />
```

### Stat

One headline number with its label and the condition it holds under.

**Use** A result a reader should see before the argument.

**Avoid** A number with no condition; say what it was measured on.

**Minimum width** `--lk-min-stat`

| Input   | Type                                |          | Meaning                                                          |
| ------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`  | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `value` | string \| { full, short }           | required | The number with its unit.                                        |
| `label` | string \| { full, short }           | required | What it measures.                                                |
| `note`  | string \| { full, short }           | optional | The condition or source.                                         |

| Size       | Shows                                               |
| ---------- | --------------------------------------------------- |
| `compact`  | Short forms; label cut at two lines, note at three. |
| `normal`   | Value, label and note.                              |
| `expanded` | As normal, with label and note one step larger.     |

| Text    | Short form | Without one                                                                                                                              |
| ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `value` | accepted   | `abbreviate`: Type scales with the container from the stat size down to body size; a list is broken only at ' · ', never inside a value. |
| `label` | accepted   | `clamp`, 2 lines                                                                                                                         |
| `note`  | accepted   | `clamp`, 3 lines                                                                                                                         |

```mdx
<Stat value="0.995" label="Reservoir" note="± 0.009" />
```

### PullQuote

A line lifted from the text, set large.

**Use** One sentence from the body that carries the piece.

**Avoid** Other people's long quotations; a quote is never cut.

**Minimum width** `--lk-min-quote`

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `cite`     | ReactNode                           | optional | Attribution; dropped in compact.                                 |
| `short`    | ReactNode                           | optional | A shorter quote for compact.                                     |
| `children` | ReactNode                           | optional | The quote.                                                       |

| Size       | Shows                             |
| ---------- | --------------------------------- |
| `compact`  | Short quote only, no attribution. |
| `normal`   | Quote and attribution.            |
| `expanded` | Quote and attribution.            |

| Text       | Short form | Without one |
| ---------- | ---------- | ----------- |
| `children` | accepted   | `require`   |
| `cite`     | none       | `drop`      |

```mdx
<PullQuote cite="Source" short="A line.">A longer line worth keeping.</PullQuote>
```

### Note

A margin note, set beside the paragraph it follows.

**Use** An aside that belongs next to one paragraph.

**Avoid** Anything the argument needs; narrow slots cut it.

**Minimum width** `--lk-min-note`

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `short`    | ReactNode                           | optional | A shorter note for compact.                                      |
| `children` | ReactNode                           | optional | The note.                                                        |

| Size       | Shows                               |
| ---------- | ----------------------------------- |
| `compact`  | Short form, else cut at four lines. |
| `normal`   | Full text.                          |
| `expanded` | Full text, body-size type.          |

| Text       | Short form | Without one      |
| ---------- | ---------- | ---------------- |
| `children` | accepted   | `clamp`, 4 lines |

```mdx
<Note>Measured on the second board.</Note>
```

### Table

A table on the wide column that scrolls sideways when it cannot fit.

**Use** Wrap a Markdown table in it.

**Avoid** Layout; it is for tabular data.

**Minimum width** `--lk-min-figure`

| Input      | Type                                |          | Meaning                                                              |
| ---------- | ----------------------------------- | -------- | -------------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width.     |
| `title`    | string \| { full, short }           | optional | A statement of what the table shows, set above it; cut at two lines. |
| `caption`  | string \| { full, short }           | optional | What the table shows; dropped in compact.                            |
| `children` | ReactNode                           | optional | A Markdown table.                                                    |

| Size       | Shows                                                                |
| ---------- | -------------------------------------------------------------------- |
| `compact`  | Table and a short title; caption dropped unless it has a short form. |
| `normal`   | Title, table and caption.                                            |
| `expanded` | As normal, with the title and caption one step larger.               |

| Text      | Short form | Without one      |
| --------- | ---------- | ---------------- |
| `title`   | accepted   | `clamp`, 2 lines |
| `caption` | accepted   | `drop`           |

```mdx
<Table title="Runs by bench" caption="Runs.">

| a | b |
| - | - |
| 1 | 2 |

</Table>
```

### Panels

A row of short definitions, as many columns as fit.

**Use** Four to six parallel terms with a sentence each.

**Avoid** Long explanations; panels are cut when narrow.

**Minimum width** `--lk-panel-min`

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |
| `children` | ReactNode                           | optional | Panel elements.                                                  |

| Size       | Shows                                            |
| ---------- | ------------------------------------------------ |
| `compact`  | Terms cut at two lines, definitions at four.     |
| `normal`   | Term and definition.                             |
| `expanded` | Term and definition, definition one step larger. |

```mdx
<Panels>
<Panel term="Seed">The random start.</Panel>
</Panels>
```

### Panel

One term and its definition inside Panels.

**Use** Only inside Panels.

**Avoid** On its own.

| Input      | Type                                |          | Meaning                                                                                   |
| ---------- | ----------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width.                          |
| `term`     | string \| { full, short }           | required | The term.                                                                                 |
| `lines`    | number                              | optional | Lines of the definition shown before it is cut; four unless a longer one must read whole. |
| `children` | ReactNode                           | optional | Its definition.                                                                           |

| Size       | Shows                                               |
| ---------- | --------------------------------------------------- |
| `compact`  | Short term, else two lines; definition cut at four. |
| `normal`   | Term and definition.                                |
| `expanded` | Term and definition, definition one step larger.    |

| Text       | Short form | Without one      |
| ---------- | ---------- | ---------------- |
| `term`     | accepted   | `clamp`, 2 lines |
| `children` | none       | `clamp`, 4 lines |

```mdx
<Panel term="Seed">The random start.</Panel>
```

### Formula

A display formula in TeX, set by KaTeX; it scrolls inside its own box rather than widening the page.

**Use** An equation that stands on its own line. The one way to set display mathematics.

**Avoid** Inline mathematics (write `$$ … $$` in the text) and hand-written MathML.

| Input      | Type                                |          | Meaning                                                                                                                                                                               |
| ---------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width.                                                                                                                      |
| `tex`      | string                              | optional | The equation as TeX. A string child does the same, and so does a `$$ … $$` block as children. Colour a term with `\htmlClass\{lk-pen-blue\}\{…\}`: blue, teal, amber, pink or violet. |
| `narrow`   | string                              | optional | The same equation broken over lines (an aligned block), shown where the block is narrower than 40rem.                                                                                 |
| `children` | ReactNode                           | optional | TeX as a string, or `$$ … $$` blocks.                                                                                                                                                 |

| Size       | Shows                                                                           |
| ---------- | ------------------------------------------------------------------------------- |
| `compact`  | Shows everything; nothing in it is secondary, so only type hyphenation changes. |
| `normal`   | Shows everything; nothing in it is secondary, so only type hyphenation changes. |
| `expanded` | Shows everything; nothing in it is secondary, so only type hyphenation changes. |

```mdx
<Formula tex={String.raw`x = \frac{a}{b}`} />
```

### Section

The unit of an article: reads its children and picks a layout.

**Use** Every run of blocks that belong together.

**Avoid** Nesting sections; use Chapter to group them.

**Minimum width** `--lk-min-prose`

| Input      | Type                                |          | Meaning                                                                                            |
| ---------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `layout`   | LayoutName                          | optional | Override the picked layout.                                                                        |
| `side`     | 'start' \| 'end'                    | optional | Side of a spread's figure.                                                                         |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size on every block inside that has none.                                                  |
| `captions` | 'below' \| 'margin'                 | optional | Where figure captions sit unless a figure says otherwise; margin takes effect in a column section. |
| `id`       | string                              | optional | Anchor.                                                                                            |
| `children` | ReactNode                           | optional | Blocks and Markdown.                                                                               |

```mdx
<Section>

Text.

</Section>
```

### Chapter

A run of sections that belong together, set a break apart.

**Use** One part of a long piece.

**Avoid** A single section.

| Input      | Type      |          | Meaning   |
| ---------- | --------- | -------- | --------- |
| `id`       | string    | optional | Anchor.   |
| `children` | ReactNode | optional | Sections. |

```mdx
<Chapter id="part-1">

<Section>

Text.

</Section>

</Chapter>
```

### Article

The grid every section sits on, where the rhythm rules run.

**Use** Around a whole body; a piece's template supplies it.

**Avoid** Inside another Article.

| Input      | Type      |          | Meaning                |
| ---------- | --------- | -------- | ---------------------- |
| `children` | ReactNode | optional | Sections and chapters. |

```mdx
<Article>

<Section>

Text.

</Section>

</Article>
```

### Printout

A tractor-feed listing: dot-matrix type on banded stock with a perforated margin, for tables, logs and ledgers.

**Use** Records that are a listing in fact: a ledger, a run log, a parts list. Table mode takes columns and rows (a statement uses `_kind` lines and marked columns); log mode keeps its lines as typed.

**Avoid** Prose, or a table that is only a table; the kit's Table is the default. Do not nest it in a figure.

**Minimum width** `--lk-min-figure`

| Input      | Type                                                          |          | Meaning                                                                                                                                                                                                  |
| ---------- | ------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`    | string \| { full, short }                                     | optional | The listing's name, on its first line.                                                                                                                                                                   |
| `columns`  | { key, label, align?, detail?, sub?, stub?, edge?, mark? }\[] | optional | Table mode: the columns. `detail` columns drop in compact; `sub` is a second heading line; `stub` makes the cells row headers; `edge` sets a dotted rule before the column; `mark` holds it highlighted. |
| `rows`     | Record\<string, ReactNode>\[]                                 | optional | Table mode: one record per line. A cell is anything that prints. `_kind` sets a line apart: head (a heading across every column), sub, total, final, memo, variance or adjust, as on a statement.        |
| `label`    | string                                                        | optional | Names the scrolling listing for assistive tech and makes it reachable by keyboard.                                                                                                                       |
| `active`   | number \| null                                                | optional | Table mode: the column held under the pointer, or shared with a chart beside it.                                                                                                                         |
| `onActive` | (column: number \| null) => void                              | optional | Table mode: told which column the pointer is over; `null` when it leaves. Needs a client parent.                                                                                                         |
| `children` | ReactNode                                                     | optional | Log mode: pre-formatted lines.                                                                                                                                                                           |
| `note`     | string                                                        | optional | Condition or source under the listing. Dropped in compact.                                                                                                                                               |
| `size`     | 'compact' \| 'normal' \| 'expanded'                           | optional | Force a size. Unset, the block picks from its container's width.                                                                                                                                         |

| Size       | Shows                                                          |
| ---------- | -------------------------------------------------------------- |
| `compact`  | Detail columns and the note are dropped; the title is clamped. |
| `normal`   | Every column, the note and both feed margins.                  |
| `expanded` | As normal.                                                     |

| Text    | Short form | Without one      |
| ------- | ---------- | ---------------- |
| `title` | accepted   | `clamp`, 2 lines |

```mdx
<Printout title="Run log" columns={[{ key: "t", label: "Time" }, { key: "v", label: "Volts", align: "end" }]} rows={[{ t: "00:01", v: "4.82" }]} />
```

### Plotter

A frame that sets a figure on plotter paper: registration marks at the corners and a legend of the pens that drew it.

**Use** An existing SVG figure that is a plotted drawing and wants its pens named. The figure is drawn as it is.

**Avoid** Photographs and screenshots, and figures with a legend of their own; the frame would say it twice.

**Minimum width** `--lk-min-figure`

| Input      | Type                                |          | Meaning                                                                                               |
| ---------- | ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `title`    | string \| { full, short }           | optional | What the sheet shows, as a statement.                                                                 |
| `pens`     | { pen, label, dash? }\[]            | optional | Pens used, from ink, pink, blue, teal, amber and violet, with a dash from solid, dot, short and long. |
| `caption`  | string \| { full, short }           | optional | One or two sentences under the sheet.                                                                 |
| `children` | ReactNode                           | optional | The figure.                                                                                           |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width.                                      |

| Size       | Shows                                                  |
| ---------- | ------------------------------------------------------ |
| `compact`  | The legend is dropped; marks, figure and caption stay. |
| `normal`   | Marks, title, figure, legend and caption.              |
| `expanded` | As normal.                                             |

| Text      | Short form | Without one      |
| --------- | ---------- | ---------------- |
| `caption` | accepted   | `clamp`, 3 lines |

```mdx
<Plotter title="Eye height by length" pens={[{ pen: "pink", label: "coupled" }, { pen: "blue", label: "isolated", dash: "short" }]}>
  <svg viewBox="0 0 320 90" role="img" aria-label="Two lines." />
</Plotter>
```

### Console

A terminal frame in phosphor ink for transcripts and interactives; the same screen in light and dark.

**Use** A session transcript, a command and its output, or a small live readout that is a screen in fact.

**Avoid** Code listings (use a code block) and anything that is not a screen. Scanlines are for a screen meant to look like a monitor.

**Minimum width** `--lk-min-live`

| Input       | Type                                |          | Meaning                                                          |
| ----------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `title`     | string \| { full, short }           | optional | The session's name, in the top line.                             |
| `lines`     | string\[]                           | optional | Transcript lines; one starting `$ ` or `\> ` is typed input.     |
| `children`  | ReactNode                           | optional | Anything else on the screen.                                     |
| `scanlines` | boolean                             | optional | Draw scanlines. Off by default.                                  |
| `size`      | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |

| Size       | Shows                             |
| ---------- | --------------------------------- |
| `compact`  | The title is clamped to one line. |
| `normal`   | Title, transcript and cursor.     |
| `expanded` | As normal.                        |

| Text    | Short form | Without one      |
| ------- | ---------- | ---------------- |
| `title` | accepted   | `clamp`, 1 lines |

```mdx
<Console title="harness" lines={["$ run --seed 7", "ok: 20 tests", "> exit"]} />
```

### Dialogue

A recorded exchange between two parties, set as a transcript on the console screen, with the two sides in columns when they spoke at once.

**Use** A real exchange kept verbatim: two agents asked the same question, a session between a person and a program. Each round is a situation, its turns and its outcome.

**Avoid** Invented or edited dialogue, and a single command and its output (use Console). Turns are shown as recorded and never reworded.

**Minimum width** `--lk-min-live`

| Input    | Type                                                          |          | Meaning                                                                                                 |
| -------- | ------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `title`  | string \| { full, short }                                     | optional | The session's name, in the screen's top line.                                                           |
| `rounds` | { situation, sides?, models?, turns, parallel?, outcome? }\[] | required | The rounds, each with turns of `\{ side, model?, text \}` where side is `hider`, `seeker` or `harness`. |
| `size`   | 'compact' \| 'normal' \| 'expanded'                           | optional | Force a size. Unset, the block picks from its container's width.                                        |

| Size       | Shows                                                          |
| ---------- | -------------------------------------------------------------- |
| `compact`  | The title is clamped to one line; the transcript is as normal. |
| `normal`   | Title, rounds, speaker labels and outcomes.                    |
| `expanded` | As normal.                                                     |

| Text    | Short form | Without one      |
| ------- | ---------- | ---------------- |
| `title` | accepted   | `clamp`, 1 lines |

```mdx
<Dialogue title="exchange" rounds={[{ situation: "Same question", turns: [{ side: "hider", model: "a", text: "Here." }, { side: "seeker", model: "b", text: "There." }] }]} />
```

### Window

A grey title-bar frame in the early-Macintosh manner, for content that is an interface: a form, a readout, a small panel.

**Use** Interface-like content that wants a frame: a settings panel, a dialog, a readout with a status line.

**Avoid** Ordinary figures and prose; the frame carries no information of its own. It does not move or close.

**Minimum width** `--lk-min-live`

| Input      | Type                                |          | Meaning                                                          |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------- |
| `title`    | string \| { full, short }           | required | The title bar's text.                                            |
| `status`   | string                              | optional | A status line under the content. Dropped in compact.             |
| `children` | ReactNode                           | optional | What the window holds.                                           |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the block picks from its container's width. |

| Size       | Shows                                                         |
| ---------- | ------------------------------------------------------------- |
| `compact`  | The status line is dropped; the title is clamped to one line. |
| `normal`   | Title bar, content and status line.                           |
| `expanded` | As normal.                                                    |

| Text    | Short form | Without one      |
| ------- | ---------- | ---------------- |
| `title` | accepted   | `clamp`, 1 lines |

```mdx
<Window title="Receiver" status="3 of 3 online">Gain 12 dB</Window>
```

### Player

The one frame of everything that plays or responds: a stage, three floating bars (top, bottom, left) and panels below.

**Use** Any figure the reader drives: a playback with a scrubber, a simulator with sliders, a map with zoom and layers. The figure supplies the stage and its state; the player draws every control from data and owns the keyboard, full screen and the live region.

**Avoid** A still figure (Figure), a figure that moves by itself with no control (useFigureClock), or a control no kind covers more than once (custom render is the exception).

**Minimum width** `--lk-min-live`

| Input          | Type                                      |          | Meaning                                                                                                                                                                                                                                                                                                                                                                     |
| -------------- | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`     | ReactNode                                 | required | The stage: SVG, canvas or DOM. The player never draws it.                                                                                                                                                                                                                                                                                                                   |
| `title`        | string \| { full, short }                 | optional | Start of the top bar; leave out when the frame's heading already says it.                                                                                                                                                                                                                                                                                                   |
| `label`        | string                                    | required | What the stage is, for assistive technology.                                                                                                                                                                                                                                                                                                                                |
| `readout`      | ReactNode                                 | optional | The current time, date or scene, in the top bar. A polite live region repeats it, not every frame.                                                                                                                                                                                                                                                                          |
| `readoutText`  | string                                    | optional | The readout as plain text, when it is not a string.                                                                                                                                                                                                                                                                                                                         |
| `transport`    | Transport                                 | optional | Present: the bottom bar (play, step, scrub, rate, loop). Optional `bands` ({ from, to, label, pen, dotted? }) draw named stretches of the clock as lines under the track, with a legend beneath and the same words in the scrubber's accessible description. Absent: a frame for an interactive that responds but does not play. Returned by usePlayback, or built by hand. |
| `scenes`       | { items, value, onChange, label? }        | optional | Scenes or chapters: tabs in the top bar, previous and next beside the transport. Each tab controls the stage, which is a tabpanel named by the selected tab.                                                                                                                                                                                                                |
| `controls`     | Control\[]                                | optional | Every control as data: { id, kind, label, where: 'top' \| 'bottom' \| 'left' \| 'panel', ... }.                                                                                                                                                                                                                                                                             |
| `set`          | (id, value) => void                       | optional | Receives a control's value when it has no onChange.                                                                                                                                                                                                                                                                                                                         |
| `panels`       | { id, title, children, open? }\[]         | optional | Stacked below the stage (a right-hand column when expanded): legend, ticker, scoreboard, notes. Each collapses.                                                                                                                                                                                                                                                             |
| `onReset`      | () => void                                | optional | Present: a reset button in the top bar.                                                                                                                                                                                                                                                                                                                                     |
| `fullscreen`   | boolean                                   | optional | The full screen button and the F key. Default true.                                                                                                                                                                                                                                                                                                                         |
| `float`        | 'inset' \| 'overlay'                      | optional | inset (default): the stage is padded by the bars, so they never cover it. overlay: bars cover its edges; for a map with nothing essential there. A compact player is always inset.                                                                                                                                                                                          |
| `autoHide`     | boolean                                   | optional | Overlay only: bars hide while playing and return on pointer, focus or pause. Never under reduced motion or on touch.                                                                                                                                                                                                                                                        |
| `size`         | 'compact' \| 'normal' \| 'expanded'       | optional | Force a size. Unset, the player picks from its own width; full screen is expanded.                                                                                                                                                                                                                                                                                          |
| `focusable`    | boolean                                   | optional | Make the stage a tab stop (default). Off when it has its own.                                                                                                                                                                                                                                                                                                               |
| `onKeyDown`    | (e: KeyboardEvent) => void                | optional | Keys the figure handles itself; call preventDefault to keep the player's map out.                                                                                                                                                                                                                                                                                           |
| `onFullChange` | (full: boolean) => void                   | optional | Called when full screen starts or ends, for a figure whose input differs there.                                                                                                                                                                                                                                                                                             |
| `stageRef`     | Ref\<HTMLDivElement>                      | optional | The stage element, for a figure that measures or draws into it.                                                                                                                                                                                                                                                                                                             |
| `hostRef`      | MutableRefObject\<HTMLDivElement \| null> | optional | The player's outermost element, for a figure that watches it.                                                                                                                                                                                                                                                                                                               |
| `id`           | string                                    | optional | Anchor.                                                                                                                                                                                                                                                                                                                                                                     |

| Size       | Shows                                                                                                                          |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `compact`  | Play and scrub (and scene previous and next); tools fold into a menu; panels become one disclosure list, closed; short labels. |
| `normal`   | All three bars, scene tabs, step, rate and loop; panels stacked below, open.                                                   |
| `expanded` | Full screen (or forced): as normal, panels in a right-hand column.                                                             |

| Text    | Short form | Without one      |
| ------- | ---------- | ---------------- |
| `title` | accepted   | `clamp`, 1 lines |

```mdx
const pb = usePlayback({ host, max: 12, step: 1 });
<Player label="Rainfall by month" readout={months[pb.t]} transport={pb}
  controls={[{ id: "zoom", kind: "button", where: "left", label: "Zoom in", icon: "zoom-in", onPress: zoomIn }]}
  panels={[{ id: "legend", title: "Legend", children: <Legend /> }]}>
  <svg>...</svg>
</Player>
```

### Frame

The figure frame under every interactive: a heading, the media, a caption and a credit, sized by the block contract.

**Use** Wrapping a Player or any client component. Live is a thin wrapper over it; reach for Live in MDX.

**Avoid** Drawing controls here; they belong to the Player inside.

**Minimum width** `--lk-min-live`

| Input      | Type                                |          | Meaning                                                                            |
| ---------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------- |
| `title`    | string \| { full, short }           | required | What the interaction is. Compact refuses it without a short form.                  |
| `caption`  | string \| { full, short }           | optional | What to try.                                                                       |
| `credit`   | ReactNode                           | optional | Provenance; dropped in compact.                                                    |
| `children` | ReactNode                           | optional | The player or interactive.                                                         |
| `size`     | 'compact' \| 'normal' \| 'expanded' | optional | Force a size. Unset, the player picks from its own width; full screen is expanded. |

| Size       | Shows                                                   |
| ---------- | ------------------------------------------------------- |
| `compact`  | Media and the short title; caption cut, credit dropped. |
| `normal`   | Title, media, caption and credit.                       |
| `expanded` | As normal, with title and caption one step larger.      |

| Text      | Short form | Without one      |
| --------- | ---------- | ---------------- |
| `title`   | accepted   | `require`        |
| `caption` | accepted   | `clamp`, 3 lines |
| `credit`  | none       | `drop`           |

```mdx
<Frame title={{ full: "Drive the reservoir", short: "Reservoir" }}><MyPlayer /></Frame>
```

## Layouts

What a Section picks from its contents, and how it collapses.

| Id                | Summary                                                                           |
| ----------------- | --------------------------------------------------------------------------------- |
| `layout:opener`   | First section of an article: prose, with at most one figure.                      |
| `layout:column`   | Prose alone, or prose mixed with several other blocks.                            |
| `layout:spread`   | Prose with exactly one figure, live block or sidebar (a sidebar beside the text). |
| `layout:plate`    | A single figure or live block and nothing else.                                   |
| `layout:gallery`  | Two or more figures and nothing else.                                             |
| `layout:stat-row` | Two or more stats and nothing else.                                               |
| `layout:margin`   | Prose with one or more notes.                                                     |
| `layout:columns`  | Never picked from contents; set with layout="columns" on a run of long prose.     |
| `layout:closer`   | Last section of an article when it carries a pull quote.                          |

### opener

First section of an article: prose, with at most one figure.

**Use** The first section of a piece: title, lede and at most one hero figure.

**Avoid** Anywhere but first; it sets display type. In a narrow container: Display type scales down; the figure stays below the text.

| Input    | Type     |          | Meaning                                                                        |
| -------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `layout` | "opener" | optional | On a Section; left out, the section picks this layout when its contents match. |

```mdx
<Section layout="opener">

## Title

A two-sentence lede.

<Figure ratio="wide" />

</Section>
```

### column

Prose alone, or prose mixed with several other blocks.

**Use** Running text, alone or with several figures, quotes and tables.

**Avoid** A figure that deserves a section of its own (use a plate). In a narrow container: Figures break out to the wide column while there is room.

| Input    | Type     |          | Meaning                                                                        |
| -------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `layout` | "column" | optional | On a Section; left out, the section picks this layout when its contents match. |

```mdx
<Section>

Two paragraphs of text.

</Section>
```

### spread

Prose with exactly one figure, live block or sidebar (a sidebar beside the text).

**Use** A passage and the one figure it explains, side by side.

**Avoid** More than one figure; the text would have nothing to sit beside. In a narrow container: Stacks, text first, once prose and figure cannot both keep their minimum width.

| Input    | Type     |          | Meaning                                                                        |
| -------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `layout` | "spread" | optional | On a Section; left out, the section picks this layout when its contents match. |

```mdx
<Section>

### Heading

Text.

<Figure caption="What to see." />

</Section>
```

### plate

A single figure or live block and nothing else.

**Use** One figure that needs the full width.

**Avoid** Two plates in a row; the second is set as a column. In a narrow container: Always full width; the caption keeps the text measure.

| Input    | Type    |          | Meaning                                                                        |
| -------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `layout` | "plate" | optional | On a Section; left out, the section picks this layout when its contents match. |

```mdx
<Section>

<Figure title="A statement" caption="What to see." />

</Section>
```

### gallery

Two or more figures and nothing else.

**Use** Two or more figures that compare.

**Avoid** Figures that need long captions; many items set them compact. In a narrow container: As many columns as fit at the figure minimum, down to one.

| Input    | Type      |          | Meaning                                                                        |
| -------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `layout` | "gallery" | optional | On a Section; left out, the section picks this layout when its contents match. |

```mdx
<Section>

<Figure caption="One" />

<Figure caption="Two" />

</Section>
```

### stat-row

Two or more stats and nothing else.

**Use** Two or more headline numbers.

**Avoid** A number that needs a paragraph; put it in the text. In a narrow container: As many columns as fit at the stat minimum, down to one.

| Input    | Type       |          | Meaning                                                                        |
| -------- | ---------- | -------- | ------------------------------------------------------------------------------ |
| `layout` | "stat-row" | optional | On a Section; left out, the section picks this layout when its contents match. |

```mdx
<Section>

<Stat value="0.995" label="Reservoir" note="± 0.009" />

<Stat value="0.724" label="Raw samples" />

</Section>
```

### margin

Prose with one or more notes.

**Use** Prose with asides that belong beside a paragraph.

**Avoid** Notes that carry the argument; they are dropped or cut when narrow. In a narrow container: Notes sit in the margin beside their paragraph, or inline under it when there is no margin.

| Input    | Type     |          | Meaning                                                                        |
| -------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `layout` | "margin" | optional | On a Section; left out, the section picks this layout when its contents match. |

```mdx
<Section layout="margin">

A paragraph.

<Note>An aside.</Note>

</Section>
```

### columns

Never picked from contents; set with layout="columns" on a run of long prose.

**Use** A long stretch of prose that would run to an uncomfortable line length at the wide column.

**Avoid** A short passage; balanced columns of three paragraphs look ragged. Not for text with figures between every paragraph. In a narrow container: Two columns, three in a very wide article, one when the slot cannot hold two; headings, figures and quotes span all of them.

| Input    | Type      |          | Meaning                                                                        |
| -------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `layout` | "columns" | optional | On a Section; left out, the section picks this layout when its contents match. |

```mdx
<Section layout="columns">

### Heading

A long run of text.

<Figure caption="Spans all columns." />

More text.

</Section>
```

### closer

Last section of an article when it carries a pull quote.

**Use** The last section when it ends on a pull quote.

**Avoid** A summary; the closer is a quote and a line, not a recap. In a narrow container: Centred on the text measure at every width.

| Input    | Type     |          | Meaning                                                                        |
| -------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `layout` | "closer" | optional | On a Section; left out, the section picks this layout when its contents match. |

```mdx
<Section layout="closer">

<PullQuote cite="Source">A line worth keeping.</PullQuote>

</Section>
```

## Templates

The page around a piece's body.

| Id                  | Summary                                                                                                                                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template:feature`  | Long-form research feature, told in parts.                                                                                                                                                                                         |
| `template:write-up` | Labs write-up: the feature opener family, shorter and more practical, with status and stack as a compact facts row.                                                                                                                |
| `template:index`    | The shelf of one kind: a standing line, the newest piece as the lead, the rest as an ordered grid of cards.                                                                                                                        |
| `template:landing`  | The front page, a dark page of its own and not an article: hero, what the studio does, featured pieces, tags, recent work, the team and the contact address. Copy is data in content/home; its styles are src/app/(home)/home.css. |

### feature

Long-form research feature, told in parts.

**Use** A long research piece told in parts, with a masthead (an optional `motif` drawing beside the title) and a table of contents. The first paragraph of a chapter takes a drop cap unless it is short (under about three lines) or sits beside a figure.

**Avoid** A short note or a reference page; it expects chapters.

| Input   | Type      |          | Meaning                                             |
| ------- | --------- | -------- | --------------------------------------------------- |
| `kinds` | string\[] | required | Piece kinds that use it: research.                  |
| `shell` | object    | required | Table of contents on, full width, feature masthead. |

```mdx
---
title: A question as a statement
kind: research
---

<Article>

<Section layout="opener">

## Title

Lede.

</Section>

</Article>
```

### write-up

Labs write-up: the feature opener family, shorter and more practical, with status and stack as a compact facts row.

**Use** A write-up of lab work: what was built or simulated, what it did, what is unproven. Status, stack and repository sit under the title as one facts row, from `status`, `stack` and `repo` in the frontmatter; a `motif` (a small line drawing) sits beside the title; the contents are on; no drop cap.

**Avoid** Finished research told in parts; use feature. A page with nothing to put in the facts row still works, but then feature's byline says more.

| Input   | Type      |          | Meaning                                              |
| ------- | --------- | -------- | ---------------------------------------------------- |
| `kinds` | string\[] | required | Piece kinds that use it: labs.                       |
| `shell` | object    | required | Table of contents on, full width, write-up masthead. |

```mdx
---
title: What the build did
kind: labs
status: Alpha
stack:
  - Python
  - FastAPI
repo: https://github.com/drksci/example
---

<Article>

<Section>

## What it is for

<Lead>

Two sentences.

</Lead>

</Section>

</Article>
```

### index

The shelf of one kind: a standing line, the newest piece as the lead, the rest as an ordered grid of cards.

**Use** A page that lists the pieces of one kind, or of one tag (/tags/\<slug>, noindex under two pieces), newest first. It works with one piece (a lead alone) and with thirty (a lead and a grid that adds rows); with none it says so in one line.

**Avoid** A page of mixed things, or one that needs filters; the shelf is ordered by date and nothing else.

| Input   | Type      |          | Meaning                                            |
| ------- | --------- | -------- | -------------------------------------------------- |
| `kinds` | string\[] | required | Piece kinds that use it: .                         |
| `shell` | object    | required | Table of contents off, full width, plain masthead. |

```mdx
<PieceIndex kind="research" />
```

### landing

The front page, a dark page of its own and not an article: hero, what the studio does, featured pieces, tags, recent work, the team and the contact address. Copy is data in content/home; its styles are src/app/(home)/home.css.

**Use** The front page only: a display heading and line, a row of what the studio does, the featured pieces, every tag in use (each to /tags/\<slug>), the newest other pieces as one-line rows, the team and the contact address.

**Avoid** Any other page, and the article look: it keeps its own legacy sheet, scoped under .home-root, and ignores the theme and the light/dark switch.

| Input   | Type      |          | Meaning                                            |
| ------- | --------- | -------- | -------------------------------------------------- |
| `kinds` | string\[] | required | Piece kinds that use it: .                         |
| `shell` | object    | required | Table of contents off, full width, plain masthead. |

```mdx
<Landing />
```

## Token groups

Design tokens by group, from the default theme.

| Id                  | Summary                                                       |
| ------------------- | ------------------------------------------------------------- |
| `token:space`       | Space scale (primitive tier, 8 tokens).                       |
| `token:step`        | Type scale (primitive tier, 8 tokens).                        |
| `token:font`        | Font families (primitive tier, 3 tokens).                     |
| `token:type-detail` | Leading, weight and tracking (primitive tier, 8 tokens).      |
| `token:measure`     | Measures (primitive tier, 5 tokens).                          |
| `token:shape`       | Radii and ratios (primitive tier, 7 tokens).                  |
| `token:line`        | Line weights (primitive tier, 2 tokens).                      |
| `token:pen`         | Plotter pens (primitive tier, 6 tokens).                      |
| `token:color`       | Colour roles (semantic tier, 9 tokens).                       |
| `token:text`        | Text roles (semantic tier, 8 tokens).                         |
| `token:gap`         | Spacing roles (semantic tier, 6 tokens).                      |
| `token:lk-grid`     | Layout kit: grid and rhythm (component tier, 8 tokens).       |
| `token:lk-min`      | Layout kit: minimum useful widths (component tier, 6 tokens). |
| `token:lk-block`    | Layout kit: blocks (component tier, 19 tokens).               |
| `token:pc`          | Piece page: contents rail (component tier, 1 tokens).         |
| `token:pl`          | Plot kit (component tier, 26 tokens).                         |
| `token:pv`          | Player (component tier, 7 tokens).                            |
| `token:sf`          | Surface blocks (component tier, 5 tokens).                    |
| `token:og`          | Social images (component tier, 13 tokens).                    |

### space

Space scale (primitive tier, 8 tokens).

**Use** Raw scales; reference them only from semantic tokens.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-space-1) var(--ds-space-2) var(--ds-space-3)
```

### step

Type scale (primitive tier, 8 tokens).

**Use** Raw scales; reference them only from semantic tokens.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-step--1) var(--ds-step-0) var(--ds-step-1)
```

### font

Font families (primitive tier, 3 tokens).

**Use** Raw scales; reference them only from semantic tokens.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-font-sans) var(--ds-font-serif) var(--ds-font-mono)
```

### type-detail

Leading, weight and tracking (primitive tier, 8 tokens).

**Use** Raw scales; reference them only from semantic tokens.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-leading-tight) var(--ds-leading-snug) var(--ds-leading-body)
```

### measure

Measures (primitive tier, 5 tokens).

**Use** Raw scales; reference them only from semantic tokens.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-measure-note) var(--ds-measure-breakout) var(--ds-measure-tile)
```

### shape

Radii and ratios (primitive tier, 7 tokens).

**Use** Raw scales; reference them only from semantic tokens.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-radius-0) var(--ds-radius-1) var(--ds-ratio-square)
```

### line

Line weights (primitive tier, 2 tokens).

**Use** Raw scales; reference them only from semantic tokens.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-line-hair) var(--ds-line-bold)
```

### pen

Plotter pens (primitive tier, 6 tokens).

**Use** Raw scales; reference them only from semantic tokens.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-pen-pink) var(--ds-pen-blue) var(--ds-pen-teal)
```

### color

Colour roles (semantic tier, 9 tokens).

**Use** Roles such as ink and paper; use in app CSS and figures.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-color-paper) var(--ds-color-ink) var(--ds-color-mute)
```

### text

Text roles (semantic tier, 8 tokens).

**Use** Roles such as ink and paper; use in app CSS and figures.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-text-caption) var(--ds-text-body) var(--ds-text-lede)
```

### gap

Spacing roles (semantic tier, 6 tokens).

**Use** Roles such as ink and paper; use in app CSS and figures.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--ds-gap-hair) var(--ds-gap-tight) var(--ds-gap-block)
```

### lk-grid

Layout kit: grid and rhythm (component tier, 8 tokens).

**Use** What component CSS reads; the only tier a block may use.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--lk-measure) var(--lk-breakout) var(--lk-section-gap)
```

### lk-min

Layout kit: minimum useful widths (component tier, 6 tokens).

**Use** What component CSS reads; the only tier a block may use.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--lk-min-prose) var(--lk-min-figure) var(--lk-min-live)
```

### lk-block

Layout kit: blocks (component tier, 19 tokens).

**Use** What component CSS reads; the only tier a block may use.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--lk-figure-radius) var(--lk-figure-surface) var(--lk-figure-ratio)
```

### pc

Piece page: contents rail (component tier, 1 tokens).

**Use** What component CSS reads; the only tier a block may use.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--pc-rail-top)
```

### pl

Plot kit (component tier, 26 tokens).

**Use** What component CSS reads; the only tier a block may use.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--pl-ink) var(--pl-paper) var(--pl-mute)
```

### pv

Player (component tier, 7 tokens).

**Use** What component CSS reads; the only tier a block may use.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--pv-chrome) var(--pv-edge) var(--pv-pad)
```

### sf

Surface blocks (component tier, 5 tokens).

**Use** What component CSS reads; the only tier a block may use.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--sf-band) var(--sf-perf) var(--sf-screen)
```

### og

Social images (component tier, 13 tokens).

**Use** What component CSS reads; the only tier a block may use.

**Avoid** Writing the value out; a raw literal fails the audit.

```mdx
var(--og-paper) var(--og-ink) var(--og-mute)
```

## Figure primitives

Drawing primitives in the plot kit, read from their doc comments.

| Id                      | Summary                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `figure:usePlayback`    | The one playback clock: play, pause, toggle, step, seek, rate, loop, range and tick count, driven from animation frames.                                                                                                             |
| `figure:Control`        | A control declared as data: slider, stepper, chips, toggle, select, button, or a custom render.                                                                                                                                      |
| `figure:SessionEmbed`   | A self-contained recorded session set into a piece as a lazy iframe that plays while on screen and pauses when it leaves.                                                                                                            |
| `figure:BAKED`          | The default theme's palette as a figure generator bakes it into an SVG, and the token each colour stands for.                                                                                                                        |
| `figure:Chips`          | A row of toggle buttons choosing one of a few states.                                                                                                                                                                                |
| `figure:Stops`          | Accessible name of the group.                                                                                                                                                                                                        |
| `figure:FlowFigure`     | Flow diagrams: boxes placed by hand, wires routed at right angles from one side of a box to a side of another.                                                                                                                       |
| `figure:panelGrid`      | Layout for a row of small-multiple panels: one column when `narrow`, two otherwise.                                                                                                                                                  |
| `figure:useFigureClock` | One frame clock per figure, for drawings that move by themselves.                                                                                                                                                                    |
| `figure:PEN_CYCLE`      | The plot kit: what every drawn figure shares.                                                                                                                                                                                        |
| `figure:WEIGHT`         | Line weights and dash patterns.                                                                                                                                                                                                      |
| `figure:DASH`           | Exported by the plot kit (kit.tsx).                                                                                                                                                                                                  |
| `figure:SIZE`           | Text sizes, in viewBox units (user space, so the text scales with the drawing).                                                                                                                                                      |
| `figure:SIZE_PX`        | The same steps as plain numbers, for layout arithmetic (how wide a label is, how far apart wrapped lines sit).                                                                                                                       |
| `figure:OVERPRINT`      | Crossing pens mix as ink on paper (or as light, in the dark theme).                                                                                                                                                                  |
| `figure:f1`             | Exported by the plot kit (kit.tsx).                                                                                                                                                                                                  |
| `figure:path`           | Exported by the plot kit (kit.tsx).                                                                                                                                                                                                  |
| `figure:ditherDefs`     | Seventeen ordered-dither patterns for one pen, ids `$\{prefix\}-0` … `-16`.                                                                                                                                                          |
| `figure:ditherFill`     | Pattern fill for a magnitude in \[0, 1]; null when it dithers to paper.                                                                                                                                                              |
| `figure:HATCH_PEN`      | Diagonal pen strokes in a series' own colour, for areas and bars.                                                                                                                                                                    |
| `figure:HATCHES`        | Exported by the plot kit (kit.tsx).                                                                                                                                                                                                  |
| `figure:hatch`          | Exported by the plot kit (kit.tsx).                                                                                                                                                                                                  |
| `figure:tone`           | Fill for a magnitude in \[0, 1], or "none" when it dithers to paper.                                                                                                                                                                 |
| `figure:dots`           | The dotted field a frame sits on; `opacity` for a darker field.                                                                                                                                                                      |
| `figure:label`          | Knock the paper out behind the text so it reads over line work.                                                                                                                                                                      |
| `figure:edgeAnchor`     | Advance of one character of the kit's mono face at the base size, in drawing units.                                                                                                                                                  |
| `figure:fitLines`       | Advance of one character when the label is not at the base size.                                                                                                                                                                     |
| `figure:frame`          | Frame on a dotted field, with ticks and optional axis labels.                                                                                                                                                                        |
| `figure:penArea`        | Width of the drawing: labels that would pass its edge are kept inside.                                                                                                                                                               |
| `figure:PlotSvg`        | Line weight (a WEIGHT step); `null` draws the band and hatching only.                                                                                                                                                                |
| `figure:wrap`           | One numbered entry of a figure's key: a short name and a plain gloss.                                                                                                                                                                |
| `figure:notes`          | The numbered stage key set beside a figure: each stage's number and name in spaced capitals, its gloss wrapped beneath in the muted ink.                                                                                             |
| `figure:withNotes`      | Finish a figure with its stage key set under the drawing at `y`: pushes the key onto `node` and returns the built figure, tall enough to hold it.                                                                                    |
| `figure:legendRow`      | One legend entry: a pen, its name, and an optional dash for a dashed line.                                                                                                                                                           |
| `figure:legendCol`      | A legend in one column on a paper patch, so it can sit over line work.                                                                                                                                                               |
| `figure:useUid`         | A DOM-safe unique id for the patterns and clips inside one plate.                                                                                                                                                                    |
| `figure:plateSvg`       | The drawing surface of a hand-drawn plate: an accessible SVG that fills its column.                                                                                                                                                  |
| `figure:Dots`           | A regular dot field, as a pattern to fill tone with.                                                                                                                                                                                 |
| `figure:PlateOf`        | A hand-drawn plate: a component that takes its accessible name as `title`.                                                                                                                                                           |
| `figure:scatter`        | `n` seeded points in the unit square, the same on every render, for marks scattered over a plate.                                                                                                                                    |
| `figure:linear`         | Exported by the plot kit (scale.ts).                                                                                                                                                                                                 |
| `figure:log`            | Exported by the plot kit (scale.ts).                                                                                                                                                                                                 |
| `figure:useTick`        | Subscribe a frame callback to the enclosing figure's clock while it runs.                                                                                                                                                            |
| `figure:FigureShell`    | The frame of every chart figure: a host element, the accessible plot svg on its paper, the figure's `defs`, optional `controls` above, and (with `clock`, from `useFigureClock(host)`) the frame clock for `useTick` in the drawing. |
| `figure:PLATE_MONO`     | Spaced capitals in the mono face: the label voice of a hand-drawn plate.                                                                                                                                                             |
| `figure:PLATE_NOTE`     | Small plain mono, for notes on a plate.                                                                                                                                                                                              |
| `figure:Tag`            | A mono label on a paper patch, so it reads over line work.                                                                                                                                                                           |
| `figure:yTicks`         | One axis tick as `frame()` takes it: the value, its position, its text.                                                                                                                                                              |
| `figure:xTicks`         | X-axis ticks for `frame()`; see {@link yTicks}.                                                                                                                                                                                      |

### usePlayback

The one playback clock: play, pause, toggle, step, seek, rate, loop, range and tick count, driven from animation frames.

**Use** A figure the reader plays and scrubs. It pauses off screen and while the tab is hidden, never autoplays under reduced motion, and returns a Transport for the Player's bottom bar. The pure half is playbackReducer.

**Avoid** A drawing that moves by itself and has no controls; use useFigureClock.

| Input       | Type                    |          | Meaning                                                           |
| ----------- | ----------------------- | -------- | ----------------------------------------------------------------- |
| `host`      | RefObject\<HTMLElement> | required | The element whose visibility gates the clock.                     |
| `max`       | number                  | required | End of the range, in the figure's units.                          |
| `min`       | number                  | optional | Start of the range. Default 0.                                    |
| `step`      | number                  | optional | Step and scrub granularity; 0 is continuous.                      |
| `perSecond` | number                  | optional | Units per second at rate 1. Default 1.                            |
| `autoplay`  | boolean                 | optional | Play when first on screen; never under reduced motion.            |
| `onFrame`   | (t: number) => void     | optional | Called after every change, for a figure that draws outside React. |

```mdx
const pb = usePlayback({ host, max: 12, step: 1, perSecond: 2, autoplay: true });
```

### Control

A control declared as data: slider, stepper, chips, toggle, select, button, or a custom render.

**Use** Every control of a Player: { id, kind, label (full and short), where, value, onChange }. A slider with stops rests only on measured rows and prints them; chips with `tabs` make a tablist whose tabs carry aria-selected and aria-controls; spread `tabPanel(controlId, value)` on the panel each one shows. The player draws each the same way in every figure.

**Avoid** A bespoke button or slider in a figure. Custom render is the exception; if two figures need one, add a kind.

| Input      | Type                                                                             |          | Meaning                                                                                                                                                                                                                 |
| ---------- | -------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | string                                                                           | required | Unique in the player; the name set(id, value) receives.                                                                                                                                                                 |
| `kind`     | 'slider' \| 'stepper' \| 'chips' \| 'toggle' \| 'select' \| 'button' \| 'custom' | required | Which control.                                                                                                                                                                                                          |
| `label`    | string \| { full, short }                                                        | required | The accessible name; the short form shows in a tight bar.                                                                                                                                                               |
| `where`    | 'top' \| 'bottom' \| 'left' \| 'panel'                                           | required | Which bar or the parameters panel draws it.                                                                                                                                                                             |
| `value`    | number \| string \| boolean                                                      | optional | The current value, by kind. A button has onPress instead.                                                                                                                                                               |
| `onChange` | (value) => void                                                                  | optional | Or the player's set(id, value).                                                                                                                                                                                         |
| `target`   | string \| { full, short }                                                        | optional | What the control acts on when there are several (a sheet, a layer). Controls with one target are drawn as one named group, and each name ends with it: 'Zoom in: Knowledge sheet'.                                      |
| `tabs`     | boolean                                                                          | optional | Chips only: a tablist with arrow keys. Each tab has role tab, aria-selected and aria-controls naming its panel (panelId(id, value), or `panel` when one area swaps); give the panel the props from tabPanel(id, value). |

```mdx
{ id: "mode", kind: "chips", where: "left", label: { full: "Mode", short: "Mode" }, options: ["pan", "tilt"], value: mode, onChange: setMode }
```

### SessionEmbed

A self-contained recorded session set into a piece as a lazy iframe that plays while on screen and pauses when it leaves.

**Use** A replay that is its own application, with traces or frames of its own, carried as it ran elsewhere. Put it in a Live block; it speaks the netscraper:play, :pause and :ready messages.

**Avoid** A new figure: those use Player with declared controls. This is for a player that already exists as a page.

| Input   | Type   |          | Meaning                                   |
| ------- | ------ | -------- | ----------------------------------------- |
| `src`   | string | required | Path of the player's page, under public/. |
| `title` | string | required | The frame's accessible name.              |

```mdx
<Live title="Recorded session"><SessionEmbed src="/pieces/slug/session/index.html" title="Recorded session" /></Live>
```

### BAKED

The default theme's palette as a figure generator bakes it into an SVG, and the token each colour stands for.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { BAKED } from "@/blocks/plot";
```

### Chips

A row of toggle buttons choosing one of a few states.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { Chips } from "@/blocks/plot";
```

### Stops

Accessible name of the group.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { Stops } from "@/blocks/plot";
```

### FlowFigure

Flow diagrams: boxes placed by hand, wires routed at right angles from one side of a box to a side of another.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { FlowFigure } from "@/blocks/plot";
```

### panelGrid

Layout for a row of small-multiple panels: one column when `narrow`, two otherwise.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { panelGrid } from "@/blocks/plot";
```

### useFigureClock

One frame clock per figure, for drawings that move by themselves.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { useFigureClock } from "@/blocks/plot";
```

### PEN_CYCLE

The plot kit: what every drawn figure shares.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { PEN_CYCLE } from "@/blocks/plot";
```

### WEIGHT

Line weights and dash patterns.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { WEIGHT } from "@/blocks/plot";
```

### DASH

Exported by the plot kit (kit.tsx).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { DASH } from "@/blocks/plot";
```

### SIZE

Text sizes, in viewBox units (user space, so the text scales with the drawing).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { SIZE } from "@/blocks/plot";
```

### SIZE_PX

The same steps as plain numbers, for layout arithmetic (how wide a label is, how far apart wrapped lines sit).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { SIZE_PX } from "@/blocks/plot";
```

### OVERPRINT

Crossing pens mix as ink on paper (or as light, in the dark theme).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { OVERPRINT } from "@/blocks/plot";
```

### f1

Exported by the plot kit (kit.tsx).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { f1 } from "@/blocks/plot";
```

### path

Exported by the plot kit (kit.tsx).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { path } from "@/blocks/plot";
```

### ditherDefs

Seventeen ordered-dither patterns for one pen, ids `$\{prefix\}-0` … `-16`.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { ditherDefs } from "@/blocks/plot";
```

### ditherFill

Pattern fill for a magnitude in \[0, 1]; null when it dithers to paper.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { ditherFill } from "@/blocks/plot";
```

### HATCH_PEN

Diagonal pen strokes in a series' own colour, for areas and bars.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { HATCH_PEN } from "@/blocks/plot";
```

### HATCHES

Exported by the plot kit (kit.tsx).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { HATCHES } from "@/blocks/plot";
```

### hatch

Exported by the plot kit (kit.tsx).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { hatch } from "@/blocks/plot";
```

### tone

Fill for a magnitude in \[0, 1], or "none" when it dithers to paper.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { tone } from "@/blocks/plot";
```

### dots

The dotted field a frame sits on; `opacity` for a darker field.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { dots } from "@/blocks/plot";
```

### label

Knock the paper out behind the text so it reads over line work.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { label } from "@/blocks/plot";
```

### edgeAnchor

Advance of one character of the kit's mono face at the base size, in drawing units.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { edgeAnchor } from "@/blocks/plot";
```

### fitLines

Advance of one character when the label is not at the base size.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { fitLines } from "@/blocks/plot";
```

### frame

Frame on a dotted field, with ticks and optional axis labels.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { frame } from "@/blocks/plot";
```

### penArea

Width of the drawing: labels that would pass its edge are kept inside.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { penArea } from "@/blocks/plot";
```

### PlotSvg

Line weight (a WEIGHT step); `null` draws the band and hatching only.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { PlotSvg } from "@/blocks/plot";
```

### wrap

One numbered entry of a figure's key: a short name and a plain gloss.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { wrap } from "@/blocks/plot";
```

### notes

The numbered stage key set beside a figure: each stage's number and name in spaced capitals, its gloss wrapped beneath in the muted ink.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { notes } from "@/blocks/plot";
```

### withNotes

Finish a figure with its stage key set under the drawing at `y`: pushes the key onto `node` and returns the built figure, tall enough to hold it.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { withNotes } from "@/blocks/plot";
```

### legendRow

One legend entry: a pen, its name, and an optional dash for a dashed line.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { legendRow } from "@/blocks/plot";
```

### legendCol

A legend in one column on a paper patch, so it can sit over line work.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { legendCol } from "@/blocks/plot";
```

### useUid

A DOM-safe unique id for the patterns and clips inside one plate.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { useUid } from "@/blocks/plot";
```

### plateSvg

The drawing surface of a hand-drawn plate: an accessible SVG that fills its column.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { plateSvg } from "@/blocks/plot";
```

### Dots

A regular dot field, as a pattern to fill tone with.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { Dots } from "@/blocks/plot";
```

### PlateOf

A hand-drawn plate: a component that takes its accessible name as `title`.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { PlateOf } from "@/blocks/plot";
```

### scatter

`n` seeded points in the unit square, the same on every render, for marks scattered over a plate.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { scatter } from "@/blocks/plot";
```

### linear

Exported by the plot kit (scale.ts).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { linear } from "@/blocks/plot";
```

### log

Exported by the plot kit (scale.ts).

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { log } from "@/blocks/plot";
```

### useTick

Subscribe a frame callback to the enclosing figure's clock while it runs.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { useTick } from "@/blocks/plot";
```

### FigureShell

The frame of every chart figure: a host element, the accessible plot svg on its paper, the figure's `defs`, optional `controls` above, and (with `clock`, from `useFigureClock(host)`) the frame clock for `useTick` in the drawing.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { FigureShell } from "@/blocks/plot";
```

### PLATE_MONO

Spaced capitals in the mono face: the label voice of a hand-drawn plate.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { PLATE_MONO } from "@/blocks/plot";
```

### PLATE_NOTE

Small plain mono, for notes on a plate.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { PLATE_NOTE } from "@/blocks/plot";
```

### Tag

A mono label on a paper patch, so it reads over line work.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { Tag } from "@/blocks/plot";
```

### yTicks

One axis tick as `frame()` takes it: the value, its position, its text.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { yTicks } from "@/blocks/plot";
```

### xTicks

X-axis ticks for `frame()`; see {@link yTicks}.

**Use** Drawing figures in the house style; import from @/blocks/plot.

```mdx
import { xTicks } from "@/blocks/plot";
```

## Writing elements

One entry per element of the writing guide; the full entries are on the writing page.

| Id                         | Summary                                                                   |
| -------------------------- | ------------------------------------------------------------------------- |
| `element:title`            | Tells a reader scanning a list which subject this is.                     |
| `element:deck`             | Lets a reader decide whether to read on, without the body.                |
| `element:lede`             | Gives the finding and its conditions to a reader who stops here.          |
| `element:section-heading`  | Lets a reader find a part of the argument from the contents list.         |
| `element:sub-heading`      | Marks a change of subject within a section.                               |
| `element:body`             | Carries the argument: mechanism, then numbers with their conditions.      |
| `element:list-item`        | Presents one of several parallel things for comparison or lookup.         |
| `element:pull-quote`       | Shows a skimming reader the sentence the section turns on.                |
| `element:caption`          | Tells the reader what to see in the figure and what it cannot show.       |
| `element:stat-value`       | Gives one number to a reader who looks at nothing else.                   |
| `element:stat-label`       | Says what the number measures and under which conditions.                 |
| `element:table-header`     | Names what every cell beneath it holds, units included.                   |
| `element:table-cell`       | Holds one value for lookup and comparison down a column.                  |
| `element:alt-text`         | Stands in for the image for a reader who cannot see it.                   |
| `element:link-text`        | Tells the reader where the link goes before it is followed.               |
| `element:summary`          | Lets a reader outside the site judge the piece from one line.             |
| `element:footnote`         | Lets a reader check a claim against where it came from.                   |
| `element:code-comment`     | Tells the reader why a line is there, which the code cannot say.          |
| `element:resume-summary`   | Tells a screener in ten seconds what the person does and at what scale.   |
| `element:resume-bullet`    | Gives an interviewer one checkable thing that was done and what it moved. |
| `element:letter-paragraph` | Connects one need of the role to one piece of evidence.                   |
| `element:change-text`      | Tells a reviewer what changed, why, and how it was checked.               |

### title

Tells a reader scanning a list which subject this is.

**Use** First line of a piece, and its name in every index, tab and link.

**Avoid** An opening "The". Colons and subtitles packed into one line. Questions, promises and superlatives.

| Input    | Type       |          | Meaning                        |
| -------- | ---------- | -------- | ------------------------------ |
| `length` | characters | optional | At most 60 characters (error). |
| `length` | words      | optional | At most 8 words (warn).        |

```mdx
Goldray
```

### deck

Lets a reader decide whether to read on, without the body.

**Use** Directly under the title; also called the standfirst or subtitle.

**Avoid** Scene-setting about the field or the era. Repeating the title. Adjectives standing in for a number.

| Input    | Type      |          | Meaning                   |
| -------- | --------- | -------- | ------------------------- |
| `length` | sentences | optional | 1 to 3 sentences (warn).  |
| `length` | words     | optional | At most 60 words (error). |

```mdx
A metal detector hears one note and forgets it. Goldray is a design for keeping every note, with the place the coil was when it sounded, until a swing becomes a picture of the ground.
```

### lede

Gives the finding and its conditions to a reader who stops here.

**Use** First paragraph of the body, or the hero blurb above it.

**Avoid** A survey of the field or a definition the reader already has. Staged openers and rhetorical questions. Detail that belongs in the body.

| Input    | Type      |          | Meaning                  |
| -------- | --------- | -------- | ------------------------ |
| `length` | sentences | optional | 2 to 3 sentences (warn). |
| `length` | words     | optional | At most 70 words (warn). |

```mdx
Goldray is designed to keep what a metal detector throws away: every measurement, with the place the coil was when it was taken, so that a swing adds up to an image. It comes in five blocks, none of them built, and every depth below is a simulation’s.
```

### section-heading

Lets a reader find a part of the argument from the contents list.

**Use** Second-level heading over a run of blocks; listed in the table of contents.

**Avoid** An opening "The". Questions, colons and closing punctuation. Headings that only work once the section has been read.

| Input    | Type       |          | Meaning                        |
| -------- | ---------- | -------- | ------------------------------ |
| `length` | characters | optional | At most 48 characters (error). |
| `length` | words      | optional | At most 7 words (warn).        |

```mdx
Nineteen minutes over the Tops
```

### sub-heading

Marks a change of subject within a section.

**Use** Third level and below, inside a section.

**Avoid** An opening "The". Restating the section heading. Clauses and full sentences.

| Input    | Type       |          | Meaning                        |
| -------- | ---------- | -------- | ------------------------------ |
| `length` | characters | optional | At most 40 characters (error). |
| `length` | words      | optional | At most 5 words (warn).        |

```mdx
Kernel lifecycle
```

### body

Carries the argument: mechanism, then numbers with their conditions.

**Use** Text measure of a section, between headings and figures.

**Avoid** "We", "our", "us", "I" and "my". Stock vocabulary, triads and "not just X, but Y". A closing line that restates the paragraph. Leading labels in front of a sentence.

| Input    | Type      |          | Meaning                   |
| -------- | --------- | -------- | ------------------------- |
| `length` | sentences | optional | 1 to 6 sentences (warn).  |
| `length` | words     | optional | At most 120 words (warn). |

```mdx
Against a commercial detector, the exposure cap costs about 6 dB, and with no pulse mode it loses to pulse detectors in the worst ground. The cure for the cliff is a ground balance that does not trust the reported height. It has not been written, so the moderate and severe figures stand as the forecast.
```

### list-item

Presents one of several parallel things for comparison or lookup.

**Use** One line of a bulleted or numbered list in the body.

**Avoid** An argument broken into bullets. A bold label and a colon in front of each item. Lists of one or two.

| Input    | Type  |          | Meaning                  |
| -------- | ----- | -------- | ------------------------ |
| `length` | words | optional | At most 30 words (warn). |

```mdx
S5 end-to-end link budget: detection depth by soil
```

### pull-quote

Shows a skimming reader the sentence the section turns on.

**Use** Display line set apart from the body, between paragraphs.

**Avoid** A line written for effect that the body does not contain. More than two in a piece. Aphorisms.

| Input    | Type      |          | Meaning                  |
| -------- | --------- | -------- | ------------------------ |
| `length` | sentences | optional | 1 to 2 sentences (warn). |
| `length` | words     | optional | At most 30 words (warn). |

```mdx
In moderate soil, 5 mm of error in the coil’s height costs a 1 g nugget 16 of its 21 centimetres.
```

### caption

Tells the reader what to see in the figure and what it cannot show.

**Use** Under or beside a figure, plate, chart or table; includes a figure's title.

**Avoid** Type labels and numbers: "Figure 3", "Diagram", "Chart". An opening "The" in a figure title. Repeating the paragraph beside it.

| Input    | Type      |          | Meaning                  |
| -------- | --------- | -------- | ------------------------ |
| `length` | sentences | optional | 1 to 2 sentences (warn). |
| `length` | words     | optional | At most 30 words (warn). |

```mdx
Five positions along one swing sight the same buried object. Not to scale.
```

### stat-value

Gives one number to a reader who looks at nothing else.

**Use** Large figure in a stat row, above its label.

**Avoid** Words where a number belongs. More significant figures than the method supports.

| Input    | Type       |          | Meaning                        |
| -------- | ---------- | -------- | ------------------------------ |
| `length` | characters | optional | At most 12 characters (error). |

```mdx
21 cm
```

### stat-label

Says what the number measures and under which conditions.

**Use** Small line with a stat value; the condition sits in a second line under it.

**Avoid** An opening "The". A label that needs the body to decode it. Verdicts.

| Input       | Type       |          | Meaning                        |
| ----------- | ---------- | -------- | ------------------------------ |
| `label`     | characters | optional | At most 24 characters (error). |
| `condition` | words      | optional | At most 12 words (warn).       |

```mdx
Depth, 1 g nugget
```

### table-header

Names what every cell beneath it holds, units included.

**Use** Top cell of a table column.

**Avoid** An opening "The". Sentences and questions. Abbreviations defined nowhere.

| Input    | Type       |          | Meaning                       |
| -------- | ---------- | -------- | ----------------------------- |
| `length` | characters | optional | At most 24 characters (warn). |
| `length` | words      | optional | At most 3 words (warn).       |

```mdx
Result
```

### table-cell

Holds one value for lookup and comparison down a column.

**Use** Body cell of a table.

**Avoid** Sentences with more than one clause. Labels inside the cell. Mixed units in one column.

| Input    | Type  |          | Meaning                  |
| -------- | ----- | -------- | ------------------------ |
| `length` | words | optional | At most 12 words (warn). |

```mdx
5 cm in moderate soil
```

### alt-text

Stands in for the image for a reader who cannot see it.

**Use** The alt attribute of an image; read aloud, and shown when the image fails.

**Avoid** Announcing the medium: "Image of", "Photo showing". Repeating the caption. Leaving it empty on an image that carries content.

| Input    | Type       |          | Meaning                       |
| -------- | ---------- | -------- | ----------------------------- |
| `length` | characters | optional | 20 to 150 characters (error). |

```mdx
Looking up through a dense Antarctic beech canopy, branches and moss-covered trunks closing out the sky.
```

### link-text

Tells the reader where the link goes before it is followed.

**Use** The words of a link, inside a sentence or a source list.

**Avoid** "Click here", "here", "this link", "read more". A bare URL in running prose. Whole sentences as links.

| Input    | Type       |          | Meaning                       |
| -------- | ---------- | -------- | ----------------------------- |
| `length` | words      | optional | 1 to 8 words (warn).          |
| `length` | characters | optional | At most 60 characters (warn). |

```mdx
drksci/vh-mdx
```

### summary

Lets a reader outside the site judge the piece from one line.

**Use** The description in frontmatter: search results, link previews, index cards.

**Avoid** Repeating the title. Calls to action. Keyword lists.

| Input    | Type       |          | Meaning                       |
| -------- | ---------- | -------- | ----------------------------- |
| `length` | characters | optional | 50 to 160 characters (error). |

```mdx
A metal-detecting instrument designed in five blocks. In simulation it finds a 1 g nugget 21 cm down in mild soil. None of it has been built.
```

### footnote

Lets a reader check a claim against where it came from.

**Use** End matter: a numbered note, or a line in the source list.

**Avoid** Argument that belongs in the body. A source with no date. Links with no description.

| Input    | Type  |          | Meaning                  |
| -------- | ----- | -------- | ------------------------ |
| `length` | words | optional | At most 40 words (warn). |

```mdx
Merrilea Price, paraphrased from ABC News, 17 Nov 2026
```

### code-comment

Tells the reader why a line is there, which the code cannot say.

**Use** Inside a code block printed in a piece.

**Avoid** Restating what the line does. Narration addressed to the reader. Commented-out code.

| Input   | Type       |          | Meaning                       |
| ------- | ---------- | -------- | ----------------------------- |
| `line`  | characters | optional | At most 80 characters (warn). |
| `block` | sentences  | optional | At most 2 sentences (warn).   |

```mdx
// Freeze the weights: a canceller left adapting removes targets too.
```

### resume-summary

Tells a screener in ten seconds what the person does and at what scale.

**Use** Top of the résumé, under the name and contact line.

**Avoid** Pronouns: "I", "my". Self-praise: "passionate", "results-driven", "proven track record". A list of tools.

| Input    | Type      |          | Meaning                   |
| -------- | --------- | -------- | ------------------------- |
| `length` | sentences | optional | 2 to 3 sentences (warn).  |
| `length` | words     | optional | At most 60 words (error). |

```mdx
Platform engineer with twelve years in payments infrastructure. Led the move of a card-processing core handling 3 million transactions a day, with no customer-facing outage. Looking for a staff role in reliability.
```

### resume-bullet

Gives an interviewer one checkable thing that was done and what it moved.

**Use** Under a role, three to five to a role.

**Avoid** "Responsible for" and other duties without outcomes. Pronouns. Two achievements joined in one bullet.

| Input    | Type      |          | Meaning                     |
| -------- | --------- | -------- | --------------------------- |
| `length` | sentences | optional | At most 1 sentences (warn). |
| `length` | words     | optional | 8 to 28 words (error).      |

```mdx
Cut settlement batch time from 4 h to 35 min by moving reconciliation to streaming, across 3 million daily transactions.
```

### letter-paragraph

Connects one need of the role to one piece of evidence.

**Use** Body of a cover or concierge letter; two to four to a letter.

**Avoid** Formal letter furniture and numbered bold headings. Enthusiasm with nothing attached to it. Retelling the résumé.

| Input    | Type      |          | Meaning                   |
| -------- | --------- | -------- | ------------------------- |
| `length` | sentences | optional | 2 to 4 sentences (warn).  |
| `length` | words     | optional | At most 80 words (error). |

```mdx
I think the role is mostly a migration problem with a reliability deadline attached. I ran one at about the same scale: 3 million transactions a day moved to a new core in nine months, with rollback rehearsed monthly. Happy to walk through what went wrong along the way.
```

### change-text

Tells a reviewer what changed, why, and how it was checked.

**Use** Commit subject and body, pull request description, changelog line.

**Avoid** "Various fixes", "updates", "misc". A walk through the diff, file by file. Praise for the change.

| Input     | Type       |          | Meaning                        |
| --------- | ---------- | -------- | ------------------------------ |
| `subject` | characters | optional | At most 72 characters (error). |
| `body`    | words      | optional | At most 120 words (warn).      |

```mdx
Add prose lint for MDX under content/
```

## Audit rules

Housekeeping rules; the full text is on the audit page.

| Id                        | Summary                                                                                                                                                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rule:raw-literal`        | A colour, size or spacing value written out in CSS or JSX outside the token files. An error in shared components, a warning in app shell files and in pieces.                                                                         |
| `rule:unused-token`       | A token that no stylesheet, component, piece or other token references. A warning for semantic and component tokens; a note for primitive scale steps.                                                                                |
| `rule:unused-component`   | A component exported from src/blocks that no other file imports, registers for MDX or uses. A barrel re-export does not count as a use.                                                                                               |
| `rule:unused-block`       | A block kind in the shared registry that no component declares as its `block`.                                                                                                                                                        |
| `rule:near-duplicate`     | Two component files, shared or in pieces, that export the same name stem (FigureCard, FigureCardV2) or whose source is at least 80% alike by three-token shingles.                                                                    |
| `rule:orphan-asset`       | A file under public/ or in a piece folder whose name appears in no source or content file.                                                                                                                                            |
| `rule:piece-boundary`     | A piece importing from another piece's folder, or any file outside a piece folder (shared code under src/, scripts) importing from it.                                                                                                |
| `rule:piece-override`     | A piece that redefines a shared token (--ds-_, --lk-_, --color-fd-_) or restyles a layout-kit class (.lk-_) in its own stylesheet. Figure tokens (--pl-\*) may be set only inside the piece's own \[data-piece] scope.                |
| `rule:figure-style`       | A stroke width, dash pattern, font size or hex colour written as a literal on an SVG element in a piece or in the plot kit. Drawings are SVG, and take pens, weights, dashes and type from the plot kit (PEN, WEIGHT, DASH, label).   |
| `rule:stale-generated`    | A generated file (token CSS and JSON, the reference pages under content/docs/system) that differs from what its generator writes now.                                                                                                 |
| `rule:stale-doc`          | A hand-written docs page whose `covers` files changed in git after the page did, that covers nothing, or that names a path no file matches. Generated pages are exempt. Skipped in a shallow clone and where there is no git history. |
| `rule:budget`             | A count over its budget in src/audit/config.ts: shared block kinds, tokens per tier, non-blank lines of bespoke code in one piece folder.                                                                                             |
| `rule:missing-spec`       | A shared block, layout or template with no spec in the catalog, or one missing its summary, use, avoid, inputs or example.                                                                                                            |
| `rule:compact-short-form` | A block set compact (its own `size="compact"`, or inside a Section that is) whose text field is declared `require` in its spec and has no short form.                                                                                 |

### raw-literal

A colour, size or spacing value written out in CSS or JSX outside the token files. An error in shared components, a warning in app shell files and in pieces.

**Use** Use a token. If none fits, add one to the theme file; in a piece, list what stays bespoke in its frontmatter with a reason.

```mdx
bun run audit  # reports raw-literal at error severity at most
```

### unused-token

A token that no stylesheet, component, piece or other token references. A warning for semantic and component tokens; a note for primitive scale steps.

**Use** Remove the token from every theme, or use it. Scale steps kept for completeness can stay.

```mdx
bun run audit  # reports unused-token at warn severity at most
```

### unused-component

A component exported from src/blocks that no other file imports, registers for MDX or uses. A barrel re-export does not count as a use.

**Use** Delete it, or register it in src/blocks/mdx.tsx if pieces should use it.

```mdx
bun run audit  # reports unused-component at warn severity at most
```

### unused-block

A block kind in the shared registry that no component declares as its `block`.

**Use** Remove the kind from BLOCKS, or declare it on the component that implements it.

```mdx
bun run audit  # reports unused-block at warn severity at most
```

### near-duplicate

Two component files, shared or in pieces, that export the same name stem (FigureCard, FigureCardV2) or whose source is at least 80% alike by three-token shingles.

**Use** Merge into one shared block. A bespoke component a second piece needs moves to the shared registry in that pull request.

```mdx
bun run audit  # reports near-duplicate at warn severity at most
```

### orphan-asset

A file under public/ or in a piece folder whose name appears in no source or content file.

**Use** Delete the file, or reference it from the piece that owns it.

```mdx
bun run audit  # reports orphan-asset at warn severity at most
```

### piece-boundary

A piece importing from another piece's folder, or any file outside a piece folder (shared code under src/, scripts) importing from it.

**Use** Move what is shared into src/blocks and register it; a piece imports only from its own folder and from shared code.

```mdx
bun run audit  # reports piece-boundary at error severity at most
```

### piece-override

A piece that redefines a shared token (--ds-_, --lk-_, --color-fd-_) or restyles a layout-kit class (.lk-_) in its own stylesheet. Figure tokens (--pl-\*) may be set only inside the piece's own \[data-piece] scope.

**Use** Change the token in the theme, or extend the shared block. A divergence that stays is listed in the piece's frontmatter with its reason.

```mdx
bun run audit  # reports piece-override at warn severity at most
```

### figure-style

A stroke width, dash pattern, font size or hex colour written as a literal on an SVG element in a piece or in the plot kit. Drawings are SVG, and take pens, weights, dashes and type from the plot kit (PEN, WEIGHT, DASH, label).

**Use** Use WEIGHT, DASH, PEN and label() from src/blocks/plot. For an intended difference, set the --pl-\* token inside the piece's \[data-piece] scope and list it under bespoke in the frontmatter.

```mdx
bun run audit  # reports figure-style at error severity at most
```

### stale-generated

A generated file (token CSS and JSON, the reference pages under content/docs/system) that differs from what its generator writes now.

**Use** Run the command named in the finding and commit the result. Never edit a generated file by hand.

```mdx
bun run audit  # reports stale-generated at error severity at most
```

### stale-doc

A hand-written docs page whose `covers` files changed in git after the page did, that covers nothing, or that names a path no file matches. Generated pages are exempt. Skipped in a shallow clone and where there is no git history.

**Use** Read the page against the changed files, correct what no longer holds, and commit the page. A page that needs no change is touched by a commit that says so.

```mdx
bun run audit  # reports stale-doc at warn severity at most
```

### budget

A count over its budget in src/audit/config.ts: shared block kinds, tokens per tier, non-blank lines of bespoke code in one piece folder.

**Use** Consolidate until the count is under budget. Raising a budget is an edit to src/audit/config.ts, argued in the pull request.

```mdx
bun run audit  # reports budget at error severity at most
```

### missing-spec

A shared block, layout or template with no spec in the catalog, or one missing its summary, use, avoid, inputs or example.

**Use** Add the spec beside the unit (src/blocks/kit/specs.ts for blocks, layout-docs.ts for layouts, `docs` on a template) and fill every field.

```mdx
bun run audit  # reports missing-spec at error severity at most
```

### compact-short-form

A block set compact (its own `size="compact"`, or inside a Section that is) whose text field is declared `require` in its spec and has no short form.

**Use** Give the field a short form: `\{ full, short \}` on a prop, or `short` for a quote.

```mdx
bun run audit  # reports compact-short-form at warn severity at most
```

## Résumé commands

Commands of the résumé command bar.

| Id                   | Summary                                                          |
| -------------------- | ---------------------------------------------------------------- |
| `command:letter`     | Show, hide or reset the letter                                   |
| `command:concierge`  | Show or hide the recruiter introduction                          |
| `command:variant`    | Open a variant of this résumé                                    |
| `command:go`         | Scroll to a section                                              |
| `command:print`      | Print, or save as PDF                                            |
| `command:md`         | Copy the résumé as Markdown                                      |
| `command:transcript` | Show or hide the plain-text transcript                           |
| `command:readme`     | Show or hide the README.TXT                                      |
| `command:theme`      | Set the colour theme                                             |
| `command:drafts`     | Show or hide the unpublished drafts                              |
| `command:share`      | Make a share link and copy it; --revoke \<id> for how to end one |
| `command:signout`    | End the owner session                                            |
| `command:help`       | List the commands                                                |

### letter

Show, hide or reset the letter

```mdx
/letter [on|off|reset]
```

### concierge

Show or hide the recruiter introduction

```mdx
/concierge [on|off]
```

### variant

Open a variant of this résumé

```mdx
/variant <slug>
```

### go

Scroll to a section

```mdx
/go <section>
```

### print

Print, or save as PDF

```mdx
/print
```

### md

Copy the résumé as Markdown

```mdx
/md
```

### transcript

Show or hide the plain-text transcript

```mdx
/transcript [on|off]
```

### readme

Show or hide the README.TXT

```mdx
/readme [on|off]
```

### theme

Set the colour theme

```mdx
/theme [light|dark|system]
```

### drafts

Show or hide the unpublished drafts

```mdx
/drafts [on|off]
```

### share

Make a share link and copy it; --revoke \<id> for how to end one

```mdx
/share [variant] [letter] --to "<label>" [--days N] [--for <app>]
```

### signout

End the owner session

```mdx
/signout
```

### help

List the commands

```mdx
/help
```

## Scripts

Package scripts.

| Id                     | Summary                                                                                                                                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `script:build`         | Production build of the site; has no side effects.                                                                                                                                                |
| `script:dev`           | Development server.                                                                                                                                                                               |
| `script:start`         | Serve the production build.                                                                                                                                                                       |
| `script:lint`          | Biome lint and format check.                                                                                                                                                                      |
| `script:format`        | Biome format, writing changes.                                                                                                                                                                    |
| `script:typecheck`     | Generate Next.js types, then tsc with no emit.                                                                                                                                                    |
| `script:test`          | Unit tests (bun test).                                                                                                                                                                            |
| `script:lint:prose`    | Writing-guide rules over MDX in content/.                                                                                                                                                         |
| `script:gen:writing`   | Regenerate /docs/system/writing from src/writing/guide.ts.                                                                                                                                        |
| `script:gen:tokens`    | Regenerate token CSS and JSON from the theme files.                                                                                                                                               |
| `script:gen:reference` | Regenerate the MCP, audit and discovery reference pages.                                                                                                                                          |
| `script:audit`         | Housekeeping audit; --json prints the report as data.                                                                                                                                             |
| `script:gen:catalog`   | Regenerate /docs/system/catalog from the specs.                                                                                                                                                   |
| `script:check:slots`   | Render every kit block in narrow, medium and wide slots at each size against a built site; fails on overflow, clipped text or one-word headings.                                                  |
| `script:check:links`   | Check every internal link in the docs, pieces and résumé against the route inventory, headings and figure anchors, and fail on an alias; given an origin, also the links in a built site's pages. |
| `script:check`         | Typecheck, lint, test, prose lint, audit and link check; what CI runs.                                                                                                                            |

### build

Production build of the site; has no side effects.

```mdx
bun run build
```

### dev

Development server.

```mdx
bun run dev
```

### start

Serve the production build.

```mdx
bun run start
```

### lint

Biome lint and format check.

```mdx
bun run lint
```

### format

Biome format, writing changes.

```mdx
bun run format
```

### typecheck

Generate Next.js types, then tsc with no emit.

```mdx
bun run typecheck
```

### test

Unit tests (bun test).

```mdx
bun run test
```

### lint:prose

Writing-guide rules over MDX in content/.

```mdx
bun run lint:prose
```

### gen:writing

Regenerate /docs/system/writing from src/writing/guide.ts.

```mdx
bun run gen:writing
```

### gen:tokens

Regenerate token CSS and JSON from the theme files.

```mdx
bun run gen:tokens
```

### gen:reference

Regenerate the MCP, audit and discovery reference pages.

```mdx
bun run gen:reference
```

### audit

Housekeeping audit; --json prints the report as data.

```mdx
bun run audit
```

### gen:catalog

Regenerate /docs/system/catalog from the specs.

```mdx
bun run gen:catalog
```

### check:slots

Render every kit block in narrow, medium and wide slots at each size against a built site; fails on overflow, clipped text or one-word headings.

```mdx
bun run check:slots
```

### check:links

Check every internal link in the docs, pieces and résumé against the route inventory, headings and figure anchors, and fail on an alias; given an origin, also the links in a built site's pages.

```mdx
bun run check:links
```

### check

Typecheck, lint, test, prose lint, audit and link check; what CI runs.

```mdx
bun run check
```