DesignSpecs: A DESIGN.md Dataset of Visual Design Specifications for AI Agents
- Source
- arxiv.org
- Author
- Jialiang Wei, Walid Maalej
- Date

Context
The DESIGN.md files developers now write to tell coding agents how an interface should look mostly pin down colors, type, spacing and corner rounding, and often leave components to prose, according to DesignSpecs, a dataset of 36,906 such files from 15,794 public GitHub repositories built by Jialiang Wei and Walid Maalej at the Hasso Plattner Institute. The format comes from Stitch, the AI design tool from Google, which introduced DESIGN.md in March 2026 as a way to carry design rules between design and coding tools; the paper dates the open-sourced draft specification to April 21, 2026. A file opens with a block of design , named values such as a primary color of #855300 or a body-md text style, which an can copy exactly, followed by Markdown prose explaining when and why to use them. An official command-line linter checks the files.
Finding the real ones took filtering. A search for files named DESIGN.md downloaded 613,207 of them in October 2026, but the same name is used for architecture plans by tools such as Kiro and OpenSpec. The authors kept only files with a proper token header, a design-system name, at least one token the official linter recognizes and no linter errors, which left 36,906 files. Copying is heavy: more than half of those files (53.3%) are byte-for-byte duplicates of another file in the set, leaving 17,240 distinct contents, and one file appears unchanged in 208 repositories. About a fifth sit inside folders, and the corpus is young and mostly obscure, with 91.0% of repositories created in 2026 and 77.5% without a single star.
In the distinct files, color tokens appear in 99.5% and typography in 97.9%, but component tokens, which describe things like a primary button, in only 45.3%; 47.5% have a Components section written only in prose. There are early signs of convergence. Inter is named as a typeface in 35.2% of files, and 46.5% include color-role names that also appear in Material Design 3 and the format's official examples. Of the 7,817 files that define components, 43.2% trigger the linter's contrast warning for at least one text and background pair below a 4.5:1 ratio, though the linter checks token values, not the rendered pages, so this does not show that the resulting interfaces fail.
The dataset describes what people write, not whether it works. The authors list as an open question whether a DESIGN.md file actually helps an agent build an interface that matches it, and their release is meant to make such tests possible by linking each file to the commit where it was found. Passing the filter does not certify design quality, it cannot tell a hand-written file from one exported by Stitch, and some files are templates or catalog entries, not the specification of a shipped product. GitHub's code search covers only default branches and returns incomplete results for some queries, and each repository was captured at a single commit, so the collection is a partial October 2026 snapshot without file histories.
- DESIGN.md, a format that came from Google's AI design tool Stitch and was open-sourced in April 2026, describes a project's visual identity with design tokens such as named colors and text styles plus Markdown prose.
- The authors collected 613,207 GitHub files named DESIGN.md in October 2026 and kept only those with YAML front matter, a design-system name, a recognized design token and zero linter errors, since the name also covers architecture docs.
- The DesignSpecs dataset holds 36,906 files from 15,794 public non-fork repositories, 17,240 of them unique, released as JSON Lines with file-level and deduplicated views linked to repositories, paths and commits.
- token — The chunk of text a model reads and writes in — roughly three-quarters of a word — and the unit AI usage is billed in.
- AI agent — An AI system that doesn't just answer once but works toward a goal in a loop — taking actions, reading the results, and deciding what to do next.
- agent skill — A reusable instruction file that teaches an agent how to do one job well — the procedure, the tools, and what counts as done.
articleSPECMINE: A Large-Scale Corpus of Spec-Driven Development ArtifactsShyam Agarwal, Bogdan Vasilescu
articleAgentLogs: A Dataset for Opening the Black Box of GitHub's Cloud AgentJonan Richards, Kosei Horikawa, Youmei Fan, Yutaro Kashiwa, Mairieli Wessel
articleThe EPIC Framework for Spec-Driven DevelopmentBruno Claudino, Ruizhe Xing, Yuanhao Zuo, Tyler Menezes, Anita Sarma, Kostadin Damevski, Zixuan Feng
Checking sign-in…
Loading comments…