official-design-md is a tracker made of two files

The whole repository is a licence and a readme

There are two entries at the top level of this repository. One is the licence file. The other is the readme.

That is the entire project. The collection of eleven design documents is a bulleted list inside the readme, each item a link with a one-line description. There is no data file, no structured format, no generated site, no build step and no feed.

The practical consequences follow from that. Nothing here can be queried. An agent cannot discover which companies publish a design document without being handed the page. A script cannot check that the links still resolve, and a diff of the repository shows only prose changes. If you wanted to build a tool that suggests the right design document for a project, you would have to scrape a readme.

None of that is wrong for what it is. A curated index maintained by a person, small enough to read in two minutes, has real value that a generated registry would not. But the word tracker in the project's own description implies more machinery than exists, and anyone planning to depend on it programmatically will find the floor missing.

The sibling repository is the mirror image: the readme points to a separate collection of ready-to-use design documents that were extracted from real websites. One is a hand-maintained list of eleven links, the other is presumably a library of files.

The admission criterion is who published it

The editorial rule is stated in the first paragraph and repeated in the licence note, and it is the most interesting thing about the project.

Every entry is a document published by the company or project itself. Not extracted from a rendered site, not reverse-engineered from their bundle, not written by a community member who studied their interface and reconstructed a spec.

That is a genuine quality bar. An extracted design system is a description of what a company does, while an official one is a statement of what they intend, and the two have different failure modes. The extracted version can drift the moment the site updates, silently, because nothing marks the extraction as stale. The official version changes only when its authors change it.

The separation is also maintained across two repositories. When a reader wants extracted documents, the readme sends them elsewhere rather than listing them here. So the same organisation is running both halves of the collection and refusing to mix them.

The criterion is enforced socially rather than technically. The contributing section asks for a link to the official file with a company name and a one-line description, and it asks reporters to flag when an official file has moved or been taken down. There is no automated check that a linked file is still first-party or still present, so the index is exactly as current as the last person who looked.

Three of the eleven links are not files you can drop into a project root

The usage instructions are three steps: follow the link to the official document, copy it into your project root, and tell your agent to use it.

That works cleanly for the entries served as a bare file on a company's own domain, where the link resolves to one document and you save it.

It does not work for the entries that live inside other people's repositories. Four of the eleven are hosted that way, and three of those are not a design document at the repository root. One is a design system sitting on a branch that is not the default branch, which is a path that will change the next time that branch is merged or deleted. Another is a design system stored under an examples subdirectory of a large component framework, which is where demonstration material lives rather than where a spec lives. The third is in a design-system repository on a branch with a non-default name.

So step two, copy it into your project root, is a description of an aspiration rather than a procedure for those three. A user who follows it will end up with a file whose relative references point at directories that do not exist in their project, because the document was written to live somewhere else.

That is not a criticism of the companies publishing these. It is a property of listing documents by provenance rather than by distribution, and the readme could note which entries are self-contained and which are not. It does not.

Filename case and host conventions are inconsistent

The convention the project documents is a file named in a particular case at the root of a project. The files it links do not agree on that case.

Among the entries served as a bare file, some use the uppercase form and some use the lowercase form for the same concept. A convention that a tool might key on, such as a filename match, would therefore have to try both cases, or match loosely.

The hosting is equally varied. Seven entries are served from seven unrelated corporate domains at no shared path convention, some at a design-system subdomain and some at the company's main marketing domain. Four are served from a source-hosting site inside other projects. There is no manifest, no common parent directory, and no way to tell from the list which of these are generated pages versus files committed to a repository.

For a human following a link, none of this matters. The file opens, it is the right document, and you copy it.

For the ecosystem this is meant to enable, it means there is no central point of contact. If the format is going to be a convention, something has to be true of it that a reader can rely on beyond the concept, and today what is reliably true is only that a file exists somewhere with roughly the right name.

No entry records a date, a version, or a licence

Read the eleven entries as a data set and notice what is missing. Each has a company name, a link, and a sentence about its visual character. None has a date, a version, a licence, or a size.

The descriptions themselves are the most interesting part of what is there, and they are genuinely useful as an index. One is described by its signature blue and a hex value, one by a signature purple and a note that its brand system was written for humans and agents together, one by dark-first with a green accent and monospace text, one by black-and-white precision, one by a void-black canvas with an emerald accent and a terminal-native character. That is the kind of thing you cannot infer from a company's own site, which is a real contribution.

But the absence of a date is what will bite first. A first-party design document changes when its authors change it, and a link with no recorded state means a reader arriving in six months cannot tell whether what they are copying matches what the company ships today. The project has thought about this problem, because the contributing section explicitly asks people to report when an official file has moved or been taken down.

That is a human process for a problem that a periodic check would solve. Nothing in the repository attempts one.

A sponsored block sits between the introduction and the list

Immediately after the section explaining what the format is, and before the collection, there is a promotional paragraph.

It is written in the register of the project's own opening, about shipping products and launches going unnoticed, and it describes a service that plugs an assistant into a social workspace to draft, schedule and publish across a stated number of channels. The only number in the block belongs to the sponsor.

Below it are three link blocks. In this copy of the readme, one carries the service name as its anchor text and the other two are empty, leaving a bare link with nothing to describe the destination.

This is ordinary sponsorship and the placement is not concealed. It is worth naming anyway because of what this particular document is. The value of a curated index is that you can trust the list: every entry was checked, nothing was added for money, and the whole page can be read as a neutral reference. A sponsor block does not break that trust, since it is not an entry, but it does mean the page is not purely a reference, and a reader skimming for links will meet an advertisement first.

The two empty anchors are the part that actually reduces the quality. A link with no label tells a reader nothing about where it goes or whether they should follow it.

The load-bearing claim is a format argument, and it is unfalsifiable here

The interesting argument in the readme is not about any of the eleven companies. It is about why this format should exist.

The comparison table sets out a two-file convention. One file is read by coding agents and describes how to build the project. The other is read by design agents and describes how the project should look and feel. Different consumers, different halves of the same problem.

The justification for using plain text is a compatibility argument rather than an authoring one: no design tool exports, no schemas, nothing to configure, and a markdown file in a project root is something any coding agent or design tool understands. The stated reason is that markdown is the format models read best, so there is nothing to parse.

That is a reasonable argument and it is also the project's whole case, which means it deserves more support than a paragraph. Whether a model reliably follows a prose design specification, and whether doing so yields consistent output across runs and across models, is not something this repository demonstrates. There is no evaluation here, no before-and-after comparison, and no account of what happens when a document is ambiguous or incomplete, which is the normal state of a design system.

What the project does establish is narrower and still useful: there is a growing set of companies publishing these files, and here is where they are.

Editorial conclusion

This index is worth bookmarking for the provenance discipline alone, since it refuses to list extracted or community-made documents and points somewhere else for those. Treat it as a reading list rather than a dependency: nothing in it records when a file was last checked or what version it was, three of the links point inside other projects rather than at a root file, and if you want a machine-readable list you will have to build one yourself.

Frequently asked questions

Official sources

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