From Figma to AI-first

OVERVIEW

Reframing the design system as the contract between designers and AI tools

Komprise designers were beginning to use AI tools like Claude and Codex as part of their daily workflow. The promise was clear: prompt-to-mockup in seconds, faster exploration, more iteration cycles per week. The reality was the opposite. AI-generated mockups consistently violated our own design system, and the time spent fixing those violations exceeded any time saved by generation. The bottleneck was not AI capability; it was that our design system, maintained exclusively in Figma, was invisible to the tools designers were starting to depend on. I led the transition to rebuild the design system as an AI-readable, markdown-based GitHub repository so that the system itself became part of the AI workflow rather than a constraint AI worked against.

PROBLEM

The gap: designers had AI tools, but AI did not have our design system

Designers across the team were experimenting with AI tools to accelerate exploration, but every prompt-generated mockup arrived with the same set of violations. Wrong color tokens, off-spec spacing, components that did not exist in our system, anti-patterns we had explicitly designed against. The fix-up time per mockup was substantial enough that AI was producing negative leverage: a prompt cycle plus rework was slower than designing from scratch. The root cause was not the AI tools themselves but the absence of any machine-readable representation of our system. Our design system lived in Figma, where AI tools could not reach it. Every designer was paying the same hidden tax: translating AI output back into Komprise's visual language by hand, every time. As more designers adopted AI tools, this tax compounded, and the strategic risk grew. We were building a workflow where the cost of using new tools was rising even as the team's reliance on them deepened.

RESEARCH & DISCOVERY

What AI actually needs from a design system is different from what Figma exposes

I ran three parallel inquiries before any building began. First, designer interviews across the team mapped where AI tools were entering the workflow (exploration, stakeholder mockups, component variations) and where the friction lived. Second, an AI consumption audit identified what each tool actually needed in order to generate conformant output. Not pretty Figma frames but rules expressed as text: component anatomy, variant logic, usage constraints, anti-patterns. Third, an industry pattern study of code-first design systems (shadcn/ui, Radix, MCP-based design tooling) showed a consistent direction across the field. Design systems are migrating from visual-asset libraries to structured-text contracts. The decisive insight surfaced quickly. AI tools do not need our design system to look right; they need it to read right. The Figma representation was solving the wrong problem for the new generation of consumers.

DESIGN PROCESS

From Figma-only to a designer-editable, AI-consumable repository in four steps

The build proceeded in four stages, each with explicit cross-functional checkpoints between designer and engineer. The sequence was deliberate — every step validated the assumptions of the next before committing engineering effort, so we never paid for migration work the schema would have invalidated, or pipeline work the migration would have reshaped.

DESIGN GOAL

Four explicit goals that anchored the system rebuild before any markdown was written

SOLUTION

A markdown-based design system repository with a designer-driven update pipeline

The shipped system has three layers. The repository itself organizes components into category folders, each containing a markdown file describing that component in four standardized sections (anatomy, variants, usage rules, anti-patterns), alongside a README per category and a tokens directory for color, type, and spacing primitives. Each markdown file links explicitly to its React implementation in the engineering codebase, so the design system and the production code stay coupled by reference. The contribution pipeline lets designers push updates without context-switching into engineering tooling. Edits flow through GitHub directly, with no PR-review bottleneck for system documentation changes (engineering reviews remain in place for code changes). The AI consumption layer wires the repository into the AI tools designers already use, so a prompt now arrives at an AI tool with the design system as context, and the generated mockup conforms to Komprise from the first iteration. The whole system was designed to feel invisible. AI tools simply produce on-brand output, designers maintain the system in plain text, and the team's leverage from new AI tooling becomes positive instead of negative.

KEY DECISION 1

Markdown vs Figma plugins vs structured tokens, and which format becomes the source of truth

The core architectural decision was format. Three options were on the table, each with substantial tradeoffs. Figma-plugin solutions (Knapsack, Specify) preserved designer comfort but added cost, kept the system locked inside Figma's tooling boundary, and provided weak AI-readability. Structured token formats (JSON via Token Studio, design-tokens spec) gave engineers parity and AI-readability but were unwriteable for designers without code knowledge. Markdown in GitHub was AI-native, version-controllable, code-adjacent, designer-editable with no specialized tooling, and had zero licensing cost. The tradeoff against markdown was the loss of some visual nuance that Figma natively expressed (motion curves, complex shadow stacks). These were addressed by escaping into linked Figma files for the small set of components where they mattered, while the system itself stayed text-first. The decision compounded value over time: as AI tools evolved and new ones emerged, our system was already in the format they expected.

KEY DECISION 2

Schema design: describe behavior and constraints, not appearance

The first markdown schema attempt dumped CSS properties and Figma attributes directly into each component file. The result was a repository AI could parse but could not actually use. The generated mockups were still inconsistent because the schema told AI what each component looked like in one specific instance, not how it should behave across contexts. The reframe was to standardize each component's markdown into four sections that describe behavior and intent rather than visual specification. Anatomy lists the structural elements. Variants enumerate states, props, and contextual rules. Usage rules describe when to reach for the component and when not to. Anti-patterns explicitly call out the wrong applications that AI was most likely to default to. The anti-patterns section turned out to carry disproportionate weight. By telling AI what not to do, we eliminated the long tail of subtle violations that even comprehensive variant documentation could not prevent.

IMPACT

Designer leverage from AI flipped from negative to positive, and a new designer role emerged

The most concrete outcome was that AI-generated mockups began arriving DS-conformant from the first iteration rather than requiring rework. The hidden translation tax that had been quietly compounding across the team disappeared. Designers reported being able to share AI-generated work directly in stakeholder reviews without the previous fix-up step, and the iteration cycle from prompt to validated mockup compressed substantially. Beyond the workflow improvement, the project established a new role definition within the design org. Designer-as-infrastructure-architect describes the work of building the systems that other designers and AI tools operate inside, and that work is now visible and valued. The team is now positioned for the next phase of AI tooling shifts (MCP servers, agentic design tools, two-way Figma sync) without architectural rework, because the system was built to consume those tools rather than be replaced by them. Specific quantitative metrics will be collected over the coming quarters as adoption deepens; the qualitative signal across the team has been consistent.

CHALLENGES & TRADEOFFS

Engineer skepticism, designer onboarding cost, and the components Figma still owns

Three challenges shaped the project and the way I navigated stakeholders. Engineering was initially skeptical that designers writing markdown would produce useful documentation rather than noise. The concern was reasonable, and I addressed it by running pair-review sessions during the schema design phase so engineers could shape the schema alongside me, which both produced a better schema and built ownership across the boundary. Designer onboarding to the GitHub workflow had real cost. The team had spent years inside Figma, and asking them to push commits felt foreign at first. I built a simple authoring guide and kept the schema deliberately minimal so the activation energy stayed low. Finally, some component categories (illustration, marketing imagery, brand expression) genuinely did not benefit from markdown representation and were left in Figma intentionally. The goal was not Figma replacement but Figma reframing, and being explicit about scope prevented overreach that would have damaged the project's credibility.

LEARNINGS

What changed in how I think about design systems and the designer role

The deepest learning was that AI is a junior designer joining the team. It works fast but needs explicit onboarding, and a design system is the onboarding document we never wrote for humans. Once I started thinking about the system as documentation for the most literal-minded teammate possible, the schema decisions became obvious. The second learning was about format as interface design. Markdown is not just a storage format; it is the interface AI uses to understand our work, and like any interface, it has to be designed for its consumer's behavior. The third learning was about leverage. Every component added to the system improves all future AI output, not just the next prompt. The system is a leverage multiplier that compounds rather than depreciates, and that property fundamentally changes the economics of design system investment. These three reframes together changed how I scope and prioritize design system work, and they will inform every system project I lead going forward.

NEXT STEPS

Where the system goes from here