How to make Codex better at UI design

To make Codex better at UI design, give it durable repository rules, a reusable UI workflow, focused InterfaceKit references, and access to the rendered application.

Codex can inspect code, edit files, run checks, use screenshots as context, and review a local page in the desktop browser. It still needs the product decisions that the repository cannot answer. Strong results come from combining product context with an interface system and a verification loop.

This Codex UI design tutorial configures that loop, then uses it to build a deployment history workflow for a developer product.

Choose the right Codex surface

The same repository guidance can support the Codex CLI, IDE extension, and desktop app, but the review loop differs.

Use the desktop app when you want Codex to open a local route, inspect the rendered state, and address comments placed on exact elements. Use the CLI or IDE when your existing browser and capture process already provide the screenshots.

OpenAI’s Codex best-practices guide recommends giving Codex a goal, context, constraints, and a clear definition of done. The rest of this Guide turns those four parts into a UI workflow.

Before you start

You need:

• a frontend repository that runs locally
• the route and product workflow to build
• the project’s normal development, lint, type, test, and build commands
• realistic data or fixtures
• one relevant InterfaceKit system
• access to the result at 1440px, 768px, and 390px

For the CLI, check the installed version:

codex --version

Start from the repository root so Codex discovers the intended instructions and skills.

Step 1: Define one product workflow

Do not ask Codex to “redesign the dashboard.”

Write a product contract:

Route: /deployments
User: A developer investigating a failed production deployment
Outcome: Find the failure, inspect its details, and redeploy safely
Primary action: Open deployment
Secondary action: Redeploy failed deployment
Data:
- Environment
- Commit
- Author
- Started time
- Duration
- Status
- Failure summary
Rules:
- Production redeploy requires confirmation
- Only maintainers can redeploy
- A deployment already in progress cannot be started again
Required states:
- Loading
- No deployments
- Populated history
- No filter results
- Request error
- Details open
- Redeploy confirmation
- Redeploy pending
- Redeploy success
- Redeploy error
- Permission denied
Breakpoints: 1440px, 768px, 390px
Must preserve: Existing routes, API contracts, analytics, and keyboard behavior

This contract gives Codex a product problem. Without it, a “deployment dashboard” prompt may produce attractive metrics that do not help anyone diagnose or act.

Step 2: Define done before asking for code

Turn the contract into checks:

• A developer can scan status, environment, commit, and start time.
• Failed deployments are visible without relying on color alone.
• Filters keep their relationship to the history they change.
• Opening a deployment exposes logs and the failure summary without losing list context.
• Redeploy confirmation names the environment and commit.
• Users without permission understand why redeploy is unavailable.
• Pending actions cannot submit twice.
• Loading, empty, no-results, error, and success states are reachable.
• The complete workflow works with a keyboard.
• The page preserves its information priority at all three target widths.
• Project checks pass.

Codex now has evidence it can use to decide whether the task is finished.

Step 3: Put stable UI rules in AGENTS.md

Codex reads AGENTS.md before working. OpenAI’s AGENTS.md documentation explains how global, repository, and nested instructions form a chain.

Put repository-wide UI rules in the root AGENTS.md:

# Frontend UI

- Inspect existing components before creating new ones.
- Use tokens from `src/styles/tokens.css`.
- Do not add a UI or icon library without approval.
- Preserve route, data, analytics, and accessibility behavior during visual work.
- Make loading, empty, error, success, disabled, and permission states reachable.
- Review changed UI at 1440px, 768px, and 390px.
- Do not commit generated review screenshots.
- Run `npm run lint`, `npm run test`, and `npm run build` before finishing.
- Report commands, results, renders reviewed, and remaining gaps.

Replace the paths and commands with the real project values.

If the repository contains several applications, add a nested AGENTS.md closer to the frontend:

# Web application

- Routes live in `src/routes`.
- Reuse components from `src/components`.
- Use the existing fixture system for visual states.
- Keep desktop, tablet, and mobile behavior in the same component.
- Review the running route before reporting completion.

Nested guidance should contain rules specific to that area. Do not repeat the entire root file.

Keep task-specific information out of AGENTS.md. The deployment contract and selected screenshots belong to this task, not every future task.

Step 4: Create a Codex UI design skill

Use a skill when you keep repeating the same UI process.

Shared repository skills live under .agents/skills/. Create .agents/skills/ui-implementation/SKILL.md:

---
name: ui-implementation
description: Build or improve product UI with project components, focused references, reachable states, responsive renders, and evidence-based correction.
---

# UI implementation

1. Read the product contract and applicable `AGENTS.md` files.
2. Inspect the route, component system, tokens, data conventions, and checks.
3. Map the supplied InterfaceKit references to existing project code.
4. List missing product decisions before editing.
5. Build the page frame and content hierarchy.
6. Implement the workflow and every required state.
7. Apply foundations through the existing token system.
8. Run the application and review 1440px, 768px, and 390px.
9. Compare structure, hierarchy, density, components, states, and styling.
10. Fix concrete differences and rerender.
11. Run project checks and review the diff.
12. Report evidence, deliberate deviations, and remaining gaps.

Do not add product sections, component libraries, or visual foundations that
are not supported by the task, repository, or supplied references.

OpenAI’s skills guide documents the SKILL.md format and repository path.

A useful Codex design skill owns one repeatable workflow. A generic skill that lists colors, effects, and style words will not tell Codex how to inspect, implement, or verify the product.

Invoke the skill explicitly with $ui-implementation when you want to guarantee it is part of the task. Codex can also select it when the request matches its description.

Step 5: Choose one InterfaceKit system

Browse InterfaceKit and choose a product system with comparable behavior and density.

For deployment history, collect:

• application frame
• page header
• filter toolbar
• dense resource list or table
• status treatment
• details drawer or panel
• destructive confirmation
• error and success feedback
• typography, spacing, color, border, and radius foundations

Create a reference map:

Do not ask Codex to combine arbitrary pieces from several products. One coherent system provides relationships between page, component, and foundation decisions.

Step 6: Give Codex focused context

The task should name the files and references that matter:

$ui-implementation

Goal
Build the deployment history workflow defined in
docs/deployment-history-contract.md.

Context
- src/routes/deployments.tsx
- src/components/Button.tsx
- src/components/Drawer.tsx
- src/components/StatusBadge.tsx
- src/styles/tokens.css
- the supplied InterfaceKit frame, resource-list, drawer, confirmation,
  and foundation references

Constraints
- Reuse existing components and tokens.
- Preserve API contracts, analytics, and keyboard behavior.
- Do not add dashboard metrics or activity panels.
- Do not install another UI or icon library.

Done when
- Every required state is reachable.
- The workflow works at 1440px, 768px, and 390px.
- Keyboard and focus behavior are verified.
- Project checks pass.
- The final report includes rendered and command evidence.

Use exact paths from the repository. Do not attach the whole design library when the task depends on a small set of entries.

Step 7: Plan before editing

For a multi-file UI workflow, use Plan mode with /plan or the Plan mode control in the Codex surface.

Ask Codex to inspect before it writes:

Read the applicable AGENTS.md files, product contract, target route,
existing components, tokens, and supplied references.
Do not edit yet.

Return:
1. Current route and data flow.
2. Components and foundations to reuse.
3. Reference patterns mapped to project code.
4. Missing product decisions.
5. State transitions for details and redeploy.
6. Responsive behavior at 1440px, 768px, and 390px.
7. Accessibility risks.
8. An implementation and verification plan.

Name every new component or variant you expect to add.

Review the plan. Ask why a new component is necessary when an existing one appears close. Remove sections that do not serve the product contract.

Planning is not required for every small change. It is useful here because the task connects several states, files, and review steps.

Step 8: Build in three passes

Separate structure, behavior, and visual foundations so each pass can be reviewed.

Pass 1: Frame and hierarchy

Implement only the deployment page frame and static content structure.

Reuse the existing application shell.
Apply the supplied content rail, page-header alignment, filter position,
history structure, details region, and responsive layout.
Use realistic deployment content.

Do not connect redeploy or tune decorative details yet.
Run the app and review 1440px, 768px, and 390px.
Report hierarchy, overflow, and reuse problems.

The page should make the failure investigation path clear before visual polish.

Pass 2: Workflow and states

Implement the deployment history workflow through the existing data,
permission, and mutation patterns.

Support loading, no-deployments, populated, no-filter-results,
request-error, details-open, redeploy-confirmation, redeploy-pending,
redeploy-success, redeploy-error, and permission-denied states.

Make every state reachable for review.
Preserve focus when the details panel and confirmation open and close.
Prevent duplicate redeploy requests.
Do not add visual foundations in this pass.

Interact with each state in the running application. A state listed in code but unavailable to review is not verified.

Pass 3: Foundations and polish

Apply the supplied typography, spacing, color roles, borders, radius,
and elevation through the project token system.

Compare the running page with the labeled references.
Correct component density, hierarchy, alignment, and responsive behavior.
Preserve every verified state and interaction.

Rerender at 1440px, 768px, and 390px.
List each correction and the evidence behind it.

This order keeps a polished first screenshot from hiding missing product behavior.

Step 9: Use image inputs when the browser is not shared

Codex accepts screenshots and other images as context. OpenAI’s image-input documentation shows how to label the image and state the intended result.

In the CLI, pass one or more images:

codex -i reference.png,current.png \
  "Compare the deployment page with the reference. List structural and responsive differences before editing."

Use real local image paths. When several images are attached, identify which one is the reference and which one is the current render.

Do not ask Codex to copy a screenshot without explaining the product. A screenshot cannot reveal data contracts, permissions, focus order, or missing states.

Step 10: Review the local app in the desktop browser

The Codex desktop app can share a local browser with the task. OpenAI’s browser documentation describes using it to inspect rendered state, take screenshots, leave comments, and verify changes.

Use this loop:

1. Ask Codex to start or confirm the development server.
2. Open the exact local route.
3. Put the page into the state you want to review.
4. Check desktop, tablet, and mobile widths.
5. Leave comments on exact elements or regions.
6. Ask Codex to address only those comments.
7. Review the route again after the change.

A useful browser comment names the problem, desired result, and boundary:

At 768px this filter row pushes the deployment history below the first
viewport. Keep environment and status available, move secondary filters
into the overflow menu, and do not change desktop behavior.

Then ask:

Address the browser comments on the deployment page.
Preserve the existing route, data flow, component APIs, and verified states.
Rerun the affected checks and review the same widths again.

The element selection, route, and current state give Codex more useful context than “this page still feels wrong.”

Step 11: Make every state reachable

Create a review matrix:

Use the repository’s established fixture, story, preview, test-data, or development-state mechanism. Ask Codex to propose the smallest local-only option if the project has none.

Step 12: Correct Codex with evidence

Use four parts:

Observed problem
At 390px the commit, environment, and failure status are split across
three disconnected rows. The redeploy action appears before the failure summary.

Reference
The supplied compact resource pattern keeps identifier and status together,
then places the summary before actions.

Required change
Group commit and status in the first row, move environment into supporting
metadata, and place redeploy after the failure summary.

Constraints
Keep desktop structure, data fields, component APIs, and keyboard order.
Rerender at 390px and 430px.

Correct issues in this order:

1. Missing or wrong behavior.
2. Page structure and information hierarchy.
3. Responsive failure and overflow.
4. Component misuse.
5. Typography and spacing.
6. Color, borders, radius, shadow, icons, and motion.

This prevents surface polish from consuming the review while the workflow is still wrong.

Step 13: Review the diff and verification evidence

Use the Codex diff panel or your normal Git diff before accepting the task.

The final report should include:

• files changed
• existing components reused
• components or variants added
• states reviewed and how they were reached
• viewport sizes inspected
• screenshots or browser comments addressed
• keyboard workflow result
• lint, type, test, and build commands with results
• deliberate deviations from the reference
• anything that remains unverified

Ask Codex to show command output and rendered evidence instead of only stating that the task is complete.

Step 14: Apply the system to a second route

Use the same frame, list density, status language, details pattern, feedback, and responsive rules for project activity or environment history.

Ask Codex to report:

• which parts were reused
• which existing variant needed extension
• which new product decision was unavoidable
• which page-local styles can now be removed

A strong deployment page may still be one composition. A related route reveals whether Codex built a reusable product system.

What to do when Codex UI is still weak

Direct answers about Codex UI design

How do I make Codex more effective?

Give Codex a goal, focused context, explicit constraints, and observable done criteria. Store repeated repository rules in AGENTS.md, package the UI process as a skill, and let Codex inspect and verify the running result.

How do I make the best use of Codex?

Use Codex for repository inspection, implementation, repeated state work, test execution, visual comparison, and bounded correction. Keep product priority and final design judgment explicit.

Is Codex good for frontend?

Codex is useful for frontend implementation when it can inspect the existing application, reuse the component system, run the project, view or receive screenshots, and verify behavior. A vague visual prompt does not use those strengths.

What are the best design skills for Codex?

The best Codex design skill defines one repeatable outcome with clear inputs, steps, verification, and output. For UI, that means inspecting context, mapping references, building the workflow, reviewing responsive renders, correcting evidence, and running project checks.

A Codex frontend design skill should improve the process, not replace the project’s visual system. A Codex UI design skill that only changes surface styling is too narrow to produce a complete interface.

What should a Codex UI design prompt include?

Include the product goal, relevant files and references, constraints, required states, breakpoint sizes, checks, and the evidence Codex must report. Tell Codex what it may decide and what it must preserve.

Codex frontend checklist

• The chosen Codex surface supports the intended review loop.
• The task defines one user, outcome, workflow, and state set.
• Done criteria describe observable behavior.
• Root and nested AGENTS.md files contain scoped durable rules.
• The UI skill lives under .agents/skills/ and has a precise description.
• One InterfaceKit system owns the visual direction.
• Files, references, and screenshots are focused.
• Codex inspects and plans before a multi-file edit.
• Structure, behavior, and styling are separate passes.
• Every required state is reachable.
• Desktop, tablet, mobile, and intermediate widths are reviewed.
• Browser comments name exact problems and preserved behavior.
• Keyboard behavior and accessibility are checked.
• The diff and project commands are reviewed.
• The final report includes evidence and gaps.
• A second route tests whether the system is reusable.

Continue with How to prompt AI for UI design, or compare the same workflow in Claude Code, Gemini, Kimi, or Cursor.

Browse InterfaceKit and give Codex a coherent product system to apply.