I've Never Designed Anything Like This

The real shift here wasn't adding AI to the workflow. It was structural: the same file that describes a component to a designer describes it to an AI agent and to an engineer. You don't write the component and then document it. The documentation is the component.

This is different from "design + engineering aligned" — that's cultural. This is structural alignment: one markdown spec at the center, all three consumers reading from it simultaneously. When the file is done, every consumer is done.

The standard model: a designer creates a component in Figma. An engineer implements it in code. The connection between them is informal — a Figma link, a Zeplin handoff, a Slack thread. Documentation lives separately, in Notion or Confluence or a doc site, and it's always slightly out of date because updating it is a second job.

AI tools trying to generate UI or assist with design read from whatever they can find — Figma files, code comments, documentation pages — and get inconsistent answers depending on which artifact they encounter first. The result: designers, engineers, and AI agents are all reading from different versions of the same truth.

For a team like Fluent, this compounds. 500+ tokens with no shared language to help anyone know what's redundant. Components marked "high priority" in one doc, "P0" in another, "critical" in a third. Figma component authoring was manual, repetitive, and disconnected from the spec — updating a component meant touching the same information in multiple places.

The fluent-design GitHub repository becomes the source of truth. Not Figma. Not a doc site. A repo. The shift sounds simple; the implications are substantial. One update in the markdown propagates to all consumers. Shared language means the same terms appear in glossary.md, TypeScript type comments, YAML specs, and Figma component descriptions — tokens are human-readable and AI-inferable from a single source.

The Figma asset step is where the system's speed becomes visible. Claude reads the exported spec and builds the component directly in Figma — no manual Figma work required for the build step. For a button component, this takes 7 minutes.

The important context: 7 minutes is the Figma asset step specifically. The full workflow — spec → usage → demo → Figma asset — is 1+ hours end to end. The 7-minute number is a result of the system working correctly, not a headline claim about AI speed. The speed is evidence of structural alignment. A Figma build that takes 7 minutes from an exported spec is only possible because the spec is precise enough, machine-readable enough, and complete enough for the model to act on without ambiguity.

The technology-agnostic markdown spec is what makes cross-platform extension possible. The same spec that generates a web component generates an iOS/SwiftUI component. The same spec that a human designer reads is the spec an MCP-compatible tool consumes.

This was the core collaboration: the engineering architecture and the design specification were built together, from the beginning, to serve the same source. That joint authorship is what makes the system structural rather than cultural — it's not a design team and an engineering team agreeing to look at the same file. It's one file that's actually right for both.

The shared language diagram is the most concrete proof the system is working: the same term appearing in glossary.md, a TypeScript type description, a YAML spec field, and a Figma component description — unchanged, without translation, without interpretation.

Before this system, a designer might call something a "label," an engineer might call it a "caption," the Figma component description might say "text," and a documentation page might use all three. AI tools trying to connect these get inconsistent answers. The glossary resolves this: one term, defined once, verified to appear consistently across all surfaces.