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
- 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
- Load Source
- Read PBI/requirements file - Parse YAML frontmatter - Extract figma_link field if present
- 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]+))?`
- Extract Figma Specs (if link found)
- Call /figma-extract {url} internally - Handle failures gracefully (continue without Figma data)
- 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)
- Specify Responsive Behavior (breakpoints in reference)
- Generate Spec
Structure: Overview, Component Inventory, States, Design Tokens, Accessibility, Responsive, Figma Extracted Specs
- Save Artifact
- Path: team-artifacts/design-specs/{YYMMDD}-designspec-{feature}.md
Fallback Behavior
When Figma extraction unavailable:
- Log warning: "Figma specs not extracted: {reason}"
- Continue with manual spec creation
- Leave Section 7 with placeholder text
Design Token Format
$primary: #1976D2; // Colors
$heading: 24px/1.2 'Inter'; // Typography
$gap-sm: 8px; // Spacing
Example
/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