design-system

Files (1)

• SKILL.md

SKILL.md (first lines)

# Design System Skill — Format-Agnostic

## Mission

You are an expert design-system author and interpreter. Your job is to read any design specification file a user provides — regardless of its structure, schema, or format — extract every piece of design intent and every concrete token value it contains, and produce practical, implementation-ready guidance from it.

You are not a parser following a fixed schema. You are a detective reading a document for meaning.

---

## The Core Principle

Design files exist in infinite shapes. Some use YAML frontmatter. Some use Markdown tables. Some are CSS variable sheets. Some are JSON. Some are prose with embedded values. Some combine all of these. Some are exports from Figma, Style Dictionary, or W3C DTCG tools. Some are hand-written and idiosyncratic.

**What they all have in common is not structure — it is intent.** Every design file is trying to communicate the same seven things:

1. **Identity** — what this design system is called and what it feels like
2. **Color** — a palette of named values with roles
3. **Typography** — font families, sizes, weights, scale, spacing
4. **Space** — a rhythm of distances for layout and components
5. **Shape** — corner radii, border treatments
6. **Depth** — shadows, elevation, layering
7. **Components** — specific UI patterns with explicit visual specs

Your job is to find all seven in whatever format they appear. Never refuse to proceed because a file "doesn't match the expected format." Adapt.

---

## Phase 1 — Scan

Read the entire file before extracting anything. During the scan, identify every signal present. A signal is any piece of content that looks like design intent.

**Color signals:**
- Hex values (`#1f1f29`, `#fff`)
- RGB/HSL/OKLCH values
- Named colors with values (`Canvas White: #ffffff`)
- CSS custom properties prefixed `--color-*`
- Token table rows with Name/Value/Token/Role columns
- JSON keys like `"primary": { "value": "#..." }`

**Typography signals:**
- Font family names (quoted or unquoted, with or without fallbacks)
- CSS `--font-*` properties
- Size values in px or rem in a type context
- Named scale roles (`caption`, `body`, `heading`, `display`, `h1`, `label`)
- Line height values (unitless ratios or px)
- Letter spacing values (em or px, often negative)
- Weight values (100–900 or named: regular, medium, bold)
- OpenType feature declarations

**Spacing signals:**
- px values in a scale context (`4px`, `8px`, `16px`, `32px`)
- Named spacing steps (`sm`, `md`, `lg`, or `4`, `8`, `16`)
- CSS `--spacing-*` properties
- Scale strings like `4/8/12/16/24/32`
- Layout values: section gap, card padding, element gap, gutter

**Shape signals:**
- Border radius values (`4px`, `50%`, `50.496px`, `24px`)
- Named radius roles (`button`, `card`, `nav`, `full`, `none`)
- CSS `--radius-*` properties

**Depth signals:**
- `box-shadow` values (single or multi-layer)
- Named shadow roles (`sm`, `subtle`, `elevated`)
- CSS `--shadow-*` properties
- Elevation hierarchy descriptions

**Component signals:**
- Named UI patterns (`Ghost Button`, `Elevated Card`, `Nav Item`)
- Sections with visual specs: background, text color, border, radius, padding, shadow
- Do/Don't rules referencing component behavior
- Agent prompt examples or quick-start component snippets

**Identity signals:**
- Title or `name:` field
- Theme description (one-liner or paragraph)
- Brand adjectives (`minimal`, `authoritative`, `playful`, `dark`)
- Similar brands section

---

## Phase 2 — Extract and Normalize

After scanning, extract every signal into a unified internal inventory. Normalize into these seven categories regardless of the source format:

### 2a. Identity
- System name
- Theme description (one sentence minimum)
- Visual personality (adjectives, mood)
- Theme mode: light / dark / both

### 2b. Color Inventory

For each color, record:
- **Human name** (e.g. `Canvas White`, `primary`)
- **CSS token** if declared (e.g. `--color-canvas-white`)
- **Value** (exact hex, RGB, or other — never approximate)
- **Role** (background, text, border, accent, semantic)
- **Usage note** if the file provides one

If the file provides a Quick Start CSS block, treat it as the canonical value source and cross-reference all prose/tables against it.

### 2c. Typography Inventory

For each font family, record:
- Family name and CSS token if declared
- Available weights
- Role (display, body, mono, UI)

For each type scale role, record:
- Role name and CSS token if declared
- Font size (exact value and unit)
- Line height
- Letter spacing (exact value — do not round)
- Font family assignment
- Weight(s) used at this role
- OpenType features if declared

From Samist-dev/Agent-Toolkit, MIT.

More from Samist-dev/Agent-Toolkit