--- name: modu-ai/moai-design-tools source: https://app.decimal.ai/s/modu-ai-moai-design-tools@1/SKILL.md source_sha256: f47f0c485f1d --- # 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 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 | Rationalization | Reality | |---|---| | "I can implement the design from the screenshot, I do not need Figma context" | Screenshots lose component structure, spacing tokens, and interaction states. Figma MCP provides structured design data. | | "Pencil files are just for designers, developers do not need them" | Pencil files contain layout constraints and component hierarchy. Developers use them as the source of truth for implementation. | | "I will export to code and clean it up" | Generated code is a starting point, not a deliverable. Export without review produces non-semantic, non-accessible markup. | | "Design tokens are too rigid, I need custom values" | Custom values bypass the design system. Extend tokens through the system, not around it. | | "I will sync with the designer after implementation" | Post-implementation sync means rework. Sync before implementation means alignment. | ## 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