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

$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