moai-design-tools

设计工具集成专家

全面介绍从设计到代码的工作流，涵盖三大核心能力：Figma MCP（获取设计）、Pencil MCP（视觉渲染）和 Pencil-to-code 导出（生成 React/Tailwind）。

默认设计风格（shadcn/ui Nova）

如果用户没有指定具体的设计风格，请使用 shadcn/ui Nova 预设，并采用 Notion 风格的中性色方案：

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 风格配置

属性	值	描述
风格	nova	现代、简洁的设计语言
基础颜色	neutral	Notion 风格的灰度色板
主题	neutral	统一的中性色主题
图标库	hugeicons	内容丰富的图标集
字体	noto-sans	简洁易读的无衬线字体
圆角	small	微妙的圆角
菜单强调	bold	突出的菜单高亮效果

何时使用默认风格

在以下情况下应用 Nova 预设：

• 用户没有提供具体细节，只要求设计“简洁”“现代”或“极简”
• 未指定品牌指南或设计系统
• 创建仪表板、管理面板或效率工具
• 构建文档或以内容为主的界面

快速选择工具

Figma MCP - 设计上下文与生成

通过远程 MCP 服务（https://mcp.figma.com/mcp）集成官方 Figma MCP。使用以下命令安装：claude plugin install figma@claude-plugins-official

最适合：从 Figma 文件获取设计上下文、提取设计令牌、使用 Code-to-Canvas（generate_figma_design）生成新设计、访问 FigJam 看板，以及使用 Code Connect 将组件关联到代码。

主要优势：包含 16 个官方工具，包括读取（get_design_context、get_variable_defs、get_screenshot、get_metadata）、写入（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）、设计系统（search_design_system、create_design_system_rules）和实用工具（whoami）。测试版期间，目前可免费写入画布。

工作流：安装插件 → get_design_context → get_variable_defs → get_screenshot → 实现设计 → 对照截图进行验证。

Context7 库：/figma/docs

Pencil MCP - 视觉设计渲染

Pencil MCP 集成，用于创建和编辑 .pen 设计文件（schema v2.9），支持 AI 辅助设计生成。CLI：@pencil.dev/cli v0.2.4。

最适合：快速原型设计、视觉设计迭代、根据文本描述创建 UI 模型、协作式设计讨论、实现前的视觉方案提案。

主要优势：文本转设计、批量设计操作、集成样式指南、无需实现即可预览视觉效果、协作式设计工作流、支持插槽的组件系统、设计库（.lib.pen）。

可用的 Pencil MCP 工具（14 个 + 1 个仅限 CLI 的工具）：

注意：.pen 文件是纯 JSON（可用 Git 比较差异、可合并）。共有 13 种节点类型：Rectangle、Ellipse、Line、Polygon、Path、Text、Frame、Group、Note、Prompt、Context、IconFont、Ref。

工具	用途
batch_design	批量创建、修改和操作设计元素（Insert/Copy/Replace/Update/Delete/Move/Generate）
batch_get	按模式或节点 ID 读取设计组件及层级结构
get_screenshot	将设计渲染为 PNG 图片预览
snapshot_layout	分析计算后的布局结构及边界框，并检测重叠
get_editor_state	获取当前编辑器上下文、活动文件和选区
get_variables	读取设计令牌和主题变量（颜色、间距、圆角、尺寸、字体）
set_variables	更新设计令牌和主题变量
search_all_unique_properties	递归搜索节点的所有唯一属性
replace_all_matching_properties	递归替换所有匹配的节点属性
get_guidelines	获取设计指南（主题：code、table、tailwind、landing-page、design-system）
get_style_guide	按名称或标签获取样式指南
get_style_guide_tags	列出所有可用的样式指南标签
open_document	打开现有的 .pen 文件或创建新文件
find_empty_space_on_canvas	查找可用于放置新元素的空白区域
export_nodes	仅限 CLI — 导出为 PNG、JPEG、WEBP、PDF，并支持缩放倍数

工作流：用自然语言描述 UI → 使用 batch_design 生成设计 → 使用 get_screenshot 进行视觉检查 → 迭代设计 → 准备就绪后导出为代码。

**CLI 身份验证：**使用 pencil login（交互式），或设置 PENCIL_CLI_KEY 环境变量（CI/CD）。Agent 模式：pencil --out file.pen --prompt "..." --model claude-sonnet-4-6。

Context7 库：/pencil/docs

Pencil-to-Code 导出 - React/Tailwind 代码生成

通过基于提示词的工作流，将 .pen 设计导出为可用于生产环境的 React 和 Tailwind CSS 代码。

最适合：将已批准的 .pen 设计转为实现代码、生成采用 Tailwind 样式的 React 组件、确保代码忠实呈现设计、根据视觉设计快速开发前端。

主要优势：基于提示词生成代码（无导出 API）、使用 batch_get 读取 .pen JSON 结构、通过 get_variables 提取设计令牌、生成带 Tailwind 类的 React 组件、保留组件结构。

工作流：使用 batch_get 获取框架数据 → 分析 JSON 结构 → 映射到 React/Tailwind → 应用设计令牌 → 根据截图验证。

注意：Pencil-to-Code 是基于提示词的工作流。不存在 pencil.export_to_react() API 或 pencil.config.js 配置文件。

快速决策指南

在以下情况选择 Figma MCP：

• 需要从现有 Figma 文件中提取设计上下文
• 与使用 Figma 的设计师合作
• 需要获取设计令牌和组件规范
• 需要 Figma 中的截图或视觉参考
• 需要记录现有设计系统

在以下情况选择 Pencil MCP：

• 从头开始创建新设计
• 需要快速原型设计和视觉迭代
• 更倾向于基于文本的设计工作流
• 希望借助 AI 生成设计
• 与团队开展协作式设计讨论

在以下情况选择 Pencil-to-Code Export：

• 设计已在 .pen 格式中定稿
• 准备将视觉设计实现为代码
• 需要使用 Tailwind 样式的 React 组件
• 设计还原度至关重要
• 需要根据设计快速开发前端

Pencil MCP 工作流

开始设计会话

1. 检查编辑器状态

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

2. 打开或创建文档

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

3. 获取设计指南

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

创建设计

1. 使用 batch_design 生成

   使用 batch_design 高效执行批量操作。语法：

   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. 使用默认 Nova 风格进行设计

   创建组件时，如果用户未指定风格：

   • 使用中性色调（灰色、白色）
   • 使用较小的圆角（4-6px）
   • 使用 Noto Sans 或系统无衬线字体
   • 保持简洁、极简的美感
   • 使用一致的 4px/8px 间距网格

3. 使用 get_screenshot 检查

   get_screenshot() → Visual validation of design
   

管理设计令牌

1. 读取变量

   get_variables() → Current design tokens and themes
   

2. 更新变量

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

布局分析

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

常见的设计转代码模式

通用模式

以下模式适用于全部三个工具，各工具的具体实现有所不同。

设计令牌管理：

所有工具都支持设计令牌的提取和管理。Figma MCP 从现有文件中提取令牌，Pencil MCP 在创建设计时生成令牌，Pencil-to-code 将令牌导出为 CSS 变量或 Tailwind 配置。

组件架构：

所有工具都维护组件层级结构。Figma MCP 从 Figma 读取组件结构，Pencil MCP 在 DNA 代码中创建组件结构，Pencil-to-code 生成保留层级结构的 React 组件。

响应式设计：

所有工具都支持响应式布局。Figma MCP 提取响应式变体，Pencil MCP 在 DNA 中定义响应式断点，Pencil-to-code 生成 Tailwind 响应式类。

样式一致性：

所有工具都确保设计一致性。Figma MCP 根据设计系统进行验证，Pencil MCP 强制使用设计令牌，Pencil-to-code 应用一致的 Tailwind 类。

工作流最佳实践

适用于所有工具：

设计系统集成：

• 开始设计工作前定义设计令牌
• 在各工具中使用一致的命名约定
• 为设计值维护单一事实来源
• 记录令牌用法和组件模式

版本控制：

• 提交 Figma 元数据快照以供参考
• 在代码库中对 .pen 文件进行版本管理
• 使用 git 跟踪设计迭代
• 在代码注释中记录设计决策

协作：

• 使用 Figma 评论提供设计反馈
• 分享 .pen 画板以进行视觉审查
• 为设计变更创建拉取请求
• 将设计文档与代码一同维护

质量保证：

• 根据样式指南验证设计令牌
• 测试响应式断点
• 验证是否符合无障碍要求
• 检查生成的代码并进行优化

工具专属实现

有关工具专属实现指南的详情，请参阅参考文件：

Figma MCP 实现

文件：reference/figma.md

涵盖 Figma MCP 连接设置、文件元数据获取、组件树提取、设计令牌检索、截图捕获和样式指南生成。

主要章节：MCP 配置、身份验证设置、文件访问模式、元数据查询、组件层级解析、令牌提取格式、截图 API 用法、设计系统文档。

Pencil MCP 渲染

文件：reference/pencil-renderer.md

涵盖 batch_design 操作、样式指南集成、.pen 画板渲染、视觉设计迭代、协作工作流和设计版本控制。

关键章节：batch_design 语法、自然语言设计提示词、渲染选项、画板配置、设计优化模式、版本控制策略、团队协作工作流。

Pencil 到代码导出

文件：reference/pencil-code.md

涵盖将 .pen 设计导出为 React 组件、生成 Tailwind CSS、保留组件结构、处理响应式布局以及集成设计系统。

关键章节：导出配置、React 组件生成、Tailwind 类应用、props API 设计、状态管理集成、生成组件测试、优化策略。

工具比较

文件：reference/comparison.md

提供详细的比较矩阵，涵盖使用场景、工作流模式、集成复杂度，以及何时使用各个工具。

关键章节：功能比较表、工作流决策矩阵、工具集成模式、迁移策略、生态系统兼容性、团队工作流建议。

导航指南

使用设计转代码功能时：

1. 如果要选择工具，请先查看上文的“快速工具选择”
2. 未指定样式时，使用默认 Nova 样式
3. 查看“常见设计转代码模式”，了解通用概念
4. 打开特定工具的参考文件，查看实现细节
5. 评估多个工具时，参考 comparison.md
6. 使用 Context7 工具获取最新的工具文档

Context7 文档访问

使用 Context7 MCP 获取最新的工具文档：

Figma：

• 使用 resolve-library-id 并输入 "figma" 获取库 ID
• 使用 get-library-docs 并将主题设为 "mcp"、"api"、"design-tokens"、"metadata"

Pencil：

• 使用 resolve-library-id 并输入 "pencil" 获取库 ID
• 使用 get-library-docs 并将主题设为 "mcp"、"dna-codes"、"rendering"、"export"

官方文档

• Pencil 官方网站：https://pencil.dev
• Pencil 文档：https://docs.pencil.dev
• Pencil AI 集成：https://docs.pencil.dev/getting-started/ai-integration

配合使用效果良好

• moai-domain-uiux：设计系统和组件架构
• moai-domain-frontend：React 实现模式
• moai-library-shadcn：shadcn/ui 组件集成（Nova 预设）
• moai-lang-typescript：用于生成组件的 TypeScript
• moai-lang-react：React 最佳实践
• moai-foundation-core：SPEC 驱动的开发工作流

---

状态：Active 版本：5.1.0（Pencil 文档同步 — schema v2.9、CLI v0.2.4、插槽、库、完整节点类型） 最后更新：2026-04-05 工具：Figma MCP（16 个工具，官方远程服务）、Pencil MCP（14 个工具 + 仅限 CLI 的 export_nodes）、Pencil 到代码导出 默认样式：shadcn/ui Nova（中性、noto-sans、小圆角） UI 套件：Shadcn UI（默认）、Halo（玻璃拟态）、Lunaris（深色模式）、Nitro（极简）