design.md

Open source alternative to Supernova

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

Last verified Nov 9, 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.8K

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,286 GitHub stars
Licence MIT

God's Eye View

Featured

Alternative toFlightradar24

Real-time global intelligence on a 3D globe

64,214 GitHub stars
Licence MIT with third-party data restrictions

Hallmark

InDesign & Creative

Design skill for coding agents with 48 themes, real photos and lint.

51,128 GitHub stars
Licence MIT

inspo

Alternative toRefero

Real production sites as design reference for AI coding agents

990 GitHub stars
Licence MIT

bg0

Alternative toremove.bg

Background removal that runs in your browser, never uploads

493 GitHub stars
Licence Apache-2.0

hyperframes

Alternative toRemotion

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

82,479 GitHub stars
Licence Apache-2.0

by category

Open source tools in these categories#

125

Inbox Zero

Alternative toSuperhuman

AI email assistant that drafts replies and clears your inbox

12,987 GitHub stars
Licence AGPL-3.0
#Email

rakazo

Alternative toGrok Bot

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

7,869 GitHub stars
Licence Apache-2.0
#AI Agents

SnitchFeed

Live monitoring on LinkedIn, X, Reddit & more. Agentic social listening for startups.

Marketing & Growth

Advertise your product

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

Find open source alternatives to paid software

Who design.md is for#