Skip to Content
drksci
System

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.

IdSummary
block:ProseRunning text; bare Markdown inside a Section is wrapped in one.
block:LeadThe paragraph that opens a part, one size up from body.
block:KickerA short marker set above a heading, such as a part number.
block:SegueThe sentence that hands one part to the next.
block:ColophonMethod and provenance, set small in mono.
block:FigureAn image or drawing with an optional title, caption and credit; an image opens in a viewer.
block:RefAn inline reference to a numbered figure: renders Figure 3 and links to it.
block:SidebarA boxed aside for a self-contained explanation, set off by a tone and space, not a border.
block:PieceCardA piece as a chip, a card or a lead, read from its frontmatter; never shown on the piece itself.
block:LiveAn interactive figure: a client component with a heading and caption.
block:StatOne headline number with its label and the condition it holds under.
block:PullQuoteA line lifted from the text, set large.
block:NoteA margin note, set beside the paragraph it follows.
block:TableA table on the wide column that scrolls sideways when it cannot fit.
block:PanelsA row of short definitions, as many columns as fit.
block:PanelOne term and its definition inside Panels.
block:FormulaA display formula in TeX, set by KaTeX; it scrolls inside its own box rather than widening the page.
block:SectionThe unit of an article: reads its children and picks a layout.
block:ChapterA run of sections that belong together, set a break apart.
block:ArticleThe grid every section sits on, where the rhythm rules run.
block:PrintoutA tractor-feed listing: dot-matrix type on banded stock with a perforated margin, for tables, logs and ledgers.
block:PlotterA frame that sets a figure on plotter paper: registration marks at the corners and a legend of the pens that drew it.
block:ConsoleA terminal frame in phosphor ink for transcripts and interactives; the same screen in light and dark.
block:DialogueA 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:WindowA grey title-bar frame in the early-Macintosh manner, for content that is an interface: a form, a readout, a small panel.
block:PlayerThe one frame of everything that plays or responds: a stage, three floating bars (top, bottom, left) and panels below.
block:FrameThe 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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
childrenReactNodeoptionalMarkdown.
dropcapbooleanoptionalSet 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.
SizeShows
compactHyphenation on; all text kept.
normalShows everything; nothing in it is secondary, so only type hyphenation changes.
expandedShows 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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
childrenReactNodeoptionalOne or two paragraphs.
SizeShows
compactFirst paragraph only; hyphenation on.
normalEvery paragraph.
expandedEvery paragraph.
TextShort formWithout one
childrennonedrop: 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.

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
childrenReactNodeoptionalThe marker.
SizeShows
compactShows everything; nothing in it is secondary, so only type hyphenation changes.
normalShows everything; nothing in it is secondary, so only type hyphenation changes.
expandedShows 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.

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
shortReactNodeoptionalA shorter hand-off for compact.
childrenReactNodeoptionalOne sentence.
SizeShows
compactShort form, else cut at two lines.
normalFull text.
expandedFull text.
TextShort formWithout one
childrenacceptedclamp, 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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
shortReactNodeoptionalA shorter statement of method for compact.
childrenReactNodeoptionalMethod and sources.
SizeShows
compactShort form, else cut at three lines.
normalFull text.
expandedFull text.
TextShort formWithout one
childrenacceptedclamp, 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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
srcstringoptionalImage source.
altstringoptionalAlt text.
titlestring | { full, short }optionalA statement of what the figure shows, set above the media.
captionstring | { full, short }optionalWhat to see; one or two sentences.
creditReactNodeoptionalProvenance; dropped in compact.
ratio'square' | 'tall' | 'classic' | 'wide' | 'plate'optionalAspect ratio of the media box.
zoombooleanoptionalOpen 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.
childrenReactNodeoptionalCustom media; it sets its own height.
idstringoptionalAnchor, so a Ref can point at the figure.
captionAt'below' | 'margin'optionalWhere 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.
numbernumber | stringoptionalSet at compile time from the figure's place among the captioned figures of the piece; do not write it.
SizeShows
compactMedia and a short title or caption; credit dropped.
normalTitle, media, caption and credit.
expandedAs normal, with title and caption one step larger.
TextShort formWithout one
titleacceptedclamp, 2 lines
captionacceptedclamp, 3 lines
creditnonedrop
<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.

InputTypeMeaning
tostringrequiredThe id of the Figure.
numbernumber | stringoptionalSet at compile time; do not write it.
childrenReactNodeoptionalReplaces the default text.
See <Ref to="drift" />.

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

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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
titlestring | { full, short }optionalWhat the box explains; cut at two lines.
childrenReactNodeoptionalA few short paragraphs.
SizeShows
compactTitle and first paragraph; later paragraphs dropped.
normalTitle and every paragraph.
expandedAs normal, with the title one step larger.
TextShort formWithout one
titleacceptedclamp, 2 lines
childrennonedrop: 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

InputTypeMeaning
slugstringoptionalThe piece's slug, as in its path. Give this or card.
cardCardDataoptionalInstead 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'optionalcompact 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.
level2 | 3optionalHeading level of the title: 2 under a page title, 3 inside a section (the default).
SizeShows
compactChip: the short title (card.title, else title) and kind, linking to the piece; inline.
normalCard: thumbnail, kind and date, title, one line (card.line, else the deck), optional stat, up to three tags.
expandedLead: large thumbnail beside the title, the whole deck and the date.
TextShort formWithout one
titleacceptedabbreviate: A chip uses frontmatter card.title; without one, the title.
lineacceptedabbreviate: 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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
titlestring | { full, short }requiredWhat the interaction is.
captionstring | { full, short }optionalWhat to try.
creditReactNodeoptionalProvenance; dropped in compact.
childrenReactNodeoptionalThe client component.
SizeShows
compactMedia and the short title; caption cut, credit dropped.
normalTitle, media, caption and credit.
expandedAs normal, with title and caption one step larger.
TextShort formWithout one
titleacceptedrequire
captionacceptedclamp, 3 lines
creditnonedrop
<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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
valuestring | { full, short }requiredThe number with its unit.
labelstring | { full, short }requiredWhat it measures.
notestring | { full, short }optionalThe condition or source.
SizeShows
compactShort forms; label cut at two lines, note at three.
normalValue, label and note.
expandedAs normal, with label and note one step larger.
TextShort formWithout one
valueacceptedabbreviate: Type scales with the container from the stat size down to body size; a list is broken only at ' · ', never inside a value.
labelacceptedclamp, 2 lines
noteacceptedclamp, 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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
citeReactNodeoptionalAttribution; dropped in compact.
shortReactNodeoptionalA shorter quote for compact.
childrenReactNodeoptionalThe quote.
SizeShows
compactShort quote only, no attribution.
normalQuote and attribution.
expandedQuote and attribution.
TextShort formWithout one
childrenacceptedrequire
citenonedrop
<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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
shortReactNodeoptionalA shorter note for compact.
childrenReactNodeoptionalThe note.
SizeShows
compactShort form, else cut at four lines.
normalFull text.
expandedFull text, body-size type.
TextShort formWithout one
childrenacceptedclamp, 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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
titlestring | { full, short }optionalA statement of what the table shows, set above it; cut at two lines.
captionstring | { full, short }optionalWhat the table shows; dropped in compact.
childrenReactNodeoptionalA Markdown table.
SizeShows
compactTable and a short title; caption dropped unless it has a short form.
normalTitle, table and caption.
expandedAs normal, with the title and caption one step larger.
TextShort formWithout one
titleacceptedclamp, 2 lines
captionaccepteddrop
<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

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
childrenReactNodeoptionalPanel elements.
SizeShows
compactTerms cut at two lines, definitions at four.
normalTerm and definition.
expandedTerm 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.

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
termstring | { full, short }requiredThe term.
linesnumberoptionalLines of the definition shown before it is cut; four unless a longer one must read whole.
childrenReactNodeoptionalIts definition.
SizeShows
compactShort term, else two lines; definition cut at four.
normalTerm and definition.
expandedTerm and definition, definition one step larger.
TextShort formWithout one
termacceptedclamp, 2 lines
childrennoneclamp, 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.

InputTypeMeaning
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
texstringoptionalThe 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.
narrowstringoptionalThe same equation broken over lines (an aligned block), shown where the block is narrower than 40rem.
childrenReactNodeoptionalTeX as a string, or $$ … $$ blocks.
SizeShows
compactShows everything; nothing in it is secondary, so only type hyphenation changes.
normalShows everything; nothing in it is secondary, so only type hyphenation changes.
expandedShows 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

InputTypeMeaning
layoutLayoutNameoptionalOverride the picked layout.
side'start' | 'end'optionalSide of a spread's figure.
size'compact' | 'normal' | 'expanded'optionalForce a size on every block inside that has none.
captions'below' | 'margin'optionalWhere figure captions sit unless a figure says otherwise; margin takes effect in a column section.
idstringoptionalAnchor.
childrenReactNodeoptionalBlocks 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.

InputTypeMeaning
idstringoptionalAnchor.
childrenReactNodeoptionalSections.
<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.

InputTypeMeaning
childrenReactNodeoptionalSections 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

InputTypeMeaning
titlestring | { full, short }optionalThe listing's name, on its first line.
columns{ key, label, align?, detail?, sub?, stub?, edge?, mark? }[]optionalTable 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.
rowsRecord<string, ReactNode>[]optionalTable 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.
labelstringoptionalNames the scrolling listing for assistive tech and makes it reachable by keyboard.
activenumber | nulloptionalTable mode: the column held under the pointer, or shared with a chart beside it.
onActive(column: number | null) => voidoptionalTable mode: told which column the pointer is over; null when it leaves. Needs a client parent.
childrenReactNodeoptionalLog mode: pre-formatted lines.
notestringoptionalCondition or source under the listing. Dropped in compact.
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
SizeShows
compactDetail columns and the note are dropped; the title is clamped.
normalEvery column, the note and both feed margins.
expandedAs normal.
TextShort formWithout one
titleacceptedclamp, 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

InputTypeMeaning
titlestring | { full, short }optionalWhat the sheet shows, as a statement.
pens{ pen, label, dash? }[]optionalPens used, from ink, pink, blue, teal, amber and violet, with a dash from solid, dot, short and long.
captionstring | { full, short }optionalOne or two sentences under the sheet.
childrenReactNodeoptionalThe figure.
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
SizeShows
compactThe legend is dropped; marks, figure and caption stay.
normalMarks, title, figure, legend and caption.
expandedAs normal.
TextShort formWithout one
captionacceptedclamp, 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

InputTypeMeaning
titlestring | { full, short }optionalThe session's name, in the top line.
linesstring[]optionalTranscript lines; one starting $ or \> is typed input.
childrenReactNodeoptionalAnything else on the screen.
scanlinesbooleanoptionalDraw scanlines. Off by default.
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
SizeShows
compactThe title is clamped to one line.
normalTitle, transcript and cursor.
expandedAs normal.
TextShort formWithout one
titleacceptedclamp, 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

InputTypeMeaning
titlestring | { full, short }optionalThe session's name, in the screen's top line.
rounds{ situation, sides?, models?, turns, parallel?, outcome? }[]requiredThe rounds, each with turns of \{ side, model?, text \} where side is hider, seeker or harness.
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
SizeShows
compactThe title is clamped to one line; the transcript is as normal.
normalTitle, rounds, speaker labels and outcomes.
expandedAs normal.
TextShort formWithout one
titleacceptedclamp, 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

InputTypeMeaning
titlestring | { full, short }requiredThe title bar's text.
statusstringoptionalA status line under the content. Dropped in compact.
childrenReactNodeoptionalWhat the window holds.
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the block picks from its container's width.
SizeShows
compactThe status line is dropped; the title is clamped to one line.
normalTitle bar, content and status line.
expandedAs normal.
TextShort formWithout one
titleacceptedclamp, 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

InputTypeMeaning
childrenReactNoderequiredThe stage: SVG, canvas or DOM. The player never draws it.
titlestring | { full, short }optionalStart of the top bar; leave out when the frame's heading already says it.
labelstringrequiredWhat the stage is, for assistive technology.
readoutReactNodeoptionalThe current time, date or scene, in the top bar. A polite live region repeats it, not every frame.
readoutTextstringoptionalThe readout as plain text, when it is not a string.
transportTransportoptionalPresent: 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? }optionalScenes 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.
controlsControl[]optionalEvery control as data: { id, kind, label, where: 'top' | 'bottom' | 'left' | 'panel', ... }.
set(id, value) => voidoptionalReceives a control's value when it has no onChange.
panels{ id, title, children, open? }[]optionalStacked below the stage (a right-hand column when expanded): legend, ticker, scoreboard, notes. Each collapses.
onReset() => voidoptionalPresent: a reset button in the top bar.
fullscreenbooleanoptionalThe full screen button and the F key. Default true.
float'inset' | 'overlay'optionalinset (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.
autoHidebooleanoptionalOverlay only: bars hide while playing and return on pointer, focus or pause. Never under reduced motion or on touch.
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the player picks from its own width; full screen is expanded.
focusablebooleanoptionalMake the stage a tab stop (default). Off when it has its own.
onKeyDown(e: KeyboardEvent) => voidoptionalKeys the figure handles itself; call preventDefault to keep the player's map out.
onFullChange(full: boolean) => voidoptionalCalled when full screen starts or ends, for a figure whose input differs there.
stageRefRef<HTMLDivElement>optionalThe stage element, for a figure that measures or draws into it.
hostRefMutableRefObject<HTMLDivElement | null>optionalThe player's outermost element, for a figure that watches it.
idstringoptionalAnchor.
SizeShows
compactPlay and scrub (and scene previous and next); tools fold into a menu; panels become one disclosure list, closed; short labels.
normalAll three bars, scene tabs, step, rate and loop; panels stacked below, open.
expandedFull screen (or forced): as normal, panels in a right-hand column.
TextShort formWithout one
titleacceptedclamp, 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

InputTypeMeaning
titlestring | { full, short }requiredWhat the interaction is. Compact refuses it without a short form.
captionstring | { full, short }optionalWhat to try.
creditReactNodeoptionalProvenance; dropped in compact.
childrenReactNodeoptionalThe player or interactive.
size'compact' | 'normal' | 'expanded'optionalForce a size. Unset, the player picks from its own width; full screen is expanded.
SizeShows
compactMedia and the short title; caption cut, credit dropped.
normalTitle, media, caption and credit.
expandedAs normal, with title and caption one step larger.
TextShort formWithout one
titleacceptedrequire
captionacceptedclamp, 3 lines
creditnonedrop
<Frame title={{ full: "Drive the reservoir", short: "Reservoir" }}><MyPlayer /></Frame>

Layouts

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

IdSummary
layout:openerFirst section of an article: prose, with at most one figure.
layout:columnProse alone, or prose mixed with several other blocks.
layout:spreadProse with exactly one figure, live block or sidebar (a sidebar beside the text).
layout:plateA single figure or live block and nothing else.
layout:galleryTwo or more figures and nothing else.
layout:stat-rowTwo or more stats and nothing else.
layout:marginProse with one or more notes.
layout:columnsNever picked from contents; set with layout="columns" on a run of long prose.
layout:closerLast 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.

InputTypeMeaning
layout"opener"optionalOn 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.

InputTypeMeaning
layout"column"optionalOn 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.

InputTypeMeaning
layout"spread"optionalOn 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.

InputTypeMeaning
layout"plate"optionalOn a Section; left out, the section picks this layout when its contents match.
<Section>

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

</Section>

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.

InputTypeMeaning
layout"gallery"optionalOn 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.

InputTypeMeaning
layout"stat-row"optionalOn 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.

InputTypeMeaning
layout"margin"optionalOn 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.

InputTypeMeaning
layout"columns"optionalOn 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.

InputTypeMeaning
layout"closer"optionalOn 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.

IdSummary
template:featureLong-form research feature, told in parts.
template:write-upLabs write-up: the feature opener family, shorter and more practical, with status and stack as a compact facts row.
template:indexThe shelf of one kind: a standing line, the newest piece as the lead, the rest as an ordered grid of cards.
template:landingThe 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.

InputTypeMeaning
kindsstring[]requiredPiece kinds that use it: research.
shellobjectrequiredTable 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.

InputTypeMeaning
kindsstring[]requiredPiece kinds that use it: labs.
shellobjectrequiredTable 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.

InputTypeMeaning
kindsstring[]requiredPiece kinds that use it: .
shellobjectrequiredTable 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.

InputTypeMeaning
kindsstring[]requiredPiece kinds that use it: .
shellobjectrequiredTable of contents off, full width, plain masthead.
<Landing />

Token groups

Design tokens by group, from the default theme.

IdSummary
token:spaceSpace scale (primitive tier, 8 tokens).
token:stepType scale (primitive tier, 8 tokens).
token:fontFont families (primitive tier, 3 tokens).
token:type-detailLeading, weight and tracking (primitive tier, 8 tokens).
token:measureMeasures (primitive tier, 5 tokens).
token:shapeRadii and ratios (primitive tier, 7 tokens).
token:lineLine weights (primitive tier, 2 tokens).
token:penPlotter pens (primitive tier, 6 tokens).
token:colorColour roles (semantic tier, 9 tokens).
token:textText roles (semantic tier, 8 tokens).
token:gapSpacing roles (semantic tier, 6 tokens).
token:lk-gridLayout kit: grid and rhythm (component tier, 8 tokens).
token:lk-minLayout kit: minimum useful widths (component tier, 6 tokens).
token:lk-blockLayout kit: blocks (component tier, 19 tokens).
token:pcPiece page: contents rail (component tier, 1 tokens).
token:plPlot kit (component tier, 26 tokens).
token:pvPlayer (component tier, 7 tokens).
token:sfSurface blocks (component tier, 5 tokens).
token:ogSocial 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.

IdSummary
figure:usePlaybackThe one playback clock: play, pause, toggle, step, seek, rate, loop, range and tick count, driven from animation frames.
figure:ControlA control declared as data: slider, stepper, chips, toggle, select, button, or a custom render.
figure:SessionEmbedA self-contained recorded session set into a piece as a lazy iframe that plays while on screen and pauses when it leaves.
figure:BAKEDThe default theme's palette as a figure generator bakes it into an SVG, and the token each colour stands for.
figure:ChipsA row of toggle buttons choosing one of a few states.
figure:StopsAccessible name of the group.
figure:FlowFigureFlow diagrams: boxes placed by hand, wires routed at right angles from one side of a box to a side of another.
figure:panelGridLayout for a row of small-multiple panels: one column when narrow, two otherwise.
figure:useFigureClockOne frame clock per figure, for drawings that move by themselves.
figure:PEN_CYCLEThe plot kit: what every drawn figure shares.
figure:WEIGHTLine weights and dash patterns.
figure:DASHExported by the plot kit (kit.tsx).
figure:SIZEText sizes, in viewBox units (user space, so the text scales with the drawing).
figure:SIZE_PXThe same steps as plain numbers, for layout arithmetic (how wide a label is, how far apart wrapped lines sit).
figure:OVERPRINTCrossing pens mix as ink on paper (or as light, in the dark theme).
figure:f1Exported by the plot kit (kit.tsx).
figure:pathExported by the plot kit (kit.tsx).
figure:ditherDefsSeventeen ordered-dither patterns for one pen, ids $\{prefix\}-0 … -16.
figure:ditherFillPattern fill for a magnitude in [0, 1]; null when it dithers to paper.
figure:HATCH_PENDiagonal pen strokes in a series' own colour, for areas and bars.
figure:HATCHESExported by the plot kit (kit.tsx).
figure:hatchExported by the plot kit (kit.tsx).
figure:toneFill for a magnitude in [0, 1], or "none" when it dithers to paper.
figure:dotsThe dotted field a frame sits on; opacity for a darker field.
figure:labelKnock the paper out behind the text so it reads over line work.
figure:edgeAnchorAdvance of one character of the kit's mono face at the base size, in drawing units.
figure:fitLinesAdvance of one character when the label is not at the base size.
figure:frameFrame on a dotted field, with ticks and optional axis labels.
figure:penAreaWidth of the drawing: labels that would pass its edge are kept inside.
figure:PlotSvgLine weight (a WEIGHT step); null draws the band and hatching only.
figure:wrapOne numbered entry of a figure's key: a short name and a plain gloss.
figure:notesThe 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:withNotesFinish 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:legendRowOne legend entry: a pen, its name, and an optional dash for a dashed line.
figure:legendColA legend in one column on a paper patch, so it can sit over line work.
figure:useUidA DOM-safe unique id for the patterns and clips inside one plate.
figure:plateSvgThe drawing surface of a hand-drawn plate: an accessible SVG that fills its column.
figure:DotsA regular dot field, as a pattern to fill tone with.
figure:PlateOfA hand-drawn plate: a component that takes its accessible name as title.
figure:scattern seeded points in the unit square, the same on every render, for marks scattered over a plate.
figure:linearExported by the plot kit (scale.ts).
figure:logExported by the plot kit (scale.ts).
figure:useTickSubscribe a frame callback to the enclosing figure's clock while it runs.
figure:FigureShellThe 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_MONOSpaced capitals in the mono face: the label voice of a hand-drawn plate.
figure:PLATE_NOTESmall plain mono, for notes on a plate.
figure:TagA mono label on a paper patch, so it reads over line work.
figure:yTicksOne axis tick as frame() takes it: the value, its position, its text.
figure:xTicksX-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.

InputTypeMeaning
hostRefObject<HTMLElement>requiredThe element whose visibility gates the clock.
maxnumberrequiredEnd of the range, in the figure's units.
minnumberoptionalStart of the range. Default 0.
stepnumberoptionalStep and scrub granularity; 0 is continuous.
perSecondnumberoptionalUnits per second at rate 1. Default 1.
autoplaybooleanoptionalPlay when first on screen; never under reduced motion.
onFrame(t: number) => voidoptionalCalled 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.

InputTypeMeaning
idstringrequiredUnique in the player; the name set(id, value) receives.
kind'slider' | 'stepper' | 'chips' | 'toggle' | 'select' | 'button' | 'custom'requiredWhich control.
labelstring | { full, short }requiredThe accessible name; the short form shows in a tight bar.
where'top' | 'bottom' | 'left' | 'panel'requiredWhich bar or the parameters panel draws it.
valuenumber | string | booleanoptionalThe current value, by kind. A button has onPress instead.
onChange(value) => voidoptionalOr the player's set(id, value).
targetstring | { full, short }optionalWhat 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'.
tabsbooleanoptionalChips 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.

InputTypeMeaning
srcstringrequiredPath of the player's page, under public/.
titlestringrequiredThe 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.

IdSummary
element:titleTells a reader scanning a list which subject this is.
element:deckLets a reader decide whether to read on, without the body.
element:ledeGives the finding and its conditions to a reader who stops here.
element:section-headingLets a reader find a part of the argument from the contents list.
element:sub-headingMarks a change of subject within a section.
element:bodyCarries the argument: mechanism, then numbers with their conditions.
element:list-itemPresents one of several parallel things for comparison or lookup.
element:pull-quoteShows a skimming reader the sentence the section turns on.
element:captionTells the reader what to see in the figure and what it cannot show.
element:stat-valueGives one number to a reader who looks at nothing else.
element:stat-labelSays what the number measures and under which conditions.
element:table-headerNames what every cell beneath it holds, units included.
element:table-cellHolds one value for lookup and comparison down a column.
element:alt-textStands in for the image for a reader who cannot see it.
element:link-textTells the reader where the link goes before it is followed.
element:summaryLets a reader outside the site judge the piece from one line.
element:footnoteLets a reader check a claim against where it came from.
element:code-commentTells the reader why a line is there, which the code cannot say.
element:resume-summaryTells a screener in ten seconds what the person does and at what scale.
element:resume-bulletGives an interviewer one checkable thing that was done and what it moved.
element:letter-paragraphConnects one need of the role to one piece of evidence.
element:change-textTells 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.

InputTypeMeaning
lengthcharactersoptionalAt most 60 characters (error).
lengthwordsoptionalAt most 8 words (warn).
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.

InputTypeMeaning
lengthsentencesoptional1 to 3 sentences (warn).
lengthwordsoptionalAt 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.

InputTypeMeaning
lengthsentencesoptional2 to 3 sentences (warn).
lengthwordsoptionalAt 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.

InputTypeMeaning
lengthcharactersoptionalAt most 48 characters (error).
lengthwordsoptionalAt most 7 words (warn).
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.

InputTypeMeaning
lengthcharactersoptionalAt most 40 characters (error).
lengthwordsoptionalAt most 5 words (warn).
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.

InputTypeMeaning
lengthsentencesoptional1 to 6 sentences (warn).
lengthwordsoptionalAt 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.

InputTypeMeaning
lengthwordsoptionalAt most 30 words (warn).
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.

InputTypeMeaning
lengthsentencesoptional1 to 2 sentences (warn).
lengthwordsoptionalAt 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.

InputTypeMeaning
lengthsentencesoptional1 to 2 sentences (warn).
lengthwordsoptionalAt 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.

InputTypeMeaning
lengthcharactersoptionalAt most 12 characters (error).
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.

InputTypeMeaning
labelcharactersoptionalAt most 24 characters (error).
conditionwordsoptionalAt most 12 words (warn).
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.

InputTypeMeaning
lengthcharactersoptionalAt most 24 characters (warn).
lengthwordsoptionalAt most 3 words (warn).
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.

InputTypeMeaning
lengthwordsoptionalAt most 12 words (warn).
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.

InputTypeMeaning
lengthcharactersoptional20 to 150 characters (error).
Looking up through a dense Antarctic beech canopy, branches and moss-covered trunks closing out the sky.

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.

InputTypeMeaning
lengthwordsoptional1 to 8 words (warn).
lengthcharactersoptionalAt most 60 characters (warn).
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.

InputTypeMeaning
lengthcharactersoptional50 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.

InputTypeMeaning
lengthwordsoptionalAt most 40 words (warn).
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.

InputTypeMeaning
linecharactersoptionalAt most 80 characters (warn).
blocksentencesoptionalAt 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.

InputTypeMeaning
lengthsentencesoptional2 to 3 sentences (warn).
lengthwordsoptionalAt 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.

InputTypeMeaning
lengthsentencesoptionalAt most 1 sentences (warn).
lengthwordsoptional8 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é.

InputTypeMeaning
lengthsentencesoptional2 to 4 sentences (warn).
lengthwordsoptionalAt 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.

InputTypeMeaning
subjectcharactersoptionalAt most 72 characters (error).
bodywordsoptionalAt most 120 words (warn).
Add prose lint for MDX under content/

Audit rules

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

IdSummary
rule:raw-literalA 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-tokenA 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-componentA 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-blockA block kind in the shared registry that no component declares as its block.
rule:near-duplicateTwo 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-assetA file under public/ or in a piece folder whose name appears in no source or content file.
rule:piece-boundaryA piece importing from another piece's folder, or any file outside a piece folder (shared code under src/, scripts) importing from it.
rule:piece-overrideA 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-styleA 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-generatedA generated file (token CSS and JSON, the reference pages under content/docs/system) that differs from what its generator writes now.
rule:stale-docA 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:budgetA 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-specA shared block, layout or template with no spec in the catalog, or one missing its summary, use, avoid, inputs or example.
rule:compact-short-formA 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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Résumé commands

Commands of the résumé command bar.

IdSummary
command:letterShow, hide or reset the letter
command:conciergeShow or hide the recruiter introduction
command:variantOpen a variant of this résumé
command:goScroll to a section
command:printPrint, or save as PDF
command:mdCopy the résumé as Markdown
command:transcriptShow or hide the plain-text transcript
command:readmeShow or hide the README.TXT
command:themeSet the colour theme
command:draftsShow or hide the unpublished drafts
command:shareMake a share link and copy it; --revoke <id> for how to end one
command:signoutEnd the owner session
command:helpList 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

Print, or save as PDF

/print

md

Copy the résumé as Markdown

/md

transcript

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

/signout

help

List the commands

/help

Scripts

Package scripts.

IdSummary
script:buildProduction build of the site; has no side effects.
script:devDevelopment server.
script:startServe the production build.
script:lintBiome lint and format check.
script:formatBiome format, writing changes.
script:typecheckGenerate Next.js types, then tsc with no emit.
script:testUnit tests (bun test).
script:lint:proseWriting-guide rules over MDX in content/.
script:gen:writingRegenerate /docs/system/writing from src/writing/guide.ts.
script:gen:tokensRegenerate token CSS and JSON from the theme files.
script:gen:referenceRegenerate the MCP, audit and discovery reference pages.
script:auditHousekeeping audit; --json prints the report as data.
script:gen:catalogRegenerate /docs/system/catalog from the specs.
script:check:slotsRender 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:linksCheck 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:checkTypecheck, lint, test, prose lint, audit and link check; what CI runs.

build

Production build of the site; has no side effects.

bun run build

dev

Development server.

bun run dev

start

Serve the production build.

bun run start

lint

Biome lint and format check.

bun run lint

format

Biome format, writing changes.

bun run format

typecheck

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

bun run typecheck

test

Unit tests (bun test).

bun run test

lint:prose

Writing-guide rules over MDX in content/.

bun run lint:prose

gen:writing

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

bun run gen:writing

gen:tokens

Regenerate token CSS and JSON from the theme files.

bun run gen:tokens

gen:reference

Regenerate the MCP, audit and discovery reference pages.

bun run gen:reference

audit

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

bun run audit

gen:catalog

Regenerate /docs/system/catalog from the specs.

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.

bun run check:slots

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:links

check

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

bun run check

On this page