In a Markdown Registry sample of 1,162 public-GitHub DESIGN.md files, most files had no YAML design tokens. Among the 254 files that did contain tokens, 88.6% produced no errors under @google/design.md 0.4.0, but only 8.3% had neither errors nor warnings. These are results for files found by the registry’s crawl, not an estimate for every DESIGN.md on GitHub.
What the audit checked
The analysis used every file named DESIGN.md in the Markdown Registry’s crawl of public GitHub repositories. It selected each file’s latest stored version, checked its content against its SHA-256, and ran @google/design.md version 0.4.0 on October 4, 2026. The registry does not cover all of GitHub, so the findings describe its sampled repositories.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
Blackmagic Design USB Davinci Resolve Editor Keyboard | $669.00 | Buy on Amazon |
| 2 |
|
Editors Keys Dedicated Keyboard for Photoshop | PC Shortcut Keyboard | $99.99 | Buy on Amazon |
| 3 |
|
Learn Markdown: The Complete Guide on Markdown Formatting | $0.99 | Buy on Amazon |
As an Amazon Associate I earn from qualifying purchases.
The 1,162 files contained 715 distinct file contents: 447 counted files were byte-for-byte copies of another file in the sample. Counts therefore represent files, not unique design systems. For each rule, the audit counted a file once even if the linter reported multiple findings for that rule.
Most files described design in prose, not YAML tokens
Google’s alpha DESIGN.md format combines optional YAML front matter for structured design tokens—such as colors, typography, spacing, rounded corners, and components—with a Markdown body that explains how to apply the system. Of the 1,162 audited files, 908 (78.1%) had no YAML content, including fenced YAML that the linter can read.
#1 Best Overall
- Designed for professional editors who need to work faster and turn over quickly
- Designed for DaVinci Resolve 16
- Integrated search wheel integrated directly into the keyboard
That does not make a file invalid: the format allows prose-only guidance. But prose values are not machine-checked as tokens or carried into CSS or Tailwind settings by the described export workflow. The gap is notable in the sample: 747 of those 908 prose-only files (82.3%) named at least three distinct three- or six-digit hex colors in their prose. An agent may be able to read those colors, but the linter cannot validate them as structured tokens.
Token-bearing files: few were warning-free
The remaining 254 files contained tokens. The distinction between “no errors” and “clean” matters: most avoided errors, while very few avoided warnings as well.
| Result among token-bearing files | Files | Share |
|---|---|---|
| No errors | 225 of 254 | 88.6% |
| Neither errors nor warnings | 21 of 254 | 8.3% |
| At least one error | 29 of 254 | 11.4% |
The warning and error categories overlap, so their counts should not be added as if each file belonged to only one category. The figures count files with a rule finding, not total findings.
Common warnings and format issues
- Unreferenced colors: 103 files (40.6%) defined a color that no component referred to. The rule applies only when a file defines components and excludes standard color families such as
primaryandsurface. - Typography as a string: 81 files (31.9%) expressed a typography token as one string rather than an object. In version 0.4.0, this rule can emit one warning per character, although the audit counts the file once for the rule.
- Low-contrast component pairs: 66 files (26.0%) had a component text/background pair below the 4.5:1 threshold that the report attributes to WCAG AA.
- Undefined component sub-tokens: 47 files (18.5%) used a component sub-token not defined by the format.
- No
primarycolor: 43 files (16.9%) defined colors but did not name oneprimary.
Errors found
Among the 29 files with at least one error, the audit reported an invalid dimension in 22, a CSS color the linter could not read in 9, a reference to a nonexistent token in 4, and a nonnumeric font weight in 1. These error counts overlap. The linter’s dimension check expects a number followed by px, em, or rem; values such as normal for line height or bare 0 fail that check.
Run the linter on your own file
The package documentation describes the command as a way to “Validate a DESIGN.md file for structural correctness.” To reproduce the audit’s package version, run:
npx @google/[email protected] lint DESIGN.mdThe documented general command is npx @google/design.md lint DESIGN.md. The CLI accepts a file path or standard input and defaults to JSON output. It exits with code 1 when it finds errors and 0 otherwise; a zero exit code does not mean there are no warnings.
The format is alpha, and lint rules can change. Pin the version and record the date whenever you compare results. Exact rule descriptions can differ between documentation snapshots, so the findings above are specifically tied to version 0.4.0 and the October 4, 2026 audit.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Quick Recap
How to read the results
- The 78.1% prose-only figure uses all 1,162 audited files as its denominator; warning and error percentages use only the 254 token-bearing files.
- A high no-error share is not the same as a warning-free share: 88.6% had no errors, compared with 8.3% with neither errors nor warnings.
- The audit measures a registry-derived file sample, includes duplicate copies, and does not establish the quality of all DESIGN.md files or unique design systems across GitHub.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
