Design skills for coding agents: how to get better UIs from Claude Code and Codex

Ask Claude Code or Codex for a landing page and you will get something that works. It is responsive, it has a hero, it has cards. It also looks like every other page an agent has built this year. Anthropic describes the cause in its post on frontend design: without guidance, models land on safe choices that dominate web training data, such as Inter, purple gradients on white and minimal motion. The model is capable of better design. What it needs are rules, a vocabulary and a way to look at its own work. This guide shows how to give it all three, in Claude Code and in Codex, with files you can copy.

Why agent-built UIs end up looking alike

A coding agent begins every session with no taste of its own for your project. It sees your prompt, your code and whatever instruction files it loads. If none of those say "our headlines use this typeface at this size", the agent goes with the most likely answer, and the most likely answer is the average of the web. That is why the fix is not a cleverer prompt each time, but written context the agent reads every time.

1Step 1: Put the non-negotiables into CLAUDE.md or AGENTS.md

Both agents read a project instruction file when a session starts.

• Claude Code reads CLAUDE.md (or .claude/CLAUDE.md) in your project, plus ~/.claude/CLAUDE.md for personal rules. Anthropic's docs advise keeping each file below 200 lines, since longer files eat context and weaken adherence.
• Codex reads AGENTS.md, walking from the repository root down to your working directory and concatenating what it finds, plus ~/.codex/AGENTS.md globally. The combined size is capped at 32 KiB by default.
• Both: current Claude Code versions read AGENTS.md when there is no CLAUDE.md. If you keep both, place @AGENTS.md at the top of CLAUDE.md to import it, and a single file serves both agents.

Hold on to only the rules that apply to every UI task. Specific, checkable lines do the job; "make it look nice" does not.

## Design
- Styles come from src/styles/tokens.css. No raw hex values, font names or pixel sizes in components.
- Two typefaces: display for headlines, body for everything else.
- Use the brand-ui skill for any work on pages, components or layout.
- A UI change is done only after screenshots at 390 px and 1440 px were checked against that skill.

2Step 2: Turn your design system into tokens

Rules written in prose get interpreted. Tokens written in code get used. Define your fonts, colors, type sizes and spacing once, and instruct the agent to use nothing else. In Tailwind CSS v4, variables in @theme turn into utilities: --font-display gives you font-display, --color-accent gives you bg-accent and text-accent.

@import "tailwindcss";

@theme {
  --font-display: "Fraunces", Georgia, serif;
  --font-body: "Instrument Sans", system-ui, sans-serif;

  --color-ink: #1b1b3a;
  --color-paper: #f5f7ff;
  --color-accent: #0f7b6c;
  --color-muted: #5c6178;

  --text-display: 4rem;
  --spacing: 0.25rem;
}

Fraunces and Instrument Sans are open-source Google Fonts, used here purely as examples. If you are not on Tailwind, place the same values in :root as CSS custom properties. The idea stays the same: the agent chooses from your list rather than from its habits.

3Step 3: Write your own design skill

A skill is a folder containing a SKILL.md file: YAML frontmatter with a name and a description, followed by Markdown instructions. Claude Code and Codex both follow the open Agent Skills standard, so a single file can serve both.

Here is how the agent works with it: at the start of a session it only sees the name and description of each skill. When your task matches that description, it pulls in the full instructions. That is what lets a skill carry far more detail than CLAUDE.md or AGENTS.md without spending context on every turn. You can also invoke it yourself: /brand-ui in Claude Code, $brand-ui in Codex.

Where the file lives:

• Claude Code: .claude/skills/brand-ui/SKILL.md in the project, or ~/.claude/skills/brand-ui/SKILL.md across all your projects.
• Codex: .agents/skills/brand-ui/SKILL.md in the repository, or ~/.agents/skills/brand-ui/SKILL.md across all your projects.

Both tools accept a symlinked skill folder, so you can maintain one copy and link it into the other spot. According to the standard, the name uses lowercase letters, digits and hyphens, matches the folder name and stays within 64 characters; the description stays within 1,024 characters and explains when to use the skill.

---
name: brand-ui
description: Design rules for this product's interface. Use when building or restyling pages, components or layouts, and when choosing fonts, colors or spacing.
---

# Brand UI

Read src/styles/tokens.css before writing styles. Use only its tokens.

## Typography
- Headlines use font-display, everything else font-body. No third family.
- Type scale in px: 14, 16, 20, 28, 40, 64. Body text at least 16 px, line-height 1.5.
- Body text lines stay under 70 characters (max-width: 65ch).
- Headlines get tight tracking (-0.02em). No all-caps labels.

## Spacing and layout
- Spacing follows the 4 px scale: 4, 8, 12, 16, 24, 32, 48, 64, 96.
- Sections get at least 96 px vertical padding on desktop.
- Left-align text. Center only the hero headline.

## Color
- One accent color, used for the primary action and nothing else.
- Body text reaches at least 4.5:1 contrast against its background.

## Before you finish
- Take screenshots at 390 px and 1440 px, compare them with these rules and fix what does not match.
- Name any rule you broke on purpose and why.

4Step 4: Install a design skill someone else already wrote

You do not have to begin from scratch.

• Anthropic's frontend-design skill is available as a plugin in Claude Code's official marketplace: run /plugin install frontend-design@claude-plugins-official. The same SKILL.md is published in the anthropics/skills repository on GitHub under skills/frontend-design, released under the Apache 2.0 license. It tells the agent to pick typefaces deliberately instead of defaulting, to establish a clear type scale, to keep lines under 80 characters, and to plan a compact token system of 4 to 6 named colors before writing any code. It also names the typical tells of generated pages, like all-caps labels above every heading.
• For Codex, OpenAI's plugin catalog offers Build Web Apps, whose frontend-app-builder skill starts from a design concept and checks the result in a browser. In the Codex CLI, /plugins opens the plugin browser.

Read any shared skill once before installing it. Then layer your own brand-ui skill on top: general skills raise the floor, while your skill makes the result yours.

5Step 5: Close the loop with screenshots

An agent that cannot see its output only knows that the code compiles. Anthropic's best-practice docs say it plainly: give Claude a check it can run, and for UI work that check is a screenshot compared against a design.

• Claude Code: paste an image into the prompt or drag it in. With the Claude in Chrome extension (claude --chrome), Claude can open your local site, capture screenshots and read console errors. This requires a direct Anthropic plan such as Pro or Max.
• Codex: attach images with codex -i screenshot.png "..." or paste them into the composer. For its own checks, Codex can use a screenshot tool or a browser, for example through Playwright.

One prompt that works in both tools:

Prompt for your agent

Here is the reference design. Build this page with our tokens, then take screenshots at 390 px and 1440 px, compare them with the reference and the brand-ui skill, list every difference and fix it before you report back.

What good design instructions sound like

What separates a vague instruction from a useful one is whether you could check it.

• Typography: not "use a nice font", but "headlines in font-display at 64 px, weight 600, tracking -0.02em; body at 16 px, line-height 1.5".
• Spacing: not "more whitespace", but "96 px between sections, 24 px between a heading and its text".
• Color: not "make it pop", but "one accent, only on the primary button and links".
• References: not "like Stripe", but a screenshot plus the three things you want from it: the type contrast, the density, the calm backgrounds.

Start with the type

If you only change one thing, change the typeface. Colors and spacing matter, but type is what readers look at on every single line, and it is where agent-built pages resemble each other the most. Anthropic's own skill says it in one sentence: typography carries the personality of the page. Put the fonts into your tokens, name their roles in your skill, and the rest of the design becomes easier to judge.

Questions people ask

What is the difference between a skill and CLAUDE.md or AGENTS.md? CLAUDE.md and AGENTS.md load in every session, so they fit short rules that always apply. A skill loads only when the task calls for it, so it can carry the detailed design system without spending context on unrelated work.

Does the same SKILL.md work in Claude Code and Codex? Yes, as long as you stick to the fields of the Agent Skills standard, such as name and description. Place the folder in .claude/skills/ for Claude Code and .agents/skills/ for Codex, or symlink one to the other.

Why does my agent keep using Inter and purple gradients? Because nothing in its context tells it otherwise, and those are the most common choices on the web. Tokens, a design skill and a screenshot check replace the default with your own decision.

Is Anthropic's frontend-design skill free to use? Yes. It is released under the Apache 2.0 license and installs from Claude Code's official plugin marketplace.

A typeface your agent makes for the project

All the steps in this guide run into the same limit: your agent can choose fonts well, but it can only choose from fonts that already exist, and so can everyone else's agent. MakeFont is building the missing piece: a skill and an MCP server that let your agent create a typeface for your project, one nobody else has, and drop it into your tokens like any other font. It is in development and not available yet. Early access is open, and What is MakeFont explains the idea.