design.md

Open source alternative to Supernova

28.4K stars
Apache-2.0
Active this week
Last commit 5 days ago

Last verified Oct 19, 2026

Connect coding agents to design-system tokens and rationale through DESIGN.md files. Apache-2.0 licensed with an npm CLI for lint, diff, and export.

Visit website GitHub28.4K

Read the full breakdownWho it is for, how it works, trade-offs and the FAQ

who it's for

Who design.md is for#

Agent-generated UI in product repos

Use DESIGN.md when coding agents regularly create pages or components and need a shared visual identity file.

Skip if:

You only use agents for backend code or one-off prototypes with no design-system expectations.

Design-system handoff

Use it to turn brand rules and component choices into a file that engineering agents can lint and apply.

Skip if:

Your team requires designers to approve every pixel directly in a visual editor before implementation.

Token regression review

Use the diff command when design tokens change and you want agents to explain what shifted.

Skip if:

Your design tokens already have mature internal validation and no agent handoff gap.

the problem

The problem it solves#

Coding agents can generate usable interfaces, but they often lose visual consistency because design context lives outside the repo or inside one-off prompts. Teams need a source file that gives agents exact token values and the reasoning behind them, so every generated component follows the same visual system.

how design.md solves it

How it solves it#

Token and rationale format

A DESIGN.md file combines YAML front matter for exact token values with markdown sections that explain the design intent behind those values.

Agent-ready linting

The @google/design.md CLI validates DESIGN.md files and returns structured JSON findings that agents can act on during implementation.

Design drift detection

The diff command compares two DESIGN.md files and reports added, removed, and modified token groups before UI regressions spread.

Export paths for implementation

The CLI can export tokens to Tailwind-oriented JSON, Tailwind v4 CSS variables, and DTCG token JSON for downstream build systems.

Portable markdown contract

Because the format is plain markdown plus YAML, teams can version it beside application code and update it through normal review flows.

strengths · trade-offs

Strengths and trade-offs#

Strengths

Clear fit for agent workflowsThe project is built specifically for coding agents, which makes it more direct than asking agents to infer design rules from screenshots or broad brand docs.
Readable by people and toolsDesigners can explain choices in prose while engineers and agents consume exact token values from the same file.
Permissive licenseApache-2.0 licensing keeps adoption straightforward for internal tools, commercial products, and agency workflows.

Trade-offs

-Specification, not a design appDESIGN.md does not replace Figma, Sketch, or a design review process. It documents implementation rules for agents after design direction exists.
-Early format discipline requiredTeams need to maintain the file as the design system changes, or agents will faithfully follow stale tokens.
-Best with tokenized systemsThe format works best when a team can express its visual identity through named colors, typography, spacing, rounding, and component tokens.

versus alternatives

design.md vs alternatives#

Compared to Figma

Figma is the better place to explore layouts visually, collaborate on mockups, and hand off designed screens. DESIGN.md is better when the design direction already exists and coding agents need a durable file they can read inside the repo. Use Figma for visual creation; use DESIGN.md to preserve design-system rules during agent-assisted implementation.

tech stack · detected from GitHub

What it's built on#

Languages: TypeScript

frequently asked

FAQ#

What is DESIGN.md?

DESIGN.md is a markdown-based specification for describing a design system to coding agents. It combines YAML tokens with prose rationale so agents know both the exact values and the design intent.

What license does DESIGN.md use?

GitHub metadata reports the DESIGN.md repository as Apache-2.0 licensed.

How do you validate a DESIGN.md file?

The official README shows the @google/design.md CLI. Run npx @google/design.md lint DESIGN.md to validate a file and return structured findings.

Does DESIGN.md replace Figma?

No. DESIGN.md is a repo-friendly contract for agents and implementation workflows, not a visual design canvas.

also worth a look

Similar open-source tools#

21st.dev

Alternative toTailwind UI

Browse and install production-ready shadcn/ui components via CLI

2,188 GitHub stars
Licence MIT

God's Eye View

Featured

Alternative toFlightradar24

Real-time global intelligence on a 3D globe

58,501 GitHub stars
Licence MIT with third-party data restrictions

inspo

Alternative toRefero

Real production sites as design reference for AI coding agents

903 GitHub stars
Licence MIT

bg0

Alternative toremove.bg

Background removal that runs in your browser, never uploads

451 GitHub stars
Licence Apache-2.0

hyperframes

Alternative toRemotion

Turn HTML and CSS into rendered MP4 videos, built for AI agents.

68,359 GitHub stars
Licence Apache-2.0

garden-skills

InWeb Development

Production-ready agent skills for Claude Code, Cursor, and Codex

13,104 GitHub stars
Licence MIT

by category

Open source tools in these categories#

Featured

rakazo

Alternative toGrok Bot

AI teammates you own: your keys, your model, your machine.

4,904 GitHub stars
Licence Apache-2.0
#AI Agents

Inbox Zero

Alternative toSuperhuman

AI email assistant that drafts replies and clears your inbox

12,712 GitHub stars
Licence AGPL-3.0
#Email

Omnara

Alternative toClaude Managed Agents

Open-source agent deployment API. Self-host or use Omnara Cloud.

2,957 GitHub stars
Licence Apache-2.0
#AI Agents

Feature your project

The projects we add and every new guide. Free, unsubscribe any time.

Find open source alternatives to paid software

Who design.md is for#