Map Design Language

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](#designmd-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 — 

The design language , for grounding mockups and new UI. 

## Surfaces at a glance   

| # | Surface | Audience | Toolkit | Styling model |
|---|---|---|---|---|
| 1 |  |  |  |  |

##    

- **Toolkit:** 
- **Docs:**    
- **Components:** 
- **Tokens:** color  · spacing  · radius  · type 
- **Styling model:** ; appearance from 

## Maintenance

- Generated  from agent research.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: preetamnath
• Source: preetamnath/agent-skills
• License: MIT
• Homepage: https://www.preetamnath.com/blog/agent-skills

Install and usage instructions live in the source repository linked above.