| name | map-design-language |
| description | Research a project's design language and write or refresh a lean meta/DESIGN.md of facts — surfaces, toolkits, tokens, styling models, docs pointers — that grounds mockups and new UI. TRIGGER when: user asks to map, document, or bootstrap the design language, or to create/refresh meta/DESIGN.md; a skill needs grounding facts and meta/DESIGN.md is missing or stale. SKIP when: meta/DESIGN.md exists and is current (just read it); inventing a new aesthetic from a blank canvas (frontend-design). |
Map Design Language
Research what a project's UI is actually built from — toolkits, tokens, components, styling models — and record it as a lean meta/DESIGN.md of facts. Other skills (generate-mockups, product-interview) and humans read it to ground UI work. This skill writes the facts; how to use them (fidelity, how to mock) belongs to the consuming skill.
When to use
YES: no meta/DESIGN.md exists and a skill or human needs grounding facts; the file exists but a surface's toolkit/tokens changed or it has gaps; the user asks to map/document/bootstrap/refresh the design language.
NOT this if:
meta/DESIGN.md exists and is current → just read it.- you're inventing a new aesthetic from a blank canvas →
frontend-design.
Protocol
Step 1 — Detect state and mode
Check for meta/DESIGN.md:
- Missing → bootstrap mode: research everything, write the file.
- Exists → read it. A surface's toolkit/tokens changed, or blocks are missing/incomplete → refresh mode: update the affected blocks only. Current and complete → stop; tell the user it's already good.
Step 2 — Probe the surfaces (don't assume)
Determine whether the project has one implicit surface or several distinct UI contexts — different toolkits, audiences, or render targets (e.g. an admin app vs a buyer extension, web vs email). Do a light scan (root package.json/workspaces, extensions/ or app dirs, framework imports) — if the layout isn't obvious at a glance, delegate the scan to a single read-only general-purpose subagent that returns the candidate surface list (name + path + toolkit guess). If ambiguous, confirm the surface list via AskUserQuestion.
- One surface → the file is a single flat facts block, no Surfaces table.
- Multiple surfaces → a Surfaces table + one block per surface.
Step 3 — Fan out research (read-only)
Dispatch parallel read-only general-purpose agents, scaled to the surface count:
- One surface → one agent covers styling system + tokens + components.
- Multiple surfaces → one agent per surface (plus a surface-map agent if the layout is unclear).
Each agent returns, concretely and with file paths: toolkit + version · the tokens actually used (names and/or values) · key components / signature patterns · the styling model (free-form CSS vs prop-constrained component library) · where appearance comes from (own CSS vs inherited branding) · the library's docs link. Extract real values; don't dump files.
Refresh: fan out only over the surfaces whose blocks are stale or incomplete — leave current blocks unread.
Step 4 — Assemble and checkpoint
Synthesize into the DESIGN.md template — facts only. Do NOT write fidelity ratings or how-to-mock guidance (that is the consuming skill's job). Keep it lean: the project-used subset + a docs link per external library, not a mirror of the library. Before writing, summarize in chat in this shape, then confirm via AskUserQuestion ("Write it" / "Adjust"):
**Design language summary (pre-write):**
- Surfaces: [surface — toolkit — styling model, one per line | single surface — no table]
- Key facts: [toolkit + tokens + components, one line per surface]
Refresh: synthesize only the affected blocks; leave the rest untouched.
Step 5 — Write or refresh
- Bootstrap → write
meta/DESIGN.md from the template; stamp the Maintenance date.
- Refresh → edit only the changed blocks in place; keep structure and any human edits; update the Maintenance date. Say which blocks changed.
Report the path.
Rules
- Facts only. DESIGN.md states what the UI is made of. Fidelity expectations and how-to-mock live in the consuming skill (
generate-mockups), never here.
- Probe surfaces, don't assume. One implicit surface → a single flat block, no Surfaces table. Add the table only for genuinely distinct toolkits.
- Point to library docs; don't mirror. For an external library, capture only the project-used subset + a docs link — the library owns its exhaustive API.
- Lean v1. Enough to ground UI work, not a full design-system spec.
- Read-only research. The fan-out agents only read; the parent assembles and writes.
- Refresh in place. Update changed blocks; never rewrite a maintained file wholesale.
DESIGN.md template
Inline the filled version into meta/DESIGN.md. Omit the Surfaces table and the surface numbering for a single-surface project.
# Design reference — <project>
The design language <per surface, if multiple>, for grounding mockups and new UI. <If multi-surface: ground against the specific surface being worked on — token vocabularies are not interchangeable across surfaces.>
## Surfaces at a glance <!-- OMIT for a single-surface project -->
| # | Surface | Audience | Toolkit | Styling model |
|---|---|---|---|---|
| 1 | <name + path> | <who> | <framework + lib + version> | <free CSS · or prop-only + branding source> |
## <Surface name> <!-- one block per surface; a single surface gets one block, unnumbered -->
- **Toolkit:** <framework + component library + version>
- **Docs:** <link to the library's UI docs> <!-- external libraries only -->
- **Components:** <the components / signature patterns actually used>
- **Tokens:** color <values> · spacing <scale> · radius <scale> · type <families/weights>
- **Styling model:** <free-form CSS · or prop-constrained>; appearance from <own CSS · or inherited branding>
## Maintenance
- Generated <date> from agent research.
