# Design Spec

> Create UI/UX design specifications from requirements or Figma designs. Covers component specs (Atom/Molecule/Organism), accessibility audits (WCAG 2.1 AA), design tokens, responsive behavior, and dev handoffs. Triggers on "design spec", "ui spec", "component spec", "accessibility audit", "design handoff", "design tokens", "wireframe", "mockup".

- Skill: `majiayu000/design-spec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/design-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/design-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/design-spec

---


# Design Specification

Create comprehensive UI/UX specifications for implementation.

## When to Use
- PBI needs design documentation
- Figma design ready for handoff
- Component specification required
- Accessibility audit needed
- Design system additions

## ⚠️ MUST READ References

**IMPORTANT: You MUST read these reference files for complete protocol. Do NOT skip.**

- **⚠️ MUST READ** `references/design-system-reference.md` — component specs, accessibility audit template, design tokens, responsive breakpoints, handoff checklist

## Workflow

1. **Determine Source Type**
   - If URL starting with `figma.com`: treat as direct Figma source
   - If file path: read file and check for `figma_link` in frontmatter

2. **Load Source**
   - Read PBI/requirements file
   - Parse YAML frontmatter
   - Extract `figma_link` field if present

3. **Detect Figma Link**
   ```
   Sources (priority order):
   1. Direct Figma URL argument
   2. frontmatter.figma_link
   3. Figma URLs in "Design Reference" section
   ```
   Pattern: `https?://(?:www\.)?figma\.com/(design|file)/([a-zA-Z0-9]+)(?:/[^?]*)?(?:\?node-id=([0-9]+:[0-9]+))?`

4. **Extract Figma Specs (if link found)**
   - Call `/figma-extract {url}` internally
   - Handle failures gracefully (continue without Figma data)

5. **Define Components** (use template from `references/design-system-reference.md`)
   - Type classification: Atom / Molecule / Organism / Template
   - States: default, hover, active, disabled, error, loading
   - Design tokens mapping
   - Accessibility requirements (WCAG 2.1 AA)

6. **Specify Responsive Behavior** (breakpoints in reference)

7. **Generate Spec**
   Structure: Overview, Component Inventory, States, Design Tokens, Accessibility, Responsive, Figma Extracted Specs

8. **Save Artifact**
   - Path: `team-artifacts/design-specs/{YYMMDD}-designspec-{feature}.md`

## Fallback Behavior
When Figma extraction unavailable:
1. Log warning: "Figma specs not extracted: {reason}"
2. Continue with manual spec creation
3. Leave Section 7 with placeholder text

## Design Token Format
```scss
$primary: #1976D2;     // Colors
$heading: 24px/1.2 'Inter'; // Typography
$gap-sm: 8px;          // Spacing
```

## Example
```bash
/design-spec https://www.figma.com/design/ABC123/UserProfile
/design-spec team-artifacts/pbis/260119-pbi-user-profile.md
```

## Output
Creates: `team-artifacts/design-specs/{YYMMDD}-designspec-{feature}.md`


## IMPORTANT Task Planning Notes

- Always plan and break many small todo tasks
- Always add a final review todo task to review the works done at the end to find any fix or enhancement needed