official-design-md: A Tracker of First-Party DESIGN.md Files for AI Agents

What DESIGN.md Is and the Gap It Fills

AI coding agents can read code, understand architecture, and generate new files. Giving one consistent visual constraints has been harder. A component library documents API shapes. A Figma file documents visual intent. Neither is in a format an LLM can directly act on without intermediate parsing or tooling.

DESIGN.md, introduced as a concept by Google Stitch, is the simplest possible answer: a plain markdown file in the project root. It describes how the project should look and feel, using the same format that language models read most naturally. No Figma export, no JSON schema, no framework-specific configuration. A developer drops the file into a repository, and any AI coding agent that reads the project root picks it up.

The analogy offered in the README is precise: AGENTS.md tells coding agents how to build the project; DESIGN.md tells design agents how the project should look. The two files sit side by side and serve different audiences.

What This Repository Tracks

official-design-md is not a tool and contains no code. It is a curated index of DESIGN.md files that were published by the companies or projects themselves, not extracted from source code, reverse-engineered, or written by the community. The distinction matters: an official DESIGN.md reflects deliberate authorial intent about how the design system should be used with AI agents.

As of the last push on 2026-09-21, the repository lists 11 entries. Each entry in the README names the company, links directly to the official DESIGN.md file, and includes a one-line description of what the file defines.

A companion repository, awesome-design-md, is referenced in the README for cases where the design system was extracted from a real website rather than officially published. That distinction separates official adoption from community inference.

The Companies Currently Listed

The eleven entries span enterprise UI libraries, developer tool platforms, and specialized hardware companies. Ant Design from Ant Group is the enterprise-grade React UI system with a signature blue at `#1677FF` and a full semantic color palette. Atlassian, maker of Jira and Confluence, uses a structured blue palette focused on enterprise clarity. Clerk, an authentication and user management platform, uses a signature purple with a brand system written explicitly for human and AI readers.

Juspay's Blend design system covers payment products with a primary blue, Inter Display typography, and layered tokens for light and dark themes. Microsoft FAST publishes semantic CSS tokens for typography, spacing, color, and theming in its example app design system. Mintlify, a documentation platform, uses a token-driven reading-optimized design. Nuxt uses Nuxt UI with Tailwind CSS v4 and dark mode by default.

Oxide Computer, which builds rack-scale hardware, publishes a dark-first design system with a green accent, monospace UI elements, and OKLCH color tokens. Resend, an email API for developers, uses a minimal dark theme with monospace accents. Vercel's Geist design system is documented as black-and-white precision with a developer-first minimal approach. VoltAgent itself publishes a DESIGN.md with a void-black canvas, emerald accent, and terminal-native styling.

The range shows how different the content can be: Ant Design's file describes a comprehensive semantic palette, while Oxide's file reflects a product that targets systems engineers in a data center context.

How to Use a DESIGN.md File

The README gives a three-step workflow. Follow the link to the official DESIGN.md, copy it into the project root, and tell the AI agent to use it. There is no build step, no import, and no configuration file to update.

The practical outcome depends on how the AI agent handles the project root. Agents that read AGENTS.md, CLAUDE.md, or similar files on startup will pick up DESIGN.md from the same directory. Agents that do not scan the root automatically need to be told explicitly where the file is, or the file's contents need to be pasted into the system prompt or context.

For teams building their own DESIGN.md, the existing files in the index serve as working examples. Vercel's file illustrates how to describe a minimal monochromatic system. Oxide's file shows how to express dark-first styling and specific OKLCH color tokens. The format is unconstrained markdown, so a team can include as little or as much as is useful.

Contributions to the index require opening an issue first to discuss, then sending a pull request that adds the company name and a link to the official file with a one-line description.

Limitations of an Index-Only Repository

official-design-md has no mechanism for detecting when a linked DESIGN.md moves or is taken down. The repository links to external URLs on the companies' own domains and on GitHub. A domain change, a path restructure, or a company decision to remove the file breaks the link without any notification. The README asks contributors to report changed or removed files, but this is a manual process with no automation.

The repository also does not verify whether a submitted DESIGN.md is genuinely official or merely plausible. The contribution guidelines describe the requirement as "official DESIGN.md files published by the company or project itself," but there is no cryptographic proof or direct communication channel with each company listed.

The standard itself is new. The README acknowledges this explicitly: "The DESIGN.md standard is new and official adoption is growing." The eleven entries represent early adopters. A team evaluating whether to invest in writing a DESIGN.md for their own project is making a bet on the adoption trajectory of a convention that no single body governs.

DESIGN.md Compared to Storybook and Design Token Systems

Storybook is the most widely used tool for documenting component libraries. It renders components in isolation with interactive controls and documents their API surface. A Storybook setup requires framework integration, component stories written in JavaScript or TypeScript, and a build process. An AI agent can scrape Storybook documentation, but the format is not designed for direct LLM consumption.

Design token systems like Style Dictionary or Theo export design variables (colors, spacing, type scales) from a source of truth into multiple target formats. They are precise but require tooling to transform and import. They describe values, not intent or usage context.

DESIGN.md sits at the opposite end of the complexity axis. It is a single file, in a format LLMs process natively, describing intent and usage in prose and structured markdown. It does not replace a component library or a token system, but it answers a question those tools do not address: what should the AI agent do when generating new UI that has no existing component? The DESIGN.md gives the design vocabulary and visual principles in a form the agent can act on immediately without a build step or API call.

Editorial conclusion

official-design-md is worth bookmarking if you use AI coding agents that can consume a DESIGN.md file and want to base your UI on an established design system. The index is only as current as its contributors, so verify that any linked file is still live at the linked URL before relying on it. For teams building their own system, this repository shows the format and tone that companies like Vercel, Oxide, and Clerk chose, which is more useful than any abstract specification.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. VoltAgent/official-design-md on GitHub