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

# Tool

One self-contained HTML page that does one thing to whatever the reader gives it. Type, drag, paste, choose; the answer changes as you go; there is nothing to submit and nothing to install. A calculator, a converter, a checker, a planner, a reshaper. Small, sharp, and finished.

Every other template in this family hands the reader an answer. This one hands them the thing that produces answers, because their question has a parameter in it and yours does not.

## When to reach for it

Reach for it when the answer to the question is a function rather than a fact: when it depends on numbers only the reader has, when they will ask it again next week with different inputs, or when the useful thing is not the answer but the feel of how the answer moves. "How much would it be if", "work out X for me", "convert this", "check whether", "is this any good", "clean this up" are the phrases.

Two of these are worth building and the rest usually are not. **The answer is not proportional**, so nobody can guess it and a table of three cases would mislead: that is a model the reader drives, and the page exists to let them find the cliff. Or **the data cannot leave**, which is the stronger case: a bank statement, a staff list, a spreadsheet of somebody's health readings. A single file that reads it in their own browser and forgets it is the honest answer to a question they could not otherwise ask anyone, and it is worth saying so in the opening line rather than the fine print.

If neither is true, a tool that does arithmetic anyone could do in a spreadsheet is a page nobody needed.

Reach for it unprompted when you notice you are about to write the same calculation out three times with different numbers, or when a page you are writing has a paragraph beginning "of course this depends on".

Do not reach for it when the reader wants your judgment: a tool that produces a number is not a recommendation, and dressing a recommendation up as a slider hides the argument. Do not reach for it when the answer needs data the page cannot carry, since nothing here may reach the network. Do not reach for it for something that needs an account, a file on their disk, or a service. And do not build a tool that would be a worse version of something in the browser already.

## The shape

**The page is the tool.** Three slots, and the first and last are small, because everything worth saying about a tool is something the tool is about to demonstrate.

- **A name and one line.** What goes in and what comes out. Not a manual, and not a thesis: whatever you were about to write in an opening paragraph, drag the slider instead.
- **The tool.** Controls and answer in one card, with nothing between them. It recomputes as things change. This is the page.
- **The fine print.** Four one-liners in two columns under the card, and all four earn their place: **where the input goes** (nowhere), **what it assumes**, **where it is wrong**, and **where the defaults came from**. Four sentences, not four sections. A reader who wants the limits finds them in one glance, and a reader who does not is already using the thing.

What used to be a prose section headed "the answer it opens with" is now the opening answer itself, written into the HTML. See below.

## The rules that make a tool a tool

**It arrives with a real example already in it.** Every control starts at a value that produces a real answer, and the answer is on screen before anyone touches anything. A blank tool has to be learned before it helps, and most readers will not; a tool that opens on a worked example teaches itself in the time it takes to read it. Choose the example to be the interesting case rather than the easy one.

**And that opening answer is written into the HTML, not only computed.** Put the default result in the output element as static markup; let the script replace it on load with the same figures. That one duplication is what buys a page that still answers with its scripts off, printed, or pasted into a mail client, and it is why this template no longer needs a prose section restating the default. The two copies have to agree, and the way to make agreeing automatic rather than careful is to render the page once and paste back what the script produced.

**Compute the comparison, do not leave it to the reader.** A tool that prints "3.5 min" and "24 min" in two places has told them nothing; a tool that writes "take one person off and the average wait goes from 3.5 minutes to 24" has explained something. Where the finding is a ratio, a difference or a threshold, have the script say it in a sentence. That sentence is usually the reason the page is worth sending to somebody.

**One thing, done completely.** Two tools on a page are two pages. The temptation is always to add the adjacent feature, and every one of them costs the reader the confidence that they have understood the whole thing.

**No submit.** Output follows input immediately. A button that means "now compute" is a button that means "I built this like a form".

**The answer is takeable.** Copy to clipboard on anything the reader will paste somewhere else, and a visible fallback when the clipboard is refused, which happens inside frames. Where output is long, it is selectable text on the page rather than only a button.

**Say where the input goes.** Which is: nowhere. Nothing is sent, nothing is stored, it works offline. That is a real property of this format and worth stating outright, because the text people most need to reshape is usually the text they least want to hand to a website.

**State the limits or you are claiming there are none.** Every tool is wrong somewhere: an assumption, a rounding, a case it does not handle, a question it is not answering. Name them. A calculator with a confident number and no caveats gets acted on.

## What varies here

Free, and expected to differ between two pages made a day apart: the controls, which may be fields, sliders, chips, selects, a textarea or a drop target; whether the output is a number, a table, a chart, a strip, a rendering or reformatted text; whether the reader's state lives in the URL; and the density.

Fixed: the page is the tool. One line above it, four lines below it, nothing else.

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

Nothing beyond the starter's fonts, icon set and Tailwind build, unless the answer wants a chart, in which case Chart.js pinned to an exact version, and the same rule as everywhere: **the numbers the chart draws are on the page as a table too, always rendered.** A tool whose output disappears with a failed script tag was a website.

Before reaching for one, check the shape of what you are drawing: a bar per row, with a label and a value, is HTML and a percentage width. A page that loads nothing cannot be broken by a CDN, and most tool output is that shape.

The arithmetic itself is never a dependency. Date and time zone work is `Intl`, which is in the browser and knows the real rules including daylight saving; formatting is `toLocaleString`; parsing is a regular expression you wrote. Everything a tool of this size needs is already there.

## Refusals

A tool that opens blank, or one whose opening answer exists only in the script. A submit button. A tool that does two things. **Prose sections around it**; the page is the tool. A number with no statement of what it assumes. A recommendation wearing a slider. Anything that reaches the network, uploads a file, or asks for a key. A chart with no table under it. A chart library loaded to draw six bars. Output the reader cannot copy. A control whose label is a variable name. A page that explains the tool for four paragraphs before showing it. Instructions that would not be needed if the thing were laid out better. Precision the inputs do not support, and a currency, a rate or a date presented as though it were current when it is an example.

## Honesty about the numbers

The defaults are the page's most dangerous content, because they look like research: an example interest rate is not a rate anyone is offering, an example price is not a price, an example paste is not a source. That is the fourth line of the fine print, and it is there so somebody reads it before they quote one.

Where the answer depends on the date, fix the date rather than using today's, print it, and say why it matters. An overlap computed "now" is quietly a different answer next month, and a page that does not say which day it assumed cannot be checked. The same goes for a rate, a version, or a table of rules that changes: name the one it used.

And where the tool is exact, say that too. Arithmetic that is exact for its stated assumptions is worth more than a hedge, as long as the assumptions are on the page.