efecto-web-design

Efecto — 使用 AI 设计网页

Efecto 是一款实时网页设计工具，可由 AI Agent 通过编程方式控制。你可以创建一个会话，让用户在浏览器中打开一个 URL，然后推送设计命令并立即渲染。每个节点都对应一个使用 Tailwind CSS 设置样式的真实 HTML 元素——原生适用于 Web、语义清晰且像素精准。

---

设置

此技能需要 Efecto MCP 服务。请在工具列表中查找 create_session、add_section 或 get_document 等工具，以确认服务是否可用。

如果没有 Efecto 工具，请安装 MCP 服务：

Claude Code

claude mcp add efecto -- npx -y @efectoapp/mcp

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "efecto": {
      "command": "npx",
      "args": ["-y", "@efectoapp/mcp"]
    }
  }
}

Windsurf / VS Code / 其他 MCP 客户端

{
  "mcpServers": {
    "efecto": {
      "command": "npx",
      "args": ["-y", "@efectoapp/mcp"]
    }
  }
}

安装后，你将可以使用 68 个 MCP 工具，包括图片搜索和原生动画创作。MCP 服务会将你的 Agent 连接到 efecto.app 上的 Efecto 设计画布。

---

会话的工作方式

Agent ──POST /execute──> Server ──SSE──> Browser (renders live)
Agent <──poll/response── Server <──POST── Browser (returns results)

1. 通过 MCP 服务或 REST API 创建会话
2. 用户在浏览器中打开返回的 Efecto URL
3. 推送工具调用——每次调用都会在浏览器中执行并返回结果
4. 用户可以实时看到你构建设计时的每项更改

会话在闲置 2 小时后过期。浏览器必须先连接，工具调用才能执行。如果你重启或丢失 MCP 进程，请使用用户当前的 Efecto URL 调用 attach_session，而不是创建重复的会话。

---

快速入门——7 个步骤构建页面

步骤 1：创建会话

create_session
  label: "Landing page design"

返回 { sessionId, documentId, designUrl }。告诉用户打开该 URL。会话 ID 会自动保存，后续所有工具都会使用它。

如果用户已有包含 ?session=... 的 Efecto URL，请恢复该会话：

attach_session
  designUrl: "https://efecto.app/design/<file-id>/untitled?session=<session-id>"

不要再次调用 create_session 来“重新连接”。 对于现有 URL，请使用 attach_session。除非传入 force: true，否则第二次调用 create_session 会拒绝覆盖已配对的会话。

步骤 2：等待浏览器连接

wait_for_connection

阻塞等待浏览器打开 URL 并完成配对（默认 120s）。如果已经配对，则立即返回。

随时可以检查路由状态：

session_status                # legacy single-session shape (sessionId, paired, browserConnected, knownSessions)
session_status { all: true }  # list shape — all sessions in this MCP process with isActive / paired flags

步骤 3：创建画板

create_artboard
  name: "Homepage"
  width: 1440
  height: 900
  backgroundColor: "#ffffff"
  className: "flex flex-col"

返回画板 ID。始终将 className 设为 "flex flex-col"，以便子元素纵向排列。

步骤 4：使用 JSX 添加区块

add_section
  parentId: "<artboard-id>"
  jsx: '<nav name="Primary Navigation" className="flex items-center justify-between px-16 py-5 bg-white w-full">
    <h2 name="Brand Name" className="text-xl font-bold text-gray-900">Acme</h2>
    <div name="Navigation Links" className="flex items-center gap-8">
      <a name="Features Link" className="text-sm text-gray-600" href="#">Features</a>
      <a name="Pricing Link" className="text-sm text-gray-600" href="#">Pricing</a>
      <button name="Get Started Button" className="px-4 py-2 text-sm font-medium text-white bg-gray-900 rounded-lg">Get Started</button>
    </div>
  </nav>'

这是构建复杂布局最高效的方式——每个区块使用一个 JSX 字符串。

步骤 5：读取当前状态

get_document

返回每个节点都带有 data-id 属性的类 JSX 标记。使用这些 ID 进行更新。

步骤 6：通过更新微调

batch_update
  updates: [
    { nodeId: "abc", className: "text-2xl font-extrabold text-gray-900" },
    { nodeId: "def", textContent: "Updated heading text" }
  ]

步骤 7：迭代

重复步骤 4-6，添加更多区块、调整样式并完善设计。用户可以实时看到每项更改。

---

设计工具

读取状态

工具	用途
get_selection	返回当前选中的节点/画板及其 JSX 子树
get_document	以 JSX 形式返回文档。大型文档推荐使用范围限定模式：outline: true（为每个顶层子项提供单行摘要）、artboardId（单个画板）、maxDepth（限制遍历深度；0 = 仅画板标题，1 = 仅顶层子项）。响应中包含大致的 token 数量。
list_artboards	列出所有画板及其 ID、名称和尺寸
find_nodes	按名称、文本内容、类型或 className 搜索节点。返回不含子树的 ID——请先用此工具定位节点，再调用 get_node_tree。
get_node_tree	仅序列化一个节点/画板子树——在使用 outline 或 find_nodes 后深入查看。

创建内容

工具	用途
create_artboard	创建新的画板（屏幕/框架）
add_section	从 JSX 标记添加复杂布局（推荐）
add_node	向父节点添加单个节点

修改内容

工具	用途
update_node	更新任意节点属性（className、textContent、tag、style、src、link、elementId 等）
update_class	快捷方式：仅替换节点上的 className
update_artboard	更新画板属性（name、size、background、className、timelineDuration）
batch_update	一次调用更新多个节点（批量设置样式）
replace_section	用新的 JSX 替换节点及其子节点

动画

工具	用途
list_animation_presets	列出原生 Efecto 动画预设及其 ID、类别、默认值和支持的控件
apply_animation_plan	一次调用应用经过验证的多层动画计划
clear_animations	清除节点、所选内容、画板或整个文档中的原生动画

整理结构

工具	用途
move_node	更改节点的父级或顺序
duplicate_node	深度克隆节点并生成新的 ID
duplicate_artboard	深度克隆画板以创建不同版本
group_nodes	将所选节点放入一个框架容器中
ungroup_node	解散分组，并将子节点移至父级
reorder_node	将节点置于最前或移至最后（z 轴顺序）

显示与选择

工具	用途
select_nodes	高亮节点以供用户查看
set_visibility	显示/隐藏节点（类似 Figma 的眼睛图标）
delete_nodes	删除节点及其子节点
delete_artboard	删除画板及其所有内容

对齐与分布

工具	用途
align_nodes	对齐多个节点（左/居中/右/顶部/中部/底部）
distribute_nodes	均匀分布节点（水平/垂直）

历史记录

工具	用途
undo	撤销上一步操作（Cmd+Z）
redo	重做上一步撤销的操作（Cmd+Shift+Z）

视口与文档

工具	用途
zoom_to_artboard	缩放视口以显示指定画板
zoom_to_fit	缩放视口以适配所有画板
set_viewport	设置视口缩放级别和/或平移位置
rename_document	重命名文档
new_document	创建新的空白文档（替换当前文档）

画布与读取

工具	用途
move_artboard	在画布上重新定位画板，以用于多屏流程
deselect_all	清除当前节点选择
get_node_tree	返回一个节点/画板子树的 JSX（比完整文档更快）

填充与导出

工具	用途
set_fill	设置节点或画板的填充（背景）——纯色、渐变或图像。自动处理双重写入。
export_image	将画板或节点导出为图像（PNG、JPEG、WebP、SVG）。返回 Base64 数据 URL。

主题

工具	用途
get_theme	返回当前主题令牌（颜色、字体、圆角）和活动模式
set_theme	设置主题令牌——颜色、字体、边框圆角。支持部分更新。
set_theme_mode	在浅色/深色/自定义模式之间切换
reset_theme	将主题重置为默认值

设计验证

工具	用途
audit_design	根据专业质量规则审核设计：排版（比例、字重对比、字号）、颜色（中性色一致性、纯黑、低对比度组合）、间距（4 pt 网格、触控目标）和 AI 低质设计检测（单调的布局）。传入 artboardId 可审核单个画板；省略则审核所有画板。
repair_design	在一次操作中对整个文档（或单个画板）应用安全、确定性的修复：补全缺失的 w-full、补全缺失的 flex、将任意 Tailwind 值转换为内联样式、将纯黑替换为 zinc-950、增大触控目标、填充占位图像、为文本补上默认值。传入 dryRun: true 可预览。

图片搜索

工具	用途
search_images	搜索免费图库图片（Lummi）。无需会话。返回可与 add_node 或 set_fill 配合使用的网址。

---

原生动画 — 为现有设计添加动画

Efecto 具有原生图层动画系统。请勿使用 Tailwind animate-*、transition-* 或 duration-* 类来制作动画。

“为此添加动画”的工作流：

1. 使用 get_selection、get_document、get_node_tree 或 list_artboards 检查目标。
2. 调用 list_animation_presets 查看支持的预设 ID 和设置。
3. 选择有意义的图层：主视觉图片、标题、辅助文案、CTA、卡片、图标或产品视觉元素。避免为每个嵌套子元素都添加动画。
4. 调用 apply_animation_plan 并设置带时间的条目。使用 mode: "replace" 创建新的动画系统，或使用 mode: "append" 添加退出/尾声动画。
5. 当画板需要明确的播放结束时间时，使用 update_artboard 设置 timelineDuration。
6. 使用 select_nodes 高亮已更改的图层。

时间设置默认值：

• 小型 UI 元素：0.18-0.35s。
• 主视觉/幻灯片元素：0.35-0.6s。
• 同级元素的交错延迟：0.04-0.12s。
• 进入动画：ease-out。
• 退出动画：ease-in。

预设使用建议：

• fade-in：用于辅助内容，效果细腻。
• slide-in：用于方向性显现，通常移动 16-48px。
• scale-in：用于卡片、产品图片、徽章和模态框。
• blur-in：用于电影感/编辑风格的显现。
• tilt-in、spin-in、bounce-in、pop-spark：用于活泼或促销场景。
• mask-in、fade-mask-in、slide-mask-in、scale-mask-in：用于高冲击力的主视觉、画框或标题显现。使用 maskStyle: "linear" 实现干净的擦除效果，使用 "diagonal" 增添编辑风格的活力，使用 "iris" 实现聚光显现。使用 maskDirection 设置边缘移动方向，使用 maskOrigin 设置光圈原点。
• mask-reveal、iris-reveal：仍可使用的旧版组合别名，但建议优先使用上述明确指定的遮罩预设。
• 退出预设（fade-out、slide-out、scale-out 等）应留出足够的阅读时间再开始。

文本节点可使用 appearBy: "word" 或 "line" 逐词或逐行显现标题。仅在动态标题场景中使用 "char"；非文本节点必须使用 "block"。

示例：

apply_animation_plan
  mode: "replace"
  animations: [
    { nodeId: "<headline-id>", presetId: "fade-in", offset: 0, settings: { duration: 0.55, easing: "ease-out", appearBy: "word" } },
    { nodeId: "<hero-image-id>", presetId: "scale-in", offset: 0.08, settings: { duration: 0.5, easing: "ease-out", scaleFrom: 0.96 } },
    { nodeId: "<cta-id>", presetId: "slide-in", offset: 0.28, settings: { duration: 0.35, easing: "ease-out", direction: "up", distance: 20 } }
  ]

---

图片 — 搜索并使用真实照片

Efecto 内置由 Lummi 提供支持的图片搜索功能。Lummi 是一个提供免费高质量图库照片、插画和 3D 渲染图的资源库。请使用此功能，而非占位图片，让设计显得精致、真实。

search_images 工具

此工具无需会话即可使用——随时调用，甚至可以在创建会话之前调用。

search_images
  query: "mountain landscape"
  orientation: "horizontal"
  limit: 4

返回包含 url、thumbnail、alt、width、height、photographer 和 orientation 的图片列表。

筛选条件

筛选条件	值	使用时机
query	任意搜索词	始终使用——描述所需内容（“团队协作”、“抽象渐变”、“咖啡馆”）
orientation	horizontal、vertical、square	与布局匹配：主视觉横幅用横向，移动端/快拍用纵向，卡片用正方形
type	photo、illustration、3d	默认返回全部类型。写实图像用 "photo"，风格化图形用 "illustration"
luminance	dark、neutral、bright	与设计氛围匹配：深色主题页面用 "dark"，明亮通透的设计用 "bright"
limit	1–20（默认值：6）	数量保持较少（3–6），避免上下文过载

工作流：搜索 → 应用

步骤 1：搜索图片

search_images
  query: "modern office workspace"
  orientation: "horizontal"
  luminance: "bright"
  limit: 3

步骤 2a：添加为图片节点

add_node
  parentId: "<section-id>"
  type: "image"
  src: "<url-from-search>"
  alt: "Modern office workspace"
  className: "w-full h-[400px] rounded-2xl object-cover"

步骤 2b：设置为背景填充

set_fill
  targetId: "<section-id>"
  fill: { type: "image", url: "<url-from-search>", size: "cover", position: "center" }

步骤 2c：在 JSX 中使用（add_section）

add_section
  parentId: "<artboard-id>"
  jsx: '<section className="flex items-center gap-16 px-16 py-24 w-full">
    <div className="flex flex-col gap-6 grow">
      <h1 className="text-5xl font-bold text-gray-900">Our Story</h1>
      <p className="text-lg text-gray-500">Building the future of design.</p>
    </div>
    <img src="<url-from-search>" alt="Team at work" className="w-[560px] h-[380px] rounded-2xl object-cover" />
  </section>'

提示

• 先搜索，再设计。 先找到图片，再围绕图片构建布局。与事后再添加图片相比，这样能打造出更好的构图。
• 让图片方向与布局匹配。 Hero 区域使用横向图片，侧边栏／移动端使用纵向图片，网格卡片使用方形图片。
• 使用亮度筛选器。 对于深色主题设计，搜索 luminance: "dark"，以便找到能自然融入深色背景的图片。
• 在图片节点上设置 object-cover，让图片填满容器且不失真。
• 优先使用真实图片，而非占位符。 不要使用 <div className="w-full h-[400px] bg-gray-100 rounded-2xl" />，而应搜索相关图片并使用。

---

着色器节点与视觉效果

着色器节点是一种强大的节点类型，结合了生成式视觉效果、图像／视频处理和视觉特效（ASCII、抖动、半色调、故障风格、艺术滤镜）。它们通过 WebGL 渲染，可以像其他节点一样放置在设计中的任意位置。

创建着色器节点

使用 add_node 和 type: "shader"：

add_node
  parentId: "<artboard-id>"
  type: "shader"
  shaderType: "meshGradient"
  className: "w-full h-[400px] rounded-2xl"

输入源

输入类型	描述	关键属性
shader（默认）	生成式 WebGL 视觉效果	shaderType、shaderSettings
image	对图像应用特效	mediaInput: { mediaUrl, mediaType: "image", objectFit }
video	对视频应用特效	mediaInput: { mediaUrl, mediaType: "video" }
fill	对纯色应用特效	fillColor: "#hex"

生成式着色器类型（11 种）

着色器	描述	最适用于
meshGradient	平滑的有机色彩混合	Hero 背景、氛围视觉效果
dotGrid	动态点阵图案	科技／数据美学风格
voronoi	基于单元的有机图案	抽象纹理
liquidMetal	金属流体模拟	高端／奢华视觉效果
chrome	镀铬反射效果	大胆、反光的点缀
pulsar	径向脉冲能量	动态、引人注目
blackHole	引力扭曲效果	戏剧性的深色视觉效果
glass	磨砂玻璃折射	微妙、优雅的叠加效果
spiral	螺旋运动图案	令人着迷、活泼有趣
particles	漂浮粒子系统	氛围感、大气感
fireworks	爆发式粒子效果	庆祝、能量感

视觉特效（28 种）

在任意输入源上应用特效。设置 effectId 和 effectEnabled: true：

add_node
  parentId: "<section-id>"
  type: "shader"
  inputType: "image"
  mediaInput: { mediaUrl: "<image-url>", mediaType: "image", objectFit: "cover" }
  effectId: "ascii-standard"
  effectEnabled: true
  className: "w-full h-[500px] rounded-2xl"

类别	特效 ID	描述
ASCII	ascii-standard、ascii-dense、ascii-minimal、ascii-blocks、ascii-braille、ascii-technical、ascii-matrix、ascii-hatching	将视觉效果转换为 ASCII 字符画
抖动	dither-floyd-steinberg、dither-atkinson、dither-stucki、dither-sierra、dither-sierra-lite、dither-burkes、dither-jarvis-judice-ninke、dither-two-row-sierra、color-separation	复古抖动图案
半色调	halftone-mono、halftone-cmyk	印刷风格的点阵图案（单色或 CMYK）
故障风格	glitch-vhs、glitch-digital、glitch-weird、glitch-chromatic	数字损坏与扭曲
艺术	art-kuwahara、art-crosshatch、art-lineart、art-engraving、art-stipple	绘画与素描风格滤镜

后期处理堆栈

使用 postProcesses 叠加更多特效：scanlines、vignette、bloom、grain、noise、pixelate、wave、rgb-glitch、brightness-contrast、color-tint、sepia、grid、dot-screen、light-beams、warp、motion-blur、chromatic-aberration、curvature。

postProcesses: [
  { type: "grain", enabled: true, settings: { intensity: 0.3 } },
  { type: "vignette", enabled: true, settings: { intensity: 0.5 } }
]

常见方案

从图像生成 ASCII 艺术 Hero：

search_images  query: "city skyline"  orientation: "horizontal"  limit: 1
add_node
  parentId: "<artboard-id>"
  type: "shader"
  inputType: "image"
  mediaInput: { mediaUrl: "<url>", mediaType: "image", objectFit: "cover" }
  effectId: "ascii-standard"
  effectEnabled: true
  className: "w-full h-[500px]"

生成式渐变背景：

add_node
  parentId: "<artboard-id>"
  type: "shader"
  shaderType: "meshGradient"
  className: "w-full h-[600px]"

对照片应用半色调效果：

add_node
  parentId: "<section-id>"
  type: "shader"
  inputType: "image"
  mediaInput: { mediaUrl: "<url>", mediaType: "image", objectFit: "cover" }
  effectId: "halftone-mono"
  effectEnabled: true
  className: "w-[400px] h-[400px] rounded-2xl"

---

节点类型与 HTML 标签

每个节点都与一个 HTML 元素一一对应。type 决定行为；tag 决定渲染时使用的 HTML 元素。

类型	默认标签	所有有效标签	内容属性
frame	div	div, section, article, aside, main, nav, header, footer, ul, ol, li, figure, figcaption, form, table, thead, tbody, tr, th, td	（无 — 纯容器）
text	p	p, span, h1, h2, h3, h4, h5, h6, blockquote, label, li	textContent
image	img	img	src、alt、objectFit
button	button	button, a, div	textContent、variant
link	a	a, button, div, span	textContent、href、target
icon	svg	svg	iconName（kebab-case）、iconLibrary、iconWeight
input	input	input, textarea, select	placeholder、inputType、label
video	video	video	src、poster、autoPlay、loop、muted
shader	（WebGL）	—	shaderType、inputType、effectId、effectEnabled、effectSettings、postProcesses
component	div	div	componentId、overrides

JSX 中标签决定类型

为 add_section 编写 JSX 时，HTML 标签决定节点类型：

<div>       -> frame       <img>        -> image
<section>   -> frame       <button>     -> button
<nav>       -> frame       <a>          -> link
<header>    -> frame       <input>      -> input
<footer>    -> frame       <video>      -> video
<h1>-<h6>   -> text        <svg>        -> icon
<p>         -> text        <i>          -> icon
<span>      -> text        <Icon>       -> icon
                           <HeartIcon>  -> icon (name resolved from tag)

---

add_section JSX 格式

这是构建布局的主要方式。使用 HTML 标签和 Tailwind className 属性编写标准 JSX。

格式规则

1. 使用 HTML 标签 — div、section、nav、h1、p、img、button、a 等。
2. 使用 className 设置样式 — 仅使用 Tailwind CSS 类
3. 文本写在标签之间 — <h1 className="...">Hello</h1>
4. 图片使用自闭合标签 — <img src="https://..." alt="..." className="..." />
5. 仅在引用现有节点时使用 data-id（来自 get_document）
6. 不要使用 React 专属语法 — 不要使用 onClick、useState、片段或组件
7. 图标使用带有 icon 属性的 <svg> — <svg icon="arrow-right" className="w-5 h-5 text-gray-600" />

示例：完整分区

<section className="flex flex-col items-center gap-12 px-16 py-24 bg-white w-full">
  <div className="flex flex-col items-center gap-4 max-w-2xl">
    <span className="text-sm font-semibold text-blue-600 uppercase tracking-widest">Why Choose Us</span>
    <h2 className="text-4xl font-bold text-gray-900 text-center">Everything you need to scale</h2>
    <p className="text-lg text-gray-500 text-center">Built for modern teams that move fast and ship faster.</p>
  </div>
  <div className="flex gap-8 w-full max-w-5xl">
    <div className="flex flex-col gap-3 p-8 bg-gray-50 rounded-2xl grow">
      <svg icon="lightning" className="w-8 h-8 text-blue-600" />
      <h3 className="text-lg font-semibold text-gray-900">Lightning Fast</h3>
      <p className="text-sm text-gray-500">Deploy in seconds, not hours. Our edge network ensures sub-50ms latency worldwide.</p>
    </div>
    <div className="flex flex-col gap-3 p-8 bg-gray-50 rounded-2xl grow">
      <svg icon="shield-check" className="w-8 h-8 text-blue-600" />
      <h3 className="text-lg font-semibold text-gray-900">Enterprise Security</h3>
      <p className="text-sm text-gray-500">SOC 2 certified with end-to-end encryption. Your data stays yours.</p>
    </div>
    <div className="flex flex-col gap-3 p-8 bg-gray-50 rounded-2xl grow">
      <svg icon="headset" className="w-8 h-8 text-blue-600" />
      <h3 className="text-lg font-semibold text-gray-900">24/7 Support</h3>
      <p className="text-sm text-gray-500">Our team is always on. Get answers in minutes, not days.</p>
    </div>
  </div>
</section>

---

图标

Efecto 支持 4 个图标库，合计约 9,400 个图标。图标以 SVG 形式渲染，并从 currentColor 继承颜色。

如何在 JSX 中编写图标

标准格式：

<svg icon="arrow-right" className="w-5 h-5 text-gray-600" />

• icon — 图标名称，使用 kebab-case（例如 arrow-right、magnifying-glass、google-logo）
• className — 使用 w-* / h-* 设置尺寸，使用 text-* 类设置颜色
• iconLibrary — 可选：phosphor（默认）、lucide、heroicons、radix
• iconWeight — 可选：thin、light、regular（默认）、bold、fill、duotone（仅限 Phosphor）

常见图标名称（Phosphor — 默认图标库）

分类	图标
箭头	arrow-right、arrow-left、arrow-up、arrow-down、caret-right、caret-down
操作	check、x、plus、minus、magnifying-glass、funnel、pencil、trash
界面	gear、sliders、dots-three、list、squares-four、sidebar
社交	google-logo、apple-logo、github-logo、x-logo、linkedin-logo、discord-logo、facebook-logo、instagram-logo、youtube-logo
对象	envelope、lock、eye、eye-slash、star、heart、user、users、house、lightning、fire、rocket
媒体	image、camera、play、pause、microphone、speaker-high
商务	shopping-cart、credit-card、currency-dollar、receipt、package

图标尺寸指南

w-3 h-3     /* 12px — tiny, inline indicators */
w-4 h-4     /* 16px — inline with small text */
w-5 h-5     /* 20px — standard UI icon */
w-6 h-6     /* 24px — default, comfortable */
w-8 h-8     /* 32px — feature icons, cards */
w-10 h-10   /* 40px — hero feature icons */
w-12 h-12   /* 48px — large decorative */
w-16 h-16   /* 64px — hero section centerpiece */

分区中的图标用法

带图标的功能卡片：

<div className="flex flex-col gap-3 p-8 bg-gray-50 rounded-2xl grow">
  <svg icon="lightning" className="w-8 h-8 text-blue-600" />
  <h3 className="text-lg font-semibold text-gray-900">Lightning Fast</h3>
  <p className="text-sm text-gray-500">Deploy in seconds, not hours.</p>
</div>

带图标的按钮（图标是同级元素，不是子元素）：

<div className="flex items-center gap-2 bg-gray-900 text-white px-5 py-2.5 rounded-lg">
  <span className="text-sm font-medium">Get Started</span>
  <svg icon="arrow-right" className="w-4 h-4" />
</div>

社交图标行：

<div className="flex items-center gap-4">
  <svg icon="x-logo" className="w-5 h-5 text-gray-400" />
  <svg icon="github-logo" className="w-5 h-5 text-gray-400" />
  <svg icon="linkedin-logo" className="w-5 h-5 text-gray-400" />
  <svg icon="discord-logo" className="w-5 h-5 text-gray-400" />
</div>

带图标的输入框：

<div className="flex items-center gap-2 border border-gray-200 rounded-lg px-3 py-2 bg-white">
  <svg icon="magnifying-glass" className="w-4 h-4 text-gray-400" />
  <input placeholder="Search..." className="text-sm text-gray-900 grow" />
</div>

使用其他图标库（Lucide）：

<svg icon="check" iconLibrary="lucide" className="w-5 h-5 text-green-600" />

使用字重变体（Phosphor bold）：

<svg icon="star" iconWeight="fill" className="w-5 h-5 text-yellow-500" />

---

可用的 Tailwind CSS 模式

布局

flex                    /* Horizontal flex row */
flex flex-col           /* Vertical flex column */
items-center            /* Center cross-axis */
items-start             /* Align to start */
justify-between         /* Space between children */
justify-center          /* Center main-axis */
gap-2 gap-4 gap-8      /* Gap between flex children */
grow                    /* Fill remaining space (DO NOT use flex-1) */

间距

p-4 p-6 p-8 p-12       /* Padding all sides */
px-6 py-4               /* Horizontal / vertical padding */
pt-8 pb-16              /* Top / bottom padding */
mx-auto                 /* Center horizontally */

尺寸

w-full                  /* Full width of parent */
w-auto                  /* Width from content */
w-fit                   /* Shrink-wrap width */
w-[600px]               /* Fixed pixel width */
max-w-2xl max-w-5xl     /* Maximum width constraints */
min-h-screen            /* Minimum full viewport height */
h-[400px]               /* Fixed pixel height */

排版

text-xs text-sm text-base text-lg text-xl text-2xl text-3xl text-4xl text-5xl text-6xl text-7xl text-8xl text-9xl
font-light font-normal font-medium font-semibold font-bold font-extrabold font-black
leading-tight leading-snug leading-normal leading-relaxed
tracking-tight tracking-normal tracking-wide tracking-widest
text-left text-center text-right
uppercase lowercase capitalize

主题感知颜色（首选）

Efecto 支持语义化令牌系统。启用主题后，这些类会自动适配浅色、深色和自定义模式：

/* Backgrounds */
bg-background              /* Page/artboard background */
bg-card                    /* Card surfaces */
bg-popover                 /* Popover/dropdown surfaces */
bg-primary                 /* Primary action backgrounds */
bg-secondary               /* Secondary surfaces */
bg-muted                   /* Muted/subtle backgrounds */
bg-accent                  /* Accent highlights */
bg-destructive             /* Destructive/error backgrounds */
bg-input                   /* Input field backgrounds */

/* Text */
text-foreground            /* Primary text */
text-primary-foreground    /* Text on primary backgrounds */
text-secondary-foreground  /* Text on secondary surfaces */
text-muted-foreground      /* Muted/secondary text */
text-accent-foreground     /* Text on accent backgrounds */
text-card-foreground       /* Text on cards */
text-popover-foreground    /* Text on popovers */
text-destructive-foreground /* Text on destructive backgrounds */

/* Borders */
border-border              /* Default border color */
ring-ring                  /* Focus ring color */

何时使用语义化颜色与硬编码颜色：

• 语义化（bg-primary、text-foreground）：UI 组件、按钮、卡片、文本——任何应随主题或模式变化而适配的内容
• 硬编码（bg-blue-500、text-white）：装饰元素、品牌专属颜色、插画、渐变

这些类映射到 CSS 自定义属性（--background、--primary 等），并会在主题或模式变化时自动更新。shadcn 是默认令牌系统，但这些都是标准 CSS 变量——任何提供这些变量的设计系统都能使用。

颜色（仅限命名颜色）

使用 Tailwind 命名颜色。切勿使用任意十六进制值，例如 bg-[#f9f9f9]——它会在运行时静默失效。

/* Backgrounds */
bg-white bg-black bg-gray-50 bg-gray-100 bg-gray-900 bg-neutral-950
bg-blue-50 bg-blue-500 bg-blue-600 bg-indigo-500 bg-purple-500
bg-green-50 bg-green-500 bg-red-50 bg-red-500 bg-amber-50 bg-yellow-400

/* Text */
text-white text-black text-gray-400 text-gray-500 text-gray-600 text-gray-700 text-gray-900
text-blue-600 text-blue-500 text-indigo-600 text-green-600 text-red-600

/* Borders */
border-gray-100 border-gray-200 border-gray-300 border-blue-500

/* If you MUST use a specific hex color, use inline style instead: */
style: { "background-color": "#f9f9f9" }

边框与圆角

border border-2                      /* Border width */
border-gray-200 border-gray-300      /* Border color */
rounded rounded-lg rounded-xl rounded-2xl rounded-full  /* Border radius */

效果

shadow-sm shadow shadow-md shadow-lg shadow-xl
opacity-50 opacity-75
ring-1 ring-2 ring-blue-500          /* Ring / outline */

渐变

bg-gradient-to-r from-blue-500 to-purple-500
bg-gradient-to-b from-white to-gray-50
bg-gradient-to-br from-indigo-500 via-purple-500 to-pink-500

填充（首选：set_fill 工具）

对于纯色、渐变和图像背景，优先使用 set_fill 工具，而不是手动设置 className/style。它会自动处理双写模式。

# Solid color
set_fill  targetId: "<id>"  fill: { type: "solid", color: "blue-500" }

# Linear gradient
set_fill  targetId: "<id>"  fill: { type: "gradient", gradient: { type: "linear", angle: 90, stops: [{ color: "#3b82f6", position: 0 }, { color: "#8b5cf6", position: 1 }] } }

# Radial gradient
set_fill  targetId: "<id>"  fill: { type: "gradient", gradient: { type: "radial", stops: [{ color: "#3b82f6", position: 0 }, { color: "#1e1b4b", position: 1 }] } }

# Image fill
set_fill  targetId: "<id>"  fill: { type: "image", url: "https://...", size: "cover", position: "center" }

# Clear fill
set_fill  targetId: "<id>"

节点和画板均适用。对于画板，纯色填充会更新 backgroundColor，以保持向后兼容。

链接与锚点

任何节点都可以通过 add_node、update_node 或 batch_update 中的 link 属性变为可点击。使用 elementId 将节点设为锚点目标。

链接类型	用例	必填字段
url	外部 URL	url，可选的 target: "_blank"
page	跳转到另一个画板	pageId（画板 ID）
section	滚动到元素锚点	sectionId（与某个 elementId 匹配）
email	mailto 链接	email
phone	tel 链接	phone

# Make a button link to an external URL
update_node  nodeId: "<btn-id>"  link: { type: "url", url: "https://example.com", target: "_blank" }

# Mark a section as an anchor target
update_node  nodeId: "<section-id>"  elementId: "pricing"

# Link a nav item to that anchor
update_node  nodeId: "<nav-link-id>"  link: { type: "section", sectionId: "pricing" }

# Link to another artboard (page navigation)
update_node  nodeId: "<link-id>"  link: { type: "page", pageId: "<artboard-id>" }

# Remove a link
update_node  nodeId: "<id>"  link: null

适用于任何节点类型——框架、文本、图像、按钮。对于已发布的网站，page 和 section 链接会变成真实导航。

---

画板最佳实践

标准尺寸

名称	宽度	高度	用例
桌面	1440	900+	完整的网站页面
桌面（窄版）	1280	800+	以内容为主的页面
平板电脑	768	1024	平板电脑响应式视图
移动设备	375	812	iPhone / 移动视图

始终从以下内容开始

create_artboard:
  name: "Homepage"
  width: 1440
  height: 900
  backgroundColor: "#ffffff"
  className: "flex flex-col"

• className: "flex flex-col" 至关重要——没有它，子元素会重叠在 (0,0)
• backgroundColor 是内联样式属性，不是 Tailwind 类
• 内容溢出时高度会自动增长，但应设置初始高度

---

常见区块模式

导航栏

<nav className="flex items-center justify-between px-16 py-5 bg-white w-full border-b border-gray-100">
  <h2 className="text-xl font-bold text-gray-900">Acme</h2>
  <div className="flex items-center gap-8">
    <a className="text-sm font-medium text-gray-600" href="#">Features</a>
    <a className="text-sm font-medium text-gray-600" href="#">Pricing</a>
    <a className="text-sm font-medium text-gray-600" href="#">About</a>
    <button className="px-5 py-2.5 text-sm font-medium text-white bg-gray-900 rounded-lg">Get Started</button>
  </div>
</nav>

主视觉区块（居中）

<section className="flex flex-col items-center justify-center gap-8 px-16 py-32 bg-white w-full">
  <div className="flex flex-col items-center gap-6 max-w-3xl">
    <span className="px-4 py-1.5 text-xs font-semibold text-blue-700 bg-blue-50 rounded-full uppercase tracking-wider">Now in Beta</span>
    <h1 className="text-6xl font-bold text-gray-900 text-center leading-tight">Build beautiful websites at the speed of thought</h1>
    <p className="text-xl text-gray-500 text-center">The AI-powered design tool that turns ideas into production-ready pages. No code required.</p>
  </div>
  <div className="flex items-center gap-4">
    <button className="px-8 py-3.5 text-base font-semibold text-white bg-blue-600 rounded-xl">Start Free Trial</button>
    <button className="px-8 py-3.5 text-base font-semibold text-gray-700 bg-white border-2 border-gray-200 rounded-xl">Watch Demo</button>
  </div>
</section>

主视觉区块（分栏——左侧文本，右侧图像）

<section className="flex items-center gap-16 px-16 py-24 bg-white w-full">
  <div className="flex flex-col gap-6 grow">
    <h1 className="text-5xl font-bold text-gray-900 leading-tight">Ship your next product in record time</h1>
    <p className="text-lg text-gray-500">From prototype to production in minutes. Our platform handles the complexity so you can focus on what matters.</p>
    <div className="flex items-center gap-4">
      <button className="px-6 py-3 text-base font-semibold text-white bg-gray-900 rounded-lg">Get Started</button>
      <a className="text-base font-medium text-gray-600" href="#">Learn more</a>
    </div>
  </div>
  <img src="https://placehold.co/600x400" alt="Product screenshot" className="w-[560px] h-[380px] rounded-2xl object-cover bg-gray-100" />
</section>

功能网格（3 列）

<section className="flex flex-col items-center gap-16 px-16 py-24 bg-gray-50 w-full">
  <div className="flex flex-col items-center gap-4 max-w-2xl">
    <h2 className="text-4xl font-bold text-gray-900 text-center">Powerful features for modern teams</h2>
    <p className="text-lg text-gray-500 text-center">Everything you need to design, build, and ship — all in one place.</p>
  </div>
  <div className="flex gap-8 w-full max-w-6xl">
    <div className="flex flex-col gap-4 p-8 bg-white rounded-2xl shadow-sm grow">
      <div className="flex items-center justify-center w-12 h-12 bg-blue-100 rounded-xl">
        <span className="text-blue-600 text-lg font-bold">1</span>
      </div>
      <h3 className="text-xl font-semibold text-gray-900">Real-Time Collaboration</h3>
      <p className="text-sm text-gray-500 leading-relaxed">Work together with your team in real time. See cursors, selections, and changes as they happen.</p>
    </div>
    <div className="flex flex-col gap-4 p-8 bg-white rounded-2xl shadow-sm grow">
      <div className="flex items-center justify-center w-12 h-12 bg-green-100 rounded-xl">
        <span className="text-green-600 text-lg font-bold">2</span>
      </div>
      <h3 className="text-xl font-semibold text-gray-900">One-Click Deploy</h3>
      <p className="text-sm text-gray-500 leading-relaxed">Push to production with a single click. Built-in CI/CD, preview deployments, and rollbacks.</p>
    </div>
    <div className="flex flex-col gap-4 p-8 bg-white rounded-2xl shadow-sm grow">
      <div className="flex items-center justify-center w-12 h-12 bg-purple-100 rounded-xl">
        <span className="text-purple-600 text-lg font-bold">3</span>
      </div>
      <h3 className="text-xl font-semibold text-gray-900">AI Assistant</h3>
      <p className="text-sm text-gray-500 leading-relaxed">Built-in AI that understands your codebase. Generate components, fix bugs, and refactor with natural language.</p>
    </div>
  </div>
</section>

用户评价 / 社会认同

<section className="flex flex-col items-center gap-12 px-16 py-24 bg-white w-full">
  <div className="flex flex-col items-center gap-6 max-w-2xl">
    <p className="text-2xl text-gray-700 text-center leading-relaxed italic">"This tool completely transformed our workflow. We shipped our redesign in two weeks instead of two months."</p>
    <div className="flex items-center gap-4">
      <div className="w-12 h-12 bg-gray-200 rounded-full"></div>
      <div className="flex flex-col">
        <span className="text-sm font-semibold text-gray-900">Sarah Chen</span>
        <span className="text-sm text-gray-500">VP of Design, Stripe</span>
      </div>
    </div>
  </div>
  <div className="flex items-center gap-12">
    <span className="text-sm font-medium text-gray-400">Trusted by</span>
    <span className="text-lg font-bold text-gray-300">Stripe</span>
    <span className="text-lg font-bold text-gray-300">Vercel</span>
    <span className="text-lg font-bold text-gray-300">Linear</span>
    <span className="text-lg font-bold text-gray-300">Notion</span>
    <span className="text-lg font-bold text-gray-300">Figma</span>
  </div>
</section>

定价卡片

<section className="flex flex-col items-center gap-12 px-16 py-24 bg-gray-50 w-full">
  <div className="flex flex-col items-center gap-4">
    <h2 className="text-4xl font-bold text-gray-900">Simple, transparent pricing</h2>
    <p className="text-lg text-gray-500">No surprise fees. Cancel anytime.</p>
  </div>
  <div className="flex gap-8 w-full max-w-4xl">
    <div className="flex flex-col gap-6 p-8 bg-white rounded-2xl border border-gray-200 grow">
      <div className="flex flex-col gap-2">
        <h3 className="text-lg font-semibold text-gray-900">Starter</h3>
        <div className="flex items-baseline gap-1">
          <span className="text-4xl font-bold text-gray-900">$19</span>
          <span className="text-sm text-gray-500">/month</span>
        </div>
        <p className="text-sm text-gray-500">Perfect for individuals and small projects.</p>
      </div>
      <button className="w-full py-3 text-sm font-semibold text-gray-700 bg-gray-100 rounded-lg">Get Started</button>
    </div>
    <div className="flex flex-col gap-6 p-8 bg-gray-900 rounded-2xl grow">
      <div className="flex flex-col gap-2">
        <h3 className="text-lg font-semibold text-white">Pro</h3>
        <div className="flex items-baseline gap-1">
          <span className="text-4xl font-bold text-white">$49</span>
          <span className="text-sm text-gray-400">/month</span>
        </div>
        <p className="text-sm text-gray-400">For growing teams that need more power.</p>
      </div>
      <button className="w-full py-3 text-sm font-semibold text-gray-900 bg-white rounded-lg">Get Started</button>
    </div>
    <div className="flex flex-col gap-6 p-8 bg-white rounded-2xl border border-gray-200 grow">
      <div className="flex flex-col gap-2">
        <h3 className="text-lg font-semibold text-gray-900">Enterprise</h3>
        <div className="flex items-baseline gap-1">
          <span className="text-4xl font-bold text-gray-900">$99</span>
          <span className="text-sm text-gray-500">/month</span>
        </div>
        <p className="text-sm text-gray-500">For large organizations with custom needs.</p>
      </div>
      <button className="w-full py-3 text-sm font-semibold text-gray-700 bg-gray-100 rounded-lg">Contact Sales</button>
    </div>
  </div>
</section>

行动号召（CTA）

<section className="flex flex-col items-center gap-8 px-16 py-24 bg-gray-900 w-full">
  <h2 className="text-4xl font-bold text-white text-center">Ready to get started?</h2>
  <p className="text-lg text-gray-400 text-center max-w-xl">Join thousands of teams already building faster. Start your free trial today.</p>
  <div className="flex items-center gap-4">
    <button className="px-8 py-3.5 text-base font-semibold text-gray-900 bg-white rounded-xl">Start Free Trial</button>
    <button className="px-8 py-3.5 text-base font-semibold text-gray-300 bg-transparent border border-gray-700 rounded-xl">Talk to Sales</button>
  </div>
</section>

页脚

<footer className="flex items-center justify-between px-16 py-8 bg-white border-t border-gray-100 w-full">
  <span className="text-sm text-gray-500">2026 Acme Inc. All rights reserved.</span>
  <div className="flex items-center gap-6">
    <a className="text-sm text-gray-500" href="#">Privacy</a>
    <a className="text-sm text-gray-500" href="#">Terms</a>
    <a className="text-sm text-gray-500" href="#">Contact</a>
  </div>
</footer>

统计数据 / 指标行

<section className="flex items-center justify-center gap-16 px-16 py-16 bg-blue-600 w-full">
  <div className="flex flex-col items-center gap-2">
    <span className="text-4xl font-bold text-white">10K+</span>
    <span className="text-sm text-blue-200">Active Users</span>
  </div>
  <div className="flex flex-col items-center gap-2">
    <span className="text-4xl font-bold text-white">99.9%</span>
    <span className="text-sm text-blue-200">Uptime SLA</span>
  </div>
  <div className="flex flex-col items-center gap-2">
    <span className="text-4xl font-bold text-white">50ms</span>
    <span className="text-sm text-blue-200">Avg Latency</span>
  </div>
  <div className="flex flex-col items-center gap-2">
    <span className="text-4xl font-bold text-white">4.9/5</span>
    <span className="text-sm text-blue-200">User Rating</span>
  </div>
</section>

---

提示、注意事项与最佳实践

黄金法则

1. 修改现有设计前，始终先调用 get_document。你需要 data-id 属性。
2. 用户要求你在“这里”编辑或添加内容时，使用 get_selection——它会返回所选节点及其 JSX 子树，便于你进行上下文相关的编辑。
3. 切勿猜测节点 ID——始终从 get_document、get_selection 或 find_nodes 中读取。
4. 使用带 JSX 的 add_section 构建结构。它的效率远高于一次用 add_node 添加一个元素。
5. 对多个小改动使用 batch_update。一次调用即可替代多次调用。
6. **优先更新，而不是删除后重建。**使用 update_node 或 update_class。

关键注意事项

Artboard 的 className 必须包含 flex flex-col 否则，子元素会重叠在 (0,0) 位置。这是最常见的错误。

Artboard 的 backgroundColor 是属性，而不是 className

WRONG:  className: "bg-gray-900 flex flex-col"
RIGHT:  backgroundColor: "#1a1a1a", className: "flex flex-col"

切勿在 className 中使用任意十六进制颜色值 Tailwind 4 会在构建时生成 CSS。像 bg-[#f9f9f9] 这样的动态类在运行时没有对应的 CSS，因此不可见。

WRONG:  className: "bg-[#f9f9f9] text-[#333333]"
RIGHT:  className: "bg-gray-50 text-gray-700"
ALSO OK: style: { "background-color": "#f9f9f9", "color": "#333333" }

注意：系统会自动将任意十六进制颜色转换为内联样式，但建议优先使用命名颜色。

flex-1 不起作用——请改用 grow Tailwind 桥接层会将 flex-1 归类为未映射类。请使用 grow 实现相同效果。

Frame 节点没有 textContent Frame 类型（div、section、nav、header、footer）无法直接容纳文本。请在其中使用文本节点（h1、p、span）。

Button 节点会忽略子元素 Button 渲染器只使用 textContent。不要在 Button 内嵌套图标或其他元素——请改用 flex 容器包裹：

<div className="flex items-center gap-2 bg-blue-600 text-white px-5 py-2.5 rounded-lg">
  <span className="text-sm font-medium">Continue</span>
  <svg icon="arrow-right" className="w-4 h-4" />
</div>

顶层区块需要 w-full 自动修复器会添加此类，但请务必为 Artboard 的直接子元素添加 w-full，使其占满整个宽度。

没有 src 的图片会显示占位图 如果省略 src，系统会插入 https://placehold.co/600x400。用于生产环境的设计时，请务必提供真实的 src。

必需结构与质量门槛

• 为图层命名且名称应有意义。 为每个区块、布局组、卡片、文本块、控件、图片和图标添加简洁且具语义的 name 属性（例如，<section name="Hero">、<div name="Hero Copy">、<h1 name="Hero Heading">）。切勿使用 Frame、Text 或 Icon 这类通用名称；纯装饰且未命名的叶节点是唯一例外。
• 明确声明嵌套布局。 每个包含两个或更多子元素的 Frame 都必须在 className 中明确包含 flex 或 grid，包括嵌套包装器。添加匹配的方向、对齐、间距和换行类；不要依赖隐式块级流布局。
• 达到 WCAG AA 对比度要求。 普通文本的对比度必须达到 4.5:1，大号文本必须达到 3:1。根据文本最终渲染时的有效背景进行评估：有自身背景时使用自身背景，否则沿祖先 Frame 向上追溯至 Artboard，并将不透明度／Alpha 合成纳入计算。评估对比度前，先根据当前模式解析语义主题令牌。
• 持续审查，直到没有问题。 构建或编辑后，调用 audit_design。使用 batch_update 或 replace_section 修复所有 contrast-ratio、implicit-block-container 和 generic-layer-name 问题，然后再次调用 audit_design。如果使用 repair_design，请检查其更改并重新审查。只有在这三类问题都归零后才能宣布完成，并使用 get_document 确认有意义的图层仍保留语义名称。

设计技巧

• 最大宽度容器：使用居中对齐的 max-w-5xl 或 max-w-6xl，并将内容放在容器内，以确保文本宽度易于阅读
• 间距一致：使用 Tailwind 间距刻度（4、6、8、12、16、24 是常用的区块内边距值）
• 颜色层级：标题使用 gray-900，正文使用 gray-500，次要文本使用 gray-400
• 区块节奏：交替使用白色和 gray-50 背景，以区分不同区块
• 按钮层级：主要按钮 = 深色实底；次要按钮 = 描边或浅色背景

---

完整示例：SaaS 落地页

从头开始逐步构建完整的 SaaS 落地页。

步骤 1：创建会话和 Artboard

create_session
  label: "SaaS Landing Page"

如果要恢复打开的 Efecto URL，请改用 attach_session。等待浏览器连接（wait_for_connection），然后：

create_artboard:
  name: "Landing Page"
  width: 1440
  height: 900
  backgroundColor: "#ffffff"
  className: "flex flex-col"

步骤 2：导航栏

add_section:
  parentId: "<artboard-id>"
  jsx: |
    <nav className="flex items-center justify-between px-16 py-5 bg-white w-full border-b border-gray-100">
      <div className="flex items-center gap-2">
        <div className="w-8 h-8 bg-blue-600 rounded-lg"></div>
        <h2 className="text-lg font-bold text-gray-900">Launchpad</h2>
      </div>
      <div className="flex items-center gap-8">
        <a className="text-sm font-medium text-gray-600" href="#">Product</a>
        <a className="text-sm font-medium text-gray-600" href="#">Features</a>
        <a className="text-sm font-medium text-gray-600" href="#">Pricing</a>
        <a className="text-sm font-medium text-gray-600" href="#">Docs</a>
      </div>
      <div className="flex items-center gap-3">
        <a className="text-sm font-medium text-gray-600" href="#">Sign In</a>
        <button className="px-5 py-2 text-sm font-medium text-white bg-blue-600 rounded-lg">Start Free</button>
      </div>
    </nav>

步骤 3：主视觉区

add_section:
  parentId: "<artboard-id>"
  jsx: |
    <section className="flex flex-col items-center gap-10 px-16 py-32 bg-white w-full">
      <div className="flex flex-col items-center gap-6 max-w-3xl">
        <span className="px-4 py-1.5 text-xs font-semibold text-blue-700 bg-blue-50 rounded-full uppercase tracking-wider">New: AI-Powered Workflows</span>
        <h1 className="text-6xl font-extrabold text-gray-900 text-center leading-tight tracking-tight">Ship products faster than ever before</h1>
        <p className="text-xl text-gray-500 text-center leading-relaxed">The all-in-one platform for modern product teams. Design, build, test, and deploy from a single dashboard.</p>
      </div>
      <div className="flex items-center gap-4">
        <button className="px-8 py-4 text-base font-semibold text-white bg-blue-600 rounded-xl">Start Free Trial</button>
        <button className="px-8 py-4 text-base font-semibold text-gray-700 bg-white border-2 border-gray-200 rounded-xl">Watch Demo</button>
      </div>
      <p className="text-sm text-gray-400">Free for 14 days. No credit card required.</p>
    </section>

步骤 4：社会认同栏

add_section:
  parentId: "<artboard-id>"
  jsx: |
    <section className="flex items-center justify-center gap-12 px-16 py-12 bg-gray-50 border-y border-gray-100 w-full">
      <span className="text-sm text-gray-400">Trusted by leading teams at</span>
      <span className="text-lg font-bold text-gray-300">Stripe</span>
      <span className="text-lg font-bold text-gray-300">Vercel</span>
      <span className="text-lg font-bold text-gray-300">Linear</span>
      <span className="text-lg font-bold text-gray-300">Notion</span>
      <span className="text-lg font-bold text-gray-300">Figma</span>
    </section>

步骤 5：功能网格

add_section:
  parentId: "<artboard-id>"
  jsx: |
    <section className="flex flex-col items-center gap-16 px-16 py-24 bg-white w-full">
      <div className="flex flex-col items-center gap-4 max-w-2xl">
        <h2 className="text-4xl font-bold text-gray-900 text-center">Built for speed, designed for scale</h2>
        <p className="text-lg text-gray-500 text-center">Powerful tools that grow with your team. No compromises.</p>
      </div>
      <div className="flex gap-6 w-full max-w-5xl">
        <div className="flex flex-col gap-4 p-8 bg-gray-50 rounded-2xl grow">
          <div className="flex items-center justify-center w-12 h-12 bg-blue-100 rounded-xl">
            <span className="text-blue-600 font-bold">1</span>
          </div>
          <h3 className="text-lg font-semibold text-gray-900">Visual Editor</h3>
          <p className="text-sm text-gray-500 leading-relaxed">Drag-and-drop interface with pixel-perfect precision. Design at the speed of thought.</p>
        </div>
        <div className="flex flex-col gap-4 p-8 bg-gray-50 rounded-2xl grow">
          <div className="flex items-center justify-center w-12 h-12 bg-green-100 rounded-xl">
            <span className="text-green-600 font-bold">2</span>
          </div>
          <h3 className="text-lg font-semibold text-gray-900">Instant Deploy</h3>
          <p className="text-sm text-gray-500 leading-relaxed">One-click deployment to our global CDN. Preview environments for every branch.</p>
        </div>
        <div className="flex flex-col gap-4 p-8 bg-gray-50 rounded-2xl grow">
          <div className="flex items-center justify-center w-12 h-12 bg-purple-100 rounded-xl">
            <span className="text-purple-600 font-bold">3</span>
          </div>
          <h3 className="text-lg font-semibold text-gray-900">AI Copilot</h3>
          <p className="text-sm text-gray-500 leading-relaxed">AI that understands your design system. Generate components, layouts, and content automatically.</p>
        </div>
      </div>
    </section>

步骤 6：行动号召

add_section:
  parentId: "<artboard-id>"
  jsx: |
    <section className="flex flex-col items-center gap-8 px-16 py-24 bg-gray-900 w-full">
      <h2 className="text-4xl font-bold text-white text-center">Start building today</h2>
      <p className="text-lg text-gray-400 text-center max-w-xl">Join 10,000+ teams already shipping faster with Launchpad. Free trial, no strings attached.</p>
      <div className="flex items-center gap-4">
        <button className="px-8 py-4 text-base font-semibold text-gray-900 bg-white rounded-xl">Start Free Trial</button>
        <button className="px-8 py-4 text-base font-semibold text-gray-300 bg-transparent border border-gray-700 rounded-xl">Talk to Sales</button>
      </div>
    </section>

步骤 7：页脚

add_section:
  parentId: "<artboard-id>"
  jsx: |
    <footer className="flex items-center justify-between px-16 py-8 bg-gray-900 border-t border-gray-800 w-full">
      <div className="flex items-center gap-2">
        <div className="w-6 h-6 bg-blue-600 rounded-md"></div>
        <span className="text-sm font-semibold text-gray-400">Launchpad</span>
      </div>
      <span className="text-sm text-gray-500">2026 Launchpad Inc. All rights reserved.</span>
      <div className="flex items-center gap-6">
        <a className="text-sm text-gray-500" href="#">Privacy</a>
        <a className="text-sm text-gray-500" href="#">Terms</a>
        <a className="text-sm text-gray-500" href="#">Status</a>
      </div>
    </footer>

步骤 8：验证并优化

调用 get_document 验证结构。需要调整时，使用 batch_update 一次性修改多个节点的颜色、间距或文本内容。

---

响应式设计工作流

创建响应式变体：

1. 先构建桌面设计（1440px）
2. 使用 duplicate_artboard 克隆设计，创建平板（768px）和移动端（375px）版本
3. 使用 batch_update 调整：
   • 将水平 flex 行切换为 flex flex-col，实现纵向堆叠
   • 减小内边距：px-16 改为 px-6，py-24 改为 py-16
   • 缩小文字：text-6xl 改为 text-4xl，text-4xl 改为 text-2xl
   • 调整间距值：gap-8 改为 gap-4
   • 更改网格布局：将三列功能区改为单列堆叠

---

深色模式设计

首选：使用主题系统 — 它会自动处理浅色和深色模式：

1. 使用预设调用 set_theme（例如 presetId: "default"）——其中包含浅色和深色模式
2. 使用 mode: "dark" 调用 set_theme_mode——画板会切换为深色主题令牌
3. 使用语义类（bg-background、text-foreground、bg-card 等）——颜色会自动适配当前模式
4. 随时可以使用 mode: "light" 调用 set_theme_mode，切回浅色模式

手动备用方案（适用于不使用语义令牌的自定义非主题设计）：

1. 设置画板 backgroundColor: "#0a0a0a" 或 "#111111"
2. 使用反转的颜色刻度：
   • 标题：text-white 或 text-gray-100
   • 正文：text-gray-400
   • 次要内容：text-gray-500
   • 背景：bg-gray-900、bg-gray-800、bg-neutral-900
   • 边框：border-gray-800
   • 卡片：bg-gray-900 搭配 border border-gray-800
3. 按钮：主按钮使用 bg-white text-gray-900，次按钮使用 border border-gray-700 text-gray-300

---

主题系统

Efecto 的主题系统可让你定义设计令牌（颜色、圆角），为语义 Tailwind 类提供支持。主题支持多种模式（浅色、深色或自定义），切换模式时所有画板都会实时更新。

主题工具

工具	描述
get_theme	返回当前主题：id、名称、模式、activeMode 和解析后的当前活动令牌
set_theme	应用预设、导入 CSS，或直接提供令牌对象
set_theme_mode	切换当前活动模式（例如 "light" -> "dark"）
reset_theme	完全移除主题——恢复为原始 Tailwind 颜色，不使用语义令牌

应用预设

set_theme
  presetId: "blue"

可用预设：default、zinc、slate、rose、blue、green、violet、orange。每种预设都包含浅色和深色模式。

切换模式

set_theme_mode
  mode: "dark"

使用自定义令牌

Agent 可以从任何来源导入设计令牌——用户仓库的 globals.css、shadcn 主题、Radix 颜色、Open Props，或手工创建的值。只要 CSS 使用 --variable-name: value; 声明，就能正常使用。

从 CSS 文件导入（例如用户的 globals.css）：

set_theme
  css: ":root { --background: #ffffff; --foreground: #0a0a0a; --primary: #e11d48; --primary-foreground: #fff1f2; --secondary: #f5f5f5; --secondary-foreground: #171717; --muted: #f5f5f5; --muted-foreground: #737373; --border: #e5e5e5; --ring: #fb7185; --radius: 0.5rem; } .dark { --background: #0a0a0a; --foreground: #fafafa; --primary: #fb7185; --primary-foreground: #1c1917; --secondary: #262626; --secondary-foreground: #fafafa; --muted: #262626; --muted-foreground: #a3a3a3; --border: #404040; --ring: #e11d48; }"

如果用户说“使用我的品牌颜色”或“与我的仓库保持一致”，请读取其 CSS 文件，并通过 css 参数传入。

从头创建令牌（用于品牌）：

set_theme
  modes: {
    "light": { "primary": "#6d28d9", "primaryForeground": "#f5f3ff", "background": "#fafafa", "foreground": "#1a1a1a" },
    "dark": { "primary": "#a78bfa", "primaryForeground": "#1a1a1a", "background": "#0a0a0a", "foreground": "#fafafa" }
  }

缺失的令牌键会自动继承默认值。

使用令牌构建

主题启用后，在 JSX 中使用语义类：

<div className="bg-background text-foreground">
  <div className="bg-card border border-border rounded-lg p-6">
    <h2 className="text-foreground text-xl font-bold">Card Title</h2>
    <p className="text-muted-foreground">Supporting text</p>
    <button className="bg-primary text-primary-foreground px-4 py-2 rounded-md">Action</button>
  </div>
</div>

这些类在任何模式下都能正确渲染——从浅色切换到深色时，所有颜色都会更新。

Supported Token Keys

CSS Variable	Token Key	Usage
--background	background	Page background (bg-background)
--foreground	foreground	Primary text (text-foreground)
--card	card	Card surface (bg-card)
--card-foreground	cardForeground	Card text (text-card-foreground)
--popover	popover	Popover surface (bg-popover)
--popover-foreground	popoverForeground	Popover text (text-popover-foreground)
--primary	primary	Primary action (bg-primary)
--primary-foreground	primaryForeground	Text on primary (text-primary-foreground)
--secondary	secondary	Secondary surface (bg-secondary)
--secondary-foreground	secondaryForeground	Text on secondary (text-secondary-foreground)
--muted	muted	Muted surface (bg-muted)
--muted-foreground	mutedForeground	Muted text (text-muted-foreground)
--accent	accent	Accent surface (bg-accent)
--accent-foreground	accentForeground	Text on accent (text-accent-foreground)
--destructive	destructive	Error/danger (bg-destructive)
--destructive-foreground	destructiveForeground	Text on destructive (text-destructive-foreground)
--border	border	Default borders (border-border)
--input	input	Input borders (bg-input)
--ring	ring	Focus rings (ring-ring)
--radius	radius	Border radius base