AI agent workflow
Codex can inspect a codebase, implement features, and run validation. DESIGN.md adds the missing visual layer: product taste, layout rules, token usage, component states, and the difference between a marketing surface and an operational app screen.
Keep AGENTS.md focused on architecture and commands, and keep DESIGN.md focused on UI. Before a frontend task, ask Codex to read both files, reuse existing components, and explain conflicts before introducing new visual patterns.
A good DESIGN.md turns subjective feedback into concrete checks: radius, spacing, hierarchy, contrast, loading states, empty states, and allowed component variants. That makes Codex output easier to validate before it ships.
Move from this landing page into deeper DESIGN.md references, examples, and guides.
DESIGN.md is a visual instruction file for Codex. It defines color roles, spacing, typography, component variants, and anti-patterns that Codex should follow when implementing UI features autonomously — without requiring mid-task clarification from the user.
AGENTS.md covers engineering rules — commands, architecture, and code behavior. DESIGN.md covers visual rules — appearance and product taste. Reference both at the start of each UI task: "Read AGENTS.md for engineering rules and DESIGN.md for visual rules before implementing."
Color roles with semantic meaning, exact spacing values, component variants with when-to-use rules, page-level layout patterns, and an explicit anti-pattern list. Anti-patterns are especially important for autonomous agents like Codex, which cannot ask "is a gradient okay here?" before adding one — the file must answer those questions proactively.
Treat DESIGN.md as a review checklist. After Codex generates UI, check each rule against the output: does card padding match? Are anti-patterns absent? Is the typography hierarchy correct? This structured review takes minutes instead of open-ended visual evaluation, and feedback to Codex is precise and repeatable.