Prevent DESIGN.md and CSS token conflicts in Codex projects

If your website already uses CSS custom properties, DESIGN.md should tell Codex where those properties live and how to use them. Copying their values into another document creates a second place to maintain.

This matters after several rounds of agent edits. The main button may use the shared colour while a new pricing button contains a hex value copied from an older prompt. Both are valid CSS. They stop matching when the shared colour changes.

This guide follows that conflict in a small, illustrative example for designers and developers maintaining a website. If you are deciding what a startup website should communicate, the founder guide covers that broader job.

A design token is a name for a reusable value. A button can use --action-background instead of repeating a colour in every button rule. Inspect the stylesheet, theme configuration and shared button before writing new rules. Find out whether a design tool or build step generates those files. Hand-editing generated CSS may have no lasting effect because the next build can replace it.

In the example below, styles/tokens.css owns the action colours. styles/button.css owns the button appearance and states. The page component decides where the main action goes. DESIGN.md explains the purpose of the action, names those files and points to the approved visual reference. Replace these example paths with real paths in your repository.

Some projects make DESIGN.md the token source. Google's alpha format can hold YAML token values and written guidance; its spec says the tokens convert to formats such as tokens.json and Tailwind theme configs, and a project build step can turn them into CSS. In that arrangement, edit the token in DESIGN.md and treat exported CSS as generated. Vercel's published design.md takes another approach for its report sites: it gives agents priority and composition rules, then points to a separate stylesheet for exact tokens and controls. That is a Vercel-specific brief, not a universal file schema. Either arrangement needs an explicit owner for each editable value.

Suppose the shared stylesheet sets --action-background to #1d4ed8. A later edit gives .button-primary its own background of #2563eb. Changing the token will not change that button. The correction below makes the button refer to the shared values.

This works if the custom properties are in scope and these declarations win the cascade. CSS custom properties inherit and participate in the cascade. A theme or a more specific rule can still change the computed result, so a source diff alone does not prove the button's rendered colour.

We opened the downloadable fixture in a local browser on 24 September 2026. With the duplicated rule loaded, its button computed to rgb(37, 99, 235) even though --action-background on the same button was #1d4ed8. Switching to the corrected rule changed the computed background to rgb(29, 78, 216), the RGB form of that token. This is a browser result for the included example, not a test of Codex or your website.

The fixture also has a local theme that sets --action-background to #0f766e. With the corrected rule, the button computed to rgb(15, 118, 110). With the duplicated rule, it stayed rgb(37, 99, 235) while the token on the button changed. That comparison shows why searching for a hex value is not enough: first find the winning declaration and the token value on the element.

If DESIGN.md names an old colour but CSS owns the token, correct the note after confirming the intended design. If DESIGN.md is the normative token source and CSS is generated, change the YAML token and regenerate CSS. If neither file has an agreed owner, compare the approved reference with the rendered page and settle that decision before asking Codex to edit. Do not copy an old colour into another file merely to make the documents match.

Codex documents how it discovers AGENTS.md instructions. Use that entry point to direct website work to DESIGN.md rather than assuming Codex has read an arbitrary Markdown file. An instruction should send it to the actual token and component files and ask it to report conflicts before editing. The example below uses an informal DESIGN.md project note; it does not claim to implement Google's schema.

The note says what the booking button does, where its colour is defined and which shared component to reuse. It also names the pages and interaction states to review. Those details settle a real edit. They cannot prevent an incorrect edit by themselves.

Ask Codex to report affected selectors and pages before it edits. Check its explanation against the diff: fixing one button should not quietly replace the palette or rebuild unrelated components.

In the browser's computed-style view, select each affected button and find the winning background-color declaration. Check the resolved value of --action-background on that element. If it still uses the old colour, look for a later selector, local token override or theme rule before changing the global token again. Tab to the button and confirm visible focus. Check loading and disabled states if the product has them. At a phone width, use the real label and follow the button to its destination.

Preserve intentional variants. A destructive action may need a different colour and component variant; record why and name its owning token. When the shared design changes, update its owning source and inspect every place that consumes it. Revise DESIGN.md when the purpose or usage rule changes.

The ZIP contains index.html, the shared tokens, before and after button rules, and check-example.mjs. Its CSS files sit at the ZIP root so index.html opens directly; the styles/ paths above illustrate where a project might keep them. Extract it and open index.html in a browser. Switch rules and the local theme to see the computed background and token printed below the button. Run node check-example.mjs from the extracted folder with a current Node.js release to check the source patterns. The script does not render a browser or assess contrast, and neither check tests whether Codex can make the correction unaided.

AI assistance was used to compare the primary documentation, assemble the example and check the article for factual and writing problems. An automated agent ran the source check and opened the HTML example in a browser on 24 September 2026; the observations above come from that fixture only. No claim here depends on John personally running Codex or verifying a production website. The linked documentation was checked the same day.