AI Agents
DESIGN.md for Codex
How to use DESIGN.md with Codex so autonomous AI-generated frontend code follows your product design system instead of generic defaults.
Why Codex needs design context
When Codex runs autonomously — inspecting a codebase, planning an implementation, and validating the result without real-time input — every visual micro-decision gets resolved by whatever defaults its training data favored most heavily. That autonomy makes design memory critical. When Codex implements a UI feature, it makes dozens of micro-decisions: card padding, button shape, heading weight, border style, icon usage, mobile behavior, loading states, empty states. Without a DESIGN.md file, those decisions default to common patterns from training data. The result is UI that is technically correct but visually generic — the kind of dashboard or settings page that could have been generated for any product. DESIGN.md changes the input. Instead of leaving visual decisions to Codex defaults, the file states what the product should look like in enough detail that an autonomous agent can implement it correctly without asking for clarification. For products with established design systems this means fewer rework cycles. For products built from scratch it means generated UI starts coherent instead of needing a cleanup pass after each feature.
Pairing DESIGN.md with AGENTS.md for Codex
Codex respects AGENTS.md as an engineering instruction file. The cleanest pattern is to pair AGENTS.md with DESIGN.md as two parallel instruction layers: one for code behavior, one for visual behavior. AGENTS.md covers architecture, commands, testing requirements, and coding standards. DESIGN.md covers colors, typography, spacing, component variants, page patterns, and anti-patterns. Keeping them separate prevents either file from growing too large and makes maintenance easier — a design change updates only DESIGN.md, an engineering change updates only AGENTS.md. When starting a UI task with Codex, include a reference to both: "Read AGENTS.md for engineering rules and DESIGN.md for visual rules before implementing. Reuse existing components where they match the spec. Explain in your plan how DESIGN.md applies to this feature before writing code." The plan step is important for autonomous agents: it surfaces how Codex is interpreting the design rules before it implements them, which is far easier to correct than reviewing output after a full implementation pass.
Best prompt pattern for Codex UI work
Codex works best on UI tasks when the prompt is structured as a brief with a pre-read step. A reliable structure: declare the files to read, describe the feature goal, set the visual constraints from DESIGN.md, name the components to reuse, and define the acceptance criteria. A practical example: "Read AGENTS.md and DESIGN.md. Implement a subscription billing settings page with the following DESIGN.md constraints: two-column form layout at desktop, section headers match the Settings heading style, destructive actions use the danger button variant, empty state for no subscription uses the standard empty-state pattern. Reuse the existing FormSection and SettingsCard components. Do not add marketing copy or promotional design elements to this surface." This structure allows Codex to implement without mid-session clarification because the visual expectations are defined upfront alongside the engineering expectations.
What a Codex-ready DESIGN.md should include
A DESIGN.md file that works well for Codex must be specific about the visual decisions an autonomous agent cannot infer from context. Abstract instructions like "make it look professional" are not useful. Concrete instructions like "base card radius is 6px, compact variant is 4px, never use radius above 12px on operational surfaces" are directly implementable. For Codex, the most valuable sections are: color roles (what the primary accent means, what semantic colors represent, which surfaces are dark vs. light), spacing rules (exact pixel values for the padding system, grid columns, section gaps), component variants (exactly which button types exist and when to use each), page-level patterns (how a full-page list, a settings section, and a detail view should be structured), and anti-patterns (an explicit list of visual choices that are never correct in this product). Anti-patterns deserve special attention for autonomous agents because Codex cannot ask "is a gradient okay here?" before adding one. The file needs to answer those questions proactively.
Making generated code easier to review
One of the main arguments for DESIGN.md with Codex is that it makes generated UI easier to review. Without a reference spec, reviewing Codex output requires the reviewer to hold the entire design system in their head and evaluate the UI against it. That is slow, inconsistent across reviewers, and hard to explain to the agent when feedback is needed. With DESIGN.md, the review process becomes a checklist. Check each rule in the file against the generated output: does the card padding match? Does the empty state follow the defined pattern? Are any anti-patterns present? Is the typography hierarchy correct? This structured review takes minutes instead of open-ended visual evaluation, and feedback to Codex is precise: "The table row height should be 44px per the spacing rules, not 52px." Precise feedback is easier for Codex to apply correctly than general feedback like "the table feels too spacious." Over time, as rules get refined and Codex output gets more consistent, the review becomes a quick sanity check rather than a line-by-line audit.
Building a feedback loop with Codex and DESIGN.md
The value of DESIGN.md grows with each Codex session. After implementation, review the output and identify patterns in where the agent diverged from the spec. If Codex consistently uses the wrong button variant for destructive actions, the rule is probably too ambiguous — rewrite it with an explicit example: "Destructive actions (delete, disconnect, remove) always use the danger button variant with red background. Do not use the outline-danger variant for actions that are immediately irreversible." If Codex consistently applies correct spacing but incorrect radius, the radius rule needs more specificity. This feedback loop has a compounding effect: each iteration of DESIGN.md makes the next Codex session produce more consistent output, which means fewer review cycles, which means faster feature development. The file starts as a design brief and evolves into a tested specification — one validated against real AI-generated code and refined based on what actually worked. That is more reliable than a design system validated only against human implementation.
Use DESIGN.md with a real product reference
Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.
Related guides
DESIGN.md for Kiro
How to use DESIGN.md with Kiro, the AWS agentic IDE built around specs, steering, hooks, and production-minded implementation.
DESIGN.md for Windsurf
How to use DESIGN.md with Windsurf and Cascade so AI edits follow your product design system instead of default editor taste.
DESIGN.md for Bolt
How DESIGN.md helps bolt.new generate full-stack browser apps with stronger UI direction, cleaner components, and less generic styling.