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

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.

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 component specifications
• Need screenshots or visual references from Figma
• Documenting existing design systems

Choose Pencil MCP when:

• Creating new designs from scratch
• Rapid prototyping and visual iteration needed
• Text-based design workflow preferred
• Want AI-assisted design generation
• Collaborative design discussions with team

Choose Pencil-to-Code Export when:

• Design is finalized in .pen format
• Ready to implement visual designs as code
• Need React components with Tailwind styling
• Maintaining design fidelity is critical
• Rapid frontend development from designs

Pencil MCP Workflow

Starting a Design Session

1. Check Editor State

   get_editor_state() → Determine active .pen file and user selection
   

2. Open or Create Document

   open_document(filePathOrNew: "new") → Create new .pen file
   open_document(filePathOrNew: "/path/to/file.pen") → Open existing
   

3. Get Design Guidelines

   get_guidelines(topic: "code" | "table" | "tailwind" | "landing-page")
   get_style_guide_tags() → Get available style tags
   get_style_guide(tags: ["minimalist", "dashboard"], name: "nova")
   

Creating Designs

1. Generate with batch_design

   Use batch_design for efficient batch operations. Syntax:

   foo=I("parent", { ... })    // Insert new node
   baz=C("nodeid", "parent", { ... })  // Copy node
   foo2=R("nodeid1/nodeid2", {...})    // Replace node
   U(foo+"/nodeid", {...})     // Update node
   D("dfFAeg2")               // Delete node
   M("nodeid3", "parent", 2)   // Move node
   G("baz", "ai", "...")       // Generate image with AI
   

2. Design with Default Nova Style

   When creating components without user-specified style:

   • Use neutral color palette (grays, whites)
   • Apply small radius (4-6px)
   • Use Noto Sans or system sans-serif
   • Maintain clean, minimal aesthetic
   • Apply consistent 4px/8px spacing grid

3. Review with get_screenshot

   get_screenshot() → Visual validation of design
   

Managing Design Tokens

1. Read Variables

   get_variables() → Current design tokens and themes
   

2. Update Variables

   set_variables(variables: { primary: "#3B82F6", ... })
   

Layout Analysis

snapshot_layout() → Analyze computed layout rectangles
find_empty_space_on_canvas(direction: "right", size: { w: 200, h: 100 })

Common Design-to-Code Patterns

Universal Patterns

These patterns apply across all three tools with tool-specific implementations.

Design Token Management:

All tools support design token extraction and management. Figma MCP extracts tokens from existing files, Pencil MCP generates tokens during design creation, Pencil-to-code exports tokens as CSS variables or Tailwind config.

Component Architecture:

All tools maintain component hierarchy. Figma MCP reads component structure from Figma, Pencil MCP creates component structure in DNA codes, Pencil-to-code generates React components preserving hierarchy.

Responsive Design:

All tools handle responsive layouts. Figma MCP extracts responsive variants, Pencil MCP defines responsive breakpoints in DNA, Pencil-to-code generates Tailwind responsive classes.

Style Consistency:

All tools ensure design consistency. Figma MCP validates against design system, Pencil MCP enforces design tokens, Pencil-to-code applies consistent Tailwind classes.

Workflow Best Practices

Applicable to all tools:

Design System Integration:

• Define design tokens before starting design work
• Use consistent naming conventions across tools
• Maintain single source of truth for design values
• Document token usage and component patterns

Version Control:

• Commit Figma metadata snapshots for reference
• Version .pen files in repository
• Track design iterations with git
• Document design decisions in code comments

Collaboration:

• Use Figma comments for design feedback
• Share .pen frames for visual review
• Create pull requests for design changes
• Maintain design documentation alongside code

Quality Assurance:

• Validate design tokens against style guide
• Test responsive breakpoints
• Verify accessibility compliance
• Review generated code for optimization

Tool-Specific Implementation

For detailed tool-specific implementation guidance, see the reference files:

Figma MCP Implementation

File: reference/figma.md

Covers Figma MCP connection setup, file metadata fetching, component tree extraction, design token retrieval, screenshot capture, and style guide generation.

Key sections: MCP configuration, authentication setup, file access patterns, metadata queries, component hierarchy parsing, token extraction formats, screenshot API usage, design system documentation.

Pencil MCP Rendering

File: reference/pencil-renderer.md

Covers batch_design operations, style guide integration, .pen frame rendering, visual design iteration, collaborative workflows, and design version control.

Key sections: batch_design syntax, natural language design prompts, rendering options, frame configuration, design refinement patterns, version control strategies, team collaboration workflows.

Pencil-to-Code Export

File: reference/pencil-code.md

Covers .pen design export to React components, Tailwind CSS generation, component structure preservation, responsive layout handling, and design system integration.

Key sections: Export configuration, React component generation, Tailwind class application, props API design, state management integration, testing generated components, optimization strategies.

Tool Comparison

File: reference/comparison.md

Provides detailed comparison matrix covering use cases, workflow patterns, integration complexity, and when to use each tool.

Key sections: Feature comparison table, workflow decision matrix, tool integration patterns, migration strategies, ecosystem compatibility, team workflow recommendations.

Navigation Guide

When working with design-to-code features:

1. Start with Quick Tool Selection (above) if choosing a tool
2. Apply Default Nova Style when no style specified
3. Review Common Design-to-Code Patterns for universal concepts
4. Open tool-specific reference file for implementation details
5. Refer to comparison.md when evaluating multiple tools
6. Use Context7 tools to access latest tool documentation

Context7 Documentation Access

Access up-to-date tool documentation using Context7 MCP:

Figma:

• Use resolve-library-id with "figma" to get library ID
• Use get-library-docs with topic "mcp", "api", "design-tokens", "metadata"

Pencil:

• Use resolve-library-id with "pencil" to get library ID
• Use get-library-docs with topic "mcp", "dna-codes", "rendering", "export"

Official Documentation

• Pencil Official: https://pencil.dev
• Pencil Docs: https://docs.pencil.dev
• Pencil AI Integration: https://docs.pencil.dev/getting-started/ai-integration

Works Well With

• moai-domain-uiux: Design systems and component architecture
• moai-domain-frontend: React implementation patterns
• moai-library-shadcn: shadcn/ui component integration (Nova preset)
• moai-lang-typescript: TypeScript for generated components
• moai-lang-react: React best practices
• moai-foundation-core: SPEC-driven development workflows

Status: Active Version: 5.1.0 (Pencil docs sync — schema v2.9, CLI v0.2.4, slots, libraries, full node types) Last Updated: 2026-04-05 Tools: Figma MCP (16 tools, Official Remote Server), Pencil MCP (14 tools + export_nodes CLI-only), Pencil-to-Code Export Default Style: shadcn/ui Nova (neutral, noto-sans, small radius) UI Kits: Shadcn UI (default), Halo (glassmorphic), Lunaris (dark-mode), Nitro (minimal)

Common Rationalizations

Red Flags

• Implementation uses hardcoded values instead of design tokens from Figma or Pencil
• Exported code committed without semantic HTML cleanup
• Interaction states (hover, focus, active, disabled) missing from implementation
• Pencil file updated but implementation not synced
• Design tool export contains absolute positioning that breaks responsive layout

Verification

• Design tokens from Figma or Pencil used for colors, spacing, and typography
• All interaction states implemented (hover, focus, active, disabled)
• Exported code cleaned up with semantic HTML and accessibility attributes
• Implementation matches design file at all breakpoints (compare visually)
• No hardcoded pixel values where design tokens are available