DESIGN.md in BoB

DESIGN.md in BoB — Evaluation & Provisioning Fit

Understand why. How Google Labs’ DESIGN.md format fits into BoB project provisioning: where the file lives, how a project opts in, and how it relates to the existing design-skill family. This is the foundation decision record for the design-system-context capability (#899); the tooling requirements (#902 injection, #903 lint gate, #904 diff/export) build on the decisions recorded here. (Back to explanation index.)

What DESIGN.md is

DESIGN.md is a format specification from Google Labs for describing a visual identity to coding agents. One file combines machine-readable design tokens (YAML front matter: colors, typography, rounded, spacing, components) with human-readable design rationale (markdown prose below the front matter). Tokens give agents exact values; prose tells them why those values exist and how to apply them.

The companion CLI is @google/design.md — “agent-first”: every command emits structured JSON an agent can act on directly.

CLI evaluation (v0.3.0, evaluated 2026-07-02)

Pinned version: @google/design.md@0.3.0 (alpha; published versions to date: 0.1.0, 0.1.1, 0.2.0, 0.3.0). All four commands were exercised hands-on against a sample file.

Command	Surface	Verified behavior
lint <FILE>	--format json|text; - for stdin	Validates structure; findings carry severity (error/warning/info), path, message, plus a summary count object. Rules include broken/circular refs, WCAG AA contrast (4.5:1) on component color pairs, orphaned tokens, missing primary/typography, section order, unknown-key typo detection.
diff <BEFORE> <AFTER>	--format json|text	Token-level change report — added/removed/modified arrays per section (colors, typography, rounded, spacing, components) plus prose-change detection.
export <FILE> --format <fmt>	css-tailwind, json-tailwind, tailwind (alias), dtcg	css-tailwind emits Tailwind v4 CSS @theme custom properties; json-tailwind emits Tailwind v3 theme.extend JSON; dtcg emits W3C Design Tokens (2025.10 schema).
spec	--rules, --rulesOnly, --format markdown|json	Broken in 0.3.0 as packaged: the base spec command fails (the spec.md source file is missing from the package’s dist directory). --rulesOnly works and prints the active lint-rule table. Alpha-quality signal — see churn risk.

Decision: where DESIGN.md lives

Project root, committed — <project>/DESIGN.md, exactly analogous to dev.json. Rationale:

• It is the upstream tool’s own convention (the CLI and ecosystem assume the root path), so BoB adds no translation layer.
• Like dev.json, it is a per-project declarative manifest: owned by the project repo, version-controlled, and the single source of truth for its domain (visual identity). This satisfies the Prime Directive with no new machinery.
• Opt-in is presence: a project opts in by committing a DESIGN.md at the root. No registry flag, no provisioning-manifest key. Tooling (lint hooks, prompt injection, PR diff checks) keys off file existence, mirroring how warp-drive keys off dev.json existence.

Decision: how it’s provisioned

A registry skill scoped to web apps — never auto-loaded globally.

• The DESIGN.md tooling surface ships as a registry skill with orchestrator metadata applies_to.project_types: [web-app] (and web stacks), category: design — the same scoping as the existing design-systems skill. CLI/library repos (including BoB itself) never see it. Realized by design-md-context (#902); usage: Inject DESIGN.md Context.
• The skill wraps the pinned CLI (npx @google/design.md@0.3.0 …) so no project needs a direct dependency; the pin lives in one place.
• Projects that opt in get the skill via their provision manifest (provisions/<project>.json) — recommendable by the orchestrator when it detects a web-app project type with a design capability.

Relationship to the existing design-skill family

DESIGN.md is the machine-readable token layer the design skills reference, not a competing surface. The four existing skills divide up the how of design work; DESIGN.md records the what — the project’s actual identity — in a form both agents and tooling can parse:

Skill	Role	Relationship to DESIGN.md
frontend-design	Knowledge-only creative direction — distinctive, non-generic UI during code generation	Reads DESIGN.md (when present) as the project’s committed identity; its creative choices must land inside those tokens rather than inventing a palette per session.
visual-design	Design fundamentals — color theory, type scales, spacing systems	The theory used to author good token values; DESIGN.md is where the chosen values persist.
design-systems	Component libraries, Tailwind themes, shadcn/Radix integration	Consumes exported tokens (design.md export) when wiring themes; owns the component-architecture layer above tokens.
brand-guidelines	A concrete brand (Anthropic look-and-feel)	What a DESIGN.md front matter instantiates for one org — a committed DESIGN.md is effectively a per-project brand-guidelines file.

Reconciling the two token→Tailwind paths

registry/skills/design-systems/scripts/scaffold-tokens.sh already converts a JSON token definition into CSS custom properties (tokens.css, :root + optional .dark) and a Tailwind theme-extension JS module (tailwind.tokens.js). design.md export covers overlapping ground (css-tailwind → Tailwind v4 @theme CSS; json-tailwind → Tailwind v3 theme.extend JSON; dtcg → W3C Design Tokens). To keep the two paths from silently overlapping (this feeds #904’s export docs):

• Project has a committed DESIGN.md → use design.md export, always. The DESIGN.md is the single source of truth for tokens; exporting from it keeps CSS/Tailwind output derived from the owned artifact. Running scaffold-tokens.sh from a separate tokens.json on such a project would create a second token owner — a Prime Directive violation.
• No DESIGN.md (ad-hoc or legacy token JSON) → scaffold-tokens.sh remains the tool. It also still covers what design.md export cannot yet do: dark-mode variants (--dark) and file-writing conventions (--output, dry-run).
• Migration path: a project using scaffold-tokens.sh that adopts DESIGN.md moves its tokens.json values into the front matter once, then switches to design.md export; scaffold-tokens.sh is not run again on that project.

Alpha churn risk

The format and CLI are explicitly alpha, and the risk is not hypothetical: in the published 0.3.0 package the spec command is broken outright (the spec.md source file is missing from the package’s dist directory). Stance:

• Pin exactly. All BoB tooling invokes npx @google/design.md@0.3.0 — never a floating tag. The pin lives in the wrapping registry skill only, so an upgrade is a one-line, one-owner change.
• Upgrade deliberately, not on cadence. Alpha releases are irregular (0.1.0 → 0.3.0 in the current run); a calendar cadence would churn for no benefit. Instead, re-evaluate when a release note lands that affects a surface BoB consumes (lint JSON shape, diff shape, export formats), rerun the hands-on smoke (lint/diff/export against a sample), and bump the pin in a single commit.
• Consume conservatively. Downstream tooling (#903 lint gate, #904 diff) should depend only on the stable-looking JSON envelope (findings[] with severity/message, summary counts; diff’s per-section added/removed/modified) and treat unknown fields as pass-through, so a format addition doesn’t break gates.
• The committed DESIGN.md file is the durable artifact. Even if the CLI churns or is abandoned, the file itself (YAML front matter + prose) remains readable by agents directly — the injection path (#902) does not depend on the CLI at all.

Google Stitch as an upstream source

Google Stitch is a UI-generation platform that emits DESIGN.md natively, reachable from Claude Code via its MCP server (npx @_davideast/stitch-mcp proxy, with official Claude Code support). The proxy exposes screen-level tools (build_site, get_screen_code, get_screen_image), giving two complementary channels: DESIGN.md carries the system-level rules; Stitch MCP carries per-screen layouts.

Verdict: first-class upstream source, never a BoB surface. The reproducibility boundary:

• Stitch is optional, auth-gated (gcloud auth login), rate-capped, and per-project — three properties that disqualify it as a BoB-managed surface. It cannot be version-controlled, cannot be reproduced offline or in CI, and cannot be provisioned declaratively.
• The committed DESIGN.md is the BoB-managed artifact. Stitch is one way a project produces or updates that file (alongside hand-authoring or extracting from existing code); once committed, everything downstream — lint (#903), injection (#902), diff/export (#904) — operates on the file alone and works identically whether or not Stitch was ever involved.
• A project that wants Stitch wires the MCP server into its own .mcp.json. That wiring is project-local configuration, not a registry item; at most, the DESIGN.md registry skill documents the option.

stitch-skills repo evaluation

google-labs-code/stitch-skills (Apache-2.0, TypeScript, actively maintained — ~6.3k stars as of this evaluation) is a library of agent skills in the open Agent Skills standard, organized as three plugins: stitch-design (generate/edit screens, extract-design-md, manage-design-system), stitch-build (React/React-Native conversion, shadcn/ui), and stitch-utilities (design-md — analyze a project and generate a DESIGN.md; taste-design — premium DESIGN.md generation; prompt enhancement).

Verdict: adopt selectively, don’t mirror the repo.

• The repo states its skills require the Stitch MCP server configured and running — that dependency puts the stitch-design and stitch-build plugins behind the same auth/rate boundary as Stitch itself. They are usable by a project that has opted into Stitch, but are not candidates for general registry adoption.
• The DESIGN.md-authoring utilities (design-md, taste-design, extract-design-md) are the interesting subset for #902: they already implement “read a codebase / read a DESIGN.md, produce or apply design context”, which overlaps heavily with the planned injection skill. #902 should start by evaluating whether wrapping or adapting these (license is compatible) beats building from scratch — likely a hybrid: reuse their extraction/generation prompts, keep BoB’s own injection mechanics.
• Skills install via npx plugins add google-labs-code/stitch-skills at project scope — compatible with per-project opt-in, but a BoB registry wrapper should pin a commit/version, mirroring the CLI pinning stance.

Summary of decisions

Question	Decision
Where does DESIGN.md live?	Project root, committed; opt-in is file presence (dev.json analogy).
How is it provisioned?	Registry skill scoped to applies_to.project_types: [web-app]; wraps the pinned CLI; never auto-loaded globally.
Version strategy	Exact pin (@google/design.md@0.3.0) held in the wrapping skill; deliberate upgrades on surface-affecting releases; consume only the stable JSON envelope.
Relation to design skills	DESIGN.md is the token layer the skills reference; design.md export owns token export wherever a DESIGN.md exists; scaffold-tokens.sh remains for projects without one.
Stitch	Optional upstream source of the committed file — auth-gated, per-project MCP wiring; never a BoB surface.
stitch-skills	Selective adoption: evaluate the DESIGN.md-authoring utilities for #902; skip the MCP-dependent plugins for the registry.