Codex Subagents for Design Review

The pattern

Most design reviews fail because they ask one reviewer to hold too many lenses at once.

Accessibility. Copy. First-time user clarity. Edge states. Design-system compliance. Visual hierarchy. Mobile behavior.

One agent can review all of that, but it usually averages. It finds the obvious issues and misses the quiet ones.

Codex subagents let you split the review into narrow lanes.

scope dispatch

Dispatcher Parent Codex thread Defines scope, dispatches lanes, merges findings

• Lane 01 Review A11y Contrast, keyboard, labels, semantics
• Lane 02 Review First user Can a new person understand it?
• Lane 03 Review Copy Labels, CTAs, errors, tone
• Lane 04 Review Edge states Loading, empty, error, long content
• Lane 05 Review DS rules Tokens, components, patterns

The parent thread is the editor. The subagents are specialists. You are the reviewer who decides what to fix.

When to use this

Use Codex subagents when:

• the page is important enough to deserve more than one review lens
• you have a preview URL, local app, screenshot, or component folder
• your design-system rules are available in AGENTS.md, docs, or markdown
• you need a prioritized report before shipping
• you want review depth without waiting for five sequential passes

Do not use subagents when:

• you only need one copy tweak
• you already know the problem
• the design is still a throwaway sketch
• you do not have enough context for any reviewer to judge correctly

The five review lanes

1. 01

   Accessibility

2. 02

   First user

3. 03

   Copy

4. 04

   Edge states

5. 05

   Design system

Lane 1: Accessibility reviewer

Job: find issues that can block users or create compliance risk.

Checks:

• contrast
• keyboard reachability
• visible focus
• input labels
• heading order
• button vs link semantics
• target size

Output max: 5 findings.

Lane 2: First-time user reviewer

Job: review as someone who has never seen the product.

Checks:

• page purpose
• primary action
• information hierarchy
• onboarding friction
• terms that assume internal knowledge
• whether the next step is obvious

Output max: 5 findings.

Lane 3: Copy reviewer

Job: catch language problems that make the interface feel vague or untrustworthy.

Checks:

• generic CTAs
• unclear form labels
• vague error messages
• empty states
• inconsistent terminology
• marketing words inside product UI

Output max: 5 findings.

Lane 4: Edge-state reviewer

Job: inspect what happens when the happy path breaks.

Checks:

• loading states
• empty states
• errors
• partial data
• long names
• narrow screens
• disabled and pending states

Output max: 5 findings.

Lane 5: Design-system reviewer

Job: compare the implementation against your system rules.

Checks:

• approved components
• semantic tokens
• spacing scale
• typography scale
• motion rules
• component variants
• banned patterns from AGENTS.md

Output max: 5 findings.

The parent prompt

Use this when you want Codex to run the whole panel.

Run a parallel design review using subagents.

Target:
[PASTE URL, screenshot path, or folder path]

Context:
- Read AGENTS.md and any design-system docs before reviewing.
- If a browser is available, inspect the target at desktop and mobile widths.
- Subagents are review-only. Do not edit files.

Dispatch five independent subagents:
1. Accessibility reviewer
2. First-time user reviewer
3. Copy reviewer
4. Edge-state reviewer
5. Design-system reviewer

Each subagent must return:
- Max 5 findings
- Severity: Blocking, High, Medium, Low
- Evidence
- Suggested fix
- Confidence: High, Medium, Low

After all subagents return, merge the findings into one report:
- Deduplicate overlap
- Sort by severity
- Preserve which lane found each issue
- Flag disagreements between lanes
- End with the 3 fixes I should make first

This prompt works best after you have already given Codex project rules. Without rules, the design-system reviewer has to guess.

Why read-only matters

Review and repair are different modes.

In review mode, you want broad attention and low risk. The agent should inspect, compare, and report.

In repair mode, you want narrow scope and controlled edits. The agent should fix one approved issue at a time.

Mixing them creates sloppy work. The agent finds ten problems, starts fixing three, forgets four, and leaves you with a diff that is hard to review.

The merge format

Ask the parent thread to return this:

# Design review report

## Blocking

1. Issue title
   - Found by: Accessibility, Design-system
   - Evidence:
   - Why it matters:
   - Fix:
   - Confidence:

## High

## Medium

## Low

## Disagreements

## First 3 fixes

The “Found by” line is important. If accessibility and design-system lanes both flag the same button, that issue is more likely to matter than a lone low-confidence note from one lane.

Example: pricing page review

Run a parallel design review using subagents.

Target:
http://localhost:4321/pricing

Context:
- This is a pricing page for AI Design Guide.
- The UI should feel editorial, practical, and trustworthy.
- Avoid generic SaaS polish, vague CTAs, and fake urgency.
- Read AGENTS.md if present.

Use the five-lane review panel.
Do not edit files.
Return the merged report only.

After the report comes back, pick one issue:

Fix only Blocking issue #1.

Scope:
- Edit the smallest number of files.
- Do not touch pricing logic.
- Preserve existing layout.

After editing:
- Show files changed.
- Explain the fix.
- Tell me how to verify it.

That separation keeps the review crisp and the implementation diff reviewable.

The subagent personas

If your Codex setup supports custom subagent personas, create them as durable reviewers. Keep them boring and specific.

Accessibility reviewer persona

You are an accessibility reviewer for product UI.

Mode:
- Read-only.
- Do not edit files.
- Do not comment on visual taste unless it affects accessibility.

Review:
- WCAG 2.2 AA contrast
- keyboard reachability
- focus visibility
- labels and names
- semantic controls
- target size
- heading structure

Output:
Max 5 findings. Severity, evidence, fix, confidence.

Design-system reviewer persona

You are a design-system compliance reviewer.

Mode:
- Read-only.
- Read AGENTS.md, token docs, component docs, and local design-system rules first.
- Do not invent rules.

Review:
- component reuse
- semantic token usage
- spacing scale
- typography scale
- motion rules
- banned patterns
- duplicate UI patterns

Output:
Max 5 findings. Severity, evidence, fix, confidence.
If the rule is not documented, label it as a recommendation, not a violation.

That last sentence matters. Agents love turning taste preferences into fake laws. Make them distinguish documented rules from judgment calls.

Common mistakes

Too many lanes

Ten reviewers sounds thorough. It is usually noise. Start with five. Drop to three for smaller screens.

Vague lanes

“Visual reviewer” is too broad. “Typography reviewer” or “spacing reviewer” is narrow enough to be useful.

Letting subagents merge

Subagents cannot deduplicate what they cannot see. Let each lane return its own report. The parent thread does the merge.

Asking for fixes too early

If the prompt says “review and fix everything,” the result will be hard to trust. Review first. Fix second.

Missing project context

The design-system lane needs rules. Put them in AGENTS.md, a design-system docs folder, or another project-readable file.

A three-lane version

For smaller work, use three lanes:

1. Accessibility
2. First-time user clarity
3. Design-system compliance

This catches most serious issues without overproducing review text.

Run a lightweight parallel design review with three read-only subagents:
1. Accessibility
2. First-time user clarity
3. Design-system compliance

Target: [URL or screenshot]

Each returns max 3 findings.
Parent merges, deduplicates, and gives me the top 5 fixes.

The weekly design-system review

Once the pattern works manually, turn it into a recurring workflow:

Every Friday, review the design-system preview URL with the five-lane subagent panel.

Scope:
- Homepage
- Components index
- Button docs
- Form docs
- Any changed pages from this week

Output:
- One report grouped by severity
- New issues since last week
- Issues that disappeared
- Top 3 fixes for next week

Do not automate this until the manual version has produced two useful reports. Automation multiplies whatever quality you already have.

Exercise

Run your first Codex multi-lens review

1. Pick one target

2. Add context

3. Run the five-lane parent prompt

4. Merge and choose

You are done when the report names issues you would not have caught in a single broad review.