VoltAgent/official-design-md Is a Link Index, Not a Design System
Official DESIGN.md files published by companies themselves. First-party design systems that AI agents read to generate consistent UI.
At a glance
- What is it?
- The repository collects eight first-party DESIGN.md files published by companies such as Vercel, Atlassian and Ant Design. It holds no code, no schema and no parser, so its value depends entirely on whether the upstream files stay where they are.
- Who is it for?
- Adopt this repository as a discovery list if you are evaluating how companies write DESIGN.md files, or if you want a starting point for writing one of your own. Do not treat it as a dependency: there is nothing to install, and the eight entries are external URLs that can move or disappear without notice from this repo.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What This Repository Actually Contains
The README is blunt about the scope: this is "the tracker for first-party DESIGN.md adoption." Every entry is a DESIGN.md published by the company or project itself, and the README rules out extracted, reverse-engineered or community-made files. The Collection section lists eight of them, each as a single link with a one-line description: Ant Design, Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel and VoltAgent. That is the whole artifact. There is no source directory, no generator, no validation script and no data file behind the list. The repository is a markdown page plus a MIT licence. Anyone expecting a tool will be disappointed, because there is nothing here to run. The audience is narrower and more specific than the topics list suggests. It is for people who need to know which organizations have committed to publishing a design system document in plain markdown, and who want the canonical URL for each one rather than a copy. A second repository, awesome-design-md, is pointed at for the opposite case: ready-to-use files extracted from real websites. The split is deliberate and worth respecting. If you want a design system you can drop into a project today without asking anyone's permission, the extracted collection is the one you want. If you want to see how Vercel or Atlassian writes the format in their own voice, this is the index for that.
The DESIGN.md Format and Where It Came From
According to the README, DESIGN.md is a concept introduced by Google Stitch, described as a plain-text design system document that AI agents read to generate consistent UI. The format is deliberately minimal. The README states there are no Figma exports, no JSON schemas and no special tooling, and that markdown is used because it is the format LLMs read best, so there is nothing to parse or configure. The claimed workflow is to drop the file into a project root, after which an AI coding agent or Google Stitch understands how the UI should look. The repository draws a clean division of labour between two files. AGENTS.md tells coding agents how to build the project. DESIGN.md tells design agents how the project should look and feel. That pairing is the most useful idea in the README, because it separates build instructions from visual constraints instead of mixing them into one prompt file. The entries give a sense of what a finished document contains, though only at the level of a one-line summary. Ant Design is described as carrying a signature blue of #1677FF with a full semantic color palette. Vercel is summarized as the Geist design system with black and white precision. Nuxt is noted as powered by Nuxt UI and Tailwind CSS v4, with dark mode by default. Those are the maintainers' descriptions, not a specification. The README does not define required sections, naming conventions or a schema, and it does not claim one exists. Treat DESIGN.md as a convention rather than a standard with a validator behind it.
Getting a File Into Your Project
There is no installation step, because the repository publishes nothing executable. The README's How to Use section gives three steps: follow the link to the official DESIGN.md, copy it into your project root, and tell your AI agent to use it. The file name matters more than the path, since agents are expected to find DESIGN.md at the root alongside AGENTS.md. The practical work happens at the link. For example, the Vercel entry points at vercel.com/design.md, the Atlassian entry at atlassian.design/DESIGN.md, and the Ant Design entry at ant.design/design.md. Note that the URL casing is inconsistent across providers, with Atlassian using uppercase DESIGN.md and the others lowercase, which matters on case-sensitive filesystems if you mirror the paths. The VoltAgent entry is the odd one out: it links to a file inside a GitHub repository rather than a marketing domain, which makes it the easiest of the eight to fetch with a plain curl against raw.githubusercontent.com. The README does not document a fetch command, a checksum, a version pin or a sync script, so copying is manual and the copy will drift from the source the moment the publisher edits the original. Nothing in the repository tells you when an upstream file changes. The Contributing section asks readers to report a change if an official file moved or was taken down, which is a human process, not automation.
Why the Index Breaks Down Over Time
Link rot is the structural weakness. The repository's only content is outbound URLs, and the README's own contributing guidance anticipates the failure mode by asking people to report moved or removed files. A design system document is a living artifact at most companies, and the URL that serves it can be renamed, gated behind a login, or folded into a docs site during a redesign. When that happens, this repository does not notice. There is no CI check, no scheduled fetch and no cached copy, so a dead entry looks identical to a working one until someone clicks it. The second limitation is coverage. Eight entries is a small number, and the README says official adoption is growing, which is an admission that the list is incomplete by design. If the company whose UI conventions you need is not among the eight, the index cannot help you. The third issue is that a link is not a licence grant. The README states that all linked files remain the property of their respective owners and that the repository does not host or claim ownership of any linked content. The MIT licence on this repository therefore covers the index page only. Copying Vercel's or Atlassian's DESIGN.md into your own project is a separate decision with its own terms, and the README does not describe what those terms are for any of the eight. Read the source site before you vendor a file.
How It Differs From awesome-design-md
The maintainers publish two collections with opposite sourcing rules, and the difference is the whole point. awesome-design-md, linked from this README, offers ready-to-use DESIGN.md files extracted from real websites. That collection is useful when you need a document now and are willing to work from a reconstruction of someone else's interface. This repository refuses that approach entirely: entries must be published by the company or project itself, not extracted and not community-made. The trade is coverage and convenience for provenance. An extracted file can describe any site, including ones that will never publish a design document, but it is someone's interpretation. A first-party file is authoritative about the publisher's own system, and there are only eight of them. Neither approach is a substitute for the other. If you are building a product that should look like Linear, the extracted collection is the only place to look. If you are writing your own DESIGN.md and want to see how a company with a mature design system structured theirs, the first-party index is the better reference, because you are reading the publisher's actual intent rather than a third party's reading of their CSS.
Maintenance Cost and Licence Boundaries
The cost of using this repository is close to zero and the cost of relying on it is not. Nothing here needs upgrading, since there are no releases, no dependencies and no versioned artifacts. The maintenance burden sits with the maintainers, who have to keep eight external links alive by hand, and with anyone who vendors a linked file, who inherits the job of tracking upstream edits. The repository's MIT licence is stated plainly in the README and covers the index itself. The README also states that linked files remain the property of their respective owners and that the project does not host or claim ownership of any linked content. That sentence is the one to read carefully before copying anything. It means the MIT grant you see on this repository does not extend to Vercel's, Atlassian's or anyone else's DESIGN.md. Whether you may copy, modify or redistribute a given file depends on terms published by that company, which this repository does not summarize and does not link to. This is a factual boundary in the material, not legal advice, and the absence of any per-entry licence note is a real gap if you plan to vendor a file into a commercial codebase.
Who Should Use This and What to Check First
Use it if you are deciding how to write a DESIGN.md for your own project and want first-party examples to read, or if you are tracking which organizations have adopted the format. The eight entries span an enterprise React system, a developer deployment platform, a documentation tool, an auth provider, a Vue framework, an email API and an AI agent framework, which is enough variety to see how different companies handle color, typography and dark mode in prose. Skip it if you need an installable package, a parser, a schema or a validated standard. None of those exist here, and the README does not claim they do. Skip it too if your target is a design system from a company outside the list, since the index cannot generate entries. The first thing to verify is whether each link still resolves to a first-party file, because the repository has no mechanism to tell you otherwise. The second is the licence position on whichever file you intend to copy, since the MIT licence here stops at the index. The third is whether the file you copy is current, because a manual copy has no update path back to the source. The repository is a reading list with a clear sourcing rule, and it is honest about being one.
Editorial conclusion
Adopt this repository as a discovery list if you are evaluating how companies write DESIGN.md files, or if you want a starting point for writing one of your own. Do not treat it as a dependency: there is nothing to install, and the eight entries are external URLs that can move or disappear without notice from this repo. Before you copy any of them into a project root, open the linked file directly, check whether it is still live, and read the licence terms of the company that published it, since this repository's MIT licence covers only the index and explicitly does not cover the linked documents.
Community notes