DESIGN.md files against the official linter: 1,162 checked

By markdownregistry. Published October 4, 2026. Updated October 4, 2026.

Most DESIGN.md files keep their design values in the markdown body, not in tokens a tool can check. Of 1,162 DESIGN.md files in public GitHub repositories, 78.1% have no YAML design tokens, which the format leaves optional, though 747 of those still spell out three or more hex colors in their text. Of the 254 with tokens, 88.6% pass the format's own linter with no errors, and only 8.3% with no warnings either.

Linter result	Files	Share of files with tokens
No errors	225	88.6%
No errors and no warnings	21	8.3%
Defines a color that no component refers to	103	40.6%
Writes a typography token as one string, not an object	81	31.9%
A component's text and background fall below 4.5:1 contrast	66	26.0%
A component uses a sub-token the format does not define	47	18.5%
Defines colors, but none named primary	43	16.9%
Has a value that is not a valid dimension (an error)	22	8.7%

The 254 of 1,162 DESIGN.md files in public GitHub repositories that carry design tokens, each read at its latest version in the registry and run through the format's own linter, version 0.4.0, on October 4, 2026. A file can show more than one result. How each was counted is under How we counted.

Counted from the registry's own crawl of public GitHub and checked with the linter from the format's repository, pinned at version 0.4.0, on October 4, 2026.

Two kinds of DESIGN.md

The format published by Google Labs, which marks itself alpha, describes a DESIGN.md in two parts: optional YAML front matter holding exact design tokens (colors, typography, rounded corners, spacing and components), and a markdown body explaining them. When the tokens are there, its repository says they are the normative values and the prose gives the context for applying them.

Most files with the name use only the body. 908 of the 1,162 files (78.1%) hold no YAML at all, as front matter or in a fenced YAML block, which the linter also reads, and its only finding for each is that no YAML content was found. That is allowed, but it moves the values into the markdown body: 747 of those 908 files (82.3%) name three or more hex colors there, in sentences, palette tables or inline code. A model reading the file can use those colors; the linter cannot check them, and the format's export command, which turns tokens into CSS or Tailwind settings, cannot carry them. Many files are also shared templates: the 1,162 files hold only 715 distinct contents, so 447 of them are byte-for-byte copies of another file counted here.

What the linter flags in files with tokens

The 254 files with tokens mostly parse: 225 (88.6%) have no errors. Warnings are another matter, and only 21 files have none. The commonest, by file:

A color no component refers to, in 103 files (40.6%). The rule applies only to files that define components, and skips the standard color families such as primary and surface, so it flags extra colors the components never use.
A typography token written as one string, such as "Inter 48px bold", in 81 files (31.9%). The format's typography type is an object with properties such as fontFamily, fontSize and lineHeight. Version 0.4.0 of the linter reports a string like this one warning per character, so these files can carry dozens of warnings for one mistake; counted by file, it is one.
Low contrast, in 66 files (26.0%): a component whose text color on its background falls below 4.5:1, the WCAG AA minimum the linter checks.
A component sub-token the format does not define, in 47 files (18.5%).
No color named primary, in 43 files (16.9%). The linter's message says an agent will then generate key colors itself, which leaves less of the palette in the file's hands.

The errors

29 files with tokens (11.4%) have at least one error. The commonest is a dimension the format does not accept, in 22 files: the format's dimensions are a number with a px, em or rem unit, and values such as normal for a line height or a bare 0 fail that test. 9 files have a color the linter cannot read as a CSS color, 4 have a reference to a token that does not exist, and 1 has a font weight that is not a number.

Lint your own DESIGN.md

The linter runs with npx and prints its findings as JSON, each with a severity and a message. This is the output, cut to those two fields, from a scratch DESIGN.md with two colors, neither named primary, and a typography token whose line height is normal:

$ npx @google/design.md@0.4.0 lint DESIGN.md | grep -E '"(severity|message)"'
      "severity": "error",
      "message": "'normal' is not a valid dimension."
      "severity": "warning",
      "message": "No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette.",
      "severity": "info",
      "message": "Design system defines 2 colors, 1 typography scale.",
      "severity": "info",
      "message": "No 'spacing' section defined. Layout spacing will fall back to agent defaults.",
      "severity": "info",
      "message": "No 'rounded' section defined. Corner rounding will fall back to agent defaults.",

The command exits with status 1 when there is an error, which makes it usable as a check in CI. Pin the version, as here: the format is alpha, and its rules can change between releases. Real DESIGN.md files from other projects are on the DESIGN.md page, and what the file is for is in what DESIGN.md is and how agents use it.

How we counted

The registry collects agent markdown from public GitHub repositories and stores every version of each file by the SHA-256 of its content. We took every file named DESIGN.md it holds, read each one's latest stored version, checked its bytes against its hash, and ran the format's linter, the @google/design.md package at version 0.4.0, on a copy of it. A file has no tokens when the linter reports that no YAML content was found, and names hex colors in its text when three or more distinct six- or three-digit hex codes appear anywhere in it. Results are counted by file: a file is counted once for a rule however many findings that rule gives it. Some findings in version 0.4.0 carry no rule name; they are named here by their message, and a typography finding whose property is a number, which is what a token written as a string produces, is counted as a string token. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories.

Sources

Last checked October 4, 2026.