@codeharbor/agent-playbook 0.1.0 → 0.1.2

package/skills/figma-designer/README.md

@@ -0,0 +1,222 @@
+# Figma Designer Skill
+
+> "Transform Figma designs into implementation-ready specifications with pixel-perfect accuracy"
+
+## Overview
+
+This skill analyzes Figma designs through the Figma MCP server and generates detailed PRDs with precise visual specifications. It extracts design tokens, component specifications, and layout information that developers can implement directly.
+
+## Installation
+
+The skill should be symbolically linked to your Claude Code skills directory:
+
+```bash
+ln -s ~/agent-playbook/skills/figma-designer/SKILL.md ~/.claude/skills/figma-designer.md
+```
+
+## Prerequisites
+
+### Figma MCP Server
+
+Ensure the Figma MCP server is connected and accessible:
+
+```bash
+# Check if Figma MCP is available
+mcp-list
+```
+
+If not available, install from: https://github.com/modelcontextprotocol/servers
+
+Required Figma MCP tools:
+- `figma_get_file` - Get file metadata
+- `figma_get_nodes` - Get node details
+- `figma_get_components` - Get component information
+
+### Figma Access Token
+
+You need a Figma access token with appropriate permissions:
+
+```bash
+# Set environment variable
+export FIGMA_ACCESS_TOKEN="your_token_here"
+```
+
+## Usage
+
+### Basic Usage
+
+Provide a Figma link or ask to analyze a design:
+
+```
+You: Analyze this Figma design: https://www.figma.com/file/abc123/My-Design
+```
+
+The skill will automatically:
+1. Extract the file key from the URL
+2. Fetch design data via Figma MCP
+3. Analyze design tokens (colors, typography, spacing)
+4. Extract component hierarchy
+5. Generate visual specifications
+
+### With PRD Generation
+
+```
+You: Create a PRD from this Figma design: [URL]
+```
+
+Generates a complete 4-file PRD in `docs/`:
+- `{feature}-notes.md` - Design decisions
+- `{feature}-task-plan.md` - Implementation tasks
+- `{feature}-prd.md` - Product requirements
+- `{feature}-tech.md` - Technical specifications
+
+## What Gets Extracted
+
+### Design Tokens
+
+| Category | What's Extracted |
+|----------|-----------------|
+| **Colors** | Hex/RGBA values for primary, secondary, semantic colors |
+| **Typography** | Font families, sizes, weights, line heights, letter spacing |
+| **Spacing** | Padding, margin, gap values (typically 4/8/12/16px scale) |
+| **Borders** | Corner radius, border widths |
+| **Shadows** | Offset, blur, spread, color values |
+| **Icons** | Names, sizes, colors |
+| **Images** | URLs, dimensions, fit modes |
+
+### Component Analysis
+
+For each component found in the design:
+- Props (size, variant, state)
+- Layout (flex direction, alignment, gap, padding)
+- Styles (fill, stroke, effects)
+- Content (text, icons, images)
+- Constraints (responsive behavior)
+
+## Output Examples
+
+### Visual Specification
+
+```markdown
+## Screen: Login
+
+### Layout Structure
+```
+┌─────────────────────────────────────────┐
+│           Logo                          [Icon] │
+├─────────────────────────────────────────┤
+│  Welcome back                            │
+│  Sign in to continue                    │
+├─────────────────────────────────────────┤
+│  Email                    [✓]           │
+│  ┌────────────────────────────────┐    │
+│  └────────────────────────────────┘    │
+├─────────────────────────────────────────┤
+│  Password                [👁️]           │
+│  ┌────────────────────────────────┐    │
+│  └────────────────────────────────┘    │
+├─────────────────────────────────────────┤
+│         Forgot password?               │
+├─────────────────────────────────────────┤
+│  [      Sign In        ]               │
+└─────────────────────────────────────────┘
+```
+
+### Design Tokens
+
+```typescript
+// tokens.ts
+export const colors = {
+  primary: '#007AFF',
+  background: '#FFFFFF',
+  surface: '#F5F5F7',
+  textPrimary: '#1C1C1E',
+  textSecondary: '#8E8E93',
+};
+
+export const typography = {
+  displayLarge: {
+    fontSize: 28,
+    fontWeight: '700',
+    lineHeight: 34,
+  },
+  // ...
+};
+
+export const spacing = {
+  xs: 4,
+  sm: 8,
+  md: 12,
+  lg: 16,
+  xl: 24,
+  2xl: 32,
+};
+```
+
+## Integration with Other Skills
+
+### Typical Workflow
+
+```
+Figma URL → figma-designer → Visual Specs
+                                ↓
+                           prd-planner → PRD
+                                ↓
+                           implementation → Code
+                                ↓
+                           code-reviewer → Quality Check
+```
+
+### Auto-Triggers
+
+After figma-designer completes:
+- `prd-planner` (ask first) - Further refine PRD with 4-file pattern
+- `self-improving-agent` (background) - Learn design patterns
+- `session-logger` (auto) - Save design analysis session
+
+## Platform Support
+
+The skill generates specifications for:
+- **React Native** - Uses StyleSheet with exact pixel values
+- **React/Web** - CSS values with proper units
+- **SwiftUI** - Native SwiftUI values
+
+## Examples
+
+### Example 1: Quick Analysis
+
+```
+You: What are the colors used in this design?
+```
+
+Returns a table of all colors with their usage contexts.
+
+### Example 2: Component Spec
+
+```
+You: Extract the button component specifications
+```
+
+Returns props interface, variants, and all states.
+
+### Example 3: Full PRD
+
+```
+You: Create a complete PRD from this Figma file
+```
+
+Generates 4-file PRD with all visual specifications.
+
+## Tips
+
+1. **Organize Figma files** with clear naming conventions for better extraction
+2. **Use components** for reusable elements to get proper component specs
+3. **Set up auto-layout** in Figma for accurate layout information
+4. **Document prototypes** to include interaction states
+5. **Provide context** about target platform for platform-specific output
+
+## See Also
+
+- [SKILL.md](./SKILL.md) - Full skill definition with all templates
+- [prd-planner](../prd-planner/) - Create PRDs from design specs
+- [architecting-solutions](../architecting-solutions/) - Technical architecture

package/skills/figma-designer/SKILL.md

@@ -0,0 +1,407 @@
+---
+name: figma-designer
+description: Analyzes Figma designs and generates implementation-ready PRDs with detailed visual specifications. Use when user provides Figma link or uploads design screenshots. Requires Figma MCP server connection.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, AskUserQuestion
+hooks:
+  after_complete:
+    - trigger: prd-planner
+      mode: ask_first
+      condition: prd_generated
+      reason: "Further refine PRD with 4-file pattern"
+    - trigger: self-improving-agent
+      mode: background
+      reason: "Learn design patterns for future reference"
+    - trigger: session-logger
+      mode: auto
+      reason: "Save design analysis session"
+---
+
+# Figma Designer
+
+> "Transform Figma designs into implementation-ready specifications with pixel-perfect accuracy"
+
+## Overview
+
+This skill analyzes Figma designs through the Figma MCP server and generates detailed PRDs with precise visual specifications. It extracts design tokens, component specifications, and layout information that developers can implement directly.
+
+## Prerequisites
+
+### Figma MCP Server
+
+Ensure the Figma MCP server is connected and accessible:
+
+```bash
+# Check if Figma MCP is available
+mcp-list
+```
+
+If not available, install from: https://github.com/modelcontextprotocol/servers
+
+Required Figma MCP tools:
+- `figma_get_file` - Get file metadata
+- `figma_get_nodes` - Get node details
+- `figma_get_components` - Get component information
+
+## When This Skill Activates
+
+Activates when you:
+- Provide a Figma link (`https://www.figma.com/file/...`)
+- Upload a design screenshot and mention "Figma"
+- Say "analyze this design" or "extract design specs"
+- Ask to "create PRD from Figma"
+
+## Design Analysis Workflow
+
+### Phase 1: Fetch Design Data
+
+```yaml
+Input: Figma URL or File Key
+  ↓
+Extract File Key from URL
+  ↓
+Call figma_get_file to get metadata
+  ↓
+Call figma_get_nodes to get design tree
+  ↓
+Parse frame, component, and text nodes
+```
+
+### Phase 2: Extract Design Tokens
+
+Create a comprehensive design token inventory:
+
+```typescript
+// Design Token Structure
+interface DesignTokens {
+  colors: {
+    primary: string[];
+    secondary: string[];
+    neutral: string[];
+    semantic: {
+      success: string;
+      warning: string;
+      error: string;
+      info: string;
+    };
+  };
+  typography: {
+    fontFamilies: Record<string, string>;
+    fontSizes: Record<string, number>;
+    fontWeights: Record<string, number>;
+    lineHeights: Record<string, number>;
+    letterSpacing: Record<string, number>;
+  };
+  spacing: {
+    scale: number;  // 4, 8, 12, 16, etc.
+    values: Record<string, number>;
+  };
+  borders: {
+    radii: Record<string, number>;
+    widths: Record<string, number>;
+  };
+  shadows: Array<{
+    name: string;
+    values: string[];
+  }>;
+}
+```
+
+### Phase 3: Analyze Component Hierarchy
+
+```
+File
+├── Frames (Pages/Screens)
+│   ├── Component Instances
+│   │   ├── Primary Button
+│   │   ├── Input Field
+│   │   └── Card
+│   └── Text Layers
+│       ├── Headings
+│       ├── Body
+│       └── Labels
+```
+
+For each component, extract:
+- **Props**: Size, variant, state
+- **Layout**: Flex direction, alignment, gap, padding
+- **Styles**: Fill, stroke, effects
+- **Content**: Text content, icons, images
+- **Constraints**: Responsive behavior
+
+### Phase 4: Generate Visual Specifications
+
+Use this template for each screen:
+
+```markdown
+## Screen: [Screen Name]
+
+### Layout Structure
+
+```
+┌─────────────────────────────────────────┐
+│ [Header/Nav]                              │
+├─────────────────────────────────────────┤
+│                                         │
+│  [Main Content]                          │
+│  ┌───────────┐  ┌───────────┐         │
+│  │  Card 1   │  │  Card 2   │         │
+│  └───────────┘  └───────────┘         │
+│                                         │
+├─────────────────────────────────────────┤
+│ [Footer]                                 │
+└─────────────────────────────────────────┘
+```
+
+### Design Specifications
+
+#### Colors
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| Primary | `#007AFF` | Primary buttons, links |
+| Background | `#FFFFFF` | Screen background |
+| Surface | `#F5F5F7` | Cards, sections |
+| Text Primary | `#1C1C1E` | Headings, body |
+| Text Secondary | `#8E8E93` | Captions, labels |
+
+#### Typography
+
+| Style | Font | Size | Weight | Line Height | Letter Spacing |
+|-------|------|------|--------|------------|---------------|
+| Display Large | SF Pro Display | 28px | Bold (700) | 34px | -0.5px |
+| Heading 1 | SF Pro Display | 24px | Bold (700) | 32px | -0.3px |
+| Heading 2 | SF Pro Display | 20px | Semibold (600) | 28px | -0.2px |
+| Body Large | SF Pro Text | 17px | Regular (400) | 24px | -0.4px |
+| Body | SF Pro Text | 15px | Regular (400) | 22px | -0.3px |
+| Caption | SF Pro Text | 13px | Regular (400) | 18px | -0.1px |
+
+#### Spacing
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Icon padding |
+| sm | 8px | Tight spacing |
+| md | 12px | Card padding |
+| lg | 16px | Section spacing |
+| xl | 24px | Large gaps |
+| 2xl | 32px | Page margins |
+
+#### Component: Primary Button
+
+```typescript
+interface PrimaryButtonProps {
+  size?: 'small' | 'medium' | 'large';
+  variant?: 'primary' | 'secondary' | 'tertiary';
+  disabled?: boolean;
+}
+
+// Sizes
+size.small = {
+  height: 32px,
+  paddingHorizontal: 12px,
+  fontSize: 15,
+  iconSize: 16,
+}
+
+size.medium = {
+  height: 40px,
+  paddingHorizontal: 16px,
+  fontSize: 15,
+  iconSize: 20,
+}
+
+size.large = {
+  height: 48px,
+  paddingHorizontal: 24px,
+  fontSize: 17,
+  iconSize: 24,
+}
+
+// Variants
+variant.primary = {
+  backgroundColor: '#007AFF',
+  color: '#FFFFFF',
+}
+
+variant.secondary = {
+  backgroundColor: '#F5F5F7',
+  color: '#007AFF',
+}
+
+variant.tertiary = {
+  backgroundColor: 'transparent',
+  color: '#007AFF',
+}
+```
+
+#### Constraints & Responsive Behavior
+
+| Element | Constraints | Responsive Behavior |
+|---------|-------------|---------------------|
+| Header | Left, Right, Top | Sticky on scroll |
+| Sidebar | Left, Top, Bottom | Collapses to drawer on mobile |
+| Content | Left, Right (16px) | Full width on mobile |
+
+### Interaction States
+
+| Element | Default | Hover | Pressed | Disabled |
+|---------|---------|-------|--------|----------|
+| Primary Button | opacity: 1 | opacity: 0.8 | opacity: 0.6 | opacity: 0.4 |
+| Icon Button | opacity: 1 | background: rgba(0,0,0,0.05) | background: rgba(0,0,0,0.1) | opacity: 0.3 |
+| Card | shadow: sm | shadow: md | - | opacity: 0.6 |
+```
+
+## Output Formats
+
+### Option 1: Full PRD (Recommended)
+
+Generates a complete 4-file PRD:
+- `docs/{feature}-notes.md` - Design decisions
+- `docs/{feature}-task-plan.md` - Implementation tasks
+- `docs/{feature}-prd.md` - Product requirements
+- `docs/{feature}-tech.md` - Technical specifications
+
+### Option 2: Visual Spec Document
+
+Generates a design specification document:
+```
+docs/{feature}-design-spec.md
+```
+
+### Option 3: Component Library
+
+For design systems, generates:
+```
+src/components/
+├── Button/
+│   ├── Button.tsx
+│   ├── Button.test.tsx
+│   └── Button.stories.tsx
+├── Input/
+├── Card/
+└── tokens.ts
+```
+
+## Quick Reference: Design Token Categories
+
+### Always Extract These
+
+| Category | What to Extract | Why |
+|----------|----------------|-----|
+| **Colors** | Hex/RGBA values | Theme consistency |
+| **Typography** | Font family, size, weight, spacing | Text hierarchy |
+| **Spacing** | Padding, margin, gap values | Layout alignment |
+| **Borders** | Radius, width values | Shape consistency |
+| **Shadows** | Offset, blur, spread, color | Depth perception |
+| **Icons** | Name, size, color | Visual consistency |
+| **Images** | URL, dimensions, fit mode | Asset management |
+
+## Design Review Checklist
+
+Before generating PRD, verify:
+
+- [ ] All screens are accounted for
+- [ ] Design tokens are extracted
+- [ ] Component variants are documented
+- [ ] Responsive behavior is specified
+- [ ] Interaction states are defined
+- [ ] Accessibility (WCAG) is considered
+  - [ ] Color contrast ratio ≥ 4.5:1
+  - [ ] Touch targets ≥ 44x44px
+  - [ ] Focus indicators visible
+
+## Frame Analysis Template
+
+For each frame/screen in the Figma file:
+
+```markdown
+## Frame: {Frame Name}
+
+### Purpose
+{What this screen does}
+
+### Elements
+
+| Element | Type | Styles | Props |
+|---------|------|--------|-------|
+| {Name} | {Component/Text/Vector} | {css} | {props} |
+| {Name} | {Component/Text/Vector} | {css} | {props} |
+
+### Layout
+- Container: {width, height, fill}
+- Position: {absolute/relative}
+- Constraints: {left, right, top, bottom}
+- Auto Layout: {direction, spacing, padding, alignment}
+
+### Content Hierarchy
+1. {Primary element}
+2. {Secondary element}
+3. {Tertiary element}
+
+### Notes
+{Any special considerations}
+```
+
+## Integration with Other Skills
+
+### Typical Workflow
+
+```
+Figma URL → figma-designer → Visual Specs
+                                ↓
+                           prd-planner → PRD
+                                ↓
+                           implementation → Code
+                                ↓
+                           code-reviewer → Quality Check
+```
+
+### Handoff to Development
+
+After generating specifications:
+
+```markdown
+## Developer Handoff
+
+### Design Files
+- Figma: {url}
+- Design Spec: {link}
+
+### Design Tokens
+- Generated: `tokens.ts`
+- Color palette: `colors.ts`
+- Typography: `typography.ts`
+
+### Component Library
+- Storybook: {url}
+- Component docs: {link}
+
+### Assets
+- Icons: {folder}
+- Images: {folder}
+- Exports: {format}
+```
+
+## Best Practices
+
+### DO
+
+✅ Extract exact pixel values for critical dimensions
+✅ Document component variants and states
+✅ Include responsive breakpoints
+✅ Note any platform differences (iOS vs Android)
+✅ Include accessibility considerations
+✅ Export design tokens as constants
+
+### DON'T
+
+❌ Round spacing values (use exact 4px/8px/12px)
+❌ Ignore hover/focus states
+❌ Skip constraint behavior
+❌ Forget about empty states
+❌ Omit loading states
+❌ Assume platform defaults without verification
+
+## Examples and Platform Notes
+
+See `references/example-output.md` for a full sample output and platform-specific considerations.

package/skills/figma-designer/references/example-output.md

@@ -0,0 +1,86 @@
+# Example Output
+
+# Login Screen PRD
+
+## Visual Specification
+
+### Layout
+- Logo aligned left, icon aligned right
+- Form fields stacked with 16px vertical spacing
+- Primary button below the form
+
+### Technical Specs
+
+```text
+container: {
+  width: 100%,
+  height: 100%,
+  padding: 24px,
+  backgroundColor: #FFFFFF,
+  justifyContent: center,
+}
+
+input: {
+  height: 48,
+  paddingHorizontal: 16,
+  backgroundColor: #F5F5F7,
+  borderRadius: 12,
+  borderWidth: 1,
+  borderColor: transparent,
+}
+
+input:focus: {
+  borderColor: #007AFF,
+}
+```
+
+### Generated Code
+
+```typescript
+// LoginScreen.tsx
+export const LoginScreen = () => {
+  return (
+    <View style={styles.container}>
+      <Text style={styles.logo}>App Name</Text>
+      <Text style={styles.subtitle}>Welcome back</Text>
+      <TextInput placeholder="Email" style={styles.input} />
+      <TextInput placeholder="Password" secureTextEntry style={styles.input} />
+      <TouchableOpacity style={styles.button}>
+        <Text style={styles.buttonText}>Sign In</Text>
+      </TouchableOpacity>
+    </View>
+  );
+};
+```
+
+# Platform-Specific Considerations
+
+## React Native
+
+```typescript
+const styles = {
+  container: {
+    paddingHorizontal: 16,
+    paddingVertical: 16,
+    gap: 12,
+  },
+  borderRadius: 12,
+};
+```
+
+## Web (React)
+
+```css
+.button {
+  padding: 16px;
+  gap: 12px;
+  border-radius: 12px;
+}
+```
+
+## SwiftUI
+
+```swift
+.padding(16)
+.cornerRadius(12)
+```