# Map Design Language

> 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).

- Skill: `preetamnath/map-design-language` (Agent Skill)
- Install (CLI): `npx skillmds@latest add preetamnath/map-design-language`
- Raw SKILL.md: https://api.skillmd.com/api/skills/preetamnath/map-design-language/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: preetamnath (https://skillmd.com/u/preetamnath)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/preetamnath/map-design-language

---


# Map Design Language

Research what a project's UI is 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.

## 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 and not a full design-system spec. 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.

---

## DESIGN.md template

Inline the filled version into `meta/DESIGN.md`. Omit the Surfaces table and the surface numbering for a single-surface project.

```markdown
# 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.
```