Coding agents can maintain consistent visual identity using a standard design file
Coding agents no longer pick colors or fonts arbitrarily when building screens. This file stores design values and their rationale in one place, allowing agents to maintain a consistent visual identity. It contains both machine-readable data and human-readable explanations.
A structure where data and explanation coexist
The DESIGN.md file places YAML-formatted design tokens at the top and explains design intent in Markdown below. Tokens provide precise figures, such as hexadecimal color values or font sizes, that agents must use directly. The body text, in contrast, conveys context, such as why a specific color was chosen and how it should be applied in a given atmosphere. Combining these two layers allows agents to understand a design system with intent, rather than just a list of values.
Tools for automatic validation and version comparison
The CLI tool that handles this format finds structural errors in the file and checks accessibility standards.
- Structural validation Detects token reference errors and section order violations.
- Accessibility check Verifies that the contrast ratio between text and background colors meets WCAG AA standards.
- Change tracking Compares added, removed, and modified tokens when the design system is updated.
Compatibility with existing design token formats
The token structure in DESIGN.md is designed with reference to the W3C design token format. Using the export command, you can convert these tokens into formats usable by other tools. It supports exporting to Tailwind CSS v3 JSON configuration objects, v4 CSS variable blocks, and the W3C standard DTCG format. This allows you to generate design tokens suitable for various frontend environments from a single source.
Current status as an alpha version
This format is currently in alpha, with the spec, token schema, and CLI all in active development. As the format matures, structures or rules may change, so you should check the latest spec before applying it to production environments. Additionally, this project is not covered by the Google Open Source Software Vulnerability Reward Program. It is a tool that can be used experimentally in the early stages of building agent-based development workflows.
