5 Design System Mistakes That Break AI Code Generation

When AI Ignores Your Design System

You have a design system. Components in Figma. Style guide documentation. Reusable React components. Everything looks clean—until you ask Claude or Cursor to generate a new feature.

The AI creates a modal dialog. The padding is wrong. The button colors do not match. The border radius feels off. You did not ask for a random design—you have standards. But the AI did not follow them.

This is not an AI problem. It is a design system problem.

AI code generation tools are good at producing plausible UI code. But "plausible" and "consistent with your system" are different things. If your design system is not structured for machine consumption, AI will default to generic patterns learned from millions of public repositories.

Here are five common design system mistakes that break AI code generation—and how to fix them.

Mistake #1: Design Tokens Live Only in Figma

The Problem:

Your designer maintains color palettes, typography scales, and spacing values in Figma. Developers eyeball the inspector panel and hardcode values:

<button style={{ 
  padding: '12px 24px', 
  background: '#3b82f6',
  borderRadius: '8px'
}}>
  Submit
</button>

When AI generates code, it has no access to Figma. It cannot see your design tokens. So it guesses:

// AI-generated code
<button className="px-6 py-3 bg-blue-500 rounded-lg">
  Submit
</button>

Close, but not your system. blue-500 is not your primary color. px-6 is not your spacing scale.

The Fix:

Export design tokens to code. Use a format AI can read:

// tokens.ts
export const tokens = {
  color: {
    primary: {
      solid: '#2563eb',
      hover: '#1d4ed8',
    },
  },
  spacing: {
    3: '12px',
    5: '20px',
  },
  radius: {
    md: '6px',
  },
};

Now when AI generates code, it can import and reference tokens:

import { tokens } from './tokens';

<button style={{
  padding: `${tokens.spacing[3]} ${tokens.spacing[5]}`,
  background: tokens.color.primary.solid,
  borderRadius: tokens.radius.md,
}}>
  Submit
</button>

Tools:

• Style Dictionary – Transform design tokens to code
• Figma Tokens Plugin – Sync Figma variables to JSON
• FramingUI – Design system with AI-optimized token structure

Mistake #2: Inconsistent Component Naming

The Problem:

Your team uses different names for the same concept:

• PrimaryButton, ButtonPrimary, MainButton
• Modal, Dialog, Popup
• Card, Panel, Container

Humans can infer these mean similar things. AI cannot. When you ask for a "dialog," AI might generate a generic <div> instead of using your Modal component.

The Fix:

Establish canonical naming conventions and document them:

# Component Naming Standards

- **Buttons:** `Button` (variant prop: `primary`, `secondary`, `ghost`)
- **Dialogs:** `Dialog` (not Modal, Popup, Overlay)
- **Cards:** `Card` (not Panel, Container, Box)

Use TypeScript to enforce this:

// ❌ Avoid
export const PrimaryButton = () => { /* ... */ };
export const ButtonPrimary = () => { /* ... */ };

// ✅ Do
export const Button = ({ variant }: { variant: 'primary' | 'secondary' }) => {
  /* ... */
};

Now AI sees one clear pattern. When it needs a button, it uses <Button variant="primary">.

Mistake #3: No Machine-Readable Component Documentation

The Problem:

Your component docs look great in Storybook. But AI does not browse Storybook. It reads code.

If your component lacks JSDoc or TypeScript types, AI has to guess how to use it:

// What does this component do? AI has no idea.
export const TextField = (props) => { /* ... */ };

AI might generate:

<TextField text="Email" value={email} onChange={setEmail} />

But your actual API is:

<TextField label="Email" value={email} onValueChange={setEmail} />

Close, but wrong prop names. User reports a bug. You debug. Time wasted.

The Fix:

Add JSDoc comments and strong TypeScript types:

/**
 * A text input field with label and validation support.
 * 
 * @param label - Visible label above the input
 * @param value - Controlled input value
 * @param onValueChange - Callback when value changes
 * @param error - Error message to display below input
 * 
 * @example
 * <TextField 
 *   label="Email" 
 *   value={email} 
 *   onValueChange={setEmail}
 *   error={errors.email}
 * />
 */
export const TextField = ({
  label,
  value,
  onValueChange,
  error,
}: {
  label: string;
  value: string;
  onValueChange: (value: string) => void;
  error?: string;
}) => { /* ... */ };

AI reads this. It knows the prop names. It sees the example. It generates correct code.

Mistake #4: Magic Numbers Instead of Semantic Tokens

The Problem:

Your spacing system exists, but developers hardcode values:

<div style={{ marginTop: '24px', paddingLeft: '16px' }}>
  {/* ... */}
</div>

When AI generates new UI, it copies this pattern. You end up with dozens of one-off spacing values: 12px, 18px, 24px, 32px—all close to your 8px grid, but none exact.

The Fix:

Use semantic token names that explain intent:

export const spacing = {
  xs: '4px',   // Tight spacing (icon + text)
  sm: '8px',   // Compact lists
  md: '16px',  // Default component padding
  lg: '24px',  // Section spacing
  xl: '32px',  // Page-level margins
};

And enforce usage in components:

<div style={{ marginTop: spacing.lg, paddingLeft: spacing.md }}>
  {/* ... */}
</div>

AI learns the pattern. It stops inventing random pixel values. Your spacing stays consistent.

Mistake #5: Color Tokens Without Context

The Problem:

You define colors like this:

--blue-500: #3b82f6;
--gray-700: #374151;

AI sees these and uses them—but it does not know when to use them. Is blue-500 for primary actions? Links? Info messages?

Result: AI uses blue-500 everywhere it needs "some blue," regardless of semantic meaning.

The Fix:

Define semantic color tokens:

export const color = {
  // Semantic tokens (use these)
  primary: {
    solid: '#2563eb',      // Primary actions (buttons, links)
    hover: '#1d4ed8',
    text: '#1e40af',
  },
  neutral: {
    solid: '#374151',      // Default text, borders
    muted: '#6b7280',      // Secondary text
    subtle: '#9ca3af',     // Disabled states
  },
  success: {
    solid: '#059669',      // Success states, confirmations
    surface: '#d1fae5',    // Success backgrounds
  },
  // Base palette (internal use only, not for components)
  _base: {
    blue: { 500: '#3b82f6' },
    gray: { 700: '#374151' },
  },
};

Now when AI needs a primary button color, it uses color.primary.solid. When it needs muted text, it uses color.neutral.muted. Intent is explicit.

Bonus Mistake: No Clear "Source of Truth" File

AI does not explore your entire codebase to find design patterns. It looks for a clear entry point.

If your tokens are scattered across:

• styles/colors.css
• theme/spacing.ts
• constants/typography.js

...AI will not find them. It will default to generic values.

The Fix:

Create a single source of truth:

src/
  design-system/
    tokens.ts          ← All design tokens here
    components/
      Button.tsx       ← Import from tokens.ts
      TextField.tsx    ← Import from tokens.ts

In your project README or AI coding assistant config, point to this file:

# Design System

All design tokens are defined in `src/design-system/tokens.ts`.

When generating UI code, always import tokens from this file.

Claude, Cursor, and other AI tools can read this and prioritize the correct file.

Making Your Design System AI-Proof: Checklist

• ✅ Export design tokens to code (not just Figma)
• ✅ Use consistent component naming across the codebase
• ✅ Add JSDoc + TypeScript types to all components
• ✅ Replace magic numbers with semantic tokens
• ✅ Define color tokens by intent, not hue
• ✅ Create a single source-of-truth file for tokens
• ✅ Document your design system in README or AI config

The Result: AI That Respects Your Design

When you fix these mistakes, AI-generated code changes:

Before:

// Generic, inconsistent
<button className="px-6 py-3 bg-blue-500 rounded-lg">
  Submit
</button>

After:

// Consistent with your system
import { Button } from '@/design-system/components';

<Button variant="primary">Submit</Button>

AI stops guessing. It follows your system. Your UI stays consistent, even when generated at high velocity.

Conclusion

AI code generation is fast. But speed without consistency creates design debt. The mistakes above are not obvious—they only surface when AI starts generating code that "looks fine" but does not match your standards.

The fix is not better AI. It is better design system architecture:

1. Tokens in code, not just design tools
2. Consistent naming conventions
3. Machine-readable documentation
4. Semantic tokens over magic numbers
5. Clear source of truth

Make these changes, and AI becomes a force multiplier for your design system—not a threat to it.

Your design system should not just guide humans. It should guide machines. Build for both, and you get consistent UI at AI speed.

---

Ready to build an AI-proof design system?

FramingUI provides pre-built design tokens, AI-optimized components, and MCP integration so AI tools understand your design system from day one.

Explore FramingUI →