NO. 003  ·  FORM 003-A
SUNDAY · 10 MAY 2026 · field report on agentic web design
≈ 8 MIN READ

The brand book is a
Markdown file now.

Google open-sourced DESIGN.md, Anthropic shipped a design app that auto-extracts your system from a repo, and Figma's MCP server learned to write back to the canvas. Three releases this fortnight, one direction of travel: an agent's source of truth for visual work is becoming a plaintext file that lives next to the code.

§01

Tooling

— what shipped, what shifted

Claude Design reads your repo first

Anthropic's Claude Design, launched into research preview on April 17 and powered by Claude Opus 4.7, opens with an onboarding step nobody else has shipped at this fidelity: it reads your codebase and existing design files, infers the colors, typography, spacing, and component vocabulary in use, and writes a project-wide design system you can reuse on every subsequent prompt. Generation comes second; extraction comes first.

The other half of the loop is the handoff bundle: when a draft is ready to ship, the app packages the project files, the chat history, and a generated README into a structured archive, then hands you a one-line prompt you paste into Claude Code (or any coding agent) to build the production version. The contrast with classic Figma handoff is that the bundle isn't pixels with annotations — it's a folder the agent is meant to read.

Design implication "Design system" used to mean a Figma library humans referenced. It increasingly means a folder of files an agent reads on every turn — and the pixels are a downstream render of it.

Figma's MCP server learned to write back

Figma's beta MCP server matured in two stages this spring. First came reading: any MCP-aware agent (Claude Code, Codex, Cursor, Windsurf, VS Code Copilot) could pull components, variables, layout data, and FigJam content into context for design-informed code generation. Then in March came writing: the use_figma tool — exposed via the figma-use skill — lets an agent create, edit, and delete real Figma objects using your existing components, variables, and styles, instead of generating an isolated mock that has to be redrawn by hand.

May added the FigJam side: figma-use-figjam for direct board read/write, plus a generate-project-plan skill that turns a docs folder, a codebase, or a chat transcript into a real visual board agents and humans can edit together. The summary view of an existing board comes from get_figjam. Treat it as the brainstorming surface that finally has a write API.

shadcn registry as a single payload

Less heralded but as load-bearing: shadcn CLI v4.7 added files[].target aliases and package import resolution, building on March's CLI v4 release that introduced registry:base — the ability to distribute "an entire design system as a single payload" (components, dependencies, CSS variables, design tokens, fonts, and config) in one install. Combined with the registry's MCP command exposing the full registry.json to Cursor and Windsurf, the practical effect is that "set up the design system" is now a single CLI call an agent can issue without supervision.

§02

Technique

— DESIGN.md as a real spec

The format that's quietly winning

Google introduced DESIGN.md in March as part of the Stitch update — infinite canvas, project memory, voice — and open-sourced the format in April. The structure is the boring part that makes it work: a YAML front-matter block with machine-readable design tokens (color palettes, type scale, spacing units, semantic roles) and a Markdown body with the human-readable rationale (component conventions, voice notes, what-not-to-do clauses).

The reason it spreads: any agent that already reads project files can use it. Cross-tool support already covers Claude Code, Cursor, Kiro, Windsurf, and Stitch itself, and the specification is small enough to hand-edit. There's no plugin, no SDK, no service — the file is the integration surface.

Tokens are easy. Prose is the moat.

Tokens are the easy half. Anyone can dump --color-primary: #0066CC into a YAML block. The harder, more valuable half is the prose body: when to use the primary color, what a "warning" tone communicates in your voice, which components are reserved for purchase flows, what the brand's stance on motion is. These are the constraints an agent cannot infer from a token list, and they're where a real DESIGN.md earns its keep — written like a brand spine, not a config dump.

Practical move In your DESIGN.md, write at least one "Avoid" sentence per major component and at least one "When" sentence per accent color. Token plus prose plus prohibition is the unit of useful design instruction.

Reference it from AGENTS.md

The discovery pattern is also boring, also load-bearing: in your AGENTS.md, add a "UI & Design System" section with a single line: See ./DESIGN.md for visual constraints, tokens, and component conventions. Most agents already read AGENTS.md automatically — Claude Code, Cursor, Copilot, and the rest — so a one-line reference is enough to wire the design spec into every session. Next.js 16.2's create-next-app ships an AGENTS.md by default; pasting the line is a 10-second commit.

§03

Workflow

— a studio practice worth stealing

Three Markdown files, one agent stack

The pattern emerging across studios this month is a clean three-file split at the root of every project: AGENTS.md for how the codebase is built, DESIGN.md for how the brand is seen, and a skills/ folder of SKILL.md files for specific tasks the agent can be invoked to do. Each is a Markdown file. Each is checked into Git. Each is regeneratable — but the value is in the prose, not the regeneration. One framing of this split calls them the three layers of agent instruction: how to build, how to see, how to act.

The brand book used to live in a PDF. Then it lived in Figma. Now it lives in plaintext, beside the code, and designers are committing.

Bundles, not pixels, are the handoff

The studio practice worth stealing is the one Anthropic accidentally codified: stop thinking of design handoff as "a Figma file plus a Loom." Think of it as a folder. The folder contains the DESIGN.md, the page-level prompts, the components the agent should reach for, and a brief README that tells the next agent what to do with the rest. Claude Design's handoff bundle is one shape of this; Figma's write-to-canvas flow is another. The shared move is: the artifact you hand off is the artifact the agent reads, not a translation of it.

Per-surface DESIGN.md

One nuance worth lifting from teams who've been doing this for a few weeks: a single DESIGN.md per repo is too coarse if the project has more than one visual surface. Marketing pages, the in-product dashboard, and the mobile shell often want different type scales, spacing, and component vocabularies. Maintain a root DESIGN.md for shared tokens (brand color, voice, accessibility floor) and a per-surface app/marketing/DESIGN.md, app/dashboard/DESIGN.md, etc., for the specifics. Agents resolve the closest one to the file they're editing — same way tsconfig.json resolves.

Mental model Design tokens are like type definitions: you want them in one place at the top, with overrides scoped close to the files that use them. Two DESIGN.mds beat one over-stuffed one.
§04

Prompt Lab

— a concrete prompt with commentary

"Reverse-extract a DESIGN.md from a live site"

You are writing a DESIGN.md file that will be checked into a project's repository. An AI coding agent will read this file on every session and use it as the source of truth for visual decisions. Source material: the live site at [URL] and the brand prose at [/about-page or brand-doc URL]. Output a single DESIGN.md with two parts: 1. YAML front matter — machine-readable tokens. Required keys: colors: semantic groups (brand, neutral, semantic). Hex values. type: family stack, weights used, size scale, line-heights. spacing: base unit + scale. radii: scale in px. motion: durations + easings. Pull the actual values from the rendered CSS; do not invent. 2. Markdown body — human-readable rationale. Required headings: ## Voice — 2–4 sentences on tone and posture. ## Components — for each named component, one line of "use when" and one line of "avoid when." ## Color use — for each accent color, a one-line "when" rule and a one-line "avoid" rule. ## Type hierarchy — display / body / italic / mono roles, and which role each is permitted to do. ## Anti-patterns — the single most common slop move for this brand, written as a "do not" with a one-line why. Constraints: - Token names follow the W3C Design Tokens spec (kebab-case, namespaced). - Every "use when" is paired with an "avoid when." No orphan rules. - No marketing copy. Write like a checked-in spec, not a brand deck. - Keep the file under 250 lines. Brevity is the integration surface. Output: only the file contents, starting with the YAML --- fence.

Why each constraint earns its line

The two-part structure lets the YAML serve agents that just want tokens, while the Markdown body holds the rules an agent can't infer (voice, prohibitions, component intent). Pairing every "use when" with an "avoid when" forces the prompt to produce the negative space that distinguishes a real spec from a wish list. The 250-line ceiling is the most underrated rule: a DESIGN.md the agent re-reads on every session has to fit in its working context, and brevity raises the odds it survives the next refactor without rotting.

§05

Field Note

— short editorial synthesis

The brand book used to be a PDF passed around at offsites. Then it became a Figma file linked from the README. This month it's becoming a plaintext file at the root of the repo, version-controlled, diffed in pull requests, and read on every agent turn. The vehicle is humbler but the surface area is larger: when the spec lives next to the code, every commit is a potential visual decision, and every visual decision is a potential commit. Designers without git accounts are about to acquire them.

§06

Sources

— full link list
No. 003 · 10 May 2026 Type set in Anton & Newsreader, with IBM Plex Mono for spec captions. Palette: Spec Sheet — cream paper, ink, sepia, single vermilion flag.

A field experiment from the team behind Beaver Builder.