Why AI Writes Ugly Code (And How to Fix It)

You've seen it: you ask ChatGPT or Claude to build a landing page, and it returns technically functional code with the visual appeal of a 1998 government website. Blue links, gray backgrounds, Times New Roman vibes. Why does AI write such ugly code—and how can you fix it?

The Problem: AI Has No Design Context

When you prompt an AI to "build a pricing page," it has no idea about:

• Your brand colors
• Your typography choices
• Your spacing scale
• Your border radius preferences
• Your shadow style
• Your overall visual aesthetic

So it falls back to defaults. And defaults are, by definition, generic. The AI isn't being lazy—it simply lacks the information needed to make design decisions.

Example: Before Design Tokens

Here's what you might get when asking AI to create a card component:

// AI-generated without design context
function Card({ title, description }) {
  return (
    <div style={{
      backgroundColor: '#f0f0f0',
      border: '1px solid #ccc',
      borderRadius: '4px',
      padding: '16px',
      boxShadow: '0 2px 4px rgba(0,0,0,0.1)'
    }}>
      <h3 style={{ color: '#333', marginBottom: '8px' }}>
        {title}
      </h3>
      <p style={{ color: '#666' }}>
        {description}
      </p>
    </div>
  );
}

It works. It's accessible. But it looks like every other generic component ever created. The values are hardcoded, inconsistent with your brand, and impossible to maintain at scale.

The Solution: Give AI Design Context

The fix is simple in concept: give the AI your design tokens. When AI knows your design system, it can generate code that actually matches your brand.

Here's the same prompt with design context:

/* Design tokens provided to AI:
 * --color-background: #ffffff
 * --color-muted: #f1f5f9
 * --color-foreground: #0f172a
 * --color-muted-foreground: #64748b
 * --color-border: #e2e8f0
 * --radius-lg: 0.75rem
 * --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1)
 * --spacing-4: 1rem
 */

function Card({ title, description }) {
  return (
    <div className="bg-[var(--color-background)] border border-[var(--color-border)] rounded-[var(--radius-lg)] p-[var(--spacing-4)] shadow-[var(--shadow-md)]">
      <h3 className="text-[var(--color-foreground)] mb-2">
        {title}
      </h3>
      <p className="text-[var(--color-muted-foreground)]">
        {description}
      </p>
    </div>
  );
}

Same component, but now it uses your design system. Change your tokens, and every AI-generated component updates automatically.

How Skill Files Work

Modern AI coding assistants like Claude Code and GitHub Copilot support "skill files" or context files—documents that get loaded into every conversation. These files can contain:

• Your CSS variables and what they mean
• Your component naming conventions
• Your preferred patterns (Tailwind classes, CSS modules, etc.)
• Examples of well-designed components
• Explicit instructions on styling approach

# design-system.md (skill file)

## Color Tokens
Use these CSS variables for all colors:
- `--color-primary`: Main brand color, use for CTAs
- `--color-secondary`: Secondary actions
- `--color-muted`: Backgrounds, less emphasis
- `--color-foreground`: Primary text
- `--color-muted-foreground`: Secondary text

## Usage Rules
1. NEVER hardcode color values
2. ALWAYS use var(--token-name) syntax
3. Use Tailwind arbitrary values: `bg-[var(--color-primary)]`
4. Maintain consistent spacing with --spacing-* tokens

The Difference in Practice

Without design tokens, every AI interaction starts from zero. You spend half your time fixing styling issues and fighting inconsistency.

With design tokens in context, AI generates code that:

• Matches your brand from the first generation
• Uses consistent spacing based on your scale
• Applies proper colors for text, backgrounds, borders
• Follows your patterns for shadows, radii, transitions
• Requires minimal cleanup before production

Why This Matters for Teams

As AI becomes a bigger part of development workflows, design consistency becomes harder to maintain. Without shared design context:

• Developer A gets different styling than Developer B
• AI-generated components don't match hand-coded ones
• Design debt accumulates faster than ever
• Code reviews become styling reviews

With a shared design token system loaded into AI tools, every team member (human and AI) works from the same foundation.

The Future: AI + Design Systems

We're heading toward a world where AI writes most boilerplate code. The teams that will thrive are those with well-documented design systems that AI can understand and apply.

This isn't about making AI smarter—it's about giving AI the context it needs. A design system is documentation for humans and machines.

Getting Started

Ready to make AI your design-aware coding partner?

1. Define your design tokens (colors, typography, spacing, etc.)
2. Export them in multiple formats (CSS variables, TypeScript, JSON)
3. Create a skill file documenting your tokens and usage rules
4. Load it into your AI tools (Claude Code, Cursor, Copilot)

PickCSS generates all of this automatically— your design tokens, the CSS variables, and the AI skill file. Create your design system once, and every AI-generated component matches your brand.

Create your AI-ready design system and stop fixing ugly AI code.