# DESIGN.md with Codex

> Make OpenAI Codex follow DESIGN.md with a few lines in AGENTS.md. See where Codex looks for instructions, its size limit and how to check what loaded.

Canonical page: https://sitepeel.dev/guides/design-md-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.

Published: 2026-10-24

Tool used in this guide: [Design MD generator](https://sitepeel.dev/design-md-generator/index.md)

## How to use it

1. **Add DESIGN.md to the repository** Generate it from a site with Sitepeel or write it. The repository root keeps the path simple.
2. **Create or open AGENTS.md** Run /init in Codex to scaffold AGENTS.md, or open the existing one at the repository root.
3. **Add a UI section** Tell Codex to read DESIGN.md before UI changes and to use only its tokens.
4. **Check the instructions loaded** Run codex --ask-for-approval never "Summarize the current instructions." and look for your UI section.
5. **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.

Example: 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.
```

## Where Codex looks for instructions

- 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](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md)

## Questions and 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.”

## Further reading

- [OpenAI Codex docs: Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [OpenAI Codex docs: CLI slash commands and shortcuts](https://learn.chatgpt.com/docs/developer-commands?surface=cli)
- [AGENTS.md: the open format for coding agents](https://agents.md/)

## Related pages

- [What is DESIGN.md](https://sitepeel.dev/guides/what-is-design-md/index.md): DESIGN.md is a Markdown design-system file for AI coding agents. See its format, a small example, the official linter and how to make one from any site.
- [DESIGN.md with Claude Code](https://sitepeel.dev/guides/design-md-claude-code/index.md): Import DESIGN.md into CLAUDE.md with @DESIGN.md so Claude Code follows your colors, type and spacing. Includes a sample CLAUDE.md and checks.
- [DESIGN.md with Cursor](https://sitepeel.dev/guides/design-md-cursor/index.md): Point Cursor at DESIGN.md with a project rule in .cursor/rules, AGENTS.md or an @ mention. Includes a sample .mdc rule and the four rule types.
- [DESIGN.md with GitHub Copilot](https://sitepeel.dev/guides/design-md-github-copilot/index.md): Make GitHub Copilot follow DESIGN.md with copilot-instructions.md, a path-specific .instructions.md file or AGENTS.md. Includes a sample file.
- [When AI ignores DESIGN.md](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md): Your agent has DESIGN.md but the UI is still wrong? Check that it loads, remove conflicting rules, name real components and verify the result.