Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
In a Markdown Registry sample of 1,162 public-repository DESIGN.md files, 78.1% had no YAML design tokens. Among the 254 files that did contain tokens, 88.6% had no errors, but just 8.3% had neither errors nor warnings when checked with @google/design.md 0.4.0 on October 4, 2026. Those figures describe files found by the registry—not all DESIGN.md files on GitHub.
What the audit checked—and what its percentages mean
The Markdown Registry stores versions of agent Markdown files discovered in public GitHub repositories. The audit selected the latest stored version of each file named DESIGN.md, checked its contents against its SHA-256, and ran @google/design.md version 0.4.0 on October 4, 2026. It counted 1,162 files. The registry crawl does not cover every GitHub repository, so the results describe this registry sample rather than the full population of GitHub files. Markdown Registry audit methodology
The sample contained 715 distinct file contents: 447 of the 1,162 files were byte-for-byte copies of another file in the corpus. The unit counted is a file, not a unique design system. Each file was counted once per rule, even if the linter reported multiple findings under that rule.
Most files had prose guidance, not YAML tokens
Google’s alpha DESIGN.md format combines optional YAML front matter for structured design values—such as colors, typography, corner radii, spacing, and components—with a Markdown body that explains how to apply them and provides context. In the audit, 908 of 1,162 files (78.1%) had no YAML content, including fenced YAML that the linter could read. These files are not thereby invalid; they simply do not provide those values as machine-readable tokens for this linter and its export command.
Prose can still communicate useful design information to an agent. Of the 908 files without YAML, 747 (82.3%) named at least three distinct three- or six-digit hex colors in prose. But the linter cannot check prose colors, and the export command cannot carry those prose values into CSS or Tailwind settings. Markdown Registry analysis of prose-only files
How token-bearing files performed
The remaining 254 files contained tokens. Their results show why “no errors” is not the same as a clean lint: warnings were common even among files without errors.
| Result or finding | Files | Share of 254 token-bearing files |
|---|---|---|
| No errors | 225 | 88.6% |
| Neither errors nor warnings | 21 | 8.3% |
| At least one error | 29 | 11.4% |
| Color not referenced by a component | 103 | 40.6% |
| Typography token expressed as one string rather than an object | 81 | 31.9% |
| Component text/background pair below the article’s stated 4.5:1 contrast threshold | 66 | 26.0% |
| Component sub-token not defined by the format | 47 | 18.5% |
Colors defined but no color named primary |
43 | 16.9% |
Finding rows overlap: one file can trigger multiple rules, so these counts and percentages must not be summed as if they were mutually exclusive. The audit’s orphan-color rule applies only when a file defines components, and it skips standard color families such as primary and surface. The 4.5:1 contrast figure is the threshold reported in the audit as WCAG AA; these results are not an independent verification of that standard.
Free tools Windows power users keep installed
One-click scans. No signup required.
The typography result also needs context: version 0.4.0 can emit one warning per character for a string-form typography token. The audit nevertheless counts a file once for that rule, not once per warning. Markdown Registry findings for token-bearing files
Rank #3
Which errors the linter reported
Of the 254 token-bearing files, 29 (11.4%) had at least one error. The reported error categories were:
- Invalid dimension: 22 files.
- CSS color the linter could not read: 9 files.
- Reference to a nonexistent token: 4 files.
- Nonnumeric font weight: 1 file.
These categories can overlap. For the dimension check, a value must be a number followed by px, em, or rem; values such as normal for line height or a bare 0 fail that check in the audited version.
How to lint a DESIGN.md file yourself
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/design.md@0.4.0 lint DESIGN.mdThe documented command is npx @google/design.md lint DESIGN.md; adding @0.4.0 pins the version rather than relying on whichever version is currently selected by the package runner. The CLI accepts a file path or standard input and defaults to JSON output. It exits with code 1 when it finds errors and code 0 otherwise; a zero exit code does not mean there were no warnings. @google/design.md package documentation
Best Value
- Save the design guide as
DESIGN.md, or substitute your actual file path in the command. - Run
npx @google/design.md@0.4.0 lint DESIGN.mdto check it with the audited version. - Read the JSON output for both errors and warnings. A successful exit (code 0) indicates no errors, not necessarily a warning-free file.
- When comparing results, record the package version and audit date. The format is alpha and its rules can change; the official repository describes DESIGN.md as providing coding agents with persistent, structured understanding of a design system. Official DESIGN.md repository
Version matters for rule-by-rule comparisons: the npm documentation and repository snippets describe different rule sets. The audit’s specific findings therefore apply to version 0.4.0 as run on October 4, 2026, not automatically to later releases.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What to take from the results
The largest divide in this sample is between prose-only guidance and structured tokens: most files offered no YAML for the linter to inspect or export. Among files that did include tokens, errors were less common than warnings, and fully warning-free files were a small minority. Treat those results as a picture of the registry’s sampled files under one pinned linter version—not a score for every DESIGN.md on GitHub or for the quality of each design system.
Quick Recap
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.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
