Back to Devoured - May 07, 2026
DEVOURED
Component.md

Component.md

Design aifrontendaccessibility
Ian Guisard built component.md, a markdown spec format for design system components, after watching Claude Design and other AI tools consistently botch Figma implementations because critical details like tokens, accessibility, and behavior aren't captured in design files.
What: Guisard argues AI design tools (Claude Design, Figma Make, Lovable) fail to accurately recreate Figma designs because design systems only document visuals while behavior, accessibility, tokens, and implementation logic remain undocumented. His solution is component.md—a structured markdown file per component containing API specs, structural specs, color token assignments, screen-reader behavior, and behavioral rules. The implementation uses a two-stage process: deterministic extraction via the uSpec Figma plugin, then parallel specialist agents that reason about structure, color, and accessibility before converging to a single spec. uSpec 2.0 ships with the create-component-md skill and Figma extraction plugin, free and open source at uspec.design.
Why it matters: This reveals a fundamental shift in design system audiences—from humans who interpret incomplete specs to AI tools that need explicit specifications. The gap between close and correct in AI-generated implementations is not a model problem but a specification problem. As AI becomes the primary consumer of design artifacts, design systems must evolve from visual documentation to queryable, machine-readable sources of truth.
Takeaway: If you maintain a design system used by AI tools, start documenting component.md specs at uspec.design to get accurate implementations instead of guessed-at approximations.
Deep dive
  • Guisard maintains design systems used by hundreds of engineers and tested AI tools (Figma Make, Claude Code, Lovable, Claude Design) on his Figma files—none accurately recreate designs, always missing optical alignment, fonts, spacing, micro-interactions, and token assignments
  • The problem is not the AI models but upstream specification gaps: Figma files were built to be read by human engineers who interpret missing details, not by tools that need explicit specs
  • Design system source of truth is currently scattered across Figma files, designer knowledge, Slack threads, and code reviews—Figma provides information (dimensions, colors, variants) but not the full specification
  • Component.md is a proposed markdown spec—one file per component—that serves as the actual source of truth readable by both humans and LLMs, containing API specs, structural specs, color token assignments, voice/screen-reader behavior, and behavioral rules
  • Implementation uses two stages: deterministic extraction via the uSpec Figma plugin (walks through sub-components, captures layout/variants/tokens/layer tree as JSON) followed by agentic creation where specialist agents reason in parallel about structure, color, and accessibility before converging to a single component.md file
  • This separates cheap work (script-based extraction that pulls numbers from Figma) from expensive work (LLM-based reasoning about what those numbers mean), avoiding hallucinations and reducing costs
  • The schema example shows an error state spec with both color tokens (error-border-accessible for container stroke) and ARIA attributes (aria-invalid: true) in one file, ensuring both ship together
  • Guisard argues this represents a shift from static documentation interpreted by humans to interactive documentation that reshapes based on the reader (human designer, engineer, or AI tool)
  • Figma's role shifts from being asked to serve as implementation spec to being the studio where visual exploration happens cheaply before decisions are captured in the blueprint (component.md)
  • uSpec 2.0 ships with the create-component-md skill and Figma extraction plugin, free and open source, documented at uspec.design with code on GitHub
  • The article includes concrete visual examples showing a textfield and picker component three ways: Figma source, what Claude Design ships without a spec (close but wrong), and what it ships with component.md (accurate)
Decoder
  • Design tokens: Named variables that store design decisions like colors, spacing, and typography values (e.g., error-border-accessible) so they can be consistently referenced across components and platforms.
  • ARIA: Accessible Rich Internet Applications—a set of HTML attributes (like aria-invalid, aria-errormessage) that provide semantic information to assistive technologies like screen readers.
  • VoiceOver / TalkBack: Screen reader software built into iOS/macOS (VoiceOver) and Android (TalkBack) that reads interface elements aloud for blind and low-vision users.
  • MCP server: Model Context Protocol server—a way to expose structured data and capabilities to AI tools so they can query and interact with external systems.
Original article

AI design tools struggle to accurately recreate designs from Figma because most design systems only describe visuals, while important details like behavior, accessibility, tokens, and implementation logic remain undocumented or scattered across teams. The proposed solution is a “component.md” spec for every component — a structured markdown file that acts as a true source of truth both humans and AI tools can read to generate consistent implementations. Rather than replacing design tools, the idea is to separate visual exploration in Figma from the detailed specifications AI systems need to reliably build products.

Explore all 73 articles in today's digest

Fresh dev news, AI-digested daily. Never miss a trend at devoured.fyi