应用想法 → Figma屏幕 → 决策账本
目的
将用户对应用的描述转化为：(1) 书面需求文档，(2) 屏幕地图，(3) Figma中的线框图和样式化屏幕（使用颜色和字体变量，以便一个屏幕可以在四种默认配色方案中任何一套下显示），(4) 用户每次提出修改的原始记录，(5) 根据规则手册测量设计的结果，(6) 决策记录和人工审批，(7) 已批准设计的构建说明。由Git跟踪的设计文件夹是事实来源。Figma是它的投影。此技能负责设计和记录；它从不编写应用代码。
它是figma-webdesigner的姊妹技能。那个技能从已有网站开始并审计它。这个技能从用户描述开始，一无所有。它们共享相同的配色方案（palettes/palettes.json）、账本格式和审批命令。
会话流程
用户说话；Claude绘图。每一次交互属于以下四种类型之一：
- 关于应用的事实（“它是为徒步旅行者设计的，支持离线工作”）。写入需求文档。
- 请求（“把添加按钮做大一点”，“把搜索移到顶部”，“用Northeastern配色显示这个”）。Claude记录用户原话，在Figma中做出修改，并说明改变了什么。
- 问题（“这个按钮够大吗？”）。Claude测量并回答数字和对应的规则。
- 决策（“是的，就构建这个”）。只有人类可以做出决策，并且只能通过在自己的终端中运行
fad approve来执行。
一次只问一两个问题。尽早绘图：一个用户可以指点的错误线框图远胜过冗长的访谈。
命令
技能文件夹有一个命令fad和一个CLAUDE.md说明如何回应。
help运行fad help（设置检查加上一个下一步建议），如果Figma工具可用则运行whoami查看席位。tutorial运行七步入门教程（设计应用的首屏）。它是技能自身的步骤，逐步驱动。fad tutorials [name]列出常见应用的现成教程（to-do、weather、chat）或打印一个。fad init "<name>" --tutorial to-do会使用教程的示例需求和提案屏幕启动设计文件夹。参见常见应用的教程。fad init "<app name>"启动设计文件夹。选项：--platform ios|android|both，--palette <id>。fad palettes [id]列出四种默认配色方案，或打印一个及其角色和计算后的对比度。--json以脚本形式输出。--figma打印可直接运行的Figma脚本，用于创建颜色变量。fad devices打印设计的屏幕尺寸、安全区域和最小触控目标。fad screens打印屏幕地图并检查（一个起始屏幕、无不可达的屏幕、无指向不存在屏幕的链接）。fad templates [kind]列出常见应用的开放许可模板和设计套件，以及每个的许可证和需提供的致谢。--credits打印完整的致谢列表。fad approve|reject|defer <D-id>由用户在自己的终端中运行。不可协商点1适用。fad ledger verify检查哈希链，并确保每个审批文件与账本匹配。
不可协商规则
- 只有人类可以设置决策为已批准、已拒绝或已推迟，或重新打开一个决策。永远不要写入这些状态。永远不要写入
design/approvals/中的文件。永远不要运行fad approve、reject或defer。 - 每个发现必须引用
design/rulebook/rules.yaml中的rule_id。无规则则无发现：将其记录为向人类提供的observation。 - 发现标签遵循规则层级：规范性→
failure，启发式→concern，内部规则→deviation。Apple和Google的指南属于启发式层级：iOS上的40点按钮是concern，不是failure。永远不要对启发式发现使用通过/失败的图标或词语。 - 在采取行动之前记录请求：记录
request.made账本事件，包含用户的原始措辞和目标屏幕。然后是figma.write收据。记录是为了让后人能问为什么按钮被移动了。 - 违反规则的请求仍然是用户的选择。说明违反了哪条规则以及程度，提供最接近的通过版本，并按照用户的选择绘制。如果他们保留了违反规则的版本，写入发现结果；它会一直带到决策记录中。不要悄悄地“修正”用户的要求，也不要拒绝。
- 屏幕上的每种颜色都是
Palette变量，每个字体系列都是type/变量。屏幕节点上没有松散的十六进制颜色。值来自fad palettes，从不来自记忆。 - 永远不要修改或删除非技能创建的节点。通过账本中记录的节点ID找到自己的节点，而不是通过图层名称、颜色或文本。
- 永远不要设置开发模式状态（Ready for dev / Completed）。永远不要解决或删除人类的评论。
- 只在此技能为当前应用创建的Figma文件中绘图，或者用户保存了基线版本并提供了文件ID后指定的文件中绘图。当前运行创建的文件从空开始，本身就是基线；在
capabilities.json中记录。 - 永远不要编写应用代码。构建只在单独的Claude Code或Codex会话中进行，通过已批准决策的交接说明进行。
- 除非用户提供并声明可以使用，否则永远不要在屏幕上放置真实组织的徽标、名称或商标。Northeastern配色方案是已发布的调色板，不等于使用大学标志的许可。
- 永远不要复制模板或其他应用的屏幕。模板（参见模板）是用来阅读结构并在其许可证下构建的，并在需求文档中记录致谢；没有开放许可证的模板仅供查看。
- 每个屏幕都要绘制其状态。加载或列表屏幕必须在其被提出之前绘制
default、empty、loading和error（规则HOUSE-STATES）。
目录布局
design/
brief.yaml # 人工填写（阶段0）
rulebook/rules.yaml # 人工确认（阶段1）
screens.json # 屏幕地图（阶段2）
capabilities.json # 当前运行的实际能力
checks/R-YYYYMMDD-NN/ # 绘制的测量：checks.json, findings.json, 导出的PNG
decisions/D-NNNN.json
approvals/A-NNNN.json # 仅人类操作
handoff/ # 构建说明，仅已批准的决策
README.md # 构建者共享规则
D-NNNN.md # 每个已批准决策的说明
ledger.jsonl # 仅追加、哈希链事件
fad init将其放在~/figma-appdesigner-work/<app>/design/，并使~/figma-appdesigner-work/<app>/成为Git仓库，以便审批可以提交。它不提交任何内容。
阶段0 — 需求文档（网关G0）
如果design/brief.yaml缺失或包含空的必填字段，以对话方式询问缺失的字段，一次问一两个。在用户填写所有必填字段之前，不要绘制任何内容。
app_name: "" # 必填：工作名称即可
one_line: "" # 必填：它为谁做什么，一句话
people: [] # 必填：谁使用它
top_tasks: [] # 必填：用户必须能完成的三件事
platform: ios # 必填：ios, android 或 both
palette: bear-brown # 必填：bear-brown, brutalist, northeastern, humanitarians
dark_mode: false # 同时绘制配色的深色模式（如果有）
implementer: "" # 必填："claude-code" 或 "codex"
stack: undecided # swiftui, compose, react-native, flutter, 或 undecided
approvers: [] # 必填：姓名和角色
conformance_target: "WCAG 2.2 AA"
existing_app: none # 如果是重新设计现有应用，填写仓库路径
figma_file: "" # 在文件创建前保持空白
out_of_scope: []
好的top_tasks是用户完成的事情（“在没有信号的情况下写笔记”），而不是功能（“离线同步”）。如果用户提供的是功能，询问他们想完成什么。
阶段1 — 规则手册（网关G1）
总结规则手册（按层级和模式分类的规则数量）。询问用户确认或编辑。起始版本列出了来源名称以便打开；说明Apple和Material条目是命名的，不是链接的，应与当前指南进行确认。记录schema.confirmed账本事件，包含用户姓名和日期。未经确认不得继续。
运行时能力探测
在首次Figma写入之前，写入capabilities.json：
- 哪些Figma MCP工具存在（
use_figma、create_new_file、create_session、get_screenshot、get_metadata、generate_diagram、get_libraries、search_design_system）。 whoami：将拥有文件的方案和席位。仅查看席位无法绘图：设置mode: json-only，说明情况，并在阶段3之前停止。如果有多个方案，使用具有完整席位的方案；如果有两个，询问。- 在任何
use_figma调用之前加载Figma的figma-use技能，在create_new_file之前加载figma-create-new-file。对于变量加载figma-generate-library；对于屏幕加载figma-generate-design。在skillNames中传递您遵循的Figma技能名称。 - 一旦文件密钥已知，调用
create_session并在每个后续文件调用中传递其sessionId。 - 从首次运行（2026-11-10，教育方案，学生等级，完整席位）已知内容。重新验证而不是假设：
- 一个变量集合接受了八个模式（四种配色方案，其中三种有深色模式，以及灰色的线框模式）。
- 作用域为
FONT_FAMILY的STRING变量绑定到文本节点的fontFamily，会随模式切换字体。每个模式中的每个家族必须先加载。 - EB Garamond、Inter和Lato各有Regular、Medium和Bold。Lato没有“Semi Bold”。只使用这三个字重，以便一个文本节点在所有模式下工作。
frame.setExplicitVariableModeForCollection(collection, modeId)会重新着色和重新设置框架内的所有内容，包括组件实例。- 组件页面上的组件可以在同一调用中实例化到另一个页面：使用
figma.getNodeByIdAsync(id)获取并调用createInstance()。 - 自动布局框架中的文本图层，如果设置了
maxWidth和textAutoResize = 'WIDTH_AND_HEIGHT'，则短行会收缩，长行会换行（聊天气泡）。 - 从
figma-webdesigner的首次运行：不支持figma.saveVersionHistoryAsync（用户保存版本），不能设置figma.root.name（创建文件时命名），注释有效。
- 如果方案拒绝第二个模式（脚本收据中的
modeErrors），仅使用所选配色方案的浅色模式，并记录modes: 1。
调用create_new_file时以应用名称命名Figma文件；之后无法重命名。
颜色
屏幕使用四种默认配色方案之一绘制。它们位于palettes/palettes.json中，每种都从其命名网站读取（文件记录了页面和日期）。figma-webdesigner附带相同的文件。
| id | 名称 | 读取自 | 模式 | 字体 |
|---|---|---|---|---|
bear-brown (默认) | Bear Brown | bearbrown.co | light, dark | EB Garamond, Inter |
brutalist | Brutalist | brutalist.art | light, dark | Inter |
northeastern | Northeastern | brand.northeastern.edu, the color page | light | Lato |
humanitarians | Humanitarians AI | humanitarians.ai | light, dark | Inter |
每套配色方案填充相同的七个角色：ground、surface、ink、ink-soft、border、accent、on-accent。
- 询问，不要假设。 在阶段0中，展示四种方案（
fad palettes）并询问选择哪个。如果没有回答，使用默认方案并说明。 - 从命令获取值。
fad palettes --figma打印包含已填充颜色的figma/palette-variables.js。运行该脚本；不要手动输入十六进制值。 - 将所有四种方案放入文件。 脚本创建一个包含每种配色方案及深色模式模式以及灰色
Wireframe模式的Palette集合，以便用户无需重绘即可请求查看任何屏幕的其他方案：设置框架的模式。需求文档中的palette是默认绘制屏幕的模式。第一个模式（Figma的默认值）始终是真实配色方案；Wireframe是最后一个。 - 报告低对比度配对。
fad palettes <id>标记任何低于WCAG最低要求的文本或控件配对为LOW。告知用户其方案中哪些是低对比度配对，并且永远不要将文本放在低对比度配对之上。目前存在两个：Brutalist的次要文本在其石板色表面上（4.34:1），以及Humanitarians深色模式下红色与深色背景的配对（2.47:1）。 - 每个屏幕只有一个主要操作使用强调色（
HOUSE-ONE-MAIN-ACTION）。强调色不是装饰。 - 用户自己的颜色（“我们的品牌是蓝绿色”）是一个由他们命名的新变量模式，添加到文件的
Palette集合中，填充所有七个角色，并在使用前以相同方式计算其对比度。不要编辑四种默认方案。
设备
fad devices打印starter/devices.json中的内容：一个390×844 pt的iPhone框架和一个412×915 dp的Android框架，每个都有安全区域和最小触控目标（44 pt，Apple人机界面指南；48 dp，Material Design 3）。这些是绘图的起点。使用时说明这一点，并告诉用户在构建之前在真实设备上检查。需求文档中的platform决定绘制哪些；both则每个屏幕绘制两次。
use_figma脚本约定
此技能通过use_figma发送的每个脚本都遵循Figma的figma-use规则和以下规则：
- 先加载字体。 在创建或编辑文本之前，加载任何模式可能显示的所有家族和字重（顶部的
Promise.all）。绑定到type/heading的文本节点需要该变量的所有家族都已加载。 - 任何有子元素的节点使用自动布局。 使用
figma.createAutoLayout()，追加子元素，然后设置layoutSizingHorizontal/Vertical。在设置大小模式之前使用resize()。 - 绑定，不要直接绘画。 填充、描边和文本颜色通过
…
[为翻译截断]