How to Use Google's Design.md with Claude Design

Google just open-sourced a file format called design.md — and it’s already pulled in thousands of stars on GitHub. For designers and developers working with AI tools, this isn’t a small update. It’s a shift in how we prompt, build, and share design systems.

The Design.md protocol gives every AI tool a standardized way to read your design system: your colors, typography, spacing, components, and tokens. That means no more guessing, no more inconsistent outputs, and no more rebuilding the same design five times because the AI forgot what your buttons look like.

In this issue, you’ll learn exactly how to use Design.md with Claude Design, where to find design inspiration, how to audit your system with Google’s CLI tool, and how to move your work into a real production pipeline. Whether you’re brand new to AI-powered design or you’ve been experimenting for months, this walkthrough will save you hours.

What is the Design.md protocol?

Design.md is a Google-backed, open-source file format that defines a design system in a way any AI can read and follow. Think of it as a universal language for design — colors, typography, spacing, components, and rounding levels all packaged into a single portable file.

Here’s why it matters: AI is non-deterministic. Run the same prompt twice and you’ll often get different results. Design.md solves that by giving the AI a fixed reference. Every prompt, every iteration, and every tool now has a standard to follow.

Key benefits of using Design.md

Consistency across prompts — your AI will respect the same design rules every time.
Portability — the file works across Claude Design, Cursor, Figma plugins, and any tool that supports it.
Sharing made simple — pass one file to a teammate or another AI and your system travels with it.
Production-ready output — designs feel cohesive instead of randomly generated.

Google also released a CLI tool alongside the protocol so you can lint, audit, and check your design system the same way developers check their code. More on that later.

Find strong design inspiration first

Before you prompt any AI, decide on a style. The quality of your final design depends on the quality of your reference. Here are five sites worth bookmarking.

Dribbble

A go-to for exploring landing page concepts. Great for casting a wide net and seeing different styles in one place.

Figma Community

Free community-made files you can open directly in Figma. Perfect if you already work in Figma and want to remix existing designs.

Framer Marketplace

This is the premium tier — polished templates with motion, animations, and micro-interactions baked in. Worth browsing if interaction design matters to your project.

Awwwards

The Awwwards Nominees page features real, vetted, award-quality websites. Every design here has earned its spot.

New Form

This is the sleeper hit. New Form is component-focused — you start with a single component, then expand into full sections and complete pages. Browse the community page, search by style, and you’ll find free, animated, production-quality pieces you can use as context for your AI.

The bonus? New Form lets you export both HTML and design.md directly. That makes it the perfect bridge between inspiration and your Design.md workflow.

Build a design using Claude Design

Once you’ve found a reference you like, the next step is bringing it into Claude Design. Here’s the full workflow.

Pick a design and remix it

In New Form, click any design you like. On the left, you’ll see the full layout. On the right, you’ll see the design system itself — typography, spacing, icons, and buttons — all structured to follow Google’s Design.md spec.

Click Remix, then prompt the AI. For this walkthrough, the prompt was a simple instruction to turn the design into a hero section. The first output won’t always be perfect — that’s where iteration comes in. After a few cycles, you’ll land on a version that feels production-ready.

Export your files

Once you’re happy, you can download either:

The HTML file — includes the full design plus structure.
The design.md file — pure design system, portable, reusable anywhere.

For this stage, the HTML works best because we want the full hero section as context. Save it, and we’re ready to move to Claude Design.

Create a Claude Design project

In Claude Design, create a new prototype and select High Fidelity. Name your project, then upload the HTML file. Use a simple prompt like:

Create a landing page with the provided HTML file.

Here’s what makes Claude Design impressive: it builds a plan before it builds the design. You’ll see steps like:

Copy the hero section into the project.
Create the design system — palette, typography, spacing rhythm.
Generate sections — hero, capabilities, showcase, pricing, CTA.
Wire scroll animations and interactions.
Verify the output — a built-in workflow step in Opus 4.6 that double-checks the work.

When the build finishes, you’ll see a full landing page that matches the original animation, glow effects, typography, and color palette — with new sections like a 2×3 capability grid, hover states, gradient backgrounds, and a pricing layout that respects your design tokens.

Use edit mode for small tweaks

Claude Design uses a lot of tokens per prompt — it’s still in beta, so usage caps are tight. The smart move is to use Edit Mode for small adjustments instead of burning a prompt on every change.

In Edit Mode, you can:

Select any element and edit text directly.
Change colors, sizes, padding, and margin live.
Adjust gap, direction, and alignment in flex containers.
Test typography tweaks without re-prompting.

Treat it like a real design app. Reserve prompts for big changes; use Edit Mode for everything else.

Use Design.md as context instead of HTML

Now let’s flip the workflow. Instead of uploading an HTML file, let’s use a design.md file as context. This is where things get interesting.

Why Design.md produces better results

When you upload HTML, the AI tries to recreate that exact component. When you upload Design.md, the AI uses the system to generate fresh designs that follow your rules. Same colors, same typography, same spacing — but new layouts.

Here’s a real comparison from the workflow:

HTML-based build: the AI kept the original hero section intact but left awkward empty space between new sections it generated.
Design.md-based build: the AI created an entirely new hero (with a cursor-following background), better-spaced sections, and a cleaner pricing layout — all while respecting the original system.

The Design.md output felt more cohesive on the first try because the AI wasn’t bound to a single component. It was free to remix within fixed rules.

How to run a Design.md workflow in Claude Design

Download a design.md file from New Form (or generate your own).
Create a new Claude Design project.
Attach the design.md file.
Prompt: Create a landing page with the provided design file.
Let Claude detect the dark mode, accent colors, glassy surfaces, and other tokens on its own.

The result will be visually similar to your reference but original — a remix, not a clone.

Audit your system with the Google Design.md CLI

Google shipped a command-line tool along with the protocol. It lets you lint and analyze your design system the same way you’d lint code.

How to install it

Copy the installation command from the Design.md GitHub repo and paste it into your terminal. Once installed, you’ll have access to a full set of commands.

Run a lint check

The lint command checks your design.md file for issues before runtime. Run it against your file, and you’ll get a report that flags things like:

Accessibility issues — for example, a button color combination that falls below the WCAG contrast ratio.
Unused tokens — colors or styles defined but never applied to a component.
System health checks — a summary of how many colors, typography scales, rounding levels, spacings, and components your system uses.

Why this matters

Accessibility warnings are critical. A button that looks great on your screen might be unreadable for someone with poor eyesight or anyone using their phone in bright sunlight. The lint tool catches these issues before they reach production.

The summary at the bottom also gives you a reality check. If your system has 30 colors and 10 typography scales, it’s bloated. If you have two of each, it’s probably underdeveloped. Use it as a health check.

Other useful commands

The CLI also supports:

Diff checks — compare versions of your design system the way you’d compare Git commits.
Exports — convert your design.md to Tailwind, design tokens, or other frameworks.
Custom commands — explore the docs to find what fits your workflow.

Move your design from Claude Design into production

Claude Design is built for design — not function. Buttons don’t work. Forms don’t submit. To make your design production-ready, you need to move it somewhere else.

Option 1 — extract Design.md from your project

There’s no native export for Design.md yet (Claude Design is still in beta), but here’s a clean workaround:

Open your Claude Design project.
Select the design file representing your full landing page.
Click Download Project.
Open the downloaded file in any code editor.
Copy the full code.
Paste it into New Form’s Code Mode.
New Form will analyze the design and generate a complete design.md for you.
Download it.

You now have a portable design.md based on the full landing page Claude generated.

Option 2 — hand off to Claude Code

This is the production-ready route. When you hit your Claude Design usage limits, click Hand Off to Claude Code. Claude Design will generate a command you can paste into:

Claude Code in the terminal.
The Claude Desktop app.
Claude Code Web (still finicky — desktop is more reliable right now).

You can also add optional instructions like implement the hero section only or make the pricing page functional.

Once the command runs, Claude Code fetches your design from the server and starts iterating — this time with a live preview, working components, and component-level selection for context-aware prompting. You’ll burn through your Claude Code usage instead of Claude Design’s tight beta limits, which is a much better trade.

Common mistakes to avoid

A few things to watch out for as you start working with Design.md and Claude Design:

Don’t prompt for small changes. Use Edit Mode. Every prompt eats your beta usage.
Don’t expect functionality in Claude Design. It’s a design tool. Treat it that way.
Don’t skip the lint check. Accessibility issues compound fast if you build a system without auditing it.
Don’t confuse HTML and Design.md inputs. HTML recreates a specific component. Design.md generates new designs that follow your rules.
Don’t rely on Claude Code Web yet. Desktop is more stable while the platform matures.

Wrapping up

The Design.md protocol is more than a file format — it’s a shared language between designers, developers, and AI. Used alongside Claude Design and Google’s CLI tool, it lets you go from inspiration to production-ready landing page faster than ever, with way more consistency than prompting alone could deliver.

Pick one design from New Form this week, export its design.md, and run it through Claude Design. You’ll feel the difference within your first build — and the workflow you build around it is the kind of leverage that compounds every project after.