Codex UI design that stays consistent

Codex can make one screen look good in a single pass. Consistency is harder: it's a property of two or more screens, and it only holds when the rules are written down somewhere Codex reads every time. The usual failure isn't an ugly page; it's two pages that each look fine and disagree with each other.

Example task used in this guide: an orders list and an order detail page that name the same status differently ("Shipped" vs "DISPATCHED") and style "cancel" differently.

Give Codex both screens at once

Asking Codex to "tidy up the order page" tends to create a third style. Ask for the two screens together and make the goal consistency itself: the same status has the same words and badge everywhere, and the same kind of action looks the same everywhere.

Start by having Codex list every place each screen shows a status or a cancel action, and how each looks today. In the "before" pair above, that list alone shows the problem: a green dot saying "Shipped" on one screen, a solid tag saying "DISPATCHED" on the other, and a shouting red CANCEL button that looks more important than anything else on the page.

Write the rules once

Codex reads AGENTS.md automatically. Keep it for how to work, and point it at DESIGN.md for what things should look like:

## UI work

- Before changing any screen, read DESIGN.md and follow it. If something you need isn't in it, say so instead of inventing a new style.
- Reuse the shared components in src/components/ui. Don't restyle them inside a page.
- A change to a shared component must be checked on every page that uses it.
- When a visual decision isn't covered and UXKIN is connected, look it up with find_ui_references or find_ui_materials and note which reference you used.

DESIGN.md holds the product's visual decisions. For this task the important part is a small vocabulary: which statuses exist, what each is called, how each badge looks, and how destructive actions behave.

# DESIGN.md: Orders

## Order statuses (same words and badge everywhere)
| Status          | Badge            | Meaning                         |
|-----------------|------------------|---------------------------------|
| Not shipped yet | outline, neutral | Paid, not picked yet            |
| Running late    | filled, amber    | Past the promised ship date     |
| Shipped         | filled, green    | Handed to the carrier           |
| Cancelled       | outline, muted   | Will not ship; refund started   |

Never use "Dispatched", "Pending" or a dot without text.

## Actions
- One primary (filled) button per screen, for the main next step.
- Destructive actions (Cancel order, Refund) are outlined red, end with "…" and open a confirmation. They are never the primary button.

## Exceptions
Record any exception here with the reason, so the next change doesn't undo it.

Note the exceptions section. If a screen really needs to differ, write down why. Otherwise the next change will "fix" it back, or copy it everywhere.

Start from a real design system

If you don't have a DESIGN.md yet, starting from a real one is faster than inventing one. With UXKIN connected, Codex can call find_ui_materials with a style and category, like "ecommerce light" or "dark fintech", and get real design systems with named colors and the job each color does, their fonts and components. With full access it also gets each pack's complete DESIGN.md.

Use it as a starting point, not a template: take the structure (how statuses are named and colored, how actions are ranked) and make the values yours. Your brand colors and components always win.

Review the screens side by side

• Put both pages next to each other at the same width and zoom. The same status should look identical on both.
• Check every status, including the rare ones ("Running late", "Cancelled"), not only the one in your test data.
• Try Cancel order: it asks for confirmation, and nothing else about the action changed.
• If a shared component changed, check the other pages that use it.
• Check a phone width (390px), a desktop width (1440px) and the keyboard.

Ask Codex to list anything that still differs, with the reason. Each item is either a bug to fix or an exception to record in DESIGN.md.

Set up UXKIN in Codex

The quickest way is the setup prompt from the Agent SDK tab: paste it into Codex and it does the steps below itself. To do it by hand:

1. Install the no-ui-slop skill

npx skills add https://uxkin.com --skill no-ui-slop -g -a codex -y

It installs to ~/.agents/skills/no-ui-slop, which Codex loads in every project.

2. Connect the UXKIN MCP server

Codex reads the token from an environment variable. Set UXKIN_TOKEN to the token from your setup prompt (in your shell profile, so it's there every time), then add the server:

export UXKIN_TOKEN="YOUR_UXKIN_TOKEN"
codex mcp add uxkin --url https://uxkin.com/mcp --bearer-token-env-var UXKIN_TOKEN

That writes this to ~/.codex/config.toml, which you can also edit directly. The file only names the variable, never the token:

# ~/.codex/config.toml
[mcp_servers.uxkin]
url = "https://uxkin.com/mcp"
bearer_token_env_var = "UXKIN_TOKEN"

Important: Codex only sees the variable if it exists where Codex starts. If you set it after opening Codex, or in a different terminal, the server looks configured but can't sign in. Restart Codex after setting it.

3. Check it

Run codex mcp list: uxkin should show as enabled, with UXKIN_TOKEN as its token variable. Then type /mcp inside Codex: uxkin should be listed with find_ui_references and find_ui_materials. (The list only checks the settings; /mcp shows it actually connected.) No need for a test search; the next UI task is the test.

A prompt you can use

Adapt the file paths to your project. It asks for both screens at once, uses the rules files, and ends with a side-by-side check:

Make order statuses and actions consistent between the orders list (src/app/orders/page.tsx) and the order detail page (src/app/orders/[id]/page.tsx).

Read AGENTS.md and DESIGN.md first, then list every place each screen shows a status or a Cancel action, and what it looks like today.

If UXKIN is connected and DESIGN.md doesn't cover something, use find_ui_materials (for example "ecommerce light") to see how a real design system names and colors statuses, and say what you're adopting and why.

Then:
- Use one StatusBadge component with the four statuses in DESIGN.md, on both screens.
- Make Cancel order an outlined destructive action with a confirmation on the detail page; don't make it the primary button.
- Don't change what the actions do, only how they look and are worded.

Check both pages at 390px and 1440px, and by keyboard. Show both screens side by side and list anything that still differs, with the reason.

Questions