Documentation Is the New Interface — and Design Systems Are the Testing Ground

Key Insights

1 — Design System Teams Now Design Two Interfaces Simultaneously

Figma’s new “Make Kit Guidelines” are documentation written not for humans, but for an AI agent that generates code from design tokens and components. That sounds like a technical footnote — but it’s an architecture shift. Design system teams that previously built one interface for developers (Storybook, docs sites, readmes) are now building a second: one for machines that interpret and apply these systems.

The implication extends beyond Figma. Every system consumed by AI agents — codebases, knowledge bases, API documentation — faces the same question: Is our documentation a reference or a control layer? Figma answers by treating guidelines as a standalone design discipline, not an appendix.

2 — Granularity Beats Completeness

The central architecture decision: “Multiple short guidelines files are better than a few large files.” Not because short files look nicer, but because AI agents operate within limited context windows. A monolithic design-system.md with 2,000 lines forces the agent to carry irrelevant information. Twenty focused files — button.md, color.md, typography.md — enable precise retrieval.

This is a design decision that has nothing to do with content and everything to do with information architecture. The parallel to microservices isn’t accidental: decomposition enables targeted addressing. If you document your design system as a monolith, you’re building an architecture that penalizes AI agents.

3 — Imperative Over Descriptive: Documentation as Constraint

Figma recommends replacing vague phrasing with imperative statements. Instead of “Use small text sparingly,” it becomes “Do not use small text except for captions.” The difference isn’t stylistic — it’s functional: an AI agent cannot resolve ambiguity. “Sparingly” is interpretable for a human; for an agent, it’s noise.

The consequence: good AI documentation reads like a rulebook, not a style guide. That changes who writes it and how. Content designers optimizing for readability must now also optimize for parsability — and the two goals compete.

4 — Folder Structure Is Retrieval Architecture

The recommended structure — components/, foundations/, composition/ with an overview.md each as router — isn’t filesystem aesthetics. It’s the search architecture through which the AI agent navigates. An overview.md in the components folder acts as an index routing the agent to the right detail file. Folder structure becomes API.

This has an uncomfortable consequence for existing design systems: their documentation structure, organically grown from Confluence pages and Storybook addons, is no longer neutral storage. It’s actively detrimental when an AI agent needs to traverse it. Migration isn’t a docs project — it’s an architecture refactoring.

5 — Decision Trees as Control Logic

Instead of prose descriptions, Figma recommends decision trees: “Which button variant? → Primary for main actions, Neutral for secondary, Subtle for tertiary.” This isn’t a documentation style — it’s control flow logic. The agent doesn’t get text to interpret; it gets an algorithm to execute.

The parallel to classic interface design is direct: a decision tree in documentation is functionally equivalent to a dropdown selector in UI — it reduces the decision space to valid options. Documentation becomes interaction.

6 — Convergence: The Same Principles Emerge Independently Across Domains

Figma’s recommendations converge with patterns that emerged in entirely different contexts. AI-optimized knowledge bases follow the same rules: atomic files over monoliths, index files as routers, imperative framing, decision chains over prose. Anyone building a personal knowledge system for LLM agents arrives at the same architecture decisions as Figma — without having read Figma’s guidelines.

This points to a cross-domain pattern: there’s an emergent grammar for “documentation that controls machines.” It’s neither tool-specific nor domain-bound. It follows from technology constraints — context windows, retrieval mechanisms, ambiguity intolerance — and these constraints are universal.

Critical Assessment

What holds up

• The core thesis is robust: AI agents consume documentation fundamentally differently than humans. This changes what “good documentation” means — not as replacement, but as extension.
• Practical principles work: Granularity, imperative style, and decision trees demonstrably improve AI-generated output quality — not just in Figma Make, but in any RAG architecture.
• Cross-domain convergence as evidence: When independent systems (design systems, knowledge bases, codebases) converge on the same patterns, that’s a stronger argument than any single recommendation.
• “Treat AI like a new engineer” is the right mental model — it lowers the barrier for teams that have never considered AI consumers of their documentation.

What needs context

• Vendor context: Figma sells a product (Make) that specifically needs these guidelines. The recommendations are sound but not neutral — they optimize for Figma’s retrieval pipeline, not for AI agents in general.
• Maturity: The field is six months old. Whether “AI-compatible documentation” establishes itself as a distinct discipline or merges into good documentation practice remains open.
• Counter-hypothesis: Perhaps AI doesn’t demand new documentation — it makes existing documentation’s flaws visible. Imperative, granular, and structured is what we should have always written — AI is just the occasion to finally do it.
• Effort: Dual documentation (for humans and machines) doesn’t double the work, but it creates maintenance costs. Who synchronizes developer docs with agent guidelines when components change?
• Knowledge base parallels have limits: A personal knowledge system for a single agent and a design system for a team of 50 developers have different governance requirements.

Discussion Questions for the Next Lab

01 Dual Interface: If design system teams now document for humans and machines simultaneously — who on the team owns this? Does Design Ops need a new role, or is this an extension of existing documentation engineering practice?

02 Documentation as Product: Is the consequence that documentation itself becomes a designed artifact — with its own information architecture, its own testing, its own quality gates? And if so: what does that mean for budgets and prioritization in design system teams?

03 Convergence Test: What other systems — codebases, API docs, onboarding materials — benefit from the same principles (granularity, imperative, decision trees)? Is there a universal checklist for “AI-ready documentation”?

04 Taking the Counter-Hypothesis Seriously: If the “new” rules are actually old ones (clear, structured, precise) — is “AI-compatible documentation” a standalone topic or just a rebranding of documentation quality?

05 Build vs. Buy: Is it worth migrating existing design system documentation for AI — or is it more efficient to build it in parallel and keep the old version for humans?

Sources

• Figma Developer Documentation: Write Design System Guidelines for Make Kits
• Figma Make: AI-Powered Code Generation

Glossary

Make Kit / Figma’s package format for design systems that enables AI code generation. Contains components, tokens, and guidelines as a machine-readable unit.

Context Window / The maximum amount of text an AI model can process simultaneously. Limits how much documentation an agent can “see” — making granularity an architecture decision.

Retrieval / The mechanism by which an AI agent finds and loads relevant documentation into its context window. Folder structure, filenames, and index files are retrieval infrastructure.

Decision Tree / Branching if-then logic that guides an agent through variant selection. In documentation: an alternative to prose descriptions that eliminates ambiguity.

RAG (Retrieval-Augmented Generation) / Architecture pattern where an AI model retrieves external documents before responding. Design system guidelines for AI are functionally RAG documents.

Dual Interface / The pattern of maintaining two documentation layers in parallel — one for human developers (readable, contextual), one for AI agents (parsable, imperative, granular).