Vibe Coding Problems: 7 Visual Bugs AI Code Generators Always Ship

cing, color, and typography. Create a centralized token file that serves as the single source of truth.

// src/design/tokens.ts
export const DesignTokens = {
  spacing: {
    'xs': '12px',
    'sm': '16px',
    'md': '24px',
    'lg': '32px',
    'xl': '48px',
  } as const,
  
  colors: {
    brand: {
      primary: '#2563EB',
      primaryHover: '#1D4ED8',
      secondary: '#4F46E5',
    },
    neutral: {
      text: '#111827',
      bg: '#F9FAFB',
      border: '#E5E7EB',
    }
  } as const,

  typography: {
    base: {
      family: 'Inter, system-ui, sans-serif',
      weight: '500',
      size: '16px',
      lineHeight: '24px',
      letterSpacing: '-0.02em',
    },
    heading: {
      weight: '600',
      tracking: '-0.03em',
    }
  } as const,
} as const;

Step 2: Enforce Tokens via Configuration

Configure your styling framework to reject arbitrary values. This forces the AI (and human developers) to use the defined tokens, preventing approximation drift.

// tailwind.config.ts
import { DesignTokens } from './src/design/tokens';

module.exports = {
  theme: {
    extend: {
      spacing: DesignTokens.spacing,
      colors: DesignTokens.colors,
      fontFamily: {
        sans: [DesignTokens.typography.base.family],
      },
      fontSize: {
        base: [
          DesignTokens.typography.base.size,
          { lineHeight: DesignTokens.typography.base.lineHeight },
        ],
      },
      fontWeight: {
        base: DesignTokens.typography.base.weight,
        heading: DesignTokens.typography.heading.weight,
      },
      letterSpacing: {
        tight: DesignTokens.typography.heading.tracking,
        base: DesignTokens.typography.base.letterSpacing,
      },
    },
  },
  // CRITICAL: Disable arbitrary values to force token usage
  corePlugins: {
    preflight: true,
  },
  // Optional: Use a plugin or custom rule to warn on arbitrary values
  // e.g., tailwindcss-arbitrary-values-warn
};

Step 3: Batch Repair Strategy

When AI generates code, run a visual audit. Group issues by category and file, then construct a single prompt that applies all fixes simultaneously. This avoids the regression loop.

Batch Prompt Structure:

Apply the following visual corrections to [FileList]. 
Do not change functionality. Only update styling to match the Visual Contract.

1. SPACING: Replace all approximate gaps with tokens.
   - Use `gap-md` (24px) for section spacing.
   - Use `gap-sm` (16px) for element spacing.
   - Remove all `gap-4`, `gap-6`, `gap-8` unless they match tokens.

2. COLORS: Enforce brand palette.
   - Primary buttons must use `bg-brand-primary`.
   - Links must use `text-brand-primary`.
   - Remove any hex codes or non-token colors.

3. ACCESSIBILITY: Add missing semantic attributes.
   - Ensure all buttons have `aria-label` if text is icon-only.
   - Add `role="dialog"` and `aria-modal="true"` to modals.
   - Verify focus order matches DOM order.

4. RESPONSIVE: Fix intermediate breakpoints.
   - Add `md:` variants for layouts breaking at 834px.
   - Ensure grids collapse to single column below 768px.

Output only the updated files.

Architecture Rationale

• Token Enforcement: By disabling arbitrary values in the config, you create a guardrail. The model cannot output gap-[24px] or text-[#2563EB]; it must use the token classes. This eliminates the approximation error at the source.
• Batch Processing: LLMs have context windows. Providing a batch of fixes allows the model to see the global pattern of errors and apply a consistent transformation. Iterative fixes force the model to re-evaluate context repeatedly, increasing the probability of hallucination and regression.
• Separation of Concerns: The Visual Contract is decoupled from the AI generation. This allows you to swap AI tools without changing your visual standards. The contract remains the constant.

Pitfall Guide

Pitfall	Explanation	Fix
The Approximation Trap	AI selects the closest Tailwind utility (e.g., gap-4 for a 24px spec) rather than the exact value. This causes layout drift across components.	Define a custom spacing scale in tailwind.config.ts that maps exactly to your design spec. Disable arbitrary spacing values.
Z-Index Sprawl	Components receive arbitrary z-index values (e.g., z-50, z-999) without a global strategy. Modals render behind navbars; tooltips clip behind sections.	Implement a z-index layer map. Define layers like modal: 100, dropdown: 90, nav: 80. Use semantic class names like z-modal instead of numbers.
Viewport Blindness	AI relies on default breakpoints (640px, 768px, 1024px). Layouts break at intermediate widths like 834px (iPad portrait) or 900px (laptop with sidebar).	Explicitly prompt for custom breakpoints. Test on a matrix of viewports including intermediate widths. Add md: or lg: variants for specific break points.
Semantic Neglect	Models prioritize layout over semantics. Output often contains div soup, missing alt text, unlabeled inputs, and broken focus order. WebAIM data shows 95.9% of homepages have WCAG failures; AI output often underperforms this baseline.	Enforce semantic linting rules. Include accessibility requirements in the batch prompt. Use tools like axe-core in CI to catch violations automatically.
Color Drift	Brand colors are inferred from context, leading to multiple shades of the same color across buttons, links, and backgrounds.	Use a strict color palette in design tokens. Reference tokens exclusively. Run automated contrast checks to ensure accessibility compliance.
State Omission	AI generates default component states but omits hover, focus, active, and disabled variants. Buttons lack visual feedback; keyboard navigation is impossible.	Provide component templates that include all states. Prompt specifically for interactive states. Use CSS variables or Tailwind modifiers to ensure consistency.
Iterative Regression	Fixing one visual bug introduces new bugs in adjacent components. The codebase becomes unstable after multiple prompt cycles.	Adopt the batch repair strategy. Apply all fixes in a single pass. Verify the entire UI after each batch application.

Production Bundle

Action Checklist

• Define Visual Contract: Create tokens.ts with exact spacing, color, and typography values.
• Configure Strict Tooling: Update tailwind.config.ts to extend theme with tokens and disable arbitrary values.
• Generate Initial Code: Run AI generation with a prompt that references the Visual Contract.
• Run Visual Audit: Inspect UI against design spec. Check spacing, colors, breakpoints, accessibility, and states.
• Construct Batch Prompt: Group all identified issues by category and file. Use the batch prompt structure.
• Apply and Verify: Execute the batch prompt. Verify the output matches the Visual Contract.
• Automate Checks: Integrate linting rules for semantic HTML and color contrast into the CI pipeline.
• Test Viewports: Verify layout stability on intermediate breakpoints (834px, 900px).

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Rapid Prototype	AI Generation + Manual Polish	Speed is priority. Visual fidelity can be lower.	Low token cost; high manual effort for polish.
Production App	AI Generation + Visual Contract + Batch Repair	Stability and brand consistency are critical.	Moderate token cost; low manual effort; high ROI.
Accessibility Compliance	AI Generation + Strict A11y Linting + Batch Fix	AI underperforms on accessibility by default.	High initial setup cost; prevents legal risk.
Design System Migration	Batch Repair with Token Mapping	Ensures consistent migration across all components.	High token cost; eliminates drift.

Configuration Template

Use this template to enforce strict visual standards in your project. This configuration prevents AI approximation and ensures all generated code adheres to your design system.

// tailwind.config.ts
import type { Config } from 'tailwindcss';
import { DesignTokens } from './src/design/tokens';

const config: Config = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      spacing: DesignTokens.spacing,
      colors: DesignTokens.colors,
      fontFamily: {
        sans: [DesignTokens.typography.base.family],
      },
      fontSize: {
        base: [
          DesignTokens.typography.base.size,
          { lineHeight: DesignTokens.typography.base.lineHeight },
        ],
      },
      fontWeight: {
        base: DesignTokens.typography.base.weight,
        heading: DesignTokens.typography.heading.weight,
      },
      letterSpacing: {
        tight: DesignTokens.typography.heading.tracking,
        base: DesignTokens.typography.base.letterSpacing,
      },
      zIndex: {
        'nav': '80',
        'dropdown': '90',
        'modal': '100',
        'toast': '110',
      },
    },
  },
  plugins: [
    // Add plugin to warn on arbitrary values if available
    // require('tailwindcss-arbitrary-values-warn'),
  ],
  // Enforce strict mode to catch errors early
  future: {
    hoverOnlyWhenSupported: true,
  },
};

export default config;

Quick Start Guide

1. Initialize Tokens: Create src/design/tokens.ts and populate it with your exact design values.
2. Update Config: Modify tailwind.config.ts to extend the theme with your tokens and disable arbitrary values.
3. Generate Code: Run your AI tool with a prompt that includes: "Use only the defined design tokens. Do not use arbitrary values."
4. Audit and Batch: Review the output. If visual drift exists, create a batch prompt listing all corrections.
5. Verify: Apply the batch prompt. Run your app and verify visual fidelity on multiple viewports.

By implementing a Visual Contract and batch repair strategy, you transform AI-generated code from a draft into a production-ready interface. This approach eliminates the pixel-token gap, reduces token waste, and ensures your application meets the highest standards of design and accessibility.