Design Md Workflow

DESIGN.md Workflow

Use this skill when a project needs a durable, agent-readable visual identity that survives across sessions, agents and implementation passes.

Google Labs' DESIGN.md project defines an alpha format that combines machine-readable design tokens in YAML front matter with human-readable design rationale in Markdown. Agentit treats that format as an optional current external contract, not a global dependency and not a replacement for the project's real source-of-truth design system.

When to load

Load when one or more are true:

• a project already contains DESIGN.md;
• a greenfield/redesign task needs a durable visual identity for future agents;
• Figma/design tokens exist but the coding-agent handoff lacks concise project-level rationale;
• several sessions/agents keep drifting in typography, color, spacing, radii or component styling;
• a design-system change needs a reviewable token/rationale diff.

Do not load for a one-off tiny UI edit where the existing component system already answers the visual question.

Authority order

Before writing or applying DESIGN.md, identify the real source of truth.

Typical authority order:

explicit user/brand requirements
-> existing production design system / tokens / Figma source
-> canonical DESIGN.md when intentionally maintained
-> project components/styles
-> external design references
-> model preference

If DESIGN.md conflicts with production tokens or an explicitly authoritative Figma/design-system source, do not silently choose one. Determine whether DESIGN.md is stale and update the correct canonical source.

DESIGN.md is memory, not magic. It cannot make an inaccurate design system authoritative merely because it is structured.

Cold-session behavior

DESIGN.md may persist on disk because it is durable project knowledge. The skill body remains JIT.

A fresh session should inspect DESIGN.md only when visual/system consistency is material to the current task. Do not globally inject it into unrelated backend, research or writing work.

Read workflow

When DESIGN.md exists:

1. Read its front matter and prose before choosing visual direction.
2. Locate actual implementation tokens/components and compare material values.
3. Treat token values as normative only to the extent the project intentionally uses DESIGN.md as a maintained contract.
4. Extract the project's visual thesis, semantic color roles, type hierarchy, spacing/radius rules, component rules, and explicit do/don't guidance.
5. Feed only the relevant subset to the executing design/frontend worker.

Do not dump the whole document into every worker when only one component family is changing.

Create workflow

Create DESIGN.md only when persistent design memory is useful enough to maintain.

Build it from project truth, not imagination:

inspect brand + current UI + tokens + components + Figma if authoritative
-> identify stable visual decisions
-> normalize semantic token roles
-> write concise rationale explaining why/how they are used
-> map important component states
-> document deliberate omissions
-> validate
-> compare implementation against the contract

Do not fabricate a “brand system” from generic AI preferences when the project lacks enough evidence. For greenfield work, first establish a reviewed design direction using the design pack; then encode the accepted direction.

Current DESIGN.md structure

As of the inspected Google Labs alpha specification, the format supports YAML front matter for concepts including:

• name / optional version and description;
• semantic colors;
• typography roles;
• rounded scale;
• spacing scale;
• component-level token mappings;
• intentional omissions;

with Markdown rationale sections such as overview, colors, typography, layout/spacing, elevation/depth, shapes, components, and do/don't guidance.

The external format is explicitly alpha. Re-check the current upstream specification before depending on exact schema details, CLI flags or lint semantics in a material change.

Token rules

Prefer semantic roles over component accidents.

Good:

colors.action-primary
colors.text-muted
spacing.content-gap
rounded.control

Weak:

blue-500
random-gray
card-padding-17

unless those names are already the canonical project convention.

A token should earn persistence because it encodes a repeated design decision. Do not serialize every CSS declaration into DESIGN.md.

Rationale rules

The Markdown body explains decisions a raw token file cannot:

• visual thesis and brand character;
• where an accent is and is not used;
• density/whitespace intent;
• typography roles and hierarchy;
• responsive composition principles;
• material/elevation rules;
• recurring component behavior;
• anti-patterns that would make the product drift off-brand.

Write actionable constraints, not aesthetic fan fiction.

Weak:

The interface evokes an elevated digital journey through a sophisticated technological landscape.

Useful:

Use warm off-white surfaces and near-black text. Red is reserved for primary actions and critical status. Product pages stay content-dense; marketing pages may use larger editorial spacing.

Component states

When the design contract covers interactive components, capture only real semantic states:

default
hover (pointer surfaces)
focus-visible
pressed/active
disabled
loading
error/success when the component actually owns those states

Do not invent meaningless variants to make the design file look complete.

Verification

When the current upstream CLI is available and dependency use is acceptable, prefer its validator instead of hand-waving schema validity. The inspected alpha project exposes commands equivalent to:

npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN-before.md DESIGN.md

It can also export tokens to Tailwind-oriented or DTCG formats. Re-verify current command syntax from the upstream source because the format is alpha.

Lint success alone is not visual verification. Also verify:

• referenced fonts/assets actually exist or have an approved delivery path;
• component tokens map to real project implementation;
• contrast/accessibility on actual states;
• rendered desktop/mobile behavior;
• production tokens and DESIGN.md have not drifted materially.

Change discipline

When visual identity changes materially:

1. update the actual implementation/source of truth;
2. update DESIGN.md in the same reviewable change when it is canonical project memory;
3. explain the durable reason in project docs/ADR only if rediscovery would be costly;
4. verify the new design contract and rendered UI;
5. do not leave two conflicting token systems behind.

Pairing

Common JIT pairings:

• design-inspiration-research — establish evidence-backed direction before encoding it;
• design-taste-frontend — art direction;
• impeccable — critique/polish;
• figma-design-workflow — when Figma is authoritative;
• frontend-ui-engineering — implement the contract;
• browser-testing-with-devtools — rendered verification.

Load only the pairings the current task needs.

Failure modes

• auto-creating DESIGN.md in every frontend repo;
• treating an alpha external schema as permanently stable;
• making DESIGN.md override a stronger canonical source silently;
• copying a fashionable design system instead of encoding project truth;
• putting temporary campaign/page styling into the durable brand contract;
• duplicating every CSS variable with no rationale;
• claiming consistency because lint passed without checking rendered UI;
• loading the entire design system into unrelated sessions/workers.