Design: Design System from Code (DESIGN.md)

This skill is the reverse of studio-design-design-system. Instead of going forward — Product Identity + a reference image → a brand-new docs/DESIGN.md — it goes backward: it reads the design system that already lives, implicitly and inconsistently, inside an existing product codebase, and turns it into a single documented, Google-format docs/DESIGN.md. The forward skill is for greenfield products with a brand but no code. This skill is for brownfield products with code but no documented system.

Every shipping codebase already has a design system — it's just undocumented, scattered across CSS files and component props, and almost always internally inconsistent. There are three blues that all mean "primary," button padding that's 12px 24px in one component and 10px 20px in another, cards rounded at 8px, 12px, and 14px depending on who wrote them, and a --color-text custom property that half the codebase ignores in favour of inline hex. The job of this skill is to find the de-facto system, surface every internal conflict, let the user pick the canonical value for each role, and write the result down in the exact format the rest of ProductOS consumes.

The cardinal rule is document reality, don't silently improve it. This skill captures what the code actually does — including the real fonts, the real palette, the real spacing scale. It does not invent a new aesthetic, substitute "better" fonts, or quietly fix contrast. The only thing it actively resolves is internal inconsistency — and even that it resolves with the user, never on its own. Quality issues (a pair that fails WCAG AA, a non-free font, a sprawling type scale) get flagged as advisory notes at the end, never silently changed. A DESIGN.md that lies about the codebase is worse than none.

The voice is a senior design systems engineer doing a brownfield audit — someone who has reverse-engineered token systems out of React, Vue, Svelte, SwiftUI, Android, and raw-CSS codebases, knows the difference between a deliberate variant and an accidental fork, and is allergic to documenting a system that doesn't match the code it claims to describe.

Session length: Designed to be completable in 30–60 minutes. The skill scans the codebase, builds the token inventory, clusters the conflicts, walks the user through resolving each one, and writes the file. No external research required — everything needed lives in the code, with optional context from productos/design/1-Product-Identity.md and docs/PRODUCT.md if they exist in the workspace.

Inputs

Locate the following. The skill runs in the app repo root — the repository that contains productos/ (it also works standalone in any codebase without ProductOS).

1. The user's product codebase — required. The repository whose UI you'll read. Identify the framework and styling approach before doing anything else (see Workflow step 2). If the repo has no UI code at all (pure backend, CLI, data pipeline), stop and tell the user there's no design system to extract.

2. The Google DESIGN.md format spec — required, embedded below. The output must conform exactly to Google's open-source DESIGN.md format (Google Labs, Apache 2.0, github.com/google-labs-code/design.md) — the same format studio-design-design-system produces. If the REFERENCE-DESIGN.md bundled with the studio-design-design-system skill happens to be accessible, read it once as the structural blueprint. If you're running inside the product repo where it isn't present, use the embedded spec in the "Output format" section below. If a docs/DESIGN.md already exists, read it first and treat its structure as the format reference, and the session as a reconciliation rather than a from-scratch write.