Frontend Design skill for Codex

Done well means a stranger can name the direction in three words from one screenshot, every visual choice traces back to that direction, and the page still ships: AA contrast, real states, no horizontal scroll at 360 px, and reduced motion respected. Pretty but untraceable is decoration; traceable but broken is a mood board.

Before touching anything

• Read AGENTS.md and the package manifest: framework, CSS approach (Tailwind, CSS modules, vanilla), component library, and the dev-server command.
• Look for an existing design system: tokens files, tailwind.config.* or @theme blocks, a components/ui folder, Storybook. Decide with this table:

Situation	Where distinctiveness comes from
Greenfield page or prototype	Everything: direction, type, palette, layout, motion
Existing brand, no system	Keep logo and brand hue; push type, composition, imagery
Mature design system	Composition, content hierarchy, imagery, one sanctioned accent move. Never fork tokens
User supplied a mockup	Fidelity first; only fill gaps with the mockup’s own logic

• Find the real content: product name, actual copy, screenshots, data. Lorem ipsum hides hierarchy problems; write plausible specific copy if none exists and mark it as draft.

Workflow

- [ ] 1. Extract the brief (audience, single job, tone, constraints)
- [ ] 2. Commit to a direction and write the direction card
- [ ] 3. Set type
- [ ] 4. Build the palette in OKLCH
- [ ] 5. Choose the compositional system
- [ ] 6. Add texture and detail
- [ ] 7. Design motion
- [ ] 8. Build: tokens first, then sections, then states
- [ ] 9. Screenshot critique loop (max 3 rounds)
- [ ] 10. Report with the output contract

1. Extract the brief

Write four lines before any code: who is looking, the one thing the page must get them to do or understand, three tone words, and hard constraints (brand colors, framework, dark mode, performance budget). If the user gave none of this, choose and state your assumptions in one sentence rather than asking a questionnaire.

2. Commit to a direction

Generate three candidate directions, then pick the one with the most tension against the category default (a payroll tool styled like a Swiss railway timetable beats one styled like every other payroll tool). For named, ready-to-use directions with type, color and layout recipes, read references/directions.md when you need a starting point or the brief gives no aesthetic cue.

Write the direction card into your notes and keep it open for every later decision:

Direction: Lab notebook
Words: precise, warm, annotated
World it borrows from: graph paper, margin notes, specimen labels
Signature move: hand-set margin annotations that point at product UI
Type: Newsreader (display, text) + IBM Plex Mono (labels, data)
Palette: warm paper neutral, graphite ink, one oxide-red accent
Banned here: gradients, glass, pill buttons, drop shadows

The signature move is the one thing someone remembers. Every page gets exactly one; two signature moves compete and both read as noise.

3. Type

Type carries most of the personality. Rules:

• Pair by contrast of role, not similarity: a characterful display face with a sober text face, or one superfamily used at extreme size contrast. Never two similar sans serifs.
• Display sizes are where the direction shows: go large (clamp up to 4.5–8rem for heroes) with tight leading (0.9–1.05) and negative tracking (-0.02em to -0.04em) on big sans.
• Body: 16–20 px, line-height 1.45–1.65, measure 55–75ch (max-width: 65ch).
• All-caps labels need +0.06em to +0.12em tracking and a smaller size.
• Use real weights from the font (load only the ones used) and font-variant-numeric: tabular-nums for any number that changes or aligns.

If you reached for	Try instead (by direction)
Inter / Roboto / system for headlines	Editorial: Instrument Serif, Fraunces, Newsreader. Technical: Martian Mono, JetBrains Mono. Bold: Bricolage Grotesque, Unbounded, Archivo (wide/expanded widths)
Poppins / Montserrat for “friendly”	Hanken Grotesk, Schibsted Grotesk, Young Serif, General Sans (Fontshare)
A single sans for everything	Display serif + grotesk text, or grotesk + mono for labels

Load fonts with font-display: swap, self-host or use Google Fonts CSS2 with only the needed axes, and preload the display face if it is above the fold. Fetching fonts needs network; if the sandbox has it off, add the <link>/@font-face and a good fallback stack, and tell the user the font downloads at runtime.

4. Palette in OKLCH

Build colors where lightness is perceptual, so steps look even and hue swaps keep contrast:

:root {
  /* neutral with temperature: chroma 0.005-0.02, never pure gray */
  --paper: oklch(0.97 0.012 85);
  --paper-2: oklch(0.93 0.015 85);
  --ink: oklch(0.22 0.02 60);
  --ink-muted: oklch(0.45 0.02 60);
  --rule: oklch(0.85 0.015 85);
  /* one accent, used on at most ~10% of any viewport */
  --accent: oklch(0.58 0.17 35);
  --accent-ink: oklch(0.98 0.01 35);
}

• Dominant neutral 70–85% of surface, secondary neutral for bands, accent for the single action and the signature move. Accent everywhere means accent nowhere.
• Tint shadows and borders with the neutral hue instead of black at low alpha.
• Check text contrast: 4.5:1 body, 3:1 large text and UI boundaries. For ramps, semantic roles and contrast scripts, hand off to color-systems.

5. Compositional system

Pick one and say it in the direction card:

System	Use when	Key move
Asymmetric 12-col	Product marketing, portfolios	Content spans 7 + offset 1, images bleed off one edge
Editorial with margin column	Long reads, docs-like products	Narrow side column for notes, captions, numbers
Full-bleed bands	Story told in chapters	Alternate surface color per band, vary band height
Index / table	Catalogs, changelogs, data products	Rows, hairline rules, mono metadata, no cards
Poster	Launches, events	One giant type lockup, image as background plane
Bento	Genuinely heterogeneous items of unequal weight	Unequal cell sizes; never 6 equal tiles

.page {
  display: grid;
  grid-template-columns:
    [full-start] minmax(1rem, 1fr)
    [content-start] repeat(12, minmax(0, 5.5rem))
    [content-end] minmax(1rem, 1fr) [full-end];
  column-gap: clamp(1rem, 2vw, 2rem);
}
.page > * { grid-column: content; }
.bleed { grid-column: full; }
.lede { grid-column: content-start / span 7; }

Break the grid once, on purpose (an image crossing a band edge, a number hanging into the margin). Spacing comes from one scale (for example 4, 8, 12, 16, 24, 32, 48, 64, 96, 128) with section padding at the large end; cramped sections are the most common amateur tell. Deeper grid and rhythm decisions belong to layout-grids.

6. Texture and detail

• Choose one corner personality for the whole page: 0 (architectural), 2–4 px (precise), or very large (soft). Mixing 8 px cards with pill buttons with square images is noise.
• Separate with rules, surface shifts or whitespace before shadows. If shadows, use two layers tinted with the neutral hue.
• Grain lifts flat color without a gradient:

.grain::after {
  content: ""; position: absolute; inset: 0; pointer-events: none; opacity: .08;
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.8' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
}

• Prefer real product UI, photography or diagrams over generic 3D blobs and stock people. Crop product screenshots tight on the interesting part; a full app screenshot at 30% scale shows nothing.
• One icon family, one stroke weight, sized to the text it sits beside.

7. Motion

One orchestrated moment beats twenty scattered effects:

@media (prefers-reduced-motion: no-preference) {
  .reveal > * {
    animation: rise 600ms cubic-bezier(.2, .7, .2, 1) both;
    animation-delay: calc(var(--i, 0) * 70ms);
  }
}
@keyframes rise { from { opacity: 0; translate: 0 12px; } }

• Hover and press feedback 120–200 ms; entrances 400–700 ms; never animate layout properties (width, top) when transform/translate/opacity will do.
• Scroll effects only where they explain something (a diagram assembling, a number counting to its real value). Detailed state feedback belongs to micro-interactions.

8. Build

1. Tokens first (custom properties or @theme), then layout shell, then sections top to bottom, then states.
2. Semantic HTML: one h1, landmarks, buttons for actions and links for navigation.
3. Every interactive element gets hover, :focus-visible, active and disabled styles.
4. Test at 360, 768, 1440 px. Type and spacing use clamp(); nothing relies on a fixed viewport height for content.

9. Screenshot critique loop

Run the dev server (per AGENTS.md), then capture. Playwright browsers need a one-time npx playwright install chromium, which downloads and may need network approval.

mkdir -p .shots
npx playwright screenshot --full-page --viewport-size "1440,900" http://localhost:5173 .shots/desktop.png
npx playwright screenshot --full-page --viewport-size "390,844" http://localhost:5173 .shots/mobile.png
npx playwright screenshot --full-page --color-scheme dark --viewport-size "1440,900" http://localhost:5173 .shots/dark.png

Open each image (Codex can view local images) and score 1–5, honestly, against the card:

Criterion	5 looks like
Direction	Nameable in three words; matches the card
Focal point	One obvious entry per viewport; eye path is clear
Type	Pairing intentional, scale has real contrast, measure comfortable
Color	Accent disciplined, neutrals have temperature, contrast passes
Composition	Not a template; grid broken once on purpose
Craft	Alignment exact, spacing from the scale, states present, mobile intact

Pass when no score is below 3 and the average is at least 4. Otherwise fix the three lowest items, re-capture, and re-score. Stop after three rounds and report what remains. Squint test: blur your attention to the shapes; if the hero reads as “centered text, two buttons, image below”, the composition is still generic.

Generic tells and replacements

Tell	Replace with
Purple-to-blue gradient hero	Flat tinted neutral with grain, or a full-bleed photograph
Gradient text on the headline	Size, weight or a single accent word in solid color
Three equal cards with icons in rounded squares	Numbered list, table, or unequal bento with real visuals
Centered hero, two buttons, mockup below	Left-aligned lockup on asymmetric grid, product cropped and bleeding
Glassmorphism panels everywhere	Solid surfaces separated by rules or surface steps
Same radius + shadow on every element	One corner personality, borders over shadows
Emoji or mixed icon sets	One family, consistent stroke
Grayscale “trusted by” logo strip as section 2	A specific quote or metric with attribution, placed where it supports a claim
Sparkle icons and “AI-powered” chips	Show the output the product produces
Every section the same height and padding	Vary density: one tight band, one roomy band

Hard rules

• Never ship text below 4.5:1 contrast for the sake of a mood; adjust lightness in OKLCH.
• Never load more than two families plus a mono, or weights you do not use.
• Never put body text over an unprotected photo; add a scrim or move the text.
• Never hide the primary action below decorative content on mobile.
• Do not invent brand assets (logos, customer names, testimonials) and present them as real; label placeholders clearly.
• When the user names a direction, follow it even if another would score higher.

Output contract

**Direction:** <name>: <three words>. Signature move: <one line>.
**Type:** <display> / <text> / <mono>, scale <ratio>, body <size/line-height>
**Palette:** <neutral>, <ink>, <accent> (OKLCH), contrast checked: body <x:1>, accent button <y:1>
**Layout:** <system>, breakpoints tested 360/768/1440
**Screenshots:** .shots/desktop.png, .shots/mobile.png, .shots/dark.png
**Critique (final round):** Direction 5, Focal 4, Type 5, Color 4, Composition 4, Craft 4
**Known gaps:** <draft copy, placeholder images, fonts load from network>