Design Implementer Skill

This skill implements Figma designs from Linear tickets or direct Figma URLs into production-ready Flutter components.

Prerequisites

• Linear MCP Server: Must be configured for ticket lookup
• Figma MCP Server: Must be configured for design context and screenshots
• Input: Linear ticket ID (e.g., KEPLR-1578) OR Figma URL
• Optional Parameters:
  • examples: widgetbook or none (if not provided, will ask user)

Workflow

Follow these steps in order. Do not skip steps or proceed without completing each one.

Step 1: Parse Input and Gather Context

If Linear ticket ID provided:

1. Detect pattern: [A-Z]+-\d+ (e.g., KEPLR-1578, LIN-123)
2. Call mcp__linear__get_issue(id=":ticketId") to fetch ticket details
3. Extract all Figma links from ticket description and comments
4. If multiple Figma links found, ask user: "Multiple Figma links found. Which design should I implement?"
5. Store selected Figma URL for next step

If Figma URL provided directly:

1. Validate URL format: https://figma.com/design/:fileKey/:fileName?node-id=X-Y
2. Store URL for next step

Output: Confirmed Figma URL to implement

Step 2: Confirm Example Generation

1. Check if examples parameter was provided via slash command
2. If not provided, ask user: "Should I generate Widgetbook examples? (widgetbook/none)"
3. Store example choice: widgetbook or none

Output: Confirmed example generation preference

Step 3: Fetch Design Context

1. Parse Figma URL:

   • Extract fileKey: segment after /design/ (or /branch/ if branch URL)
   • Extract nodeId: value of node-id query parameter
   • Convert nodeId format: X-Y → X:Y for API calls

2. Fetch design context:

   mcp__figma__get_design_context(
     fileKey=":fileKey",
     nodeId=":nodeId",
     clientLanguages="dart",
     clientFrameworks="flutter"
   )
   

3. Fetch design screenshot:

   mcp__figma__get_screenshot(
     fileKey=":fileKey",
     nodeId=":nodeId",
     clientLanguages="dart",
     clientFrameworks="flutter"
   )
   

4. If design context is truncated:

   • Call mcp__figma__get_metadata(fileKey=":fileKey", nodeId=":nodeId") to get structure
   • Identify child node IDs
   • Fetch each child individually with get_design_context

5. Check for Code Connect mappings:

   mcp__figma__get_code_connect_map(
     fileKey=":fileKey",
     nodeId=":nodeId"
   )
   

   • If mappings exist, review existing component implementation
   • Use existing patterns as reference

Output: Full design context, screenshot, and any existing code mappings

Step 4: Analyze Design and Present Implementation Plan

Analysis:

1. Identify component name from Figma layer name
2. Detect variants (e.g., primary/secondary/ghost)
3. Detect sizes (e.g., sm/md/lg)
4. Detect states (e.g., default/hover/active/disabled/loading)
5. List all props needed based on design properties
6. Identify similar existing components in codebase

Implementation Plan: Present a clear plan to user:

Component: [ComponentName]
Platform: Flutter

Files to create:
- packages/flutter/lib/src/components/dsp_[component_name].dart
- apps/widgetbook/lib/design_system/components/[component]/showcase/[component]_showcase.dart (if examples requested)

Files to modify:
- packages/flutter/lib/design_system_playground.dart (add export)
- apps/widgetbook/lib/main.dart (register showcase if examples requested)

Detected properties:
- Variants: [list]
- Sizes: [list]
- States: [list]
- Other props: [list]

Reference components:
- [Similar component 1]
- [Similar component 2]

CRITICAL: Ask user for confirmation before proceeding: "Does this plan look correct? Should I proceed with implementation?"

Output: User-approved implementation plan

Step 5: Implement Component

Component Location: packages/flutter/lib/src/components/

1. Read reference patterns:

   • Consult references/flutter-patterns.md for template and community standards
   • Review existing dsp_button.dart for structure
   • Review ../theme/dsp_theme.dart for theme access
   • Review ../../tokens.dart for available tokens

2. Create component file:

   • Use StatefulWidget pattern for interactive components
   • Define variant/size enums with Dsp prefix
   • Implement hover/press state tracking
   • Use DspTheme.of(context) for theme access
   • Use DspTokens.* for design tokens (NEVER hardcode values)
   • Implement all variants and states from design
   • Use AnimatedContainer for smooth transitions
   • Follow Effective Dart style guidelines
   • Apply widget composition best practices
   • Apply StatefulWidget performance patterns

3. Export component:

   • Add export to packages/flutter/lib/design_system_playground.dart:

     export 'src/components/dsp_component_name.dart';
     

Custom Rules:

• Consult references/implementation-rules.md for project-specific guidelines
• Follow any additional rules defined there

Output: Component file created and exported

Step 6: Generate Examples (if requested)

For Widgetbook (Flutter):

1. Create showcase file: apps/widgetbook/lib/design_system/components/[component_name]/showcase/[component_name]_showcase.dart

2. Follow existing Widgetbook patterns:

   • Import component from package:design_system_playground/design_system_playground.dart
   • Create showcase with knobs for all properties
   • Show all variants and sizes
   • Demonstrate all states (default, hover, disabled, loading, etc.)

3. Register in main.dart:

   • Add to appropriate WidgetbookFolder in apps/widgetbook/lib/main.dart
   • Example:

     WidgetbookLeafComponent(
       name: 'ComponentName',
       useCase: WidgetbookUseCase(
         name: 'Component Showcase',
         builder: (context) => const ComponentNameShowcase(),
       ),
     ),
     

Output: Widgetbook showcase created and registered

Step 7: Validate Implementation

Visual Validation:

1. Compare component against Figma screenshot
2. Verify all variants match design
3. Verify all states implemented (hover, active, disabled, etc.)
4. Check spacing, colors, typography match design tokens

Code Validation:

1. ✅ No hardcoded values (all use theme/tokens)
2. ✅ All variants from design implemented
3. ✅ Component exported in index file
4. ✅ Enums defined for variants/sizes
5. ✅ Follows existing patterns from reference files
6. ✅ Examples created (if requested)

Build Recommendation:

• Run: yarn widgetbook
• Or: cd apps/widgetbook && flutter run -d chrome

Output: Validation report and build instructions

Implementation Rules

Custom Rules

For detailed project-specific rules, consult:

• references/implementation-rules.md - User-defined custom rules

Default Rules

General:

• NEVER hardcode values - always use design tokens
• Match Figma design exactly (1:1 visual fidelity)
• Follow existing component patterns in codebase
• Use semantic naming for variants and props

Flutter Specific:

• Prefix all components with Dsp (e.g., DspButton, DspCheckbox)
• Use snake_case with dsp_ prefix for file names (e.g., dsp_button.dart)
• Use StatefulWidget for interactive components
• Track hover/press state when needed
• Use AnimatedContainer for transitions (150ms)
• Use DspTheme.of(context) for theme access
• Use DspTokens.* for design tokens
• Follow Effective Dart style guidelines
• Apply widget composition best practices
• Apply StatefulWidget performance patterns

Reference Files

Flutter Patterns

Location: references/flutter-patterns.md

Key patterns:

• StatefulWidget structure
• Hover/press state tracking
• Theme integration
• Variant/size enums
• AnimatedContainer transitions
• Community standards (Effective Dart, Widget Composition, StatefulWidget Performance)

Implementation Rules

Location: references/implementation-rules.md

Project-specific guidelines and conventions (user-editable).

Example Scenarios

Scenario 1: Linear Ticket with Flutter Component

Input:

/implement-design KEPLR-1578

Actions:

1. Fetch Linear ticket KEPLR-1578
2. Extract Figma link from description
3. Ask user about examples → widgetbook
4. Fetch Figma design context and screenshot
5. Present plan: "Implementing Checkbox component for Flutter with Widgetbook showcase"
6. Create packages/flutter/lib/src/components/dsp_checkbox.dart
7. Export in packages/flutter/lib/design_system_playground.dart
8. Create apps/widgetbook/lib/design_system/components/checkbox/showcase/checkbox_showcase.dart
9. Register in apps/widgetbook/lib/main.dart
10. Validate against design

Scenario 2: Direct Figma URL with Examples

Input:

/implement-design https://figma.com/design/abc123/file?node-id=21-45 --examples widgetbook

Actions:

1. Parse Figma URL directly (fileKey=abc123, nodeId=21:45)
2. Examples already specified: widgetbook
3. Fetch Figma design context and screenshot
4. Present plan with detected component properties
5. Create Flutter component file
6. Export in package file
7. Create Widgetbook showcase
8. Validate against design

Scenario 3: Linear Ticket with Multiple Figma Links

Input:

/implement-design LIN-123 --examples none

Actions:

1. Fetch Linear ticket LIN-123
2. Find 3 Figma links in description
3. Ask user: "Found 3 Figma links. Which should I implement?"
4. User selects link #2
5. Examples already specified: none
6. Continue with implementation workflow (no Widgetbook showcase)

Error Handling

Linear ticket not found:

• Display error message
• Ask user to verify ticket ID
• Suggest checking Linear workspace

Figma link not found in Linear ticket:

• Display error message
• Ask user to provide Figma URL directly
• Suggest adding Figma link to ticket

Invalid Figma URL:

• Display error message with expected format
• Ask user to provide correct Figma URL

Design context truncated:

• Use get_metadata to get structure
• Fetch child nodes individually
• Inform user of fallback approach

Success Criteria

✅ Component matches Figma design visually (1:1) ✅ All variants implemented ✅ All states implemented (hover, active, disabled, etc.) ✅ No hardcoded values (uses design tokens) ✅ Component exported in package index ✅ Examples created (if requested) ✅ Follows existing patterns ✅ Enums defined for variants/sizes ✅ Follows community standards (Effective Dart, Widget Composition, StatefulWidget Performance) ✅ Build succeeds without errors