What belongs in design.md

design.md is a project file that tells an agent how to design with the pieces you already have. It is not a standard every tool loads, and it is not a second copy of your CSS. Vercel's public design.md is guidance for Vercel report pages, paired with a stylesheet the page actually loads. Their write-up says a prose-only version was interpreted differently by different models, so they moved repeatable type, spacing, and components into CSS and left the judgments in the file. Use the same split. If a value should be identical every time, name it once in the stylesheet. If a person has to decide, write the decision in design.md.

Open the file with the reader and the decision, then the moves you keep rejecting. For the fictional Harbor Ledger site the refusal list is specific: do not add a logo cloud, do not invent a time-saved number, do not use a dashboard screenshot as the hero, and do not change the $89 or $640 prices. Those lines stop a class of plausible pages. A sentence such as 'keep it clean' does not, because the model can satisfy it with almost any layout. Vercel made the same point about vague layout language and responded by naming failures they could see.

The colors and sizes the site already uses should have names, such as --background and --accent. CSS calls these custom properties. The W3C specification, a Candidate Recommendation from 16 June 2022, says you declare the value once, often on the root of the page, and refer to it with var(). The names are case-sensitive. Change the named value and every rule that uses it updates. In design.md, list the names the agent may use and the file that declares them. Do not write a second hex code for the same job. If design.md and the stylesheet disagree, the browser paints the stylesheet. Fix one of them. Do not add a third value inside a component to match the document.

List the components that already exist and the content each one needs. Harbor Ledger's primary button is for one action in a decision area, and its label should say the result, such as 'Book a 20-minute call.' A price row needs the amount, the period, and what is included. A quote needs a real person and permission. Write the states the component already has: default, hover, focus, disabled, error. An agent that invents a new card for every section will ignore this list unless you say to reuse the existing component first and add a local one only when the behavior is new.

End the file with checks a person can run after the edit. For Harbor Ledger: at a 390 × 844 px viewport, the first screen shows who it is for, the price, and the call to action; body text stays at least 16px; the call button is reachable by keyboard; and the price and button do not overlap. Check heading order, form labels, accessible names, keyboard use, focus visibility, and text alternatives. Iter0 also uses one h1 per page as a house convention so the main page topic is easy to identify. These are pass or fail observations. They are stronger than 'make it polished.' Vercel reported that in one check of six pages, known mechanical failures were fewer when their file was loaded, and they also wrote that every page still had a failure serious enough to block shipping. A design.md can reduce a named failure. It does not certify the page.

The annotated Harbor Ledger file in the downloads shows fictional facts in place, including prices and a refusal list, and it says those facts are examples. The clean template has the same headings and empty fields. Copy the template into a project and replace every example. Do not publish the Harbor Ledger prices as your own. Codex does not discover a file named design.md by itself. The Codex guide says it reads AGENTS.md, then any names you add to project_doc_fallback_filenames. Point to design.md from AGENTS.md, or add the filename to that list, and read the existing Codex article before you assume a tool will find the file.