How to Fix Claude Code's CSS Guesswork with a Design System

A developer building a stock analysis dashboard with Claude Code encountered a common frustration: the AI repeatedly generated broken CSS for the same misaligned div. Over six iterations, attempts to fix padding, switch from flex to grid, and add overflow: hidden either failed or made the problem worse.

The Problem: AI Designing Blind

The developer realized Claude Code has no visual feedback—it can't see browser output. It pattern-matches from descriptions and guesses at styling, often producing "technically valid CSS that looks like it was designed by someone who has never used a computer."

The Solution: Constrain with a Design System

Instead of giving tokens, provide a complete design system specification. The developer used:

/* spacing */
--space-xs: 4px;
--space-sm: 8px;
--space-md: 16px;
--space-lg: 32px;

/* colors */
--bg-primary: #0f1117;
--bg-card: #1a1d27;
--accent: #3b82f6;
--text-primary: #e2e8f0;
--text-muted: #64748b;
/* type scale */
--text-sm: 12px;
--text-base: 14px;
--text-lg: 18px;
--text-xl: 24px;

Then instruct: "Use only these values. No hardcoded numbers anywhere." This gives Claude a framework to reason from rather than a blank canvas for arbitrary decisions.

Separate Structure and Style Prompts

Never ask Claude to write HTML and CSS simultaneously. The developer split the process:

• First prompt: "Generate only the HTML structure for this dashboard. No style attributes, no CSS, no classes yet. Just semantic structure."
• Second prompt: "Now write the CSS for this structure using only the design system above."

This forces Claude to treat the HTML as a fixed contract before applying styles, preventing it from losing track of assumptions about its own output.

The result: the next component went from six iterations to one. The developer also raised the question of whether this design system could be enforced via a CLAUDE.md file to avoid pasting it every session.