Meet DESIGN.md: A new open standard for AI-generated UI

Key Concepts

• DESIGN.md: A structured text file format that serves as a single source of truth for a project's visual identity, design reasoning, and technical tokens.
• Design Tokens: Named entities that represent design decisions (e.g., colors, typography) rather than raw values, allowing for centralized updates.
• Specification (Spec): A formal, documented set of rules defining the structure of DESIGN.md to ensure interoperability across different AI agents and tools.
• CLI (Command Line Interface): A tool used to validate and lint DESIGN.md files against the established specification.
• Roles: The conceptual purpose of a design element (e.g., "primary" as the main ink/text color) rather than its specific visual value.

1. The Purpose and Evolution of DESIGN.md

DESIGN.md was originally created to provide AI agents (like Stitch) with a persistent understanding of a design system. It bridges the gap between reasoning (the "why" behind a design choice) and values (the technical implementation, such as hex codes or font sizes).

The format has evolved from a simple internal file into a broader specification because it is increasingly being adopted by IDEs, external agent tools, and open-source repositories. By formalizing the spec, the creators aim to provide a common foundation that prevents "drift" between design documentation and configuration files.

2. Structure: Reasoning vs. Tokens

A core innovation in the updated DESIGN.md is the integration of prose and tokens within the same file:

• Prose/Reasoning: Explains the intent, voice, and emotional goal of a design element.
• Tokens: Defines the technical implementation.
• The Benefit: By keeping these in one file, the context is preserved. If a designer changes the "primary" color, the reasoning and the token are updated in tandem, ensuring the AI agent understands both the aesthetic intent and the technical requirement.

3. The "Role-Based" Design Philosophy

The specification emphasizes that tokens are decisions, not just variables.

• Example: Instead of defining a color as "Deep Midnight Forest Green," it is defined as "Primary."
• Application: The "Primary" role acts as the main ink for headlines. If the brand changes, the developer updates the value assigned to the "Primary" role, and every component referencing that role updates automatically.
• Baseline Requirements: The spec mandates certain roles, such as "Primary" (main ink) and "Neutral" (canvas/background), to ensure consistency across different design systems.

4. Components and Extensibility

The update introduces a Components section (currently a work in progress).

• Reference-based architecture: Components do not hardcode values; they reference roles.
• Example: A button component might reference the "Primary" color role for its background. A "hover" variant can then override only the background property while inheriting other traits from the base component.
• Flexibility: While the spec provides baseline rules, it is designed to be extensible, allowing users to add custom sections that fit their specific project needs.

5. Validation and the CLI

To ensure reliability, a new CLI tool allows agents to "lint" their work against the DESIGN.md specification.

• Workflow:
  1. The agent reads the DESIGN.md context.
  2. The agent makes a design change.
  3. The CLI validates the change (e.g., checking for WCAG contrast ratio compliance).
  4. If the change fails the check, the agent is alerted to adjust its decision or provide a justification for the override.
• Significance: This creates a closed-loop system where the agent is not just consuming data but is actively held accountable to the design system's rules.

6. Community and Contribution

The specification is hosted on GitHub, serving as the central hub for:

• Defining the rules of the format.
• Filing issues and providing feedback.
• Submitting pull requests to evolve the spec.

Synthesis

The update to DESIGN.md represents a shift toward standardized, agent-readable design systems. By combining human-readable reasoning with machine-readable tokens and providing a validation CLI, the framework ensures that AI agents can generate designs that are not only aesthetically consistent but also technically compliant with accessibility standards. The project is currently seeking community feedback to refine the "Components" section and solidify the broader specification.