A DESIGN.md template for a startup beta website
A complete DESIGN.md works better when it names real files and a page you can inspect. This fictional beta-page template comes with matching HTML and CSS.
6 min read
In this note
Use a template with a page attached
The template below describes one page for Wrenboard, a fictional research tool. The page explains a product, offers Request access, and links to a local access note. It has no signup backend. That narrow scope makes every instruction inspectable: the title, text, link target, component class and phone layout all have a place in the supplied files.
Use it when you want a concrete starting document rather than a list of possible design-system headings. It is an informal project note, not a claim to implement a universal DESIGN.md format. If your project already has a design specification, adapt that document instead of creating a competing one.
Copy the complete DESIGN.md
Replace the reader, product facts and approved copy together. A page for an API buyer needs different information from a page recruiting beta testers. Keep the paths accurate: a rule naming a button file that does not exist leaves the next agent to guess.
The template names the stylesheet as the owner of exact values. This keeps the prose focused on what those values are for. The matching stylesheet below supplies them, so you can inspect the example without installing a framework.
# Wrenboard startup website
## Reader and page job
Wrenboard is a fictional research tool for product managers.
Help a visitor decide whether to request access to its private beta.
This template is a project note, not a tool-specific file format.
## Facts and copy
The product groups interview notes by research question.
Use this h1: Keep interview notes beside the question.
Use this paragraph: Group notes by research question for your next review.
Use this main action: Request access
Link it to #access. This local sample does not collect submissions.
Use this access note: Ask the product owner for a beta invitation.
Do not invent prices, customer logos, testimonials or usage counts.
## Files and exact values
index.html contains the page. styles.css owns exact style values.
Use system-ui; do not fetch fonts or images.
Use --page, --ink, --muted, --action, --on-action and --focus from styles.css.
Use .button-primary for the main action; do not create a second button style.
Use --page-width and --gutter for the outer container.
If a required value is missing, name it before proposing an addition.
## Reading order and layout
Use a header with the Wrenboard name and a main element.
Inside main, use one h1, the product paragraph, the main action,
then an access section with id="access" and an h2 labelled Beta access.
Do not add feature cards, a pricing table or a second main action.
Keep the content in one column, with the title and paragraph left-aligned.
## Interaction and phone layout
Keep the link keyboard reachable and preserve its focus-visible outline.
The action's hover state uses --action-hover.
Allow text to wrap. Do not set a fixed content height.
At 390px and 1440px, keep the page inside the viewport.
Respect prefers-reduced-motion if motion is added later.
## Check after editing
Open the page at 390x844 and 1440x900.
Tab to Request access, follow it and confirm #access is reached.
Report the files read, changed files, widths checked and any failed check.
Keep exact style values in the matching stylesheet
Save styles.css beside index.html. These are proposed values for the fictional example, not measurements from iter0 or a customer site. The main action uses one class in every view, and its focus outline remains visible when reached with the keyboard.
The document’s file paths and CSS names are part of the example. If you move it into React or another framework, point DESIGN.md to the shared control and token file that actually render the page. Do not paste this stylesheet over an existing site just to match the template.
:root {
--page: #fafaf8;
--ink: #171717;
--muted: #525252;
--action: #202020;
--action-hover: #383838;
--on-action: #ffffff;
--focus: #1d4ed8;
--page-width: 64rem;
--gutter: 1.5rem;
}
* { box-sizing: border-box; }
body { margin: 0; background: var(--page); color: var(--ink);
font: 1rem/1.6 system-ui, sans-serif; }
header, main { max-width: var(--page-width); margin-inline: auto;
padding: 1.5rem var(--gutter); }
h1 { font-size: clamp(2rem, 6vw, 4rem); line-height: 1.1;
max-width: 18ch; overflow-wrap: break-word; }
p { max-width: 60ch; color: var(--muted); }
.button-primary { display: inline-flex; align-items: center;
min-height: 44px; padding: .65rem 1rem; border-radius: .375rem;
background: var(--action); color: var(--on-action);
text-decoration: none; }
.button-primary:hover { background: var(--action-hover); }
.button-primary:focus-visible { outline: 3px solid var(--focus);
outline-offset: 3px; }
#access { margin-top: 4rem; }
Run the page without a build step
Download index.html and styles.css into one directory and open index.html in a browser. The link reaches the Beta access section on the same page. It does not send data or create an account. The HTML is complete enough to inspect the heading order and link destination directly.
Then open it at 390 by 844 and 1440 by 900. Tab to the action, check its outline and follow it. Inspect the actual line breaks and page edges. A source check can establish that an anchor target exists, but it cannot establish that the button stays visible on a phone.
<!doctype html>
<html lang="en"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Wrenboard beta fixture</title><link rel="stylesheet" href="styles.css">
</head><body><header>Wrenboard</header><main>
<h1>Keep interview notes beside the question.</h1>
<p>Group notes by research question for your next review.</p>
<a class="button-primary" href="#access">Request access</a>
<section id="access"><h2>Beta access</h2>
<p>Ask the product owner for a beta invitation.</p></section>
</main></body></html>
Connect the document to Codex explicitly
OpenAI documents AGENTS.md as Codex’s project-instruction entry point. Use this short file beside the design note. It tells the agent what to read; it does not duplicate the product’s copy or palette. The existing Codex guide explains the broader setup.
In a fresh session, ask for a review of index.html against the project instructions without repeating the expected headline or action. Compare the response with DESIGN.md and the source. For an edit test, change the action label in a disposable copy and ask the agent to correct only that link.
# Website work
Read DESIGN.md and the files it names before editing the website.
Keep changes within the page requested.
Use existing CSS tokens and controls.
What Codex checked in the supplied page
On 3 November 2026, Codex CLI 0.162.1 reviewed this fixture using codex exec -s read-only and the exact prompt below. It read AGENTS.md, DESIGN.md, styles.css and index.html. Its reply began: “No concrete mismatches found.” It reported that the wording, structure, access link, CSS tokens, button style, hover and focus rules matched the instructions. The command exited 0 without changing files.
The run loaded the user’s global configuration as well as the project files. It demonstrates a review of this compliant fixture, not how Codex handles every conflicting instruction or a broken page. Codex did not test browser rendering or keyboard behaviour. Separate source checks parsed the CSS, resolved its tokens and confirmed the #access target. A separate native Chrome check at 390 by 844 showed keyboard focus and reached #access with the Beta access text.
Repeat the review from the directory containing the downloaded files. Add a working access destination before publishing a real beta page. The landing-page brief helps you decide the audience, offer and evidence before writing your own page.
Review index.html against the project instructions in this folder. Read files only; do not edit. List each concrete mismatch between the page and the instructions, quoting the instruction you rely on.Put the brief into practice
A launch page should make the buyer, promise, proof, and next action obvious. iter0 uses this same standard when it turns a brief or reference site into a builder-ready page.
Start your launch build