At a Glance
Problem: AI-generated interfaces were inconsistent and required manual correction.
Approach: Built and tested multiple AI-readable documentation strategies using Claude Code.
Outcome: Established a new AI-readable documentation strategy that was 3x faster, significantly cheaper, and became the foundation for an emerging design-to-code workflow.
The Challenge
As AI became part of our design workflow, we ran into a new problem: our design system worked well for humans, but not for AI.
Claude could generate interfaces quickly, yet the output was inconsistent. Components were misused, design rules were missed, and developers still had to manually translate design intent. Every AI-generated screen required correction before it was usable.
Key Insight: Rather than treating AI as a separate tool, we needed to treat it as another consumer of the design system. That meant rethinking how the system itself was structured and documented.
My Approach
Nobody on the team had a clear answer. I partnered with design and engineering to create a testing framework that measured how different documentation strategies affected AI output quality, implementation accuracy, cost, and speed.
Using Claude Code, I built a repeatable testing environment that allowed us to compare documentation strategies under identical conditions.
Defined the research framework
Designed and ran the experiments using Claude Code
Analyzed performance, cost, and accuracy tradeoffs
Presented findings to design and engineering leadership
Helped define the documentation architecture now being implemented
Tools
Figma MCP, Claude Code, Notion, Gitlab, VS Code
Key Findings
Structure matters more than volume
A structured markdown file produced the same quality output as our documentation site while being more than 3x faster and significantly cheaper — 95% fewer tokens with equal accuracy. That finding gave us the confidence to commit to the approach and start figuring out how to structure it properly.
Source quality affects AI behavior
Documentation generated directly from component packages produced more reliable implementations and eliminated recurring errors. When I generated documentation from our docs site source instead, Claude consistently introduced two implementation errors. Sourcing from the package directly made them disappear on the first pass.
AI exposed weaknesses in the system
Testing surfaced ambiguities in our documentation that had previously gone unnoticed, creating a feedback loop for improving the design system itself. Several failures that initially looked like AI mistakes were actually gaps in our documentation — rules that existed but weren't specific enough for the context Claude was working in.
Impact
Defined a new direction for AI-readable design systems Turned an ambiguous problem into a tested approach for AI-assisted design and development.
Influenced architecture before implementation Identified a documentation sourcing issue that prevented implementation errors before production work began.
Aligned design and engineering leadership Used research findings to build support for a cross-functional implementation effort.
Created a foundation for AI-native workflows Reframed AI as a consumer of the design system, influencing how design and engineering collaborate moving forward.
The Solution
This is still being built, and the research was the first step toward approaching an ambiguous problem with enough confidence to move forward together.
The emerging workflow:
Designers maintain AI-readable documentation
AI generates system-compliant interfaces
Developers review real implementation code instead of translating design intent
Design system rules improve through feedback loops
The handoff changes too. Instead of designers handing off prototypes for translation into code, designers can merge-request directly from a shared prototype repo. Developers look at real code. The translation layer disappears.
Emerging Design-to-Code Workflow
Things will change as we implement. That's expected. The research didn't give us all the answers, but it gave us a strong enough foundation to start.
Deep Dive Into The Experiment
The full research breakdown for those who want it.
I tested four branches, each with a different documentation approach, asking Claude to build the same screen under identical conditions.
Branch A (control): no documentation. Claude builds however it wants.
Branch B: CLAUDE.md and CANVAS.md in the repo root, generated from the docs site source.
Branch C: no md files. Claude told to reference the live docs site before building.
Branch D: same as Branch B, but CANVAS.md generated directly from the Canvas package source.
Branch B finished in 53 seconds using 1.3k tokens. Branch C took 2 minutes 38 seconds and used 1.7k tokens. In a read-only test the gap was even wider: 25 tokens vs 633. Branch D fixed two technical errors that Branch B introduced by sourcing documentation from the wrong place.
The research didn't produce a perfect solution, but it gave us confidence in a direction. By turning assumptions into experiments, we established a repeatable process for evaluating how AI interacts with our design system and created a foundation for an emerging design-to-code workflow.
Controlled Experiment: Same Prompt, Different Documentation Strategies
