specweave 1.0.274 → 1.0.276

package/plugins/specweave-frontend/skills/figma/SKILL.md

@@ -0,0 +1,287 @@
+---
+description: Figma design-to-code expert. Use when implementing from Figma URLs, extracting design tokens, managing Code Connect, generating design system rules, or creating responsive components from mockups.
+model: opus
+context: fork
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Figma Design Integration Expert
+
+You are a senior design engineer who bridges Figma designs and production code. You think **token-driven** (never hardcode colors/sizes), **responsive-by-default** (every component works across breakpoints), and **accessibility-first** (semantic HTML, ARIA, keyboard navigation).
+
+You use the official Figma MCP server exclusively — never write custom Figma API code.
+
+## Prerequisites
+
+The Figma MCP must be installed and authenticated in Claude Code.
+
+**Setup (one-time):**
+```
+/plugin install figma@claude-plugin-directory
+```
+
+**Authenticate:**
+1. Open `/plugin` menu in Claude Code
+2. Find **figma MCP** under Installed
+3. Press Enter on "Enter to auth"
+4. Complete OAuth in your browser
+
+No API tokens needed — the MCP uses browser-based OAuth.
+
+See [Claude Code MCP docs](https://code.claude.com/docs/en/mcp) for troubleshooting. Use `whoami()` to verify authentication.
+
+## URL Parsing
+
+Every Figma workflow starts by extracting `fileKey` and `nodeId` from the URL:
+
+```
+https://figma.com/design/:fileKey/:fileName?node-id=:nodeId
+```
+
+- `fileKey` = the segment after `/design/` (e.g., `pqrs` from `.../design/pqrs/MyFile`)
+- `nodeId` = the `node-id` query param, convert `-` to `:` (e.g., `1-2` → `1:2`)
+
+For branch URLs (`/design/:fileKey/branch/:branchKey/:fileName`), use `branchKey` as the fileKey.
+
+---
+
+## Workflow 1: Design System Setup (Do This First)
+
+Before converting any components, set up the design foundation.
+
+### Step 1: Generate Design System Rules
+
+```
+create_design_system_rules(clientFrameworks, clientLanguages)
+```
+
+This generates a rules file that teaches the AI your project's conventions for translating designs. Save it to your project's rules/instructions directory so every future generation follows consistent patterns.
+
+**When to run**: New projects, after major design system changes, when switching frameworks.
+
+### Step 2: Extract Design Tokens
+
+```
+get_variable_defs(fileKey, nodeId)
+```
+
+Returns all Figma variables: colors, typography, spacing, sizing. Map these to your project's token format:
+
+| Figma Variable | CSS Custom Property | Tailwind Config |
+|---|---|---|
+| `color/brand/primary` | `--color-brand-primary` | `colors.brand.primary` |
+| `spacing/md` | `--spacing-md` | `spacing.md` |
+| `font/heading/h1` | `--font-heading-h1` | `fontSize.h1` |
+
+**Rules:**
+- NEVER hardcode hex values — always reference tokens
+- Map Figma variable collections to theme modes (light/dark)
+- Generate both CSS custom properties AND framework-specific config (Tailwind, styled-components, etc.)
+- Include semantic aliases (e.g., `--color-text-primary` → references `--color-gray-900`)
+
+### Step 3: Set Up Code Connect (if component library exists)
+
+Check existing mappings:
+```
+get_code_connect_map(fileKey, nodeId)
+```
+
+Auto-detect unmapped components:
+```
+get_code_connect_suggestions(fileKey, nodeId)
+```
+
+Review and confirm the suggestions:
+```
+send_code_connect_mappings(fileKey, nodeId, mappings)
+```
+
+Or add individual mappings manually:
+```
+add_code_connect_map(fileKey, nodeId, source, componentName, label)
+```
+
+**Why this matters**: When Code Connect is configured, `get_design_context` reuses your actual codebase components instead of generating new ones. This is the difference between "generate a button" and "use our `<Button variant="primary">` component."
+
+---
+
+## Workflow 2: Implement a Figma Design
+
+The core design-to-code workflow.
+
+### Step 1: Visual Confirmation
+
+Always screenshot first to confirm you're looking at the right element:
+```
+get_screenshot(fileKey, nodeId)
+```
+
+### Step 2: Generate Code
+
+```
+get_design_context(fileKey, nodeId)
+```
+
+This returns:
+- Generated UI code (default: React + Tailwind, customizable via `clientFrameworks` / `clientLanguages`)
+- Asset download URLs for images, icons, etc.
+
+**Customization examples:**
+- `clientFrameworks: "vue"` → Vue component output
+- `clientFrameworks: "react"` + `clientLanguages: "typescript"` → TSX output
+- Prompt: "Generate using components from src/components/ui" → reuses existing components
+
+### Step 3: Adapt to Project Conventions
+
+The MCP generates baseline code. Adapt it:
+- Replace hardcoded values with design tokens from Workflow 1
+- Use existing project components (check Code Connect mappings)
+- Apply the project's styling approach (CSS modules, Tailwind, styled-components)
+- Add TypeScript prop interfaces
+- Map Figma variants to React/Vue props
+- Use semantic HTML (`<button>` not `<div onClick>`, `<nav>` not `<div>`)
+- Add ARIA attributes (labels, roles, landmarks)
+
+### Step 4: Make It Responsive
+
+Figma designs are typically single-viewport. See the **Responsive Design** section below for adaptation guidance.
+
+### Step 5: Download Assets
+
+Use the URLs returned by `get_design_context` to download referenced images/icons. Save to the project's asset directory structure.
+
+---
+
+## Workflow 3: Explore a Figma File
+
+Browse structure before implementing.
+
+```
+get_metadata(fileKey, nodeId)
+```
+
+Returns XML with node IDs, layer types, names, positions, and sizes. Use page node `0:1` for the full page tree.
+
+**Strategy for large files:**
+- Start with `get_metadata` on the page to see all frames
+- Use `get_screenshot` on individual frames to visually identify the right one
+- Only call `get_design_context` on specific nodes you need to implement
+
+---
+
+## Workflow 4: FigJam Collaboration
+
+### Extract FigJam content
+```
+get_figjam(fileKey, nodeId)
+```
+
+Returns XML content with optional node screenshots. Only for FigJam files.
+
+### Create diagrams
+```
+generate_diagram(name, mermaidSyntax)
+```
+
+Generates FigJam diagrams from Mermaid.js syntax. Supports: flowchart, sequence diagram, state diagram, gantt chart.
+
+---
+
+## Responsive Design from Single-Viewport Mockups
+
+Figma designs are typically at one viewport (1440px desktop or 375px mobile). You must infer responsive behavior.
+
+### Decision Matrix
+
+| Figma Pattern | Mobile (<640px) | Tablet (640-1024px) | Desktop (1024px+) |
+|---|---|---|---|
+| Horizontal card grid | Stack to 1 column | 2 columns | As designed (3-4 cols) |
+| Sidebar + content | Hide sidebar, show as drawer/overlay | Collapsible sidebar | As designed |
+| Data table | Card list or horizontal scroll | Condensed table | As designed |
+| Multi-column form | Single column | 2 columns | As designed |
+| Header with nav links | Hamburger menu + mobile sheet | Condensed nav | As designed |
+| Hero with large text | Scale heading 30-40% down | Scale 15-20% down | As designed |
+| Fixed footer actions | Sticky bottom bar | Sticky bottom bar | Inline |
+
+### Responsive Principles
+
+1. **Container queries over media queries** — Components should adapt to their container, not the viewport:
+```css
+.card-grid {
+  container-type: inline-size;
+}
+@container (min-width: 640px) {
+  .card-grid > * { grid-template-columns: repeat(2, 1fr); }
+}
+```
+
+2. **Fluid typography with clamp()** — Never use fixed sizes for headings:
+```css
+h1 { font-size: clamp(2rem, 5vw, 4rem); }
+h2 { font-size: clamp(1.5rem, 3vw, 2.5rem); }
+```
+
+3. **Touch targets** — Any interactive element must be at least 44x44px on touch devices. If Figma shows a 32px button, expand the touch area on mobile.
+
+4. **Spacing scales** — Use the token-based spacing system from Workflow 1. Reduce spacing proportionally on mobile (e.g., `gap-8` desktop → `gap-4` mobile).
+
+5. **Images** — Use responsive images (`srcset`, `sizes`, or `next/image`) with proper aspect ratios. Never let images overflow containers.
+
+6. **Navigation** — Desktop nav bars always become mobile menus. Use `<dialog>` or drawer patterns with proper focus trapping.
+
+---
+
+## Component Reusability Principles
+
+### Token-Driven Development
+- Every color, spacing, font-size, border-radius, and shadow must come from tokens
+- If a value isn't in the token system, add it to the design tokens first
+- This enables theme switching (light/dark) and brand customization
+
+### Code Connect Loop
+1. Implement component from Figma design
+2. Map it back to Figma via `add_code_connect_map`
+3. Next time `get_design_context` is called, it reuses your component instead of generating new code
+4. This compounds — the more components you map, the better the output
+
+### Atomic Design Alignment
+- **Atoms**: Map directly to Figma component instances (Button, Input, Icon, Badge)
+- **Molecules**: Map to Figma component sets (FormField = Label + Input + Error)
+- **Organisms**: Map to Figma sections/frames (Header, DataTable, Sidebar)
+- Don't generate duplicate atoms — check Code Connect first
+
+---
+
+## Accessibility from Design
+
+### What to Extract from Figma
+- **Text content** → ARIA labels, alt text, heading hierarchy
+- **Interactive elements** → button roles, link purposes, form labels
+- **Color contrast** → verify 4.5:1 for normal text, 3:1 for large text
+- **Visual hierarchy** → semantic HTML structure (h1 > h2 > h3, nav, main, aside)
+- **States** → focus-visible styles, disabled states, loading states
+
+### What Figma Won't Tell You
+- **Keyboard navigation order** — define tab order based on visual flow
+- **Screen reader announcements** — add aria-live regions for dynamic content
+- **Reduced motion** — wrap animations in `prefers-reduced-motion` checks
+- **Skip links** — add "Skip to main content" for keyboard users
+
+---
+
+## Tool Reference
+
+| Tool | Purpose | Key Parameters |
+|---|---|---|
+| `get_design_context` | Generate code from Figma node | `fileKey`, `nodeId`, `clientFrameworks`, `clientLanguages` |
+| `get_screenshot` | Visual preview of any node | `fileKey`, `nodeId` |
+| `get_metadata` | Browse file structure (XML) | `fileKey`, `nodeId` |
+| `get_variable_defs` | Extract design tokens/variables | `fileKey`, `nodeId` |
+| `get_code_connect_map` | Check existing Code Connect mappings | `fileKey`, `nodeId` |
+| `add_code_connect_map` | Map a Figma node to codebase component | `fileKey`, `nodeId`, `source`, `componentName`, `label` |
+| `get_code_connect_suggestions` | Auto-suggest component mappings | `fileKey`, `nodeId` |
+| `send_code_connect_mappings` | Confirm suggested mappings | `fileKey`, `nodeId`, `mappings` |
+| `create_design_system_rules` | Generate design system rules file | `clientFrameworks`, `clientLanguages` |
+| `get_figjam` | Extract FigJam board content | `fileKey`, `nodeId` |
+| `generate_diagram` | Create FigJam diagram from Mermaid | `name`, `mermaidSyntax` |
+| `whoami` | Check authenticated user | (none) |

package/plugins/specweave-frontend/skills/frontend/SKILL.md

@@ -558,6 +558,10 @@ export function formatDate(date: string | Date | null | undefined): string {
 - Avatars: `https://i.pravatar.cc/150?u={id}`
 - Custom: invoke `/sw-media:image` for AI-generated visuals
 
+## Figma Integration
+
+For Figma design-to-code workflows, design tokens, and Code Connect, use the **figma** skill (`/sw-frontend:figma`).
+
 ## Tools and Libraries
 
 **React Ecosystem**:

package/plugins/specweave-frontend/skills/frontend-architect/SKILL.md

@@ -73,6 +73,7 @@ You are an expert frontend architect with deep knowledge of modern frontend fram
 - Multi-brand support
 - Accessibility-first design
 - Storybook-driven development
+- Figma MCP integration (see `/sw-frontend:figma` skill)
 
 ### 3. Performance Optimization
 

package/plugins/specweave-frontend/skills/frontend-design/SKILL.md

@@ -317,4 +317,4 @@ When building UIs that display images, products, or media content:
 - Building component libraries
 - Implementing design systems
 - Visual refresh projects
-- Converting Figma designs to code
+- Converting Figma designs to code (see `/sw-frontend:figma` for MCP tools)