The Problem: Why AI Apps Look 'Off'

Design drift occurs when AI agents lack a shared mental model of your application's UI. Because agents typically treat each session as a blank slate, they often reinvent components—varying button styles, spacing, and typography—rather than adhering to a consistent visual language. This results in an app that feels like a collection of disparate, one-off screens rather than a cohesive product.

Moving from Mockups to Code-Based Systems

Traditional design systems often rely on static Figma mockups, which are essentially pictures that agents struggle to replicate accurately. The author argues for a more robust approach: building the design system directly into the codebase. By defining colors, typography, and component structures as real code, you create a single source of truth that the AI can query and implement consistently.

Key components of this approach include:

  • Semantic Constraints: Limit your palette to a small set of accent, signal, and neutral colors. Instead of using raw hex codes, use generic class names (e.g., bg-accent) so that global changes can be made in one place.
  • Live Documentation: Maintain an internal 'Design System' page within your app's admin area. This serves as both a visual reference for you and a technical specification for the AI agent.
  • Component Library: Define standard structures for common elements like buttons, forms, listings, and navigation. This ensures that when you ask for a 'primary button,' the agent uses the pre-defined radius, padding, and state styles every time.

Instructing Agents to Adhere to the System

Simply having a design system in your code isn't enough; you must explicitly instruct your coding agent to use it. The author uses CLAUDE.md (or agents.md) to inject specific directives into the agent's context window:

  • Reference the Source: Point the agent to the URL or file path of your design system documentation.
  • Enforce Best Practices: Instruct the agent to check the design system before writing any new markup or styles.
  • Prohibit Ad-Hoc Styling: Explicitly forbid the use of raw hex values or custom Tailwind utility chains for standard elements like H1s, forcing the agent to use the pre-defined base styles instead.

Implementation Strategy

  • Start Early: The author emphasizes that this system is most effective when installed on day one of a new project. Retrofitting an existing, inconsistent codebase is significantly more difficult.
  • Verify Tools: When using open-source skills or frameworks, always inspect the code to understand how it modifies your project. Do not blindly trust AI agents to 'fix' design issues without oversight.
  • Iterate: Treat your design system as a living document. As you build, you will inevitably need new components (e.g., a button dropdown). Add these to your design system page first, then instruct the agent to implement them, ensuring the new pattern is captured for future use.