---
name: create-page
description: "Use when the answer is more than a few paragraphs, or lays out steps, options, a comparison, or figures. One self-contained HTML page to scan, print, send on, or use. Forms: FAQ, timeline, how-to, checklist, itinerary, comparison, dashboard, data explorer, scorecard, brief, memo, case study, explainer, recommendation, wireframe, whiteboard, or a small working tool."
---

# Create page

One self-contained HTML file that a reader can open, keep, print, send on, and in a few cases use. Twenty-one templates cover the kinds of page people actually ask for; each names a set of slots and the intent behind each one, and all of them share the look, the method, and the refusals below.

The page is the answer. When a reply would be long, structured, or worth keeping, a page beats a wall of chat: it can be scanned, linked into, printed, and handed to someone who was not in the conversation.

## Choose the template

Read the row that fits, then read that template's `template.md` in full before writing anything. Paths are given because the file listing you were handed may be truncated: open them directly.

| Template                                                                      | Reach for it when                                                                                                                                        |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Briefing memo                          | Something with real stakes has to be decided, and the situation, the options, and a recommendation belong on one page before anyone commits.             |
| Case study                                | A situation like the reader's played out start to finish, and the point is to learn from it or to show that an approach works.                           |
| Checklist                                  | A process is about to run where forgetting one step is expensive, and every item wants to be grouped, tickable, and printable.                           |
| Comparison matrix                  | Several options need measuring on the same attributes side by side, before deciding what matters.                                                        |
| Recommendation with criteria | The winner is wanted along with the arithmetic: named criteria, stated weights, scored options, and what would flip the answer.                          |
| Dashboard                                  | A period has ended and someone has to know how it went: the figures with what to compare them against, and the thing the headline hides.                 |
| Data explorer                               | There are more rows than anyone will read and the rows are the point: the whole set, what it turns out to say, and a grid to sort, filter and take away. |
| Explainer                                  | A mental model of a concept, a system, or a topic is needed before deciding or digging deeper.                                                           |
| FAQ                                              | The same questions keep arriving about one topic, and each wants answering once, in a block that can be found, skimmed, or sent.                         |
| How-to guide                                  | Something has to get done in order, with the tools listed, the traps marked, and a way to know when it is finished.                                      |
| Itinerary                                  | A destination and a span of days want planning into mornings, afternoons, and evenings that can be followed from a phone.                                |
| One-pager                                  | A project, a program, or a change is being proposed and needs one page that earns the next meeting.                                                      |
| Pros and cons                                | The question is torn on one option or between two, and each side deserves its strongest case, weighted for this situation.                               |
| Recommendation guide            | A product, a tool, or a vendor is being picked, and one page should name the pick and show its work.                                                     |
| Scorecard                                  | One vendor, tool, candidate, place, or plan is in front of the reader and wants grading across the dimensions that matter, evidence beside each.         |
| Should I…?                                  | A should-I, is-it-worth-it, or do-I-need question wants a plain answer that shows what it turns on.                                                      |
| Timeline                                    | Change over time is the explanation: the order of events says why things are as they are, or what happens next.                                          |
| TLDR brief                                | The research is done, and the reader wants only the takeaways, on one screen.                                                                            |
| Tool                                            | The answer is a function rather than a fact: a calculator, converter, checker or planner that opens with a real example already in it.                   |
| Whiteboard                                | The material has two dimensions of its own and an order throws them away: a wall of sorted notes, a plan of somewhere real, things placed on two axes.   |
| Wireframe                                  | An interface is being proposed or argued about, and the fastest way to settle it is a sequence of frames that each prove something.                      |

When two rows both fit, the tie-breaker is what the reader does next. A page that ends in a decision is a brief, a should-I, or a recommendation; a page that ends in an action is a how-to, a checklist, or an itinerary; a page that ends in understanding is an explainer, a timeline, or an FAQ; and a page the reader keeps open and comes back to is a tool, a whiteboard, or an explorer.

Three of these are a family of their own, in that the page does something rather than only saying something: a wireframe draws a proposed interface, a whiteboard is a surface the reader moves around, and a tool computes. On all three **the page is the thing** -- there is no prose column, no opening paragraph and no closing section, because a drawing under three paragraphs is an essay with pictures in it and the paragraphs are the part nobody wanted. A name, one line, the artifact, and a line of provenance under it. They obey every rule below, including the one about the network, and each says in its own `template.md` what that costs it.

When none of them fit, say so and write the page anyway, using the nearest template's slots as a starting point and this file's method as the rule. A page whose shape had to be invented is a better answer than the wrong template filled in obediently.

## Make the page

1. Read the chosen template's `template.md` in full, and its `idea.json` for the page's stated purpose.
2. Read the two examples in that template's `examples/` whose situation is nearest the user's. Each has a sidecar `.json` with a design note saying what that example chose and why; read the notes, not only the pages. Never take the first example as the target.
3. Write a three-line brief before any HTML: who reads this and what they will do next, the one thing the page has to settle for them, and the one distinctive move this page makes that the two examples did not.
4. Copy `starter.html` to `output/<slug>.html`, set its `instrument:idea` meta to the template's name, and paste the template's `main.html` inside `<main>`. The starter carries the tab icon, the skin, the fonts, the icon set, and the page behavior, each inside a `shell:start` … `shell:end` pair; leave those regions as they are, and everything under `<main>` is yours. Your own CSS goes in the gap the starter leaves between them.
5. Fill the slots with the research. Sections may be reordered, merged, renamed, or rebuilt, but every intent the template names must be answered somewhere on the page.
6. Check it against the refusals below and the template's own, open it, and look at it once at a laptop width. Fix what you see, then stop.

Research before you write, and write from what you found. A page whose facts came from the model rather than from a source is the failure this whole skill exists to avoid.

## What stays fixed, and what must vary

Fixed, because every page shares one look: the skin block in the starter, the type stack, the palette with brand green as the only saturated color, the spacing scale, a single self-contained file, and a provenance footer.

Free, and expected to differ between two pages made a day apart: the layout and column count, the density, the register, the components, the way a slot is realized, and any interaction, which must be progressive so the page reads with scripts off. Each template names what varies most in its own case.

The look follows the reader's system theme, and you never choose between them. Write the page once against the tokens and both come out right: a step on a ramp names distance from the paper rather than a lightness, so 25 is the faintest wash and 950 the darkest ink in either theme, and what changes is which end of the spectrum each lands on. The saturated middle, 400 through 600, holds still in both. That is the whole rule for white: it rides the middle and nowhere else, because every other step moves out from under it. Never hand-pick a ground for the page, and never write a `dark:` variant; `bg-background`, `bg-card`, `bg-muted`, `text-foreground` and `text-muted-foreground` already say what you mean. The one exception is a terminal or code listing, which is a well cut into the paper and keeps its own colors in both themes: `bg-code` with the four `text-code-*` inks.

`pnpm check:contrast` reads both palettes out of the skin and every page for what sits on what, so a page that fails WCAG AA in either theme fails the build. It is the reason nobody has to open the page twice.

The starter also carries three behaviors every page gets, and none of them need doing by hand: every external link wears the icon of the site it points at, footnote markers and their notes link both ways and light up when jumped to, and the page prints with sane margins. A page wider than a portrait sheet adds `@page { size: landscape }` in its own style block.

A page's own logic is one `<script type="module">` at the end of `<main>`, never a plain `<script>`. The starter's last script keeps a copy of the page for sharing as the parser reaches it, and a module script runs after that, so a shared copy carries the markup as written rather than as the script changed it. Module scripts do not share top-level names, so keep the logic in one, and attach listeners in it rather than through `onclick` attributes.

## Refusals

A page that could be any of the examples with the words swapped. A thing that lives at a URL named in plain text, or a link whose text describes the destination rather than naming the thing. Any image whose `src` is a URL or a relative path rather than inline data, any sibling file, and any relative fetch: the file has to open from a USB stick, arrive as an email attachment, and be served from a share host, and only one of those has an origin. A file over about 1.5 MB, or an inline image over 200 KB.

**What a page may load, and the test it has to pass.** Most pages load nothing beyond the starter's fonts, icon set and Tailwind build, and that is the right default. Where the material is a dataset rather than an argument, a page may also load one of the libraries in `check-ideas.ts`'s `ALLOWED_SOURCES`, pinned to an exact version. The test is not whether it loads, it is what happens when the load fails: **open the page with the network off and every number, name, place and finding is still there, in the HTML.** A library may add motion, precision or scale to something already on the page; it may never be the only copy of a fact. A chart carries its own table. A map's container carries its own list. A figure fetched at open carries the value it was written with, and the date. A page that goes blank, empty or meaningless offline is the refusal this rule exists for, and a template that reaches past the list has to say in its own `template.md` why its document kind needs it.

Each template adds the refusals that only bite in its own case.

## Honesty about research

Say on the page what it rests on and when it was read. Where two sources disagree, say so and say which one the page followed. Where a figure is an estimate, a quote, or a reconstruction rather than a published number, label it as one. Where the research is thin, the page says so in its footer rather than performing certainty: a thin honest page is useful, and a confident invented one is worse than nothing, because a reader will act on it.

Numbers are the easiest thing to invent and the hardest for a reader to check. A page carries a figure only when the prompt, a source, or arithmetic over shown inputs gave it. Scores use coarse scales — letters, a few dots, a word — unless every input is on the page, and never a decimal that implies precision the research does not have.

## References

Vocabulary, not layout. Read the one whose form is in play, not all of them.

- [`references/patterns.md`](/discover/create-page/references/patterns.md) — the recurring elements: kickers, status pills, step circles, icon lists, emphasis cards, code and terminal blocks, quoting, evidence footers, and how a block wider than the column behaves.
- [`references/charts.md`](/discover/create-page/references/charts.md) — stat tiles, bar rows, meters, sparklines, timeline bars, and the honesty rule for drawing a number.
- [`references/diagrams.md`](/discover/create-page/references/diagrams.md) — when HTML beats SVG, the SVG kit, swimlanes, parallel routes, and generated geometry.
- [`references/interaction.md`](/discover/create-page/references/interaction.md) — answer forms, runbook ticks, click-to-enlarge, details/summary, and the rule that interaction may orient but never gate.
- [`references/images.md`](/discover/create-page/references/images.md) — when a picture earns its place, how to size and inline one, and what to draw when there is no photo to use.

Each template also has a `patterns.md` beside it, for the vocabulary only that document kind uses.

# Data explorer

One self-contained HTML page whose subject is a dataset. It carries the rows themselves, not a description of them: the shape of the whole set in a few figures, the two or three things the data says, a way to regroup and re-measure it without typing, and a grid the reader can sort, filter, narrow and take away as a spreadsheet. It reads like the data pages newsrooms and public agencies publish, where the argument and the evidence are the same object.

Every other template hands the reader a conclusion and shows enough evidence to trust it. This one hands over the evidence and shows enough conclusion to make it worth opening. Reach for it when the honest answer is "here is the whole thing, and here is what I noticed in it".

## When to reach for it

Reach for it when there are more rows than anyone will read and the rows are the point: a month of readings, an export, a scrape, a survey, a public feed, a list of everything in a category. "What's in this data", "show me all of them", "let me poke at it myself", "which of these are the biggest", and "can I filter this" are the phrases. Reach for it unprompted when research you have already done produced a table long enough that quoting five rows of it would misrepresent the rest.

Do not reach for it when a shortlist would serve better (that is a comparison matrix), when the answer is a single number or a recommendation, when the rows are fewer than about thirty and a plain table in another template says it all, or when the data is too sensitive to travel — the page is the data, so sending the page sends every row.

## The shape

Each slot is an intent. Answer it in whatever form suits the material.

- **What this is.** The dataset in two or three sentences: what it counts, where it came from, when it was read, how many rows survived, and what question it was gathered to answer. The reader decides here whether to keep going.
- **The whole set at a glance.** Four or five figures that size the thing — how many, the extremes, the one that is surprising. Each is a fact from the data rather than a rounded impression.
- **What the data says.** Two to four findings, each a sentence a reader could check against the grid below. At least one of them should be about the dataset rather than about its subject: a gathered set always has a shape of its own, and saying so is the difference between a page that reports and one that understands.
- **Break it down.** A way to regroup and re-measure without writing anything: the reader picks a dimension and a measure and the page answers. Show the query it built if there is one; never ask for it.
- **Every row.** The grid. Sortable, with a filter under each heading, columns that can be hidden, a live count of what is showing, and a way to take the result away.
- **Where and when, if the data has them.** Place gets a map, time gets a chart on a shared axis. Neither is decoration: a map earns its place when position is a finding, not when the rows merely have coordinates.
- **Method.** Where the rows came from and how to get them again, what was excluded and why, what is measurement and what is metadata, and what the data cannot answer.

## What varies here

Free, and expected to differ between two pages made a day apart: whether there is a map, a globe, a time axis or none of them; which of the figures lead; how many charts and of what kind; whether the breakdown is two selects, a set of chips, or a row of tabs; the grid's columns and which are hidden by default; the density; and the order of the sections, since a set whose finding is geographic should open on the map while a set whose finding is a distribution should open on the chart.

## What it may load, and what has to survive without it

This template is the reason `SKILL.md`'s load rule exists. It may load, pinned to an exact version, any of Chart.js, Leaflet, sql.js and Tabulator. Each one has to pass the offline test on its own:

- **The grid** renders a plain HTML table of the most interesting rows first, and replaces it when the library arrives. A reader with no grid still gets rows.
- **A chart** has the same numbers as a table or a list directly beneath it, always rendered. Not in a `details`, not in a tooltip.
- **A map's container** holds the list of places, with coordinates and what each one is, as its own initial content. The map replaces it. A blank grey box is the failure.
- **The database** answers the breakdown, and the breakdown says plainly when the engine did not arrive. Every number it would have produced is still reachable in the grid.
- **The data itself is never fetched.** It is inline in the file, always. A page that goes empty offline is not this template, it is a website.

Keep the payload under about 5,000 rows and 300 KB of inline data. Past that, aggregate before you write the page and say in the method what you aggregated.

## Refusals

A page that could be any of the examples with the words swapped. A grid over data the page does not carry. A query box: the reader picks a dimension and a measure, and never types a language to get an answer. Findings that only restate the largest row, or that repeat what the glance tiles already said. A chart with no numbers under it, or a map with no list in its container. Every column shown because it existed in the source. A map because the rows have coordinates rather than because position says something. Precision the source does not have, including a decimal place the feed did not publish. A dataset presented without saying what is missing from it.

## Honesty about research

Say where the rows came from, precisely enough to fetch them again, and when they were read. Say what was excluded and why, because an exclusion is an argument. Distinguish measurement from metadata: a file's size is measured, its modification date is a claim about a filesystem. Where the set is a sample or a feed with a threshold, say so beside the count, since a reader will otherwise read it as a census. And prefer a finding about the collection over a fourth finding about the subject: the most useful thing a data page can say is often why the data looks the way it does.