DESIGN.md + Codex

Why Codex CLI + DESIGN.md Is Powerful

Codex CLI has three operating modes:

• suggest - suggests and waits for approval (like Copilot in the terminal)
• auto-edit - edits files but asks OK for commands
• full-auto - does everything on its own, without interruption

In full-auto mode, DESIGN.md is the only visual safeguard. Without it, the agent runs on the model’s creativity. With it, every edit respects the design system even when you’re not watching.

Other advantages:

1. Native AGENTS.md - Codex CLI reads this file by design. It’s the official instruction mechanism.
2. Sandbox - executes in an isolated environment. You can let it generate 10 components and review afterward.
3. Git-aware - makes granular commits. Easy to revert a component that drifted.
4. Repository context - it sees the full structure. Knows where components, styles, and configs live.

Step by Step Setup

1. Install Codex CLI

npm install -g @openai/codex

Configure the API key:

export OPENAI_API_KEY="sk-..."

Or in the configuration file ~/.codex/config.yaml:

model: o4-mini
api_key_env: OPENAI_API_KEY

2. Project structure

my-project/
├── DESIGN.md          ← Design tokens + rationale
├── AGENTS.md          ← Instructions for Codex CLI
├── CODEX.md           ← Codex-specific instructions (alternative)
├── src/
│   └── components/
├── package.json
└── ...

3. Create AGENTS.md

AGENTS.md is the file Codex CLI reads automatically on every execution. It’s the equivalent of Cline’s .clinerules, but with a name standardized across the OpenAI ecosystem.

# AGENTS.md

## Design System

This project uses the DESIGN.md format to define visual rules.
The DESIGN.md file at the root is the source of truth for all UI decisions.

### Mandatory instructions for UI

1. BEFORE generating any visual component, read DESIGN.md completely
2. Use EXCLUSIVELY the tokens defined in the YAML front matter
3. Follow the typographic scale without inventing intermediate sizes
4. Spacing must be multiples of the base value
5. Every interactive element needs: hover, focus, disabled
6. The "Constraints" section of DESIGN.md is inviolable

### Quick token reference (DESIGN.md summary)

For quick reference when context is limited:

- Primary: #1A73E8
- Secondary: #34A853
- Background: #F8F9FA
- Surface: #FFFFFF
- Text Primary: #202124
- Text Secondary: #5F6368
- Error: #D93025
- Font: Inter
- Base spacing: 8px
- Border radius: 4/8/16/9999px

### Code conventions

- TypeScript strict
- React functional components with named exports
- Tailwind CSS utility-first
- One component per file
- Explicit Props interface

### Files that must NOT be edited

- DESIGN.md (read-only, source of truth)
- AGENTS.md (this file)
- package-lock.json (managed by npm)

4. DESIGN.md as reference

Keep DESIGN.md concise for Codex CLI. The agent operates with limited token budget in the sandbox. Prioritize structured data over prose:

---
colors:
  primary: "#1A73E8"
  secondary: "#34A853"
  surface: "#FFFFFF"
  background: "#F8F9FA"
  text-primary: "#202124"
  text-secondary: "#5F6368"
  error: "#D93025"
  warning: "#F9AB00"
  success: "#34A853"
typography:
  font-family: "Inter, system-ui, sans-serif"
  scale: [12, 14, 16, 20, 24, 32, 40, 48]
  weight-regular: 400
  weight-medium: 500
  weight-bold: 700
  line-height-body: 1.6
  line-height-heading: 1.2
spacing:
  base: 8
  scale: [4, 8, 12, 16, 24, 32, 48, 64]
radius:
  sm: 4
  md: 8
  lg: 16
  full: 9999
shadows:
  sm: "0 1px 2px rgba(0,0,0,0.05)"
  md: "0 4px 6px rgba(0,0,0,0.07)"
  lg: "0 10px 15px rgba(0,0,0,0.1)"
---

# Design System

Clean, functional interface. Hierarchy through typography. Color reserved for actions.

## Components

### Primary Button
- Background: primary, text: white, radius: md, padding: 12px 24px
- Hover: darken 10%, Focus: ring 2px primary, Disabled: opacity 50%

### Secondary Button
- Background: transparent, border: 1px primary, text: primary
- Hover: background primary/5%, Focus: ring 2px primary

### Card
- Background: surface, radius: lg, padding: 24px, shadow: sm
- Hover: shadow md (transition 200ms)

### Input
- Border: 1px text-secondary/30%, radius: md, padding: 12px 16px
- Focus: border primary, ring 1px primary
- Error: border error, error text below

## Constraints

- No gradients
- Maximum 2 font-weights per component
- Icons: stroke only, 1.5px
- No text-decoration beyond links
- No opacity to create colors (use tokens)

5. Run Codex CLI

# Interactive mode (suggests and waits)
codex "Create a user profile card component with avatar, name, role and follow button"

# Auto-edit mode (edits files, asks OK for commands)
codex --mode auto-edit "Create landing page components: Hero, Features, Testimonials, CTA"

# Full-auto mode (complete sandbox)
codex --mode full-auto "Implement all base design system components defined in DESIGN.md"

Concrete Usage Example

codex --mode auto-edit "Create a responsive Navbar component with: logo left, 
centered navigation links, login button right. Mobile: hamburger menu. 
Strictly follow DESIGN.md."

Codex CLI reads AGENTS.md, sees the instruction to read DESIGN.md, extracts tokens and generates:

// src/components/Navbar.tsx
import { useState } from 'react';
import { Menu, X } from 'lucide-react';

interface NavLink {
  label: string;
  href: string;
}

interface NavbarProps {
  logo: React.ReactNode;
  links: NavLink[];
  onLogin: () => void;
}

export function Navbar({ logo, links, onLogin }: NavbarProps) {
  const [mobileOpen, setMobileOpen] = useState(false);

  return (
    <nav className="bg-white border-b border-[#5F6368]/10">
      <div className="max-w-7xl mx-auto px-6 h-16 flex items-center justify-between">
        {/* Logo */}
        <div className="flex-shrink-0">
          {logo}
        </div>

        {/* Desktop links */}
        <div className="hidden md:flex items-center gap-8">
          {links.map((link) => (
            <a
              key={link.href}
              href={link.href}
              className="text-sm text-[#5F6368] hover:text-[#202124] transition-colors"
            >
              {link.label}
            </a>
          ))}
        </div>

        {/* Login button */}
        <div className="hidden md:block">
          <button
            onClick={onLogin}
            className="
              px-4 py-2 text-sm font-medium
              bg-[#1A73E8] text-white rounded-lg
              hover:bg-[#1557B0]
              focus:ring-2 focus:ring-offset-2 focus:ring-[#1A73E8]
              transition-colors
            "
          >
            Login
          </button>
        </div>

        {/* Mobile toggle */}
        <button
          className="md:hidden p-2 text-[#5F6368]"
          onClick={() => setMobileOpen(!mobileOpen)}
        >
          {mobileOpen ? <X size={24} /> : <Menu size={24} />}
        </button>
      </div>

      {/* Mobile menu */}
      {mobileOpen && (
        <div className="md:hidden border-t border-[#5F6368]/10 bg-white">
          <div className="px-6 py-4 space-y-3">
            {links.map((link) => (
              <a
                key={link.href}
                href={link.href}
                className="block text-sm text-[#5F6368] hover:text-[#202124]"
              >
                {link.label}
              </a>
            ))}
            <button
              onClick={onLogin}
              className="
                w-full mt-4 px-4 py-3 text-sm font-medium
                bg-[#1A73E8] text-white rounded-lg
                hover:bg-[#1557B0] transition-colors
              "
            >
              Login
            </button>
          </div>
        </div>
      )}
    </nav>
  );
}

Tokens applied correctly: colors from the palette, radius rounded-lg (md: 8), spacing in multiples of 4/8, stroke icons (Lucide uses stroke by default), hover and focus states on the button.

Codex CLI-Specific Tips

Use full-auto for component batches

Full-auto mode shines when you want to generate multiple components at once:

codex --mode full-auto "Create all atomic design system components: 
Button (primary, secondary, ghost), Input, Textarea, Select, Checkbox, Radio, 
Toggle, Badge, Avatar, Tooltip. One file per component in src/components/. 
Follow DESIGN.md rigorously."

It generates all of them in sequence, using the same tokens. Consistency guaranteed.

Hierarchical AGENTS.md

Codex CLI supports AGENTS.md in subdirectories. Use them for local rules:

# src/components/AGENTS.md

## Component rules

- Export Props interfaces separately (for reuse)
- Add JSDoc with component description
- Include `className` prop for override via Tailwind merge
- Test accessibility: aria-labels, roles, keyboard navigation

Token summary in AGENTS.md

For projects where DESIGN.md is extensive, place a compact summary directly in AGENTS.md:

### Quick reference (from DESIGN.md)

| Token | Value |
|-------|-------|
| primary | #1A73E8 |
| text | #202124 |
| muted | #5F6368 |
| bg | #F8F9FA |
| radius | 8px |
| spacing | 8px base |

Codex always reads AGENTS.md. DESIGN.md might get truncated in limited contexts. The AGENTS.md summary is a fallback.

Combine with CODEX.md

If the project already has a generic AGENTS.md for multiple agents, create a CODEX.md specifically for Codex CLI:

# CODEX.md

Instructions specific to OpenAI Codex CLI for this project.

## Priorities

1. Read DESIGN.md for any visual work
2. Granular commits: one component = one commit
3. Run lint after each edit
4. Do not install dependencies without approval

Sandbox as protection

Full-auto mode runs in a sandbox. This means Codex doesn’t affect your repo until you accept the changes. Use this to your advantage:

1. Run a batch of generations
2. Review generated files
3. Accept only those that followed DESIGN.md
4. Reject and re-instruct those that drifted

Troubleshooting and Gotchas

Codex doesn’t read AGENTS.md

Check:

• The file is at the repository root
• The name is exactly AGENTS.md (case-sensitive)
• Codex is being executed at the project root
• The version is up to date: npm update -g @openai/codex

Limited context truncates DESIGN.md

The Codex sandbox has a token budget. If DESIGN.md gets truncated:

1. Keep it below 2000 tokens
2. Put the most critical tokens in the YAML front matter (read first)
3. Use the AGENTS.md summary as fallback
4. Remove extended prose because Codex needs data, not explanations

Full-auto generates inconsistent components

In large batches, Codex can “forget” tokens as it progresses through the generation. Solutions:

1. Split into smaller batches (3-5 components per execution)
2. Add to AGENTS.md: “Reread DESIGN.md before EACH component”
3. Use --mode auto-edit instead of full-auto so you can review each component

Codex installs unexpected packages

In full-auto, it might run npm install for dependencies it deems necessary. Control via AGENTS.md:

## Dependencies

Allowed dependencies for visual components:
- lucide-react (icons)
- clsx (conditional classes)
- tailwind-merge (class merge)

Do NOT install without approval:
- Component libraries (shadcn, radix, MUI, Chakra)
- CSS-in-JS (styled-components, emotion)
- Any other UI lib

Large diff hard to review

If Codex generates many files at once, use git to review:

git diff --stat        # See which files changed
git diff -- src/components/Button.tsx  # Review one by one
git add -p             # Selective staging

Mental Model: AGENTS.md as Briefing

Think of AGENTS.md as the briefing you would give a new developer joining the team:

1. “Here’s our design system” (pointing to DESIGN.md)
2. “These are the rules you cannot break” (Constraints)
3. “This is the code pattern we use” (Conventions)
4. “These files are off limits” (Read-only)

Codex CLI is that new developer. AGENTS.md is its onboarding. DESIGN.md is the visual guide. Together, they transform a generic agent into one that generates code matching your team’s standards.

Conclusion and Next Step

Codex CLI with DESIGN.md is for developers who want heavy automation. Generate 10, 20, 50 components in batch, all following the same design system, without opening an IDE. AGENTS.md ensures the agent reads the rules before every action. The sandbox enables review without risk.

The key is keeping DESIGN.md concise and AGENTS.md assertive. Less prose, more data. Less “it would be nice if,” more “do exactly this.” Codex is obedient when instructions are clear.

Next steps:

• What is DESIGN.md - complete format specification
• DESIGN.md Library - 450+ ready-made design systems
• Guides for other agents: Aider · Cline · Devin · Continue.dev