Design: Design System (image → DESIGN.md + DESIGN.html)

This skill takes an image reference the user loves — a screenshot, mockup, Figma file, or live website — and translates it into a design system captured as two mirrored files:

• docs/DESIGN.md — YAML tokens in Google's open design.md format plus prose rationale. The source of truth — AI coding agents (Claude Code, Cursor, Kiro, Stitch) read it automatically to make brand-consistent decisions.
• docs/DESIGN.html — a self-contained, human-readable style guide that renders every token and component live in a browser, styled directly from the same token values. The mirror the human opens.

Same system, two audiences: the agent reads the .md, the human opens the .html. They are always written and updated together so they never drift.

In ProductOS this is Design phase Step 2, immediately after the Product Identity. The identity supplies the words (name, worldview, contrarian belief, tone, visual style direction) and deliberately leaves the visuals undecided — this skill derives the colours, fonts, spacing, shapes, and components from a real image, guided by those words. The user's job before this session: find one image or site that looks the way the brand feels. The Visual Style references in the identity are the natural hunting ground.

Session length: 30–60 minutes. The user supplies the image; Claude does the visual analysis, the token extraction, the identity reconciliation, and both file writes. Already have a codebase instead of an image? studio-design-design-system-from-code reverse-engineers the system from the code.

Modes

• No image provided yet: ask for one (Step 0) before doing anything else. Don't draft a DESIGN.md from imagination. If the user has no image after one prompt, offer the weak fallback: "I can draft a starter system from your Product Identity's words alone and we'll refine it — but it will be far weaker than working from an image you love. Want to proceed that way, or grab a reference first?"
• docs/DESIGN.md already exists: read it (and docs/DESIGN.html if present) and ask what they want — refine specific tokens, replace with a fresh analysis from new imagery, or merge. Confirm before destructive overwrites. Whatever changes, regenerate docs/DESIGN.html so it stays in sync.
• Partial conversation: if the session was interrupted mid-flow, note where it left off and resume from that step. Don't restart.