canicode

CanICode

无需学习 CSS，就能让 Figma 设计稿如你所愿地落地。

在浏览器中试用 — 无需安装。

canicode 的功能

你在 Figma 中完成了设计，也清楚它应该呈现什么样子、如何运作——但 AI 代码生成总靠猜，而且十有八九会猜错。卡片在移动端没有堆叠排列，悬停状态消失了，内边距被统一调整。这不是我设计的样子。

canicode 是你的 Figma 文件与 AI 代码生成之间的实现前访谈。它会像开发者在实现前那样提出问题，而且使用通俗易懂的语言：

“这三张卡片在桌面宽度下并排显示——屏幕变窄时应该怎么办？”

你用日常语言回答（“좁아지면 한 줄에 하나씩” / “变窄后每行显示一张”）。canicode 会将答案转化为代码生成所需的精确技术规范，并将其作为结构化注释写回 Figma 文件，这样下次运行时就不必再猜了。

你只需留在 Figma 中，无需输入 CSS 选择器。设计意图就能落实。

→ 完整论述：docs/POSITIONING.md

三个层面

1. Linter — 17 条规则会揭示那些你凭专业直觉察觉到、却说不清的问题。“这个间距好像不太对。” → 它会找出那张内边距为 14px、而其他卡片都是 16px 的卡片。
2. 问答引导 — 针对每个问题，canicode 都会用你的词汇而非开发者的术语提问。你来回答，它负责将答案转化为规范。
3. 往返持久化 — 答案会作为 Dev Mode 注释保存在 Figma 文件中。下次运行、交给下一个人、使用下一款代码生成工具时，都能看到设计意图。

Linter 的分析是确定性的（分析本身不会消耗 LLM 令牌），在消耗量比原始 JSON 少 5 倍的情况下，像素准确率经消融验证达到 94%，并且还通过真实 Figma 设计进行了校准。

为什么选择 canicode（而不是 Claude Design）

Claude Design 于 2026 年 4 月推出，出色地覆盖了提示词 → 应用的流程——AI 根据你的提示词进行设计，并将结果交给 Claude Code。canicode 覆盖的是另一种工作流：

如果你希望 AI 替你设计，请使用 Claude Design。如果你已经完成设计，希望它完全按你的意图实现，那么 canicode 就适合你。两者并非竞争关系——它们对设计由谁负责有不同的假设。

完整论述（目标用户、工作流假设，以及 canicode 不适用于哪些情况）请参阅 docs/POSITIONING.md。

往返工作流

技能： canicode-gotchas = 调查答案仅保存在 SKILL.md 中的本地（备忘）。canicode-roundtrip = 使用相同的分析路径，外加写入 Figma（注释／属性）。只需记录问题时选择 gotchas；需要修改设计文件时选择 roundtrip。

1. 分析 — 根据 Figma 设计运行 17 条规则（报告包含评级）。
2. 提出问题 — 分析器会针对无法推断的设计信息提出问题（缺失的状态、不明确的变体、响应式设计意图）。
3. 将修复应用到 Figma — /canicode-roundtrip 技能通过 use_figma 将答案写回。每次写入都会在摘要中显示以下三种结果标记之一：
   • ✅ 场景写入成功 — 属性已直接写入场景节点或实例覆盖项。
   • 📝 已为场景节点添加注释 — 技能添加了结构化注释，而不是写入属性。对于实例子级布局写入，这是默认做法，因为将属性传播到组件定义（进而传播到它的每个实例）几乎从来都不是用户想要的。摘要中满是 📝 标记是正确行为，而不是失败。
   • 🌐 定义写入已传播 — 属性已写入组件定义，且每个实例都继承了该属性。仅当用户预先选择启用 allowDefinitionWrite 时才会发生。
4. 重新分析 — 验证问题是否已记录（注释／确认）；如果出现新问题，则重复第 2 步。
5. 交接给 figma-implement-design — canicode 的工作范围到增强设计为止。Figma 官方代码生成技能会接手已整理好的设计并生成代码。
6. 通过 Code Connect 映射收尾 — figma-implement-design 返回后，roundtrip 会询问生成的代码是否令人满意。若回答 y，canicode 会注册一个 Code Connect 映射，将 Figma 组件指向刚生成的代码，这样后续处理包含此组件的界面时，roundtrip 会复用已有实现，而不是重新生成标记。如果你的仓库尚未设置 Code Connect，则会跳过此步骤 — roundtrip 会在问题调查开始前提前提醒你，让你决定是先安装前置条件，还是不创建映射直接继续。

30 秒快速体验

1. 打开 Web 应用 — 粘贴任意 Figma URL，即可获取报告。无需安装、无需令牌，也不会产生 AI 费用。这是 Linter 视图（第 1 层），单独使用也很有帮助。
2. 如果你想使用完整的问答往返流程，再安装下方的 Claude Code 技能。

运行完整往返流程（Claude Code）

npx canicode init
# saves your Figma token + installs /canicode-roundtrip
# (the prompt asks for the token; never paste it into agent chat)

/canicode-roundtrip https://www.figma.com/design/ABC123/MyDesign?node-id=1-234
# in your Claude Code session

往返流程会调用 Figma MCP 服务来读取和写入你的设计 — 运行 claude mcp add -s project -t http figma https://mcp.figma.com/mcp 安装一次，然后重启 Claude Code。

Cursor / Claude Desktop / 其他 MCP 宿主：同样支持。CLI 安装方式（npx canicode init --cursor-skills）、裸 MCP 服务安装方式、用于 CI 门禁的 GitHub Action 以及其他渠道，都列在下方的安装矩阵中。

可选 — Code Connect（用于收尾步骤 6 的映射）：根据 Figma 的设置指南，安装 @figma/code-connect，并在仓库根目录创建 figma.config.json，然后运行 canicode doctor。如果跳过这一步，往返流程仍然可以正常运行 — 只是不会注册映射。它会提前提醒你，让你自行决定。

检查内容

每个问题都会分类为：阻塞项 > 风险 > 缺失信息 > 建议。

安装 — 任选一种

令牌安全： 切勿将 Figma 令牌粘贴到 Claude / Cursor / Agent 聊天中——会话日志可能会保留该令牌。请使用 CLI 提示（npx canicode init）、--token 或 FIGMA_TOKEN=… 环境变量。

以下每一行都是一套完整的安装方式。请勿运行多种方式——它们涵盖的用途有所重叠。

获取令牌： Figma → Settings → Security → Personal access tokens → Generate new token。Figma 的 PAT 文档 权限范围： canicode 只需只读权限。 有效期： 令牌默认有效期为 90 天；生成令牌时请查看下拉菜单。

往返流程的前置条件： /canicode-roundtrip 技能会调用 Figma MCP 服务来读取和写入设计。请运行一次 claude mcp add -s project -t http figma https://mcp.figma.com/mcp 安装，然后重启 Claude Code，以加载新的 MCP 工具。

# Interactive (TTY) — prompts for the token, never paste it into agent chat
npx canicode init

# Non-interactive (CI / non-TTY) — token via env or --token only
FIGMA_TOKEN=figd_xxxxxxxxxxxxx npx canicode init
npx canicode init --token figd_xxxxxxxxxxxxx

canicode config set-token   # rotate Figma token (interactive on TTY; --token for CI)
canicode config show        # masked token + config + reports paths
canicode config path        # absolute path to ~/.canicode/config.json

claude mcp add canicode -- npx --yes --package=canicode canicode-mcp

npx canicode analyze "https://www.figma.com/design/ABC123/MyDesign?node-id=1-234"

- uses: let-sunny/[email protected]
  with:
    figma_url: 'https://www.figma.com/design/ABC123/MyDesign?node-id=1-234'
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    min_score: 70

自定义

完整指南、示例和所有可用选项请参阅 docs/CUSTOMIZATION.md。

开发

git clone https://github.com/let-sunny/canicode.git && cd canicode
pnpm install && pnpm build

pnpm dev        # watch mode
pnpm test       # run tests
pnpm lint       # type check

架构详情请参阅 CLAUDE.md。校准流程请参阅 Calibration wiki。

贡献

分享你的 Figma 设计，帮助根据真实设计校准评分。

支持

• Bug 和问题：GitHub Issues
• **隐私：**有关数据收集和如何选择退出的详情，请参阅 PRIVACY.md

许可证

MIT