Iter0

Design systems and design.md

Keep related pages consistent

Share the header, the type, the colors, and the things you refuse to invent, so the second page still looks like the same site.

By Iter0 · Updated 2026-09-22

On this page

Consistency is shared decisions, not repeated sections

Harbor Ledger's home page answers whether a contractor should book a call. The pricing page answers what the two offers include. They should not be the same stack of sections with the words swapped. They should share the header, the type, the colors, the button, the price formatting, and the refusal to invent proof. A visitor who moves from one page to the other should recognise the site without reading a repeated hero. If the second page introduces a new font, the shared system was not actually shared.

Use the same color names on every page

CSS custom properties pass from a parent element to its children. Define --background, --foreground, --accent, and the spacing steps at the site level so both pages inherit them. A page can override one locally, and that is not automatically wrong. It creates drift when the new value is different, unreviewed, and meant to represent the same brand role. Use a page-level override only for a deliberate exception, such as an error treatment. When two pages look different, compare the named values and local overrides before adding another color.

Write the differences that are supposed to exist

The pricing page shows two offers in a comparable stack: name, price, period, what is included, and the same call to action under the pair. It does not repeat the home page's long opening. The home page shows one price and links to pricing for the comparison. Those are content differences, and they should be in the brief for each page. An agent that tries to make the pages 'match' will copy the home hero onto pricing and hide the comparison. Tell it which differences are required.

Three checks when the second page looks wrong

Open both pages at the same desktop viewport and in a 390 × 844 px phone viewport, starting at the top with browser chrome and zoom kept consistent. Check one: the header, footer, and button match. Check two: prices use the same format and the same approved numbers. Check three: each page still answers its own question in the first screen. If check one fails, fix the shared header or the shared color, not the sentence. If check three fails because the pages became copies, restore the question order for the page that lost it. A visual comparison can show tiny pixel differences. It cannot tell you which of the three checks failed. You still have to name it.

Update the file when the same mistake happens twice

The first time the pricing page invents a testimonial, delete the testimonial. The second time, add the refusal to design.md or to the project instructions, wherever that tool will read it on the next pricing edit. Do not add a new page of guidance for a single accident. Vercel's account of their own file says a correction earned its place when it kept showing up, and a rule that helped one artifact could hurt another. Recheck the home page after you add a refusal meant for pricing.

Sources

Related reading

Continue learning