UX Collective | Medium
Follow
Design.md: the one standard file carries your visual identity, for humans and agents
A new standard called DESIGN.md is emerging for defining brand design in a machine-readable and human-understandable plain-text file. This file acts as a contract for coding agents, ensuring they build interfaces that align with specific brand identities. Without such a file, agents default to generic components because visual identity is often fragmented across design tools and human knowledge. DESIGN.md solves this by combining machine-readable design tokens like colors and spacing with human-readable prose explaining their meaning and intent. This dual approach allows both people and AI to interpret the design consistently. The format is structured with specific sections such as Overview, Colors, Typography, and Components, presenting typed values above and prose below. Naming tokens and components by their role rather than their appearance is crucial for long-term maintainability and agent comprehension. Storing DESIGN.md at the repository root alongside README.md allows it to be version-controlled and reviewed like any other code. The format also supports tooling for linting, diffing, and exporting tokens into various formats, integrating design into the build process. Although the standard is still developing, writing brand DNA into a legible file is essential for the agent era. Teams can begin by selecting a known brand and drafting a DESIGN.md file, starting with tokens and then adding explanatory prose.