Back to Details

pencil-design-system

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pencil Design System Generator

Pencil设计系统生成器

Generate a complete, Mews-inspired design system in a Pencil 
.pen
file. Research the business domain, create ~60 themed tokens, build visual foundation documentation, ~25 reusable components organized by category, and composition patterns — all from a single prompt like "build a design system for a bakery." Domain screens are generated only if the user explicitly requests them.
在Pencil中生成一个完整的、受Mews启发的设计系统，保存为.pen文件。只需一个提示（如“为烘焙店搭建设计系统”），即可完成业务领域调研、创建约60个主题化设计令牌、构建视觉基础文档、按类别组织约25个可复用组件，以及设计组合模式。仅当用户明确要求时，才会生成特定领域的界面。

Input

输入

The user provides a business domain (e.g., "bakery", "fitness app", "SaaS dashboard"). Optional extras: brand name, color preferences, font preferences, specific screens wanted, light/dark theme preference. If the user gives only a domain, infer everything else from research.
If the user specifies colors or fonts: Use their values as the primary/accent/background tokens in Phase 3 and derive the remaining palette around them (secondary, muted, foregrounds). Research still runs to fill in gaps, but user preferences take priority over both research and fallback tables.
用户需提供一个业务领域（例如“烘焙店”、“健身应用”、“SaaS仪表盘”）。可选附加信息：品牌名称、颜色偏好、字体偏好、想要的特定界面、亮色/暗色主题偏好。如果用户仅提供领域，则通过调研推断其他所有信息。
若用户指定颜色或字体： 在第3阶段将其值映射为主要/强调/背景令牌，并围绕这些值推导其余调色板（次要、柔和、前景色）。仍会通过调研填补空白，但用户偏好优先于调研结果和备用表格。

Canvas Organization

画布布局

The canvas is laid out left-to-right in three core sections (always created), plus an optional screens section:
[Foundations 1440×2400] → 100px gap → [Components 1440×2400] → 100px gap → [Patterns 1440×1800] → (optional) [Screens →]
  • Foundations — Visual documentation: color palette swatches, typography specimens, spacing scale, elevation examples, border radius showcase.
  • Components — All ~25 reusable components, organized under category sub-frames (Buttons, Inputs, Typography, Badges, Alerts, Cards, Navigation, Tables, etc.).
  • Patterns — Composition showcases: form pattern, data display pattern, navigation pattern, card layout pattern. Each uses component refs to demonstrate real usage.
  • Screens (only if user requests) — 3–5 domain-relevant screens placed to the right of Patterns.
No components live at the document root except these section frames and the optional navigation index.
画布从左到右分为三个核心区域（必创建），外加一个可选的界面区域：
[Foundations 1440×2400] → 100px gap → [Components 1440×2400] → 100px gap → [Patterns 1440×1800] → (optional) [Screens →]
  • Foundations（基础层） —— 视觉文档：调色板样本、排版示例、间距尺度、层级阴影示例、圆角展示。
  • Components（组件层） —— 所有约25个可复用组件，按类别子框架组织（按钮、输入框、排版、徽章、提示框、卡片、导航、表格等）。
  • Patterns（模式层） —— 组合展示：表单模式、数据展示模式、导航模式、卡片布局模式。每个模式都使用组件引用来演示实际用法。
  • Screens（界面层） （仅用户要求时创建） —— 3-5个与领域相关的界面，放置在Patterns区域右侧。
除这些区域框架和可选的导航索引外，所有组件不得直接放在文档根节点下。

Workflow

工作流程

Execute these 10 phases in order. Each phase builds on the previous. Never skip phases. Reference files in 
references/
contain detailed specs — load them as each phase begins.
按顺序执行以下10个阶段，每个阶段都基于前一阶段的成果。不得跳过任何阶段。每个阶段开始前，需加载
references/
中的对应参考文件。

Phase 1 — Research the Domain

阶段1 —— 业务领域调研

Use 
WebSearch
to study the domain's design conventions. Identify five pillars: color palette, typography, imagery themes, screen inventory, and UI density/tone. Document findings as a design brief.
Typography is research-driven, not table-driven. Run specific font research queries (e.g., 
"bakery website fonts 2026"
, 
"best Google Fonts for bakery"
) and validate against 3–5 real websites in the domain. The font pairing table in 
domain-research-guide.md
is a fallback — always prefer research-validated choices. See 
references/domain-research-guide.md
.
使用
WebSearch
研究该领域的设计规范。确定五大核心：调色板、排版、图像主题、界面清单、UI密度与风格。将调研结果整理为设计 brief。
排版需基于调研，而非表格。 运行特定的字体调研查询（例如
"bakery website fonts 2026"
、
"best Google Fonts for bakery"
），并与该领域的3-5个真实网站进行验证。
domain-research-guide.md
中的字体配对表仅作为备选，优先选择经调研验证的字体。详见
references/domain-research-guide.md
。

Phase 2 — Initialize the Pencil Document

阶段2 —— 初始化Pencil文档

  1. Call 
    get_editor_state({ include_schema: true })
    .
  2. If no active document, call 
    open_document("new")
    .
  3. Call 
    get_guidelines({ topic: "design-system" })
    .
  4. Call 
    get_style_guide_tags()
    then 
    get_style_guide({ tags: [...] })
    with 5–10 domain-matching tags.
  5. Call 
    get_variables({ filePath })
    to check for existing tokens.
Merge the style guide with Phase 1 research to form the final design direction.
  1. 调用
    get_editor_state({ include_schema: true })
    。
  2. 若无活跃文档，调用
    open_document("new")
    。
  3. 调用
    get_guidelines({ topic: "design-system" })
    。
  4. 调用
    get_style_guide_tags()
    ，然后传入5-10个与领域匹配的标签调用
    get_style_guide({ tags: [...] })
    。
  5. 调用
    get_variables({ filePath })
    检查是否存在现有令牌。
将风格指南与阶段1的调研结果合并，形成最终设计方向。

Phase 3 — Create Design Tokens

阶段3 —— 创建设计令牌

Call 
set_variables
to create the full token system (~60 tokens). Every color, font, radius, spacing value, shadow, font size, and line height is a variable.
Handling user-specified colors: If the user provided color preferences (e.g., "terracotta and cream"), map them to the appropriate tokens (
--primary
, 
--background
, 
--accent
) and derive the rest of the palette (secondary, muted, foregrounds, borders) to complement. The industry palette tables are starting points, not mandates.
Post-creation color changes: Since all components use 
$--
token references (not hardcoded hex), calling 
set_variables
again with new color values updates the entire design system instantly — every component, pattern, and screen inherits the change. No per-node updates needed.
Token categories:
CategoryCountExamples
Core colors19
--background
, 
--foreground
, 
--primary
, 
--secondary
, 
--muted
, 
--accent
, 
--destructive
, 
--border
, 
--input
, 
--ring
Semantic colors8
--color-success
, 
--color-warning
, 
--color-error
, 
--color-info
+ foregrounds
Typography3
--font-primary
, 
--font-secondary
, 
--font-mono
Border radius6
--radius-none
(0) through 
--radius-pill
(9999)
Spacing12
--space-1
(4) through 
--space-24
(96)
Shadows4
--shadow-sm
, 
--shadow-md
, 
--shadow-lg
, 
--shadow-xl
Font sizes9
--text-xs
(12) through 
--text-5xl
(48)
Line heights3
--leading-tight
(1.25), 
--leading-normal
(1.5), 
--leading-relaxed
(1.75)
Set up theme axis 
{ "mode": ["light", "dark"] }
. All token values are domain-tailored. See 
references/design-tokens-reference.md
for full JSON payloads.
Post-creation verification: After calling 
set_variables
, immediately call 
get_variables
and verify that every color token's values show 
"theme":{"mode":"light"}
and 
"theme":{"mode":"dark"}
(not 
"theme":{}
). If theme mappings are missing, the 
set_variables
call used the wrong format — see the CRITICAL warning in 
design-tokens-reference.md
.
调用
set_variables
创建完整的令牌系统（约60个令牌）。所有颜色、字体、圆角、间距值、阴影、字号和行高均设为变量。
处理用户指定的颜色： 如果用户提供了颜色偏好（例如“赤陶色和奶油色”），将其映射到对应的令牌（
--primary
、
--background
、
--accent
），并推导其余调色板（次要、柔和、前景色、边框）以形成互补。行业调色板表仅作为起点，而非强制要求。
创建后颜色修改： 由于所有组件均使用
$--
令牌引用（而非硬编码的十六进制值），再次调用
set_variables
并传入新的颜色值即可即时更新整个设计系统——所有组件、模式和界面都会继承更改，无需逐个节点更新。
令牌类别：
类别数量示例
核心颜色19
--background
, 
--foreground
, 
--primary
, 
--secondary
, 
--muted
, 
--accent
, 
--destructive
, 
--border
, 
--input
, 
--ring
语义颜色8
--color-success
, 
--color-warning
, 
--color-error
, 
--color-info
+ 对应前景色
排版3
--font-primary
, 
--font-secondary
, 
--font-mono
圆角6
--radius-none
(0) 至 
--radius-pill
(9999)
间距12
--space-1
(4) 至 
--space-24
(96)
阴影4
--shadow-sm
, 
--shadow-md
, 
--shadow-lg
, 
--shadow-xl
字号9
--text-xs
(12) 至 
--text-5xl
(48)
行高3
--leading-tight
(1.25), 
--leading-normal
(1.5), 
--leading-relaxed
(1.75)
设置主题轴
{ "mode": ["light", "dark"] }
。所有令牌值均针对特定领域定制。完整的JSON负载详见
references/design-tokens-reference.md
。
创建后验证： 调用
set_variables
后，立即调用
get_variables
并验证每个颜色令牌的值是否包含
"theme":{"mode":"light"}
和
"theme":{"mode":"dark"}
（而非
"theme":{}
）。如果缺少主题映射，说明
set_variables
调用使用了错误的格式——请查看
design-tokens-reference.md
中的重要警告。

Phase 4 — Build Foundations (Visual Documentation)

阶段4 —— 构建基础层（视觉文档）

Create the Foundations section frame at the left of the canvas. Inside it, build 5 visual documentation frames:
  1. Color Palette — Grid of labeled swatches for all 27 color tokens.
  2. Typography Scale — 6 specimens (H1 → Caption) rendered at real sizes with metadata labels.
  3. Spacing Scale — 12 visual blocks showing each spacing value with labels.
  4. Elevation — 4 cards demonstrating shadow levels.
  5. Border Radius — 6 rectangles showcasing each radius token.
Critical: Use a neutral white backdrop (
fill: "#FFFFFF"
), NOT the design system's own 
$--background
token. The Foundations section is documentation chrome — using the themed background (e.g., cream for a bakery, blue-gray for SaaS) makes light swatches like 
--card
, 
--secondary
, and 
--muted
nearly invisible. A neutral white surface lets every color be evaluated accurately against a known reference. Swatches use 
$--
tokens for their fills; only the documentation frame itself is neutral.
These are documentation frames, NOT reusable components. They use 
$--
tokens for swatch fills everywhere. See 
references/foundations-specs.md
for exact 
batch_design
code (spread across 3 calls within 25-op limits).
After each batch, call 
get_screenshot
to verify rendering.
在画布左侧创建Foundations区域框架。在其中构建5个视觉文档框架：
  1. 调色板 —— 所有27个颜色令牌的带标签样本网格。
  2. 排版尺度 —— 6个示例（H1 → 说明文字），以实际尺寸渲染并附带元数据标签。
  3. 间距尺度 —— 12个视觉块，展示每个间距值并附带标签。
  4. 层级阴影 —— 4个卡片，演示不同阴影层级。
  5. 圆角 —— 6个矩形，展示每个圆角令牌。
重要提示：使用中性白色背景（
fill: "#FFFFFF"
），而非设计系统自身的
$--background
令牌。 Foundations区域是文档的展示层——如果使用主题化背景（例如烘焙店用奶油色，SaaS用蓝灰色），会导致
--card
、
--secondary
、
--muted
等浅色样本几乎不可见。中性白色背景可让每种颜色在已知参考下准确呈现。样本使用
$--
令牌填充；仅文档框架本身为中性色。
这些是文档框架，并非可复用组件。所有样本填充均使用
$--
令牌。具体的
batch_design
代码（分3次调用，每次不超过25个操作）详见
references/foundations-specs.md
。
每次批量操作后，调用
get_screenshot
验证渲染效果。

Phase 5 — Build Base Components (~15 Primitives)

阶段5 —— 构建基础组件（约15个基础组件）

Create the Components section frame to the right of Foundations with 
fill: "#FFFFFF"
(same neutral backdrop rationale as Foundations — light-fill variants like Ghost buttons and muted badges need a known white reference). Inside it, create category sub-frames with titles and display rows. Insert components under their category frame — NOT at document root.
BatchCategoryComponentsCount
1ButtonsPrimary, Secondary, Outline, Ghost, Destructive5
2InputsTextField, Textarea, Select, InputGroup4
3TypographyH1, H2, H3, Body, Caption, Label6
4BadgesDefault, Success, Warning, Error4
5AlertsInfo, Success, Warning, Error4
Every component has 
reusable: true
, uses only 
$--
tokens, and follows 
"Category/Variant"
naming. See 
references/component-specs.md
.
MANDATORY — Post-Batch Validation (after EVERY batch_design call):
  1. Check the batch response for "unknown properties were ignored" warnings — fix immediately.
  2. Call 
    get_screenshot
    on the affected section — visually confirm no overlapping elements, no invisible shadows, no broken layouts.
  3. If ANY horizontal arrangement shows items stacked/overlapping, the frame is missing 
    layout: "horizontal"
    . Fix it before proceeding to the next batch.
在Foundations区域右侧创建Components区域框架，设置
fill: "#FFFFFF"
（与Foundations使用中性背景的理由相同——幽灵按钮、柔和徽章等浅色填充变体需要已知的白色参考）。在其中创建带标题的类别子框架和展示行。将组件插入对应的类别框架下，不得直接放在文档根节点。
批量操作类别组件数量
1按钮主要按钮、次要按钮、轮廓按钮、幽灵按钮、危险按钮5
2输入框文本框、文本域、选择器、输入组4
3排版H1、H2、H3、正文、说明文字、标签6
4徽章默认徽章、成功徽章、警告徽章、错误徽章4
5提示框信息提示、成功提示、警告提示、错误提示4
每个组件均设置
reusable: true
，仅使用
$--
令牌，并遵循
"类别/变体"
命名规则。详见
references/component-specs.md
。
强制要求——批量操作后验证（每次
batch_design
调用后执行）：
  1. 检查批量操作响应中是否有“未知属性被忽略”的警告——立即修复。
  2. 对受影响的区域调用
    get_screenshot
    ——直观确认无重叠元素、无不可见阴影、无布局断裂。
  3. 若任何水平排列出现元素堆叠/重叠，说明框架缺少
    layout: "horizontal"
    属性。修复后再进入下一阶段。

Phase 6 — Build Composite Components (~10 Composites)

阶段6 —— 构建复合组件（约10个复合组件）

Continue inside the Components section frame, adding category sub-frames for each composite group.
BatchCategoryComponentsCount
6CardHeader + Content + Actions slots1
7NavigationSidebar container, ActiveItem, DefaultItem, SectionTitle4
8TableWrapper, HeaderRow, DataRow3
9TabsContainer, ActiveTab, InactiveTab3
10BreadcrumbsItem, Separator, ActiveItem3
11PaginationContainer, PageItem, ActiveItem, PrevNext4
12ModalDialog with Header/Body/Footer1
13DropdownContainer, Item, Divider, SectionTitle4
14MiscAvatar, Divider, Switch, Checkbox, Radio5
After batches 8, 11, and 14: run 
get_screenshot
and 
snapshot_layout({ problemsOnly: true })
. Fix issues immediately. See 
references/component-specs.md
.
在Components区域框架内继续添加复合组件类别的子框架。
批量操作类别组件数量
6卡片头部 + 内容 + 操作插槽1
7导航侧边栏容器、激活项、默认项、分区标题4
8表格容器、表头行、数据行3
9标签页容器、激活标签、未激活标签3
10面包屑项、分隔符、激活项3
11分页容器、页码项、激活项、上一页/下一页4
12模态框带头部/主体/底部的对话框1
13下拉菜单容器、菜单项、分隔符、分区标题4
14其他头像、分隔线、开关、复选框、单选框5
在批量操作8、11、14完成后：调用
get_screenshot
和
snapshot_layout({ problemsOnly: true })
，立即修复问题。详见
references/component-specs.md
。

Phase 7 — Build Patterns (Composition Showcases)

阶段7 —— 构建模式层（组合展示）

Create the Patterns section frame to the right of Components. Build 4 composition showcases that demonstrate real usage of the components:
  1. Form Pattern — Vertical stack of InputGroup refs + Submit button.
  2. Data Display Pattern — Table ref with populated rows + Pagination ref.
  3. Navigation Pattern — Sidebar ref + Breadcrumbs ref + Tabs ref.
  4. Card Layout Pattern — Grid of populated Card refs with images and domain content.
Each pattern uses only 
ref
instances + 
$--
tokens. After each pattern, run the Post-Batch Validation (screenshot + check for overlapping/broken layouts). See 
references/screen-patterns.md
.
在Components区域右侧创建Patterns区域框架。构建4个组合展示，演示组件的实际用法：
  1. 表单模式 —— 垂直排列的输入组引用 + 提交按钮。
  2. 数据展示模式 —— 填充数据的表格引用 + 分页引用。
  3. 导航模式 —— 侧边栏引用 + 面包屑引用 + 标签页引用。
  4. 卡片布局模式 —— 填充内容的卡片引用网格，包含图片和领域相关内容。
每个模式仅使用
ref
实例 + 
$--
令牌。每个模式完成后，执行批量操作后验证（截图 + 检查重叠/断裂布局）。详见
references/screen-patterns.md
。

Phase 8 — Create Domain Screens (only if user requests)

阶段8 —— 创建领域界面 （仅用户要求时执行）

Skip this phase unless the user explicitly asks for screens (e.g., "build screens for a bakery", "I need a landing page and menu screen", "create example screens"). The core deliverable is Foundations + Components + Patterns — screens are an optional add-on.
If the user requests screens, build 3–5 placed to the right of the Patterns section. Each screen uses only component 
ref
instances and 
$--
variable tokens.
Per-screen workflow:
  1. Call 
    find_empty_space_on_canvas({ direction: "right", width: 1440, height: 900, padding: 100 })
    .
  2. Insert screen frame at returned position.
  3. Build layout with component refs. Customize via 
    U(instanceId+"/descendantId", {...})
    .
  4. Add domain imagery via 
    G()
    .
  5. Call 
    get_screenshot
    to verify.
See 
references/screen-patterns.md
for domain-specific screen templates.
除非用户明确要求界面（例如“为烘焙店搭建界面”、“我需要一个着陆页和菜单界面”、“创建示例界面”），否则跳过本阶段。 核心交付物为Foundations + Components + Patterns——界面是可选附加项。
若用户要求界面，在Patterns区域右侧构建3-5个界面。每个界面仅使用组件
ref
实例和
$--
变量令牌。
单界面工作流程：
  1. 调用
    find_empty_space_on_canvas({ direction: "right", width: 1440, height: 900, padding: 100 })
    。
  2. 在返回的位置插入界面框架。
  3. 使用组件引用构建布局，通过
    U(instanceId+"/descendantId", {...})
    进行自定义。
  4. 通过
    G()
    添加领域相关图片。
  5. 调用
    get_screenshot
    验证。
领域特定界面模板详见
references/screen-patterns.md
。

Phase 9 — Layout Enforcement Pass (MANDATORY)

阶段9 —— 布局强制检查（强制要求）

Why this exists: The AI consistently drops 
layout: "horizontal"
from frames during generation, even when specs include it. This pass programmatically catches and fixes every missing layout. This phase is NOT optional — skip it and the design will have broken layouts.
Step 1 — Collect all frames with flex properties.
batch_get({ filePath, patterns: [{ type: "frame" }], searchDepth: 10, readDepth: 0 })
Search within EACH top-level section (Foundations, Components, Patterns, and any screens).
Step 2 — Identify frames needing layout enforcement. From the results, find every frame that has ANY of: 
gap
, 
alignItems
, 
justifyContent
— regardless of whether 
layout
already appears (since 
batch_get
doesn't display 
layout: "horizontal"
in its output — it's considered the default).
Step 3 — Bulk-apply 
layout: "horizontal"
to ALL identified frames.
javascript
U("frameId1", { layout: "horizontal" })
U("frameId2", { layout: "horizontal" })
// ... for every frame with gap/alignItems/justifyContent
Exclude frames that should be vertical (identifiable by name: category sections, form containers, vertical stacks). Apply 
layout: "vertical"
to those instead.
Step 4 — Verify shadows use hex colors. Check any frame with 
effect
property. If 
color
uses 
rgba()
format, replace with 8-digit hex 
#RRGGBBAA
.
Step 5 — Screenshot every section to confirm no overlapping elements.
This is safe to run multiple times — setting 
layout: "horizontal"
on a frame that already has it is a no-op.
存在原因： AI在生成过程中经常会从框架中遗漏
layout: "horizontal"
属性，即使规范中包含该属性。此步骤可通过编程方式捕获并修复所有缺失的布局设置。本阶段不可跳过——跳过会导致设计布局断裂。
步骤1 —— 收集所有包含flex属性的框架。
batch_get({ filePath, patterns: [{ type: "frame" }], searchDepth: 10, readDepth: 0 })
在每个顶级区域（Foundations、Components、Patterns以及所有已创建的界面）内搜索。
步骤2 —— 识别需要强制设置布局的框架。 从结果中找出所有包含以下任一属性的框架：
gap
、
alignItems
、
justifyContent
——无论是否已包含
layout
属性（因为
batch_get
的输出中不会显示
layout: "horizontal"
，它被视为默认值）。
步骤3 —— 为所有识别出的框架批量设置
layout: "horizontal"
。
javascript
U("frameId1", { layout: "horizontal" })
U("frameId2", { layout: "horizontal" })
// ... 为所有包含gap/alignItems/justifyContent的框架执行此操作
排除应设置为垂直布局的框架（可通过名称识别：类别区域、表单容器、垂直堆叠），为这些框架设置
layout: "vertical"
。
步骤4 —— 验证阴影使用十六进制颜色。 检查所有包含
effect
属性的框架。若
color
使用
rgba()
格式，替换为8位十六进制格式
#RRGGBBAA
。
步骤5 —— 对每个区域截图，确认无重叠元素。
本步骤可多次执行——为已设置
layout: "horizontal"
的框架再次设置该属性不会产生任何影响。

Phase 10 — Final Verification

阶段10 —— 最终验证

Run comprehensive QA. Fix every issue before presenting to the user.
  1. Visual — 
    get_screenshot
    on Foundations, Components, Patterns (and screens if created). Check alignment, spacing, typography, color, overflow.
  2. Layout — 
    snapshot_layout({ problemsOnly: true })
    to detect clipping/overflow. Fix all.
  3. Token audit — 
    search_all_unique_properties
    for 
    fillColor
    , 
    textColor
    , 
    fontFamily
    , 
    fontSize
    . Replace leaked hex values and raw font sizes with 
    $--
    tokens.
  4. Component audit — 
    batch_get({ patterns: [{ reusable: true }] })
    . Verify ~25 components.
  5. Organization audit — Verify no orphan components at document root. All should be under Components section.
  6. Fix and re-verify — Re-screenshot affected areas after fixes.
  7. Present — Summarize tokens, components, patterns (and screens if created). Show key screenshots.
See 
references/verification-checklist.md
.
执行全面的质量检查，向用户交付前修复所有问题。
  1. 视觉检查 —— 对Foundations、Components、Patterns（以及已创建的界面）调用
    get_screenshot
    。检查对齐、间距、排版、颜色、溢出情况。
  2. 布局检查 —— 调用
    snapshot_layout({ problemsOnly: true })
    检测裁剪/溢出问题，修复所有问题。
  3. 令牌审计 —— 使用
    search_all_unique_properties
    搜索
    fillColor
    、
    textColor
    、
    fontFamily
    、
    fontSize
    。将硬编码的十六进制值和原始字号替换为
    $--
    令牌。
  4. 组件审计 —— 调用
    batch_get({ patterns: [{ reusable: true }] })
    ，验证约25个组件。
  5. 组织审计** —— 验证无组件直接放在文档根节点下，所有组件应位于Components区域内。
  6. 修复并重新验证 —— 修复后对受影响区域重新截图。
  7. 交付 —— 总结令牌、组件、模式（以及已创建的界面），展示关键截图。
详见
references/verification-checklist.md
。

Phase 11 — Canvas Navigation Index

阶段11 —— 画布导航索引

Create a small navigation index frame at the canvas origin (x: 0, y: 0) showing a map of all sections with their positions:
Design System Index
├── Foundations (x, y)
├── Components (x, y)
├── Patterns (x, y)
└── Screens (x, y) — only if screens were created
This helps users navigate the canvas. Only include the Screens entry if Phase 8 was executed.
在画布原点（x: 0, y: 0）创建一个小型导航索引框架，显示所有区域及其位置：
设计系统索引
├── Foundations (x, y)
├── Components (x, y)
├── Patterns (x, y)
└── Screens (x, y) —— 仅创建界面后显示
这有助于用户导航画布。仅当执行了阶段8时，才包含Screens条目。

Phase 12 — Code Export (optional, user-triggered)

阶段12 —— 代码导出 （可选，用户触发）

Skip this phase unless the user explicitly requests code export (e.g., "export to Tailwind", "convert to code", "generate React components", "export as CSS"). This phase converts the design system into production-ready Tailwind CSS + React components.
Step 1 — Collect preferences. Ask the user for:
  • Tailwind version: v3 or v4
  • Framework: Next.js or Vite+React
Step 2 — Extract tokens. Call 
get_variables({ filePath })
to read all ~64 tokens. Categorize by type (color, number, string, shadow). Separate themed (light/dark) from static tokens.
Step 3 — Read components. Call 
batch_get({ patterns: [{ reusable: true }], readDepth: 3, searchDepth: 3 })
to get every reusable component with its full node tree.
Step 4 — Load Pencil's code generation guidelines. Call 
get_guidelines("code")
and 
get_guidelines("tailwind")
. These are the primary authority for translating Pencil nodes to code — they cover component instance mapping, property-to-Tailwind-class translation, font wiring, and visual verification. Follow them for all translation work in Steps 8-9.
Step 5 — Generate 
globals.css
. Build the CSS file with all tokens as CSS custom properties:
  • v3: 
    :root
    with HSL values (space-separated, no 
    hsl()
    wrapper), 
    .dark
    overrides, 
    @layer base
    font utilities
  • v4: 
    @import "tailwindcss"
    , 
    @custom-variant dark
    , 
    :root
    with hex values, 
    .dark
    overrides, 
    @layer base
    font utilities
Step 6 — Generate 
tailwind.config.js
(v3 only). Map all tokens to Tailwind utility names: colors via 
hsl(var(--name))
, radii, shadows, font sizes, spacing, line heights.
Step 7 — Generate font loading code.
  • Next.js: 
    layout.tsx
    with 
    next/font/google
    loader setting 
    --font-primary
    , 
    --font-secondary
    , 
    --font-mono
    CSS variables
  • Vite+React: 
    <link>
    tags in 
    index.html
    loading all three fonts from Google Fonts
Step 8 — Generate component TSX files. One file per component category (button.tsx, input.tsx, card.tsx, badge.tsx, alert.tsx, etc.). Each component:
  • Uses only token-referencing Tailwind classes (no hardcoded hex)
  • Has TypeScript interfaces with variant props where applicable
  • Accepts and spreads an optional 
    className
    prop
  • Uses v3 mapped classes (
    bg-primary
    ) or v4 arbitrary values (
    bg-[var(--primary)]
    ) based on the chosen version
Step 9 — Generate screen/page TSX files. For each screen design in the .pen file:
  1. Deep-read the screen frame: 
    batch_get({ nodeIds: [screenId], readDepth: 10, resolveInstances: true })
  2. Take a reference screenshot: 
    get_screenshot({ nodeId: screenId })
  3. Follow Pencil's Component Implementation Workflow (from Step 4's 
    get_guidelines("code")
    ):
    • Steps 1A-1C: Extract components, map ALL instances with ALL overrides and descendants
    • Step 2: Create React components using 
      get_guidelines("tailwind")
      for property-to-class mapping
    • Step 3: Validate each component with 
      get_screenshot
      — pixel-perfect match required
    • Step 4: Integrate into frame, verify instance count and prop completeness
  4. Handle screen-level elements: semantic HTML for headings/labels/links, page wrapper, form behavior, icon name conversion, image fills
  5. Assemble into a complete page file with all imports
  6. Visually verify the rendered page against the Pencil screenshot — fix any discrepancies
See 
references/code-export-guide.md
(Section 7) for the complete screen export workflow and common pitfalls.
除非用户明确要求代码导出（例如“导出为Tailwind”、“转换为代码”、“生成React组件”、“导出为CSS”），否则跳过本阶段。 本阶段将设计系统转换为可用于生产环境的Tailwind CSS + React组件。
步骤1 —— 收集偏好。 询问用户：
  • Tailwind版本： v3或v4
  • 框架： Next.js或Vite+React
步骤2 —— 提取令牌。 调用
get_variables({ filePath })
读取所有约64个令牌，按类型分类（颜色、数字、字符串、阴影），区分主题化（亮色/暗色）和静态令牌。
步骤3 —— 读取组件。 调用
batch_get({ patterns: [{ reusable: true }], readDepth: 3, searchDepth: 3 })
获取所有可复用组件及其完整节点树。
步骤4 —— 加载Pencil的代码生成指南。 调用
get_guidelines("code")
和
get_guidelines("tailwind")
。这些是将Pencil节点转换为代码的主要依据，涵盖组件实例映射、属性到Tailwind类的转换、字体配置和视觉验证。步骤8-9的所有转换工作均需遵循这些指南。
步骤5 —— 生成
globals.css
。 构建包含所有令牌的CSS文件，将其作为CSS自定义属性：
  • v3： 
    :root
    中使用HSL值（空格分隔，无
    hsl()
    包裹），
    .dark
    覆盖样式，
    @layer base
    字体工具类
  • v4： 
    @import "tailwindcss"
    ，
    @custom-variant dark
    ，
    :root
    中使用十六进制值，
    .dark
    覆盖样式，
    @layer base
    字体工具类
步骤6 —— 生成
tailwind.config.js
（仅v3）。 将所有令牌映射到Tailwind工具类名称：颜色通过
hsl(var(--name))
映射，圆角、阴影、字号、间距、行高同理。
步骤7 —— 生成字体加载代码。
  • Next.js： 
    layout.tsx
    中使用
    next/font/google
    加载器，设置
    --font-primary
    、
    --font-secondary
    、
    --font-mono
    CSS变量
  • Vite+React： 
    index.html
    中的
    <link>
    标签，从Google Fonts加载所有三种字体
步骤8 —— 生成组件TSX文件。 每个组件类别对应一个文件（button.tsx、input.tsx、card.tsx、badge.tsx、alert.tsx等）。每个组件：
  • 仅使用引用令牌的Tailwind类（无硬编码十六进制值）
  • 包含TypeScript接口，适当时包含变体属性
  • 接收并传递可选的
    className
    属性
  • 根据所选版本，使用v3映射类（
    bg-primary
    ）或v4任意值（
    bg-[var(--primary)]
    ）
步骤9 —— 生成界面/页面TSX文件。 为.pen文件中的每个界面设计生成一个文件：
  1. 深度读取界面框架：
    batch_get({ nodeIds: [screenId], readDepth: 10, resolveInstances: true })
  2. 截取参考截图：
    get_screenshot({ nodeId: screenId })
  3. 遵循Pencil组件实现工作流（来自步骤4的
    get_guidelines("code")
    ）：
    • 步骤1A-1C：提取组件，映射所有带覆盖样式和子节点的实例
    • 步骤2：使用
      get_guidelines("tailwind")
      进行属性到类的映射，创建React组件
    • 步骤3：使用
      get_screenshot
      验证每个组件——需实现像素级匹配
    • 步骤4：集成到框架中，验证实例数量和属性完整性
  4. 处理界面级元素：标题/标签/链接使用语义化HTML，页面容器，表单行为，图标名称转换，图片填充
  5. 组装为完整的页面文件，包含所有导入
  6. 将渲染后的页面与Pencil截图进行视觉比对——修复所有差异
特定领域的界面导出工作流和常见陷阱详见
references/code-export-guide.md
第7节。

Critical Rules

核心规则

Rule 1 — Always reuse components. Search with 
batch_get({ patterns: [{ reusable: true }] })
before creating. On screens, every element must be a 
ref
instance.
Rule 2 — Never hardcode values. All colors use 
$--
tokens. All fonts use 
$--font-*
. All radii use 
$--radius-*
. All font sizes use 
$--text-*
. Raw values only appear in 
set_variables
.
Rule 3 — Prevent overflow. Constrain text with 
width: "fill_container"
. Use layout frames. Validate with 
snapshot_layout({ problemsOnly: true })
.
Rule 4 — Verify visually. Call 
get_screenshot
after every major batch. Fix problems immediately.
Rule 5 — Reuse assets. Copy images with 
C()
instead of regenerating with 
G()
.
Rule 6 — Domain coherence. Every choice connects back to Phase 1 research.
Rule 7 — Canvas organization. All components go inside the Components section frame under categorized sub-frames. No components at document root. Foundations, Components, Patterns, and Screens flow left-to-right on the canvas.
规则1 —— 始终复用组件。 创建前使用
batch_get({ patterns: [{ reusable: true }] })
搜索。在界面中，每个元素必须是
ref
实例。
规则2 —— 绝不硬编码值。 所有颜色使用
$--
令牌，所有字体使用
$--font-*
，所有圆角使用
--radius-*
，所有字号使用
--text-*
。仅在
set_variables
中使用原始值。
规则3 —— 防止溢出。 使用
width: "fill_container"
限制文本，使用布局框架，通过
snapshot_layout({ problemsOnly: true })
验证。
规则4 —— 视觉验证。 每次主要批量操作后调用
get_screenshot
，立即修复问题。
规则5 —— 复用资源。 使用
C()
复制图片，而非使用
G()
重新生成。
规则6 —— 领域一致性。 每个决策均需关联到阶段1的调研结果。
规则7 —— 画布组织。 所有组件必须放在Components区域框架下的分类子框架中，不得直接放在文档根节点。Foundations、Components、Patterns和Screens在画布上从左到右排列。

Component Inventory

组件清单

#ComponentTypeVariants
1–5ButtonPrimitivePrimary, Secondary, Outline, Ghost, Destructive
6–9InputPrimitiveTextField, Textarea, Select, InputGroup
10–15TypographyPrimitiveH1, H2, H3, Body, Caption, Label
16–19BadgePrimitiveDefault, Success, Warning, Error
20–23AlertPrimitiveInfo, Success, Warning, Error
24CardCompositeHeader + Content + Actions slots
25–28Sidebar NavCompositeContainer, ActiveItem, DefaultItem, SectionTitle
29–31TableCompositeWrapper, HeaderRow, DataRow
32–34TabsCompositeContainer, ActiveTab, InactiveTab
35–37BreadcrumbsCompositeItem, Separator, ActiveItem
38–41PaginationCompositeContainer, PageItem, ActiveItem, PrevNext
42Modal/DialogCompositeOverlay + Content with slots
43–46DropdownCompositeContainer, MenuItem, Divider, SectionTitle
47–51MiscellaneousCompositeAvatar, Divider, Switch, Checkbox, Radio
编号组件类型变体
1–5按钮基础组件主要、次要、轮廓、幽灵、危险
6–9输入框基础组件文本框、文本域、选择器、输入组
10–15排版基础组件H1、H2、H3、正文、说明文字、标签
16–19徽章基础组件默认、成功、警告、错误
20–23提示框基础组件信息、成功、警告、错误
24卡片复合组件头部 + 内容 + 操作插槽
25–28侧边栏导航复合组件容器、激活项、默认项、分区标题
29–31表格复合组件容器、表头行、数据行
32–34标签页复合组件容器、激活标签、未激活标签
35–37面包屑复合组件项、分隔符、激活项
38–41分页复合组件容器、页码项、激活项、上一页/下一页
42模态框/对话框复合组件遮罩 + 带插槽的内容
43–46下拉菜单复合组件容器、菜单项、分隔符、分区标题
47–51其他复合组件头像、分隔线、开关、复选框、单选框

References

参考文件

Load the relevant file before starting each phase:
  • references/pencil-mcp-guide.md
     — Complete Pencil MCP tool reference with examples and operation syntax.
  • references/domain-research-guide.md
     — Domain research strategies, color psychology, font pairings, screen inventories.
  • references/design-tokens-reference.md
     — Token architecture, 
    set_variables
    JSON payloads, ~60 token definitions, industry palettes.
  • references/foundations-specs.md
     — Visual foundation documentation: color palette, typography scale, spacing, elevation, radius 
    batch_design
    code.
  • references/component-specs.md
     — All ~25 component 
    batch_design
    operation code with section frame organization.
  • references/screen-patterns.md
     — Layout patterns, composition showcases, and domain-specific screen templates.
  • references/verification-checklist.md
     — Visual QA, layout checks, token audits, canvas organization verification.
  • references/code-export-guide.md
     — Tailwind CSS export: token extraction, v3/v4 templates, Pencil-to-Tailwind class cheatsheet, component translation, framework setup (Next.js / Vite+React).
每个阶段开始前加载对应的参考文件：
  • references/pencil-mcp-guide.md
     —— 完整的Pencil MCP工具参考，包含示例和操作语法。
  • references/domain-research-guide.md
     —— 领域调研策略、色彩心理学、字体配对、界面清单。
  • references/design-tokens-reference.md
     —— 令牌架构、
    set_variables
    JSON负载、约60个令牌定义、行业调色板。
  • references/foundations-specs.md
     —— 视觉基础文档：调色板、排版尺度、间距、层级阴影、圆角的
    batch_design
    代码。
  • references/component-specs.md
     —— 所有约25个组件的
    batch_design
    操作代码，包含区域框架组织方式。
  • references/screen-patterns.md
     —— 布局模式、组合展示、特定领域的界面模板。
  • references/verification-checklist.md
     —— 视觉质量检查、布局检查、令牌审计、画布组织验证。
  • references/code-export-guide.md
     —— Tailwind CSS导出：令牌提取、v3/v4模板、Pencil到Tailwind类对照表、组件转换、框架设置（Next.js / Vite+React）。