Stop Complaining About ClaudeCode/Codex UI Design—Ready‑to‑Use DESIGN.md Files

Why AI‑Generated UI Looks Bad

Developers who use Claude Code or Codex to write front‑end UI frequently encounter wrong colors, ugly fonts, and odd spacing, leading to repeated rework after each build.

Missing Design System as the Root Cause

The underlying problem is that the model is never given a design system; without a DESIGN.md file it falls back to default, mediocre styles. DESIGN.md, a concept from Google Stitch, is a plain‑text markdown file that records the entire design system—color palette, typography scale, spacing, corner radius, shadows, and component rules—so an agent can read it before drawing UI, preventing style drift.

Benefits of DESIGN.md

It eliminates the need for Figma exports, JSON schemas, or any extra tooling; markdown is the format large language models understand best, and placing the file in the project root lets the agent instantly grasp the intended visual language.

Public DESIGN.md Collections

Two useful sources are mentioned:

styles.refero.design (http://styles.refero.design) – a curated set of over 2,000 design systems extracted from real products, ready to feed agents such as Cursor, Claude Code, Codex, v0, or Lovable.

awesome-design-md on GitHub (http://github.com/VoltAgent/awesome-design-md) – contains 73 design systems from Stripe, Linear, Airbnb, Vercel, Notion, ElevenLabs, etc. Each file typically includes nine sections: overall philosophy, semantic color names with hex values, full typography table, component states (buttons, cards, inputs), spacing and grid, shadow levels, do‑and‑don’t checklist, responsive breakpoints, plus a quick‑prompt for agents and a preview.html page to visualise the palette, fonts, and components.

How to Use DESIGN.md

The workflow is simple: copy a DESIGN.md from one of the sites into your project’s root directory, then instruct the agent to generate UI according to that file. Verify the effect by testing a simple page; if the colors, spacing, fonts, and overall feel match the source, the DESIGN.md is working. It is also recommended to provide a screenshot alongside the DESIGN.md so the model fully understands the visual intent.

Ready‑to‑Copy Prompts

Abstract scattered component and style tokens into a unified design system and turn it into a reusable component library; enforce that all new UI must use the library.

Ask the agent to act as a senior UX designer, walk through the core workflow from start to finish, identify weak information hierarchy, friction points, missing or erroneous states, rank them by severity, and suggest concrete fixes.

Redo a page to achieve a Linear or Stripe‑like aesthetic: restrained palette, clear typographic hierarchy, ample whitespace, consistent corner radius and shadows.

Ensure all interactions and states are correct: loading skeletons, empty and error states, hover/focus/disabled styles, and transition/feedback for key actions.

Conclusion

Instead of repeatedly fixing visual issues after each build, define “what good looks like” once in a DESIGN.md file and let the agent follow it.