DESIGN.md Specification
Give coding agents a persistent design-system brief built from exact tokens and human-readable rationale.
The stated authority is narrow: commands read named files or stdin and emit reports or exports to stdout, with no background agent, credential access, or covert transmission, supporting full least-privilege and data-flow scores. Operations are explicitly invoked and output redirection is user-controlled, although there is no dedicated confirmation mechanism. npm installation and public-registry access are disclosed, but runtime external effects are not comprehensively modeled. Diffing can identify regressions, but no restoration or undo operation exists. Sensitive-data handling is not addressed. Dependency-security evidence is limited: Bun is pinned and CI runs checks, while several development dependencies use latest, Actions use movable major-version tags, and no audit or vulnerability-response process is shown. The Apache license, package scope, and Google LLC copyright headers provide attribution, but publisher identity is unverified and no individual maintainer is identified.
The format, rules, commands, output structures, and exit codes are internally consistent, while package metadata and CI support the CLI, build, and test narrative. Availability is supported by a pinned Bun version, public npm installation, tarball and Windows registry smoke procedures, and ENOVERSIONS troubleshooting; reliance on latest dependencies, external registries, and the absence of a supplied lockfile reduce assurance. Findings have defined severities and major exit codes are documented, but messages for parsing failures, malformed files, and the full range of installation or emitter failures are not comprehensively specified.
The material identifies coding agents needing persistent design-system context and covers validation, comparison, export, and prompt-context scenarios. It separates normative tokens from explanatory prose and defines types, component properties, unknown-content behavior, and command boundaries. CLI activation is explicit, with precise arguments, stdin behavior, and output-format choices. Concrete guidance covers Windows and PowerShell, Node/npm installation, the Bun development environment, Tailwind v3/v4, and DTCG, justifying strong environment-fit scores.
The README has clear information architecture spanning the format, schema, rules, API, installation, and command reference; installation and cross-platform troubleshooting are particularly thorough. Examples cover source documents, JSON findings, diffs, exports, and the programmatic API, but there is no dedicated FAQ and not every exceptional case is addressed. Naming is mostly stable and compatibility aliases are provided, although the format remains alpha and is explicitly subject to change. Windows limitations, registry failures, alpha maturity, and VRP ineligibility are disclosed. The complete Apache-2.0 license earns full credit. Versioning consists only of an alpha status with no release history or changelog. Maintenance responsibility can only be inferred from copyright headers and package scope; no named maintainer, support channel, or update commitment is supplied.
Structured JSON findings, stable paths, severity levels, summaries, regression indicators, and several export formats are directly usable by agents and CI. Combining exact tokens with design rationale, plus validation, comparison, and interoperability exports, provides clear marginal value over unstructured design notes. Adoption appears inexpensive through npx, but no performance data, resource requirements, scale limits, or quantitative comparison with alternatives is provided, so cost-benefit is not fully demonstrated.
Core claims trace to concrete schema tables, lint-rule definitions, commands, options, exit codes, and examples. Package metadata and CI independently corroborate the workspace, build, test, Node import, tarball, and npm installation paths. Corroboration remains incomplete because implementation source, the full specification, test files, and test results are not included. Normative requirements are generally separated from examples, but the assertion that an agent will produce a particular UI is an unexecuted inference, and workflow definitions are configuration evidence rather than independently observed results.
- The format and CLI remain alpha; pin an exact package version in production workflows and use diff checks before accepting schema or output changes.
- Do not treat DESIGN.md as a sensitive-information isolation mechanism; the supplied material defines no policy for secrets, customer data, retention, or redaction.
- npm installation and npx execution depend on the public registry and its supply chain; no dependency-locking policy, audit evidence, or vulnerability-response process is shown.
- The workflow and examples show intended test paths, but this static review did not execute commands or verify the published package, test outcomes, or generated-content correctness.
- Publisher identity is not verified by the FollowAgents enterprise registry, and the material provides no explicit maintainer or support and upgrade channel.
What does this agent do, and when should you use it?
DESIGN.md is a visual-identity description format for coding agents, not a standalone AI agent. Each file combines YAML front matter for colors, typography, radii, spacing, and component tokens with Markdown sections explaining the design rationale. The `@google/design.md` CLI exposes `lint`, `diff`, `export`, and `spec` commands and emits machine-actionable JSON by default. Its linter checks issues such as broken references, WCAG contrast, orphaned tokens, and section ordering, while `diff` detects token changes and finding regressions. Exporters target Tailwind v3 JSON, Tailwind v4 CSS, and the W3C DTCG format, and a TypeScript linter API is available through `@google/design.md/linter`. It suits teams that want a version-controlled design brief shared with coding workflows, provided they can absorb changes while the format remains at alpha status.
The tool reads a local DESIGN.md file or standard input, parsing its YAML token layer and ordered Markdown rationale sections. lint runs eleven rules and returns a report containing findings, summary, and the parsed designSystem; it exits with code 1 when errors exist. diff compares two DESIGN.md files, reports added, removed, and modified tokens across colors, typography, rounded, spacing, and components, and flags a regression when errors or warnings increase. export emits json-tailwind, css-tailwind, tailwind, or dtcg, while spec prints the format specification and optionally its active lint-rule table. TypeScript applications can also import lint from @google/design.md/linter and pass it a Markdown string.
- A design-system team wants exact tokens and the reasoning behind its visual decisions stored in one version-controlled artifact.
- A frontend team needs a CI check for broken token references, structural errors, and component text contrast in DESIGN.md files.
- A reviewer comparing two design-system revisions needs a structured account of token changes and any increase in lint findings.
- A Tailwind maintainer wants to generate either a v3
theme.extendJSON object or a v4@themeCSS block from one source. - A team using the W3C Design Tokens Format Module needs to export its DESIGN.md values as DTCG
tokens.json. - A TypeScript tool author wants to call
lint(markdownString)and consume a parsed design-system report programmatically.
What are this agent's strengths and limitations?
- One Markdown artifact keeps machine-readable token values beside the human rationale that explains how to apply them.
- Structured JSON output and documented exit codes make lint and regression results suitable for automated workflows.
- Eleven explicit rules cover reference resolution, WCAG AA contrast, section ordering, unused colors, and likely schema-key mistakes.
- A single source exports to Tailwind v3, Tailwind v4, and W3C DTCG formats and is also accessible through a TypeScript linter API.
- Unknown prose sections and valid custom token names are preserved or accepted, leaving room for extensions.
- The specification, token schema, and CLI are still alpha and under active development, creating migration risk for early adopters.
- Distribution depends on npm/npx; direct npx use or initial installation needs registry access, and corporate mirrors can trigger
ENOVERSIONS. - The
design.mdbinary can collide with Windows Markdown file associations, requiring users and package scripts to use thedesignmdalias. - A successful export does not fail because of lint findings in the source, so quality gating requires a separate
lintinvocation. - No native ChatGPT, Codex, Claude, or model-API integration is documented; adopters must arrange for their coding workflow to read and apply the file.
How do you install or deploy this agent?
A command-line environment capable of running npm or npx is required; the source does not specify a Node.js version or any credentials. Install with npm install @google/design.md. On Windows shells that treat @ specially, use npm install "@google/design.md". You can also run npx @google/design.md lint DESIGN.md without a prior install; this resolves the package from the public npm registry and therefore requires network access. If npm reports ENOVERSIONS, run npm config get registry; a normal internet installation should use https://registry.npmjs.org/.
How do you use this agent?
Create a DESIGN.md containing YAML front matter followed by the supported Markdown rationale sections. Run the first validation with npx @google/design.md lint DESIGN.md, or pipe input with cat DESIGN.md | npx @google/design.md lint -. Compare revisions using npx @google/design.md diff DESIGN.md DESIGN-v2.md. Export with npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json, npx @google/design.md export --format css-tailwind DESIGN.md > theme.css, or npx @google/design.md export --format dtcg DESIGN.md > tokens.json. On Windows/PowerShell, where the .md executable name may collide with Markdown file associations, use npx -p @google/design.md designmd lint DESIGN.md; package.json scripts should likewise call the designmd alias.
How does this agent compare with similar options?
Unlike a token-only interchange file, DESIGN.md places design rationale in Markdown alongside its normative token values, while still exporting to the W3C Design Tokens Format Module's DTCG JSON. It is not a replacement for Tailwind at runtime; it acts as an upstream design source that can emit Tailwind v3 theme.extend JSON or Tailwind v4 @theme CSS.
FAQ
Is this itself an AI agent that performs design work?
Does it require an API key or paid model service?
How do lint findings affect automation?
lint exits with code 1 when errors are present and 0 otherwise, so warnings alone do not produce its failure exit code. diff exits with code 1 when the later file has more errors or warnings.Can a DESIGN.md contain custom content?
Will export refuse a file that has lint findings?
lint separately when those findings must gate the workflow.