Identity Forge

How to generate a DESIGN.md (and what it is)

A DESIGN.md tells a coding agent how your product should look and why. Generate one from a real kit and the written rules stay tied to the exact tokens in your code.

Updated July 13, 2026

What a DESIGN.md is

A DESIGN.md sits beside the code and describes the intended design in terms an agent can act on. Coding agents implement UI well, but without art direction they tend to fall back to a neutral house style. Google Labs now publishes an alpha DESIGN.md specification and validator. The format is active and useful, though the specification still warns that it may change.

A DESIGN.md needs more than a color list. Agents also need direction on layout, spacing, component treatment, and the details that distinguish one design from another. A useful brief spends most of its words on those decisions.

What belongs in a DESIGN.md

A complete brief covers the whole system, not just tokens. The DESIGN.md that Identity Forge generates is organized into these sections:

  • Overview: what the design is, who it's for, and the intended feeling in a sentence or two.
  • Colors: the semantic tokens as CSS variables ready to paste into globals.css, in light and dark. Semantic color tokens explained.
  • Typography: the type pairing, scale, tracking and weights, plus a ready Next.js font setup.
  • Layout: spacing base, container width, and composition rules.
  • Elevation & Depth: the shadow system (or a deliberate lack of one).
  • Shapes: corner radii per element (buttons, cards, inputs, badges) and border treatment.
  • Components: how core components should be treated, with a sample.
  • Page Structure & Layout: how to compose whole pages; this is where generic AI output is prevented.
  • Personality & References: the voice and touchstones behind the design.
  • Distinctive Motifs: the signature devices to reproduce; "they define the design as much as the tokens do."
  • Do's & Don'ts: the rules that keep generated UI inside the design's world.
  • Agent Rules: explicit instructions for the coding agent itself.

The motifs and don'ts are the point

Anyone can list five hex codes. What separates a real design system from a recolored template is the written intent: the motifs to reproduce and the mistakes to avoid. Those sections are why a DESIGN.md changes an agent's output where a palette doesn't.

See it backed by a real system

A DESIGN.md is only as good as the system behind it. Below is the free ambient-sage kit: the tokens, fonts, and treatments its DESIGN.md describes, rendered live:

Ambient Sage

After Work Chill

Double tap on a widget to edit settings

Save SettingsLearn more

Plus Jakarta Sans · 28 semantic tokens · light + dark

Ambient Sage. Its DESIGN.md turns exactly this system into instructions your agent follows.

Generate one (three ways)

  1. 1

    CLI: write DESIGN.md + tokens into your repo

    The fastest path. Pick a kit slug from the gallery and apply it; you get a committed DESIGN.md plus a matching tokens file.

    identityforge apply ambient-sage
  2. 2

    MCP: let the agent fetch it

    With the MCP server installed, the agent calls get_design_md(slug) to read the full brief and apply_theme to write it. Install for your tool:

    npx --yes --package=https://identityforge.io/downloads/identityforge-0.3.0.tgz identityforge install --client claude-code
  3. 3

    shadcn: install the tokens the DESIGN.md references

    If you only want the values, the registry item installs the kit's CSS variables directly.

    npx shadcn add https://identityforge.io/r/ambient-sage.json

Identity Forge generates the DESIGN.md and tokens from the same kit, so the prose describes the values in the stylesheet. For how this differs from adapting a DESIGN.md catalog entry by hand, see Identity Forge vs getdesign.md.

FAQ

What is a DESIGN.md?

A DESIGN.md is a Markdown file in your repo that tells an AI coding agent how the product should look: its intent, color and type systems, layout and spacing rules, component treatments, distinctive motifs, and do's & don'ts. The agent reads it before building UI so its output stays on-brand and consistent.

How do I generate a DESIGN.md?

Apply an Identity Forge kit: `identityforge apply <slug>` writes a complete DESIGN.md plus the matching tokens into your project. With the MCP server installed, the agent can also fetch it itself via the get_design_md tool.

Is a DESIGN.md just a list of colors?

No. Colors are the easy part. A useful DESIGN.md spends most of its words on layout, spacing, component treatment, distinctive motifs, and do's & don'ts: the places where AI-built UI actually goes generic.

Is there an official DESIGN.md spec?

Google Labs publishes an alpha DESIGN.md specification and validator. Identity Forge generates its brief and tokens from the same design kit, which keeps the written rules tied to the exported values.

All guides