DESIGN.MD & AI

How to use DESIGN.md with OpenAI Codex

Save DESIGN.md in your repository, then add a UI section to AGENTS.md telling Codex to read it before any interface change. Codex reads AGENTS.md before doing any work.

Sitepeel2 min readOctober 24, 2026

Tool used in this guide: Design MD generator

“Tell Codex where the design lives.” AGENTS.md and DESIGN.md sit in the repository root; AGENTS.md says to read DESIGN.md before UI changes, and both feed Codex. — AGENTS.md tells Codex to read DESIGN.md before UI changes.

In short

Codex loads AGENTS.md before every task, not DESIGN.md
Codex’s docs describe no import syntax: name DESIGN.md and say when to read it
Instructions stop at 32 KiB combined by default, so point to DESIGN.md instead of pasting it

Add DESIGN.md to the repository

Generate it from a site with Sitepeel or write it. The repository root keeps the path simple.

Create or open AGENTS.md

Run /init in Codex to scaffold AGENTS.md, or open the existing one at the repository root.

Add a UI section

Tell Codex to read DESIGN.md before UI changes and to use only its tokens.

Check the instructions loaded

Run codex --ask-for-approval never "Summarize the current instructions." and look for your UI section.

Review the first screen

Build one page and compare it with DESIGN.md. Add a rule when Codex repeats a mistake.

Sample AGENTS.md section for DESIGN.md

Codex’s docs describe no way to import one file into AGENTS.md, so the section names DESIGN.md and says when to open it. Codex then reads it like any other file in the repository.

AGENTS.md

# AGENTS.md

## UI and design
- Before any UI change, read DESIGN.md in the repository root.
- Use its color, typography, spacing and radius tokens. No new hex values.
- Reuse existing components; follow DESIGN.md's Do's and Don'ts.
- If DESIGN.md has no rule for a case, say so instead of inventing one.
- In your summary, list the tokens and components you used.

Design MD generator in the Sitepeel interface — Design MD generator in actionExplore the tool

Where Codex looks for instructions

TipDon’t list DESIGN.md as a fallback filename: Codex reads one file per folder, so it’s skipped wherever AGENTS.md exists.

Global: ~/.codex/AGENTS.md, or AGENTS.override.md if present; CODEX_HOME changes the folder
Project: every folder from the repository root down to where you start Codex
In each folder: AGENTS.override.md, then AGENTS.md, then fallback names; one file per folder
Files closer to your working folder come later, so their rules win
Empty files are skipped; reading stops at 32 KiB combined, set by project_doc_max_bytes

Point Codex at DESIGN.md in a prompt

In the Codex CLI, type @ to search for a file and add its path to your prompt, or use /mention DESIGN.md. To show a reference screen, start Codex with --image and a screenshot, or paste the image into the composer.

Check what Codex built

Start Codex with --cd and a subfolder to confirm nested AGENTS.md files load in order
Search the diff for raw hex values and one-off sizes
Open the page at phone and desktop widths and compare it with DESIGN.md
Instructions look stale? Restart Codex; it rebuilds them on every run, with no cache to clear

Codex still ignores the design? Check these five things

A few useful answers.

Does Codex read DESIGN.md?

Not by itself. Codex reads AGENTS.md files before doing any work. Add a line to AGENTS.md telling it to read DESIGN.md before UI changes, or add the file to your prompt with @.

Where does Codex look for AGENTS.md?

First ~/.codex/AGENTS.md (or AGENTS.override.md), then each folder from the repository root down to your working folder. It takes at most one file per folder and joins them root first.

Is there a size limit for AGENTS.md in Codex?

Yes. Codex stops adding instruction files once the combined size reaches project_doc_max_bytes, 32 KiB by default. Raise it in ~/.codex/config.toml or split instructions across nested folders.

Can AGENTS.md import other files in Codex?

Codex’s docs describe no import syntax. Name the file and say when to read it, such as “Before any UI change, read DESIGN.md.”

TAKE A CLOSER LOOK

Your next starting point is already on the web.

Inspect it. Understand it. Build something of your own.

Add to ChromeFree install Try the free tools