moai-design-tools

# Design Tools Integration Specialist

Comprehensive design-to-code workflow guidance covering three major capabilities: Figma MCP (design fetching), Pencil MCP (visual rendering), and Pencil-to-code export (React/Tailwind generation).

## Default Design Style (shadcn/ui Nova)

When no specific design style is requested, use the **shadcn/ui Nova** preset with Notion-style neutral color scheme:

```
bunx --bun shadcn@latest create --preset "https://ui.shadcn.com/init?base=radix&style=nova&baseColor=neutral&theme=neutral&iconLibrary=hugeicons&font=noto-sans&menuAccent=bold&menuColor=default&radius=small&template=next&rtl=false" --template next
```

### Nova Style Configuration

| Property | Value | Description |
|----------|-------|-------------|
| Style | `nova` | Modern, clean design language |
| Base Color | `neutral` | Notion-style grayscale palette |
| Theme | `neutral` | Consistent neutral theming |
| Icon Library | `hugeicons` | Comprehensive icon set |
| Font | `noto-sans` | Clean, readable sans-serif |
| Radius | `small` | Subtle rounded corners |
| Menu Accent | `bold` | Strong menu highlighting |

### When to Use Default Style

Apply the Nova preset when:
- User requests "clean", "modern", or "minimalist" design without specifics
- No brand guidelines or design system specified
- Creating dashboards, admin panels, or productivity tools
- Building documentation or content-focused interfaces

## Quick Tool Selection

### Figma MCP - Design Context and Generation

Official Figma MCP integration via Remote MCP server (https://mcp.figma.com/mcp). Install with: `claude plugin install figma@claude-plugins-official`

Best For: Fetching design context from Figma files, extracting design tokens, generating new designs with Code-to-Canvas (generate_figma_design), accessing FigJam boards, and linking components to code with Code Connect.

Key Strengths: 16 official tools including read (get_design_context, get_variable_defs, get_screenshot, get_metadata), write (use_figma, generate_figma_design, create_new_file), Code Connect (get_code_connect_map, add_code_connect_map, get_code_connect_suggestions, send_code_connect_mappings), FigJam (get_figjam, generate_diagram), design system (search_design_system, create_design_system_rules), and utility (whoami). Write-to-canvas is currently free during beta.

Workflow: Install plugin → get_design_context → get_variable_defs → get_screenshot → Implement design → Verify against screenshot.

Context7 Library: /figma/docs

### Pencil MCP - Visual Design Rendering

Pencil MCP integration for creating and editing .pen design files (schema v2.9) with AI-assisted design generation. CLI: `@pencil.dev/cli` v0.2.4.

Best For: Rapid prototyping, visual design iterations, creating UI mockups from text descriptions, collaborative design discussions, visual proposals before implementation.

Key Strengths: Text-to-design conversion, batch design operations, style guide integration, visual preview without implementation, collaborative design workflow, component system with slots, design libraries (.lib.pen).

**Available Pencil MCP Tools (14 + 1 CLI-only):**

**Note:** .pen files are pure JSON (Git diffable, mergeable). 13 node types: Rectangle, Ellipse, Line, Polygon, Path, Text, Frame, Group, Note, Prompt, Context, IconFont, Ref.

| Tool | Purpose |
|------|---------|
| `batch_design` | Create, modify, and manipulate design elements in batches (Insert/Copy/Replace/Update/Delete/Move/Generate) |
| `batch_get` | Read design components and hierarchy by patterns or node IDs |
| `get_screenshot` | Render design previews as PNG images |
| `snapshot_layout` | Analyze computed layout structure with bounding boxes, detect overlaps |
| `get_editor_state` | Get current editor context, active file, and selection |
| `get_variables` | Read design tokens and theme variables (colors, spacing, radii, sizes, fonts) |
| `set_variables` | Update design tokens and theme variables |
| `search_all_unique_properties` | Recursively search for all unique properties on nodes |
| `replace_all_matching_properties` | Recursively replace all matching properties on nodes |
| `get_guidelines` | Get design guidelines (topics: code, table, tailwind, landing-page, design-system) |
| `get_style_guide` | Get style guide by name or tags |
| `get_style_guide_tags` | List all available style guide tags |
| `open_document` | Open existing .pen file or create new one |
| `find_empty_space_on_canvas` | Find available space for new elements |
| `export_nodes` | **CLI only** — Export to PNG, JPEG, WEBP, PDF with scale multiplier |

Workflow: Describe UI in natural language → Generate design with batch_design → Visually review with get_screenshot → Iterate on design → Export to code when ready.

**CLI Authentication:** `pencil login` (interactive) or `PENCIL_CLI_KEY` env var (CI/CD). Agent mode: `pencil --out file.pen --prompt "..." --model claude-sonnet-4-6`.

Context7 Library: /pencil/docs

### Pencil-to-Code Export - React/Tailwind Generation

Export .pen designs to production-ready React and Tailwind CSS code via a prompt-based workflow.

Best For: Converting approved .pen designs to implementation, generating React components with Tailwind styling, maintaining design fidelity in code, rapid frontend development from visual designs.

Key Strengths: Prompt-based code generation (no export API), batch_get for reading .pen JSON structure, design token extraction via get_variables, React component generation with Tailwind classes, component structure preservation.

Workflow: batch_get frame data → Analyze JSON structure → Map to React/Tailwind → Apply design tokens → Verify against screenshot.

Note: Pencil-to-Code is a prompt-based workflow. There is no `pencil.export_to_react()` API or `pencil.config.js` configuration file.

## Quick Decision Guide

Choose Figma MCP when:
- Need to extract design context from existing Figma files
- Working with designers who use Figma
- Required to fetch design tokens and c