Patterns

A pattern is a reusable part of a document, such as a chart, a diagram or a table. Any document kind can use any pattern. Your agent loads a pattern skill before it writes the first figure of that form, and follows it for every such figure in the file.

pageship-docs picks the form from what the reader wants of each figure:

The reader wants	Form
To look up or compare exact values	Table
The shape of numbers: a trend, a distribution, a ranking, a gap	Chart
The shape and the exact values	Chart, then a table of the same values
A few headline numbers that carry the document	Key figures
How things connect: a path that branches, a structure, dependencies, a timeline	Diagram
The lines of code the text is about	Code block
An image, video or audio the source gives	Media
Items with one attribute each, or steps in one line	A list
One or two relationships, or two or three numbers	A sentence

Every pattern takes its colours from the document’s colour variables, works in light and dark, and shows only what the source gives.

Chart

Skill: pageship-chart

A chart answers one question about the source’s numbers at a glance. The agent draws it as inline SVG, with no chart library and no Mermaid, so the document loads nothing to draw it.

The form follows the question. A line or bars for change over time, sorted horizontal bars for a ranking, a split bar for shares of a whole, a histogram or dot plot for a spread, a scatter plot for how two measures relate. No pie, donut, 3D, radar or dual-axis charts. More than four series become small multiples on the same scale.
An honest scale. Bars start at zero. A line axis that starts above zero carries a break mark and a note in the caption. Ticks are even and round. Charts you compare side by side share axes. A log scale appears only for values that span more than a hundredfold, and the axis says so.
Values on the page. Every bar and line end has its value printed, series are named beside their lines instead of in a legend, and the caption says what is measured, the unit, the period and the source.
The kind of number shows. Measured values are solid. Targets are a dashed line labelled “Target”. Estimates and forecasts are dashed or outlined and labelled. Sample data says “Sample data” on the chart itself.
Pointing at a mark shows its exact value.

Code block

Skill: pageship-code-block

A code block shows the few lines the text is about and names where they come from.

Highlighted while writing. The agent runs a script that colours the code with Shiki for light and dark, and pastes the result. The document loads no highlighter. Without Node, the block is plain and the agent tells you it skipped highlighting.
Short. At most 25 lines a block. A comment such as // … marks each cut.
Copied exactly. The same names, indentation, comments and line breaks as the source. The agent doesn’t fix, reformat or complete code. Code it writes itself appears only when you ask, labelled “Illustrative”.
Labelled. Each block names its file and line range, or what it is, such as “Command” or “Output”.
Secrets removed. A token, password or key becomes REDACTED, and the label says so.
Changes as a diff, only when the source gives both versions.
No copy button and no line numbers.

Diagram

Skill: pageship-diagram

A diagram shows what a paragraph can’t show at once: a path with branches, how far apart events were, what connects to what. Each diagram makes one claim, stated in its caption.

The form follows the question. A flowchart for what happens next, a swimlane or sequence for who hands what to whom, a timeline for when things happened, a state diagram, a system map, or a tree.
Limits. A diagram drawn by hand holds at most 9 nodes and 12 connectors. Over that, the agent merges or splits it, or, when you need the whole graph at once, computes its layout with ELK while it writes, up to 30 nodes and 40 connectors. The page still loads no layout library. Mermaid in the page is the fallback when the agent can’t run the layout script.
Timelines to scale. Events sit at their real distance apart, never evenly spaced when the times aren’t.
Labels. Every node is labelled in the source’s terms. Groups of nodes differ by border style as well as colour, with a legend.
Pointing at a node shows its detail. A process of three to eight steps can be stepped through.

Interaction

Skill: pageship-interaction

A control lets the reader ask the document a question, such as “which follow-ups are mine?”. The document reads in full without it.

The patterns. Step-through for stages in order, path trace for something moving through a diagram, filter for narrowing a list, tabs for parallel versions of the same content, reveal detail for supporting text behind a summary line, and pointer states for chart marks and diagram nodes.
No control when it would hide things. Items you compare sit side by side in a table, not behind tabs. Short lists and content that fits on one screen get no control. No carousels.
Complete without it. Before you touch anything, every item and every number shows. In print, every step and panel shows and the controls are hidden. Without script, the page reads as a plain document.
Real controls. Buttons, links and details elements, usable by keyboard, with a visible focus outline and a state shown by more than colour.
State in the address. A step-through records the current stage in the URL fragment, so a link opens on that stage.

Key figures

Skill: pageship-key-figures

Key figures are the few numbers a reader needs before the detail, in a strip after the summary.

From the source only. Usually three to six. A change between two figures counts only when both share a kind, unit and basis. The strip never fills a slot with a guess.
Each figure carries its context. A label, the value as the source writes it (“about 140” stays “about 140”), its kind, its period and its source.
The kind shows. Measured, estimate, target, forecast or illustrative, in words and in the figure’s border style.
Status in words. A status such as “Off track” appears only when the source gives one.

Media

Skill: pageship-media

Media shows the images, video and audio the source gives. The document still reads in full when media fails to load, when it is printed, or when the reader can’t see or hear it.

Nothing plays on its own. Video and audio start paused, with controls. An animated image appears only with a still version for reduced motion.
Video sites become links. The Pageship sandbox blanks embedded players, so a YouTube, Vimeo or Loom page is a link with a caption.
Files embed by URL or inline. The agent inlines a local file when the document stays under 5 MB. Otherwise the agent embeds nothing and adds an open question asking where the file is hosted.
Text stands in. Every image has alt text, every piece of media has a caption from the source, and video and audio get timed captions and a transcript when the source gives them.

Motion

Skill: pageship-motion

Motion shows how a figure takes shape: the values a chart reaches, the order a process runs in, or a cause and its effect. Everything else holds still.

Figures play once, as they scroll into view. A chart grows from its initial state to its values: bars rise from the baseline, a line draws from left to right, points appear. A sequence, such as a marker moving through a diagram, plays from its first step to its last. Each stops on its end state and repeats only when you turn on Loop.
The still page tells the whole story. The markup holds the end state, so without script, in print, before the figure scrolls into view, or with reduced motion set, you see the complete figure with every value. Every value a frame shows is also in text.
Controls. A chart has Replay and Loop. A sequence has Play, Pause, Back, Next, Replay and Loop, and a line naming the current step. A full playback takes about 10 seconds or less.
Everything else holds still. Text and sections appear in full, numbers show their final value from the start, and nothing pulses, bounces or drifts.
Reduced motion. With reduced motion set, nothing plays on its own, and every control moves between states at once.
“More engaging” means clearer. A request to make a document livelier gets a stronger summary, key figures or a better chart, not more animation.

Table

Skill: pageship-table

A table lets the reader look up and compare exact values, on a phone and on paper.

Narrow. A table has at most four columns, unless the reader must compare more than three values in one row. At phone width, a table of up to four columns shows in full, with each row stacked when it doesn’t fit. A wider table scrolls inside its box with its row labels and header in view.
Values as written. The same digits, precision and unit as the source. The agent rounds and converts nothing. Totals and changes come only from plain arithmetic, and a note says which columns they come from.
Gaps say so. An empty cell reads “Not given”, never a blank, zero or dash.
The source’s order, unless the table answers a ranking, and then the caption says what it is sorted by.
Sorting and filtering only for long tables. Sort and filter buttons appear only above 15 rows, and a search box only above 30.
Print shows every row, even after filtering.