Design Intent Specialist

Design Intent Specialist

Create accurate frontend implementations from visual references while maintaining design consistency.

Core Philosophy: Visual fidelity first, with intelligent conflict resolution when references clash with existing patterns.

Quick Start

1. Check Existing Patterns (Mandatory)

Before any implementation:

1. Read /design-intent/patterns/ directory 2. Report: "Existing patterns to consider: [list with values]" 3. Understand established design decisions

2. Analyze Visual Reference

• Extract visual elements for implementation
• Identify potential conflicts with existing patterns
• Plan implementation approach

3. Implement with Conflict Resolution

When visual references conflict with existing design intent:

1. Implement the reference faithfully - This is what the user requested 2. Flag conflicts clearly - "This design uses 8px spacing, but our intent specifies 12px" 3. Ask for guidance - "Should I follow the design exactly, or adapt to established spacing?" 4. Suggest implications - "If we use this spacing, should it become our new standard?"

4. Section-by-Section Implementation

For complex designs, break down into:

• Header: Navigation, branding, user controls
• Navigation: Menu items, hierarchies, states
• Main Content: Primary content, data display, forms
• Footer: Secondary links, metadata, actions

Each section analyzed for: layout, spacing, typography, responsiveness, visual treatment.

Implementation Priority

1. Visual fidelity - Match the reference closely 2. Existing components - Use established components where they fit 3. Framework components - Leverage Fluent UI when appropriate 4. Custom components - Create only when necessary for design accuracy

Custom Components

When creating custom components, use clear naming (CustomCard vs Card) and document with header comments. See WORKFLOW.md - Custom Component Documentation for the documentation template.

Behavioral Rules

1. ALWAYS check existing design intent first - non-negotiable 2. Visual fidelity over strict consistency - implement what's requested, flag conflicts 3. Ask for guidance on conflicts - don't assume precedence 4. Track custom components - for maintainability

MCP Integration

Optional: figma-dev-mode-mcp-server (Figma extraction) and fluent-pilot (Fluent UI guidance). Works without MCPs using screenshots.

Reference Documentation

• Detailed workflow: See WORKFLOW.md
• Usage examples: See EXAMPLES.md
• Common issues: See TROUBLESHOOTING.md

Invocation

Triggered by:

• Phase 5 of `/design-intent` workflow (automatic invocation)
• User providing Figma URLs or screenshots
• Requests to implement UI from visual references

Workflow Integration

When invoked from /design-intent Phase 5, architecture decisions and exploration are complete. Focus on execution with the richer context provided by the structured workflow.

Examples

Real-world examples of the Design Intent Specialist skill in action.

---

Example 1: Screenshot to Implementation

User Input

[User attaches screenshot of a dashboard card]
"Implement this dashboard card"

Skill Response

Pattern Check:

Existing patterns to consider:
- card-hover-states.md: 200ms ease transitions, subtle elevation on hover
- spacing-sections.md: 48px between major sections
No existing card component pattern found.

Reference Analysis:

Analyzing screenshot...

Extracted elements:
- Card with rounded corners (8px radius)
- White background with subtle shadow
- 16px internal padding
- Title: 16px semibold
- Value: 32px bold
- Subtitle: 12px regular, muted color
- Trend indicator with arrow icon

Implementation:

import { Card, Text, tokens } from '@fluentui/react-components';
import { ArrowUp16Regular } from '@fluentui/react-icons';

export const MetricCard: React.FC<MetricCardProps> = ({
  title,
  value,
  trend,
  trendLabel,
}) => {
  return (
    <Card
      style={{
        padding: tokens.spacingHorizontalL,
        borderRadius: tokens.borderRadiusMedium,
        boxShadow: tokens.shadow4,
        transition: 'box-shadow 200ms ease', // From card-hover-states pattern
      }}
    >
      <Text size={400} weight="semibold">{title}</Text>
      <Text size={800} weight="bold">{value}</Text>
      <div style={{ display: 'flex', alignItems: 'center', gap: '4px' }}>
        <ArrowUp16Regular style={{ color: tokens.colorPaletteGreenForeground1 }} />
        <Text size={200} style={{ color: tokens.colorNeutralForeground3 }}>
          {trend} {trendLabel}
        </Text>
      </div>
    </Card>
  );
};

Notes:

• Applied existing card-hover-states pattern for transition
• Used Fluent UI tokens for consistency
• No conflicts detected

---

Example 2: Figma URL with Conflict

User Input

[User provides Figma URL]
"Implement this design: https://figma.com/file/abc123/Dashboard?node-id=42"

Skill Response

Pattern Check:

Existing patterns to consider:
- page-header-template.md: Back button left, title center, actions right
- button-sizing.md: Primary actions use "large" size

Reference Analysis (via MCP):

Fetching Figma design...

Page header extracted:
- Title: Left-aligned, 24px bold
- Actions: Right-aligned, medium-sized buttons
- No back button present

Conflict Detected:

## Design Conflict Detected

**Element**: Page header layout
**Reference**: Title left-aligned, no back button
**Existing Pattern**: Back button left, title center (page-header-template.md)

### Options

1. **Follow reference** - Left-aligned title, no back button
2. **Use existing pattern** - Add back button, center title
3. **Hybrid** - Keep left-aligned title, add back button

### Recommendation

Since this appears to be a top-level page (no parent to navigate back to),
following the reference makes sense. However, if this is a detail page,
the back button pattern should apply.

**Is this a top-level or detail page?**

User Response

"It's a top-level dashboard page, so no back button needed."

Continued Implementation

export const DashboardHeader: React.FC = () => {
  return (
    <div style={{
      display: 'flex',
      justifyContent: 'space-between',
      alignItems: 'center',
      padding: '16px 24px',
    }}>
      <Text size={700} weight="bold">Analytics Dashboard</Text>
      <div style={{ display: 'flex', gap: '8px' }}>
        <Button appearance="secondary" size="medium">Export</Button>
        <Button appearance="primary" size="medium">Add Widget</Button>
      </div>
    </div>
  );
};

Note: Deviated from page-header-template pattern as this is a top-level page. Consider documenting "top-level-header" as a separate pattern.

---

Example 3: Description-Based Implementation

User Input

"Create a settings page similar to the profile page layout,
with a sidebar for navigation and main content area for forms."

Skill Response

Pattern Check:

Existing patterns to consider:
- sidebar-layout.md: 240px fixed sidebar, responsive collapse at 768px
- form-spacing.md: 24px between form sections, 16px between fields
- page-header-template.md: Back button for detail pages

Implementation Plan:

Based on existing patterns:
1. Use sidebar-layout pattern (240px sidebar)
2. Apply form-spacing pattern (24px sections, 16px fields)
3. Include page-header with back button (detail page pattern)

Implementation:

export const SettingsPage: React.FC = () => {
  return (
    <div style={{ display: 'flex', minHeight: '100vh' }}>
      {/* Sidebar - from sidebar-layout pattern */}
      <aside style={{
        width: '240px',
        borderRight: `1px solid ${tokens.colorNeutralStroke1}`,
        padding: tokens.spacingVerticalL,
      }}>
        <nav>
          <NavItem icon={<Person24Regular />} active>Profile</NavItem>
          <NavItem icon={<Shield24Regular />}>Security</NavItem>
          <NavItem icon={<Alert24Regular />}>Notifications</NavItem>
          <NavItem icon={<Apps24Regular />}>Integrations</NavItem>
        </nav>
      </aside>

      {/* Main content */}
      <main style={{ flex: 1, padding: tokens.spacingHorizontalXXL }}>
        {/* Header - from page-header-template pattern */}
        <PageHeader
          backHref="/profile"
          title="Settings"
        />

        {/* Form sections - from form-spacing pattern */}
        <div style={{ display: 'flex', flexDirection: 'column', gap: '24px' }}>
          <FormSection title="Personal Information">
            <Field label="Display Name">
              <Input />
            </Field>
            <Field label="Email">
              <Input type="email" />
            </Field>
          </FormSection>

          <FormSection title="Preferences">
            <Field label="Language">
              <Dropdown />
            </Field>
            <Field label="Timezone">
              <Dropdown />
            </Field>
          </FormSection>
        </div>
      </main>
    </div>
  );
};

Patterns Applied:

• ✅ sidebar-layout.md - 240px sidebar width
• ✅ form-spacing.md - 24px between sections
• ✅ page-header-template.md - Back button included

---

Example 4: Iteration/Vibe Coding

Initial Implementation

User provides screenshot, skill implements dashboard grid.

User Feedback Round 1

"The cards feel too spread out, can we tighten the spacing?"

Skill Response

// Before
<div style={{ display: 'grid', gap: '24px' }}>

// After
<div style={{ display: 'grid', gap: '16px' }}>

Updated. The cards now have 16px gap instead of 24px.

User Feedback Round 2

"Better! But the text in the cards is a bit small for a dashboard."

Skill Response

// Before
<Text size={400}>{value}</Text>

// After
<Text size={600}>{value}</Text>

Increased metric values from size 400 to 600.

User Feedback Round 3

"Perfect! Let's keep this."

Skill Response

Implementation complete.

Patterns to consider documenting:

• Dashboard grid: 16px gap (tighter than standard 24px)
• Dashboard metrics: size 600 for values

Would you like me to run /save-patterns to capture these patterns?

---

Example 5: Complex Full-Page Design

User Input

[User attaches full dashboard mockup with header, sidebar, and data grid]
"Implement this full dashboard design"

Skill Response

Breaking down into sections:

I'll implement this full-page design section by section:

1. Header (navigation, user menu)
2. Sidebar (navigation menu)
3. Main content (data grid with filters)

Let me start with the header...

Section 1: Header [Implements header component]

Section 2: Sidebar [Implements sidebar with navigation]

Section 3: Main Content [Implements data grid with filters]

Final Assembly:

export const DashboardPage: React.FC = () => {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
      <DashboardHeader />
      <div style={{ display: 'flex', flex: 1 }}>
        <DashboardSidebar />
        <DashboardContent />
      </div>
    </div>
  );
};

Summary:

• 3 custom components created
• Applied 2 existing patterns
• 1 conflict resolved (user chose reference over pattern)
• Responsive behavior: sidebar collapses at 768px

Troubleshooting

Common issues and solutions for the Design Intent Specialist skill.

---

Issue: No Design Intent Directory Found

Symptoms

Error: Cannot find /design-intent/patterns/ directory

Cause

Project hasn't been initialized with /setup command.

Solution

Run the setup command to create the design intent structure:

/setup

This creates:

• /design-intent/memory/ - Constitution and team roles
• /design-intent/patterns/ - Design patterns
• /design-intent/diary/ - Session documentation

Workaround

If you don't want to use the full design-intent structure, you can proceed without patterns. The skill will note:

No existing design intent patterns found. Will establish new patterns based on this implementation.

---

Issue: MCP Server Not Available

Symptoms

• Figma URL provided but can't extract design data
• fluent-pilot queries fail

Cause

MCP servers not configured in project.

Solution

The skill works without MCPs - they're optional enhancements.

For Figma integration, configure in .mcp.json:

{
  "mcpServers": {
    "figma-dev-mode-mcp-server": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-figma-dev-mode"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

For Fluent UI guidance:

{
  "mcpServers": {
    "fluent-pilot": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-fluent-pilot"]
    }
  }
}

Workaround

Without MCPs:

• Provide screenshots instead of Figma URLs
• Manually describe Fluent UI components to use
• The skill can still create accurate implementations

---

Issue: Pattern Conflict Not Resolved

Symptoms

• Implementation doesn't match expected pattern
• User wasn't asked about conflict

Cause

Conflict detection might have missed the pattern, or user guidance wasn't properly incorporated.

Solution

1. Re-check patterns manually

   Check /design-intent/patterns/ for [pattern-name].md

2. Explicitly state the conflict

   "This implementation uses 8px padding, but our card-spacing pattern
   specifies 12px. Should I update this to match the pattern?"

3. After resolution, update implementation

Prevention

Always verify pattern check completed before implementation:

Existing patterns to consider:
- [list should appear here]

If list is empty or missing patterns you know exist, check file paths.

---

Issue: Custom Component Not Documented

Symptoms

• Created a custom component but no documentation header
• Later can't find why component was created

Cause

Forgot to add documentation header during implementation.

Solution

Add the standard documentation header:

/**
 * CUSTOM COMPONENT: ComponentName
 * Base: @fluentui/react-components/BaseComponent
 * Reason: [Why standard component wasn't sufficient]
 * Created: YYYY-MM-DD
 */

Prevention

The skill should automatically add this header when creating custom components. If it doesn't, remind:

"Please add the standard custom component documentation header."

---

Issue: Responsive Behavior Missing

Symptoms

• Implementation looks good on desktop
• Breaks on mobile viewports

Cause

Responsive breakpoints not considered during implementation.

Solution

1. Check constitution Article III - Responsive Design Mandate

2. Add breakpoint handling:

   // Standard breakpoints
   // Mobile: < 768px
   // Desktop: >= 768px

   @media (max-width: 767px) {
     // Mobile styles
   }

3. Common responsive patterns:

• Sidebar collapses to hamburger menu
• Grid columns reduce (3 → 2 → 1)
• Stack horizontal layouts vertically
• Reduce padding/margins

Prevention

For each section, explicitly note responsive behavior:

### Responsiveness
- < 768px: [mobile behavior]
- ≥ 768px: [desktop behavior]

---

Issue: Wrong Component Selected

Symptoms

• Used custom component when Fluent UI had one
• Used wrong Fluent UI component variant

Cause

Didn't check framework components first (Article II violation).

Solution

1. Check Fluent UI first

• Query fluent-pilot MCP if available
• Check react.fluentui.dev documentation

2. If custom still needed, document why:

   /**
    * CUSTOM COMPONENT: CustomSelect
    * Base: @fluentui/react-components/Dropdown
    * Reason: Needed async search with debounce, Dropdown doesn't support
    */

Prevention

Follow component selection priority: 1. Existing project components 2. Fluent UI components 3. Custom components (document reason)

---

Issue: Visual Fidelity vs Pattern Conflict

Symptoms

• User wants exact visual match to reference
• Existing patterns dictate different values

Cause

Unclear guidance on which takes precedence.

Solution

Default behavior: Implement reference faithfully, then flag conflict.

Ask user:

This design uses [reference value], but our pattern specifies [pattern value].

Options:
1. Follow reference (creates exception)
2. Use pattern (adapts design)
3. Update pattern (makes reference the new standard)

Which approach?

Philosophy

• Visual fidelity is primary goal
• Patterns exist for consistency
• User decides when to break patterns
• Document exceptions

---

Issue: Session Context Lost

Symptoms

• New Claude session doesn't know about previous patterns
• Re-implementing things already decided

Cause

Design intent patterns weren't documented, or diary entry wasn't created.

Solution

1. Check for diary entries

   /design-intent/diary/session-YYYY-MM-DD.md

2. Check for patterns

   /design-intent/patterns/

3. If missing, recreate from code

• Review implemented components
• Extract patterns for documentation
• Run /save-patterns

Prevention

• Always run /diary at end of session
• Run /save-patterns after successful implementations
• Commit pattern files to git

---

Issue: Skill Not Auto-Invoking

Symptoms

• Provided Figma URL but skill didn't activate
• Asked to implement UI but got generic response

Cause

Context didn't trigger skill invocation.

Solution

Use explicit triggers:

• "Implement this UI from the screenshot"
• "Create React components matching this Figma design"
• /design-intent [reference] - Full 7-phase workflow

Trigger Keywords

The skill responds to:

• Figma URLs
• Screenshots/design images attached
• "implement this UI"
• "implement this design"
• "create components from this"
• "match this visual reference"

---

Getting Help

If issues persist:

1. Check constitution at /design-intent/memory/constitution.md 2. Review existing patterns in /design-intent/patterns/ 3. Create a diary entry documenting the issue 4. Consider running /save-patterns to capture what's working

Detailed Workflow

Complete implementation process for the Design Intent Specialist skill.

Table of Contents

• Phase 1: Mandatory Design Intent Check
• Phase 2: Visual Reference Analysis
• Phase 3: Section Decomposition
• Phase 4: Implementation
• Phase 5: Conflict Resolution
• Phase 6: Iteration Support
• Constitution Integration
• Output Expectations

---

Phase 1: Mandatory Design Intent Check

This step is non-negotiable before any implementation.

Steps

1. Locate patterns directory

   /design-intent/patterns/

2. Read all pattern files

• Scan for .md files in the patterns directory
• Extract key design decisions from each

3. Report findings

   Existing patterns to consider:
   - page-header-template.md: Back navigation + responsive action buttons
   - card-hover-states.md: 200ms ease transitions, subtle elevation
   - spacing-sections.md: 48px between major sections

4. Note potential impacts

• Which patterns might apply to this implementation
• Potential conflicts to watch for

If No Patterns Exist

Report: "No existing design intent patterns found. Will establish new patterns based on this implementation."

---

Phase 2: Visual Reference Analysis

Reference Types

Analysis Checklist

For each reference, extract:

• [ ] Layout structure - Grid, flexbox, positioning
• [ ] Color palette - Primary, secondary, accent, backgrounds
• [ ] Typography - Headings, body, captions, weights
• [ ] Spacing - Margins, padding, gaps
• [ ] Component types - Buttons, cards, inputs, etc.
• [ ] Interactive states - Hover, focus, active, disabled
• [ ] Responsive hints - Breakpoint behaviors if visible

Conflict Detection

Compare reference elements against existing patterns:

Reference: 8px card padding
Existing pattern: 12px card padding (card-spacing.md)
→ FLAG for user guidance

---

Phase 3: Section Decomposition

For complex/full-page designs, break into manageable sections.

Standard Sections

1. Header

• Navigation elements
• Branding/logo
• User controls (profile, settings)
• Search functionality

2. Side Navigation (if present)

• Menu items and hierarchy
• Active/inactive states
• Collapse/expand behavior
• Icons and labels

3. Main Content

• Primary content area
• Data display (tables, cards, lists)
• Forms and inputs
• Empty/loading states

4. Footer (if present)

• Secondary links
• Metadata
• Legal/copyright

Per-Section Analysis

For each section, document:

## Section: Header

### Layout
- Flexbox row, space-between
- Fixed height: 64px
- Full width with 24px horizontal padding

### Spacing
- Gap between nav items: 16px
- Logo margin-right: 32px

### Typography
- Logo: 20px, semibold
- Nav items: 14px, regular

### Responsiveness
- < 768px: Hamburger menu
- ≥ 768px: Horizontal nav

### Visual Treatment
- Background: neutral-white
- Border-bottom: 1px neutral-stroke
- Nav hover: primary-brand underline

---

Phase 4: Implementation

Implementation Order

1. Structure first - HTML/JSX skeleton 2. Layout second - Flexbox/Grid positioning 3. Spacing third - Margins, padding, gaps 4. Typography fourth - Font sizes, weights 5. Colors fifth - Background, text, borders 6. Interactivity last - Hover, transitions, animations

Component Selection Priority

1. Existing project components (from /design-intent/patterns/)
      ↓ not available
2. Fluent UI components (query MCP if available)
      ↓ not suitable
3. Custom component (document with header comment)

Custom Component Documentation

When creating custom components:

/**
 * CUSTOM COMPONENT: CustomMetricCard
 * Base: @fluentui/react-components/Card
 * Reason: Required gradient background and custom icon positioning
 * Created: YYYY-MM-DD
 *
 * Design Reference: dashboard-v2.png, top-left KPI section
 */

export const CustomMetricCard: React.FC<CustomMetricCardProps> = ({
  // ...
}) => {
  // Implementation
};

---

Phase 5: Conflict Resolution

Resolution Flow

Conflict Detected
      ↓
Implement Reference (what user requested)
      ↓
Flag Conflict Clearly
      ↓
Ask User for Guidance
      ↓
Document Decision

Conflict Report Template

## Design Conflict Detected

**Element**: Card padding
**Reference**: 8px padding
**Existing Pattern**: 12px padding (card-spacing.md)

### Options

1. **Follow reference** - Use 8px for this implementation
2. **Use existing pattern** - Adapt to 12px padding
3. **Update pattern** - Make 8px the new standard

### Recommendation

[Recommendation based on context]

**Which approach would you prefer?**

After User Decision

• If updating pattern: Modify the pattern file
• If exception: Document why in code comments
• If new standard: Create new pattern file

---

Phase 6: Iteration Support

Vibe Coding Flow

Support rapid refinement cycles:

1. User feedback - "Make the spacing tighter" 2. Quick adjustment - Modify specific values 3. Show result - Display updated implementation 4. Repeat - Until user satisfied

Common Refinement Requests

Track Changes

Keep a mental note of refinements for potential pattern documentation:

Original: 16px gap
Refined to: 12px gap
User comment: "Tighter feels better for data-dense views"
→ Consider documenting as pattern for data-dense layouts

---

Constitution Integration

Ensure implementation follows project constitution:

• Article I (Simplicity) - Start simple, add complexity only if needed
• Article II (Framework-first) - Use Fluent UI before custom solutions
• Article III (Responsive) - Mobile-first, all breakpoints
• Article IV (Prototype) - Mock data, happy paths
• Article V (Feature-first) - Features define what, references define how
• Article VI (UI Quality) - Microinteractions, visual hierarchy
• Article VII (Documentation) - Document proven patterns

---

Output Expectations

Deliver:

1. Working implementation - Functional React components 2. Accurate visuals - Matches reference closely 3. Responsive behavior - Works across breakpoints 4. Pattern consistency - Uses established patterns 5. Conflict documentation - Clear notes on any deviations 6. Custom component tracking - Documented in code headers