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. |
<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. |
<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. |
<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 |
<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 |
<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 |
<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. |
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. |
<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. |
<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 |
<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 |
<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 |
<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 |
<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 |
<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. |
<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 |
<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. |
<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. |
<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. |
<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. |
<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 |
<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 |
<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 |
<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 |
<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 |
<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 |
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 |
<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. |
<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. |
<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. |
<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. |
<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. |
<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. |
<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. |
<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. |
<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. |
<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. |
---
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. |
---
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. |
<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. |
<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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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. |
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). |
{ 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. |
<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.
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.
import { Chips } from "@/blocks/plot";Stops
Accessible name of the group.
Use Drawing figures in the house style; import from @/blocks/plot.
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.
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.
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.
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.
import { PEN_CYCLE } from "@/blocks/plot";WEIGHT
Line weights and dash patterns.
Use Drawing figures in the house style; import from @/blocks/plot.
import { WEIGHT } from "@/blocks/plot";DASH
Exported by the plot kit (kit.tsx).
Use Drawing figures in the house style; import from @/blocks/plot.
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.
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.
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.
import { OVERPRINT } from "@/blocks/plot";f1
Exported by the plot kit (kit.tsx).
Use Drawing figures in the house style; import from @/blocks/plot.
import { f1 } from "@/blocks/plot";path
Exported by the plot kit (kit.tsx).
Use Drawing figures in the house style; import from @/blocks/plot.
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.
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.
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.
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.
import { HATCHES } from "@/blocks/plot";hatch
Exported by the plot kit (kit.tsx).
Use Drawing figures in the house style; import from @/blocks/plot.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
import { scatter } from "@/blocks/plot";linear
Exported by the plot kit (scale.ts).
Use Drawing figures in the house style; import from @/blocks/plot.
import { linear } from "@/blocks/plot";log
Exported by the plot kit (scale.ts).
Use Drawing figures in the house style; import from @/blocks/plot.
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.
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.
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.
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.
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.
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.
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.
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). |
Goldraydeck
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). |
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). |
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). |
Nineteen minutes over the Topssub-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). |
Kernel lifecyclebody
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). |
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). |
S5 end-to-end link budget: detection depth by soilpull-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). |
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). |
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). |
21 cmstat-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). |
Depth, 1 g nuggettable-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). |
Resulttable-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). |
5 cm in moderate soilalt-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). |
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). |
drksci/vh-mdxsummary
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). |
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). |
Merrilea Price, paraphrased from ABC News, 17 Nov 2026code-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). |
// 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). |
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). |
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). |
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). |
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.
bun run audit # reports raw-literal at error severity at mostunused-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.
bun run audit # reports unused-token at warn severity at mostunused-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.
bun run audit # reports unused-component at warn severity at mostunused-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.
bun run audit # reports unused-block at warn severity at mostnear-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.
bun run audit # reports near-duplicate at warn severity at mostorphan-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.
bun run audit # reports orphan-asset at warn severity at mostpiece-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.
bun run audit # reports piece-boundary at error severity at mostpiece-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.
bun run audit # reports piece-override at warn severity at mostfigure-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.
bun run audit # reports figure-style at error severity at moststale-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.
bun run audit # reports stale-generated at error severity at moststale-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.
bun run audit # reports stale-doc at warn severity at mostbudget
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.
bun run audit # reports budget at error severity at mostmissing-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.
bun run audit # reports missing-spec at error severity at mostcompact-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.
bun run audit # reports compact-short-form at warn severity at mostRé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
/letter [on|off|reset]concierge
Show or hide the recruiter introduction
/concierge [on|off]variant
Open a variant of this résumé
/variant <slug>go
Scroll to a section
/go <section>Print, or save as PDF
/printmd
Copy the résumé as Markdown
/mdtranscript
Show or hide the plain-text transcript
/transcript [on|off]readme
Show or hide the README.TXT
/readme [on|off]theme
Set the colour theme
/theme [light|dark|system]drafts
Show or hide the unpublished drafts
/drafts [on|off]share
Make a share link and copy it; --revoke <id> for how to end one
/share [variant] [letter] --to "<label>" [--days N] [--for <app>]signout
End the owner session
/signouthelp
List the commands
/helpScripts
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.
bun run builddev
Development server.
bun run devstart
Serve the production build.
bun run startlint
Biome lint and format check.
bun run lintformat
Biome format, writing changes.
bun run formattypecheck
Generate Next.js types, then tsc with no emit.
bun run typechecktest
Unit tests (bun test).
bun run testlint:prose
Writing-guide rules over MDX in content/.
bun run lint:prosegen:writing
Regenerate /docs/system/writing from src/writing/guide.ts.
bun run gen:writinggen:tokens
Regenerate token CSS and JSON from the theme files.
bun run gen:tokensgen:reference
Regenerate the MCP, audit and discovery reference pages.
bun run gen:referenceaudit
Housekeeping audit; --json prints the report as data.
bun run auditgen:catalog
Regenerate /docs/system/catalog from the specs.
bun run gen:catalogcheck: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.
bun run check:slotscheck: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.
bun run check:linkscheck
Typecheck, lint, test, prose lint, audit and link check; what CI runs.
bun run check