{"slug": "google-s-design-md-a-spec-to-stop-agents-writing-ugly-ui", "title": "Google's design.md: A Spec to Stop Agents Writing Ugly UI", "summary": "Google Labs released design.md, an open-source format specification that combines YAML front matter with Markdown prose to give AI coding agents a structured, lintable blueprint for a project's visual identity. The spec aims to prevent agents from generating visually poor user interfaces by providing machine-readable design tokens and human-readable design rationale, and includes a CLI tool for linting and validation.", "body_md": "[AI](https://www.devclubhouse.com/c/ai)Article\n\n# Google's design.md: A Spec to Stop Agents Writing Ugly UI\n\nThe new markdown-plus-YAML specification gives AI coding agents a structured, lintable blueprint for your project's visual identity.\n\n[Rachel Goldstein](https://www.devclubhouse.com/u/rachel_goldstein)\n\nCoding agents are remarkably good at writing functional React components, setting up Express routes, and refactoring legacy Python. But when it comes to frontend aesthetics, they are visually illiterate. Left to their own devices, LLMs will happily generate a button with neon green text on a bright blue background, or hallucinate a dozen random Tailwind spacing classes that completely break your layout.\n\nTo solve this, Google Labs has introduced [design.md](https://github.com/google-labs-code/design.md), an open-source format specification designed to give AI coding agents a persistent, structured understanding of a project's design system. By combining machine-readable design tokens with human-readable design rationale, the spec aims to act as a guardrail for AI-generated user interfaces.\n\n## The Hybrid Spec: Tokens Meet Prose\n\nMost design systems are split. Developers use JSON or YAML files (like Style Dictionary) to feed design tokens into their build pipelines, while designers maintain documentation in Figma or a wiki. Coding agents struggle with this split. If you only give them raw JSON tokens, they lack the context of when and why to use them. If you give them a massive PDF of brand guidelines, they fail to parse the exact hex codes and spacing values reliably.\n\n`design.md`\n\nbridges this gap by using a single file structured with YAML front matter for machine-readable tokens and Markdown for semantic prose.\n\n```\n---\nname: Heritage\ncolors:\n  primary: \"#1A1C1E\"\n  secondary: \"#6C7278\"\n  tertiary: \"#B8422E\"\n  neutral: \"#F7F5F2\"\ntypography:\n  h1:\n    fontFamily: Public Sans\n    fontSize: 3rem\n  body-md:\n    fontFamily: Public Sans\n    fontSize: 1rem\nrounded:\n  sm: 4px\n  md: 8px\nspacing:\n  sm: 8px\n  md: 16px\n---\n\n## Overview\nArchitectural Minimalism meets Journalistic Gravitas. The UI evokes a premium matte finish.\n\n## Colors\nThe palette is rooted in high-contrast neutrals and a single accent color.\n- **Primary (#1A1C1E):** Deep ink for headlines and core text.\n- **Secondary (#6C7278):** Sophisticated slate for borders and metadata.\n- **Tertiary (#B8422E):** \"Boston Clay\" — the sole driver for interaction.\n```\n\nThe YAML front matter defines the strict values (colors, typography, rounded corners, spacing, and component-specific tokens). The Markdown body below it provides the contextual rules. When an LLM reads this file, it gets the exact hex code for the tertiary color (`#B8422E`\n\n) and the explicit instruction that this color is \"the sole driver for interaction,\" meaning it should only be applied to interactive elements like primary buttons or active states.\n\nTo keep things predictable for parser engines, the specification enforces a strict ordering for Markdown sections. If present, headings must appear in this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts.\n\n## Linting and Diffing the Visual Pipeline\n\nStatic configuration files are only useful if they can be validated. Google Labs has released a CLI tool on [npm](https://www.npmjs.com) under the `@google/design.md`\n\npackage to lint and diff these files.\n\nRunning the linter parses the file, checks for broken token references, validates the token schema, and performs WCAG contrast ratio checks on your defined components.\n\n```\nnpx @google/design.md lint DESIGN.md\n```\n\nThe linter outputs structured JSON, making it easy to integrate into CI/CD pipelines or pre-commit hooks:\n\n```\n{\n  \"findings\": [\n    {\n      \"severity\": \"warning\",\n      \"path\": \"components.button-primary\",\n      \"message\": \"textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA.\"\n    }\n  ],\n  \"summary\": {\n    \"errors\": 0,\n    \"warnings\": 1,\n    \"info\": 1\n  }\n}\n```\n\nThere is also a `diff`\n\ncommand designed to compare two versions of a design system. This is particularly useful when you update your brand guidelines and need to verify if the changes will break existing token references or introduce prose regressions that might confuse an agent.\n\n```\nnpx @google/design.md diff DESIGN.md DESIGN-v2.md\n```\n\n## The Developer Angle: Integration and Trade-offs\n\nFor a working developer, adopting `design.md`\n\nis not about replacing your existing design system tooling. It is about creating a translation layer for your AI tools.\n\nIf you are already using Tailwind, Style Dictionary, or Figma Variables, you do not want to manually maintain a duplicate YAML file. The most practical path to adoption is writing a script that exports your existing design tokens into the YAML front matter of a `DESIGN.md`\n\nfile, and then appending your high-level design guidelines as the Markdown body.\n\nOnce the file lives in the root of your repository, you can feed it to your coding agents in a few ways:\n\n**System Prompts:** If you are building custom agentic workflows using LangChain or LlamaIndex, you can programmatically read`DESIGN.md`\n\nand inject it into the system prompt whenever the agent is tasked with modifying or creating UI components.**IDE Context:** For tools like Cursor or Copilot Workspace, you can reference the file in your`.cursorrules`\n\nor system instructions, ensuring the agent always references the local`DESIGN.md`\n\nbefore writing CSS, Tailwind, or styled-components.**CI/CD Guardrails:** You can run the`@google/design.md`\n\nlinter in a GitHub Action to block PRs if an automated agent (or a human developer) introduces a token change that violates contrast accessibility standards.\n\nHowever, the specification is currently in \"alpha\" and has some notable limitations. The component token schema is relatively basic, supporting only a handful of properties like `backgroundColor`\n\n, `textColor`\n\n, `typography`\n\n, `rounded`\n\n, `padding`\n\n, `size`\n\n, `height`\n\n, and `width`\n\n. Complex component states (like hover, active, or disabled) must be expressed as separate component entries (e.g., `button-primary-hover`\n\n) rather than nested objects, which can make the YAML front matter verbose and repetitive.\n\n## The Verdict\n\n`design.md`\n\nis a highly pragmatic solution to a very modern problem. It acknowledges that coding agents do not just need raw variables; they need the semantic guardrails that human designers write in documentation.\n\nWhile the specification is still early, the concept is solid. If agent frameworks and IDEs begin auto-detecting `DESIGN.md`\n\nin the same way they look for `.gitignore`\n\nor `package.json`\n\n, it could easily become the standard way we keep AI-generated code on-brand and accessible.\n\n## Sources & further reading\n\n-\n[google-labs-code/design.md](https://github.com/google-labs-code/design.md)— github.com\n\n[Rachel Goldstein](https://www.devclubhouse.com/u/rachel_goldstein)· Dev Tools Editor\n\nRachel has been embedded in the developer tooling ecosystem for nearly eight years, covering everything from IDE wars and package-manager drama to the quiet rise of AI-assisted coding. She has a soft spot for open-source maintainers and an unhealthy number of terminal emulators installed on a single laptop.\n\n## Discussion 0\n\nNo comments yet\n\nBe the first to weigh in.", "url": "https://wpnews.pro/news/google-s-design-md-a-spec-to-stop-agents-writing-ugly-ui", "canonical_source": "https://www.devclubhouse.com/a/googles-designmd-a-spec-to-stop-agents-writing-ugly-ui", "published_at": "2026-06-29 16:06:47+00:00", "updated_at": "2026-06-29 16:26:23.993123+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "generative-ai"], "entities": ["Google Labs", "design.md", "Style Dictionary", "Figma", "npm", "WCAG"], "alternates": {"html": "https://wpnews.pro/news/google-s-design-md-a-spec-to-stop-agents-writing-ugly-ui", "markdown": "https://wpnews.pro/news/google-s-design-md-a-spec-to-stop-agents-writing-ugly-ui.md", "text": "https://wpnews.pro/news/google-s-design-md-a-spec-to-stop-agents-writing-ugly-ui.txt", "jsonld": "https://wpnews.pro/news/google-s-design-md-a-spec-to-stop-agents-writing-ugly-ui.jsonld"}}