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

# Wireframe

One self-contained HTML page showing a **flow across states** of a piece of software: a sequence of frames, each drawn at the size the thing really is, with a caption under each saying what it proves. Not a prototype, not a component library, not a spec. It exists to make a proposal legible to someone who will not read the plan.

Every other template argues in sentences. This one argues in pictures, and the sentences are captions. Reach for it when the fastest way to settle a disagreement is to draw the thing and point at it.

## When to reach for it

Reach for it when someone asks for a wireframe, a mockup, a layout sketch, a UI concept, or "what would that look like"; when a proposal, plan, or bug report would be clearer as a sequence of screens; and when a conversation about an interface has gone three rounds without anyone drawing it. "Sketch the login page", "mock up the settings screen", "show me the flow", "what happens after they tap that" are the phrases.

Reach for it unprompted when a page you are already writing keeps describing an interface in prose. Three paragraphs about where a button goes is a wireframe that has not been drawn yet.

Do not reach for it when the answer is a working thing rather than a picture of one: something the reader will type into, run, or get a number out of is a [tool](../tool/template.md). Do not reach for it to document an interface that already exists and can be screenshotted, since a drawing of a real screen is a worse copy of it. Do not reach for it for a diagram of boxes and arrows, which is an explainer's job. And do not draw a whole design system: one flow, one argument.

## The shape

There are three slots and two of them are one line each, because **the page is the drawing**. This template has no prose column, no opening paragraph, and no sections after the frames.

- **A title bar.** A name, and at most one line under it saying what is being proposed and what the frames are meant to settle. It sticks to the top of the window, so it also carries the two controls and the legend.
- **The frames.** The whole rest of the page.
- **One line underneath.** What the frames are drawn against and what was invented to fill a row. Delete it when there is nothing true to put there.

Everything else goes in the captions. A caption is the only prose on this page that has a reader, because it sits under the thing it is about; the same sentence in a section three screens down is one nobody reaches. A wireframe surrounded by an argument is an argument with pictures in it, and the pictures are what was asked for.

So: no thesis paragraph, no "what this settles" ledger, no reading notes, no evidence footer. When a decision genuinely has to be argued, the argument is a [briefing memo](../briefing-memo/template.md) that links this page, not two sections bolted to it.

## The two rules that matter

**Show a sequence, not a screen.** One frame per state: resting, the moment of interaction, the result. A single screen shows what something looks like; a sequence shows what happens, which is what a proposal has to argue. Some subjects want a different axis — five states of one panel, three kinds of data, the same screen at three widths — and that is fine as long as the frames are doing comparative work. What is never fine is one frame and a paragraph.

**Show the click, mark the new.** The reader has to see what was clicked to get from one frame to the next, and what changed because of it, and neither may look like part of the design. That is what `cursor`, `ann`, `noted`, `clickable` and `fresh` are for: a pointer on the thing being clicked, a dashed orange ring for the click, a dashed violet ring for what appeared. The colors are ones interfaces do not use for themselves, so they read as commentary. One click per frame. Never a green row, a highlighted tile, or a check mark standing in for either: those look like the product, and they are not.

**And let the reader take them off.** The marks button in the title bar, and the `A` key, hide every annotation in the grid and in the enlarged view at once, so the same file is both the argument and the drawing on its own. It works because the rule hangs off the body and every annotation carries the class `ann`, which is the one thing to get right when you draw a mark by hand instead of calling the kit: a ring without that class is a ring that stays on when someone asked to see the design.

## Draw at true size

**Draw every frame at the size the thing really is.** A desktop window is 1280x800. A phone is 390x844. A settings panel is whatever it actually measures, around 520 wide. Use the ordinary type scale inside it: `text-sm`, `text-xs`, real padding, real spacing.

The page measures its own width, works out how many frames fit per row, and scales them with `transform` to match. Tapping one opens it as large as the space around the caption allows, which is why the page survives being read on a phone. Nothing renders above its true size.

So: never shrink a drawing by hand, never set a scale, and never reach for `text-[9px]` to make something fit. A frame drawn small is small twice, once in the grid and again when it is enlarged. `zoom` looks like a shortcut here and is not: it re-runs layout at the smaller size, so text re-wraps and the miniature stops matching the thing it depicts, where `transform` composites a box that was laid out once.

## Bars for prose, real copy where the idea lives

Every piece of text is a decision the reader has to evaluate. Grey bars for message bodies, article text, and anything incidental; real, final-quality copy for the labels, warnings, empty states, and buttons that carry the proposal. All lorem reads as unfinished. All real text buries the point.

Corollaries:

- The caption says **what the frame proves**, not what it depicts. "Nothing is sent by hovering" beats "the thumbs buttons".
- Put the burden of proof early. Someone who stops halfway should already have seen the thing being argued.
- Draw no chrome the proposal is not about. No sidebar, title bar, or tab strip unless they are in question, even though the kit makes drawing one a single call.
- Draw the states nobody asks for: empty, loading, one item, too many items, denied, expired, offline. That is where a design is actually decided, and it is what separates a wireframe from a picture of a happy path.

## What varies here

Free, and expected to differ between two pages made a day apart: the chrome (window, browser, phone, bare panel, or none); the frame size and whether the file mixes sizes; how many frames and along which axis they vary; whether the kit's helpers are used at all or the frames are written out; and `SLOT_H`, which is the one number worth tuning per file, since it is the height every tile gives its frame.

Fixed: the page is the frames. The title bar stays one line, the grid gets the window, and nothing is added before or after.

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

Nothing beyond the starter's fonts, icon set and Tailwind build. There is no dataset here and no library that would help.

This template does draw its frames from its own inline `states` array rather than writing them out as markup, which is the one place it differs from the rest of the family. The reason is that a frame is mostly repeated shell, and a file that writes six windows out longhand is a file nobody will revise. The array is in the page, so nothing is fetched and nothing is missing offline: open it from a USB stick in a year and it draws exactly as it does now. It is the network the offline test is about, and this page never touches it.

## Refusals

A page that could be any of the examples with the words swapped. One frame and three paragraphs. **An opening paragraph, a closing section, or any prose at all that is not a caption or the one line under the frames.** A frame with no caption, or a caption that describes the drawing instead of arguing from it. Lorem ipsum in a button. A happy path with no failure state. Chrome the proposal is not about, drawn because the kit made it easy. A click that is implied rather than marked, or marked with a green highlight that reads as part of the design. An annotation drawn without the `ann` class, so the marks button leaves it behind. A drawing shrunk by hand to fit. A wireframe of an existing screen that could have been a screenshot. Copy that says `Lorem` where a real warning belongs, or says nothing where the whole argument lives.

## Honesty about the drawing

Say what the frames are drawn against: a real product you measured, a screenshot you were given, or nothing but the description in the prompt. A wireframe drawn from a description is a proposal; one drawn from a real screen is a claim about that screen, and the difference decides how much weight a reader should put on it. That belongs in the one line under the frames, which is what that line is for.

Where a frame invents a number, a name, or a piece of data to fill a row, the same line says so rather than letting it be read as research. And where you drew something the prompt did not ask for because the flow needs it, the caption on that frame says so, so it can be argued with in the place where it is visible.