AI Design-to-Code: Why "Known" Systems Outperform "Told"…

In the rapidly evolving domain of web development, artificial intelligence is increasingly being touted as a transformative force, especially in automating the design-to-code pipeline. That said, the promise of smooth translation from visual concept to functional component has often been met with a frustrating reality: AI-generated code that looks correct but is riddled with subtle, yet critical, errors. Recent groundbreaking research by design engineer James Coombs sheds light on this persistent challenge, revealing a single, overarching variable that consistently predicts the quality and reliability of AI design tools: whether the AI has been told about a design system or genuinely knows it.

Coombs conducted a meticulous ablation study involving a 60-component design system, scrutinizing six distinct categories of AI design-to-code tools. His findings underscore a fundamental divergence in how AI interacts with design system specifications, leading to a categorical, rather than incremental, difference in output fidelity. For web development agencies and software engineering teams striving for efficiency and precision, understanding this distinction is not merely academic; it is crucial for making informed technology investments and truly leveraging AI for production-grade applications.

The Fundamental Flaw of "Told" Tools

"Told" tools represent the more intuitive, yet ultimately less reliable, approach to AI-driven design conversion. These systems typically rely on natural language descriptions, comprehensive documentation, or general framework knowledge gleaned from their vast training data. When a developer or designer instructs such an AI to "use our Button component with variant='primary'," the AI interprets this instruction based on its generalized understanding of components and common design patterns. It attempts to generate code that visually approximates a primary button, often drawing from an internal model that might vaguely resemble the desired component.

The inherent problem here is the "interpretation gap." The AI does not possess a direct, structured understanding of your specific design system's API. It might generate a button that looks visually correct but uses incorrect prop names (e.g., type='primary' instead of variant='primary'), references non-existent variants, or applies the wrong import paths. Crucially, it might even hallucinate components that don't exist within your system or apply design tokens (like specific color palettes) that are plausible but not actually part of your approved brand guidelines. Each interpretive step introduces drift, leading to output that, while superficially appealing, requires significant manual intervention and refactoring by an engineer.

This "plausibly wrong" output is often more insidious than obviously incorrect code. Clearly erroneous code is immediately identified and rewritten. Plausibly wrong code, however, can pass initial design reviews or even slip into a codebase, accumulating technical debt and introducing subtle bugs or inconsistencies that are difficult to track down later. Building on this, "Told" tools are static; their knowledge is based on their training data, meaning they struggle to keep pace with the dynamic evolution of a design system where components are frequently updated, new variants are introduced, and tokens are renamed. This makes them unsuitable for continuous integration and delivery pipelines where consistency and up-to-date information are paramount.

The Precision Power of "Known" Tools

In stark contrast, "Known" tools operate on a principle of direct, unambiguous access to the design system's truth. Instead of interpreting descriptions, these AI systems query a structured, machine-readable index of your actual components. This means when an instruction is given, the AI doesn't guess; it retrieves the exact component name, its precise prop types (often derived from TypeScript definitions), correct import paths, and validated usage examples directly from the source. The elimination of the interpretation gap is the cornerstone of their superior fidelity.

The benefits of this approach are profound for modern web development. "Known" tools ensure that the generated code is not only visually accurate but also functionally correct and fully compliant with the established design system. This leads to higher code quality, reduced debugging time, and a more consistent user experience across applications. Developers can trust the AI's output, knowing it adheres to the precise specifications of their component library. In addition, because "Known" tools can query the current state of a design system, they inherently support agility, adapting seamlessly to updates, new components, and evolving brand guidelines. This dynamic access makes them indispensable for large-scale projects and multi-developer teams where maintaining rigorous consistency is a significant challenge.

Exploring the Three "Known" Approaches

The research identifies three primary methodologies through which AI tools can achieve "Known" status, each with its own advantages and engineering considerations:

2. Hand-Mapped Component Bridge (e.g., Figma Code Connect)

A hand-mapped component bridge offers the highest possible fidelity, achieving 100% accuracy by definition. In this method, each visual component in a design tool (like Figma) is manually linked or mapped directly to its corresponding code component in the design system. This mapping explicitly defines which code component to use, along with its specific props and variants, whenever the visual component is invoked.

While offering unparalleled precision, the primary drawback of this approach is its manual maintenance burden. Every new component, every new variant, and every significant update to an existing component requires a corresponding manual update to the mapping. This process scales linearly with the number of components, making it labor-intensive and potentially a bottleneck for rapidly evolving design systems. For large and agile development teams, the overhead of constant manual synchronization can quickly outweigh the benefits of perfect fidelity, especially if the design system is frequently iterated upon.

3. AI Agent + Structured Query (e.g., MCP Server)

This represents the most advanced and future-proof "Known" approach. Here, an AI agent is equipped with a query interface that allows it to dynamically interact with and discover components directly from a live or highly current source of the design system. Instead of relying on a static index or manual mapping, the agent performs real-time queries against the actual component source code or a live API endpoint exposing its structure.

This method goes beyond simple lookup; it enables dynamic discovery. An AI agent could, for instance, be asked "what component handles file uploads?" and it would intelligently search and identify the relevant component, rather than just knowing its properties if explicitly named. Building such an interface once provides a powerful, centralized gateway for *all* current and future AI tools to access the design system accurately. This investment amortizes over time, as every new AI tool that integrates with this structured query interface immediately benefits from precise, up-to-date knowledge, significantly enhancing developer productivity and ensuring consistent outputs across various AI-powered workflows.

The Empirical Evidence: A Decisive Gap

James Coombs' ablation study provided compelling quantitative evidence to support the categorical difference between "Told" and "Known" approaches. In his controlled experiment (n=9), the results were stark:

AI Agent + MCP Query ("Known"): Achieved an impressive 27.5 out of 30 on design system compliance.
AI Design Tool Interpretation ("Told"): Scored a significantly lower 16.3 out of 30.
CLAUDE.md Rules (Explicit "Told" Guidance): Registered 16.1 out of 30, virtually identical to providing no specific guidance, highlighting the ineffectiveness of relying on natural language constraints alone.

The data unequivocally demonstrates that merely providing an AI with rules or detailed documentation, even with specific instructions like "always use the design system," does not translate to high fidelity. The gap of over 11 points between the "Known" and "Told" categories is not a marginal difference; it represents a fundamental divergence in output quality that has tangible implications for development cycles, code maintainability, and product reliability. Coombs' finding that the MCP server, providing this structured access, took only about a week to build further emphasizes the high return on investment for such an infrastructure, especially as its benefits compound with every AI tool that connects to it.

Strategic Application: When to Employ Each Approach

Understanding the "Told" vs. "Known" dichotomy allows development teams and agencies to make strategic decisions about AI tool adoption. Not every scenario demands 100% fidelity, but critical applications certainly do.

When "Told" is Acceptable:

Throwaway Prototypes: For rapid visual exploration or initial concept validation where 70% fidelity is sufficient and the code will likely be discarded or heavily refactored.
Greenfield Exploration: When a design system is not yet established, and the goal is to quickly generate placeholder UI to inform design choices.
Product Demos: For internal presentations or sales demonstrations where brand-perfect fidelity is less critical than conveying functionality or a general aesthetic.

1. AST-Parsed Component Index

This approach involves parsing the source code of your design system into an Abstract Syntax Tree (AST), which provides a structured, hierarchical representation of the code. From this AST, a structured index is generated containing critical information about each component: its name, available prop types (especially solid when using TypeScript), defined variants, and associated design tokens. This index is then regenerated whenever the design system's source code changes, ensuring it remains up-to-date.

The strength of AST-parsed indexes lies in their ability to capture the exact structure and API of components directly from their implementation. This guarantees high fidelity regarding component usage and prop validation. However, a limitation is that while it understands the *structure* of a component, it doesn't inherently grasp the *intent* or specific design context for its use. For example, it knows what a Dialog component is and its props, but it doesn't automatically know *when* to use a Dialog versus a Sheet in a user interface flow. This requires additional guidance or a more sophisticated AI agent layer to make contextual decisions.

When You Absolutely Need "Known":

Production Code Generation: For any code intended to be shipped to end-users, where correctness, consistency, and adherence to design specifications are non-negotiable.
Design System Migrations: During complex transitions or updates to a design system, where incorrect component imports or prop usage can lead to cascading errors and significant rework.
Multi-Person Teams: In environments where multiple developers contribute to a codebase, ensuring consistent component usage across the team is vital to prevent technical debt and maintain a unified user experience.
Brand-Critical Surfaces: For any user interface where brand identity and meticulous adherence to design tokens (e.g., ensuring your specific violet is used, not a generic purple) are paramount to the brand's integrity.

The Practical Takeaway for Modern Web Development

Before integrating any AI design-to-code tool into your web development workflow, the single most important question to ask is: does this tool query my real, structured components, or does it merely guess based on interpretation? The answer to this question will be the primary determinant of the tool's utility and the quality of its output.

For development teams and agencies committed to generating production-ready code with AI, the investment in a structured query interface is not optional; it's essential. Whether this takes the form of an MCP server, a robust CLI tool, or an AST-parsed index, the specific form factor is less critical than the underlying principle of providing unambiguous, structured access to your design system. Build this infrastructure once, and every AI tool, both current and future, that connects to it will benefit from unparalleled precision and reliability. The returns on this investment will compound significantly over time, accelerating development and reducing costly rework.

Crucially, the research also discredits the notion that "Told" tool fidelity can be significantly improved by writing more detailed documentation or crafting increasingly elaborate prompts. Coombs' data, particularly the phenomenon of "density inversion," indicates that adding more constraints or attempting to provide exhaustive natural language guidance can actually degrade output quality. A concise, two-sentence prompt coupled with a structured query interface consistently outperforms even the most comprehensive governance files by a wide margin. This insight liberates teams from the Sisyphean task of trying to perfect AI interpretation and redirects focus towards building robust, machine-readable design system foundations.

What This Means for Developers

For web development agencies like Voronkin, based in Montreal and serving clients across Canada, the USA, and France, this research provides an invaluable framework for guiding our AI strategy and client engagements. We understand that the hype around AI can often overshadow the practical realities of integrating it into production workflows. Our E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) approach dictates that we advise our clients not just on what's possible with AI, but what's genuinely effective and sustainable. This means proactively educating our clients on the fundamental difference between AI tools that merely interpret and those that truly understand their design systems. We see a clear mandate to help clients implement "Known" approaches, particularly the dynamic AI agent + structured query model, as a critical component of their digital strategy. This ensures that the custom design systems and web applications we build are not only robust and scalable but also future-proofed for the inevitable evolution of AI-driven development, minimizing technical debt and maximizing long-term ROI.

From a project perspective, embracing "Known" systems directly translates to more predictable timelines, reduced development costs, and significantly higher code quality for our clients. Our developers can shift their focus from laboriously correcting AI-generated code to concentrating on complex business logic, unique user experiences, and innovative features that truly differentiate our clients' products. This paradigm allows us to deliver projects faster, with fewer bugs, and with greater fidelity to the original design vision. For agencies and freelancers, this represents a crucial competitive advantage: the ability to deliver AI-assisted projects that are not just visually appealing but also technically sound and production-ready, thereby building stronger client trust and fostering long-term partnerships.

For individual developers and engineering teams, the practical steps are clear and actionable. First, prioritize building and maintaining highly structured design systems, leveraging tools like TypeScript for explicit prop definitions and well-defined design tokens. Second, adopt a critical lens when evaluating AI design tools, always questioning the mechanism of their design system awareness. Third, advocate for and invest in bridging technologies—whether it's an internal MCP server, a custom CLI, or a robust AST indexer—that expose your design system in a machine-readable, queryable format. Fourth, enhance your skills in system design and API development; understanding how to create robust interfaces for design system components will be increasingly vital. Finally, educate your project managers and stakeholders about the "Told" vs. "Known" distinction to set realistic expectations and justify the necessary upfront investment in structured foundations, ensuring that AI becomes a true accelerator rather than a source of hidden technical debt.

AI Design-to-Code: Why "Known" Systems Outperform "Told" Every Time