diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 22253231..5288cd9c 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -3,12 +3,12 @@
"owner": {
"name": "TemPad Dev"
},
- "description": "Agent plugins for using TemPad Dev design evidence in coding workflows.",
+ "description": "Agent plugins for reading Figma evidence and authoring native designs with TemPad Dev.",
"plugins": [
{
"name": "tempad-dev",
"source": "./agent-plugins/tempad-dev",
- "description": "Use selected Figma nodes as agent-ready evidence for project-consistent UI implementation.",
+ "description": "Use TemPad Dev to turn Figma evidence into UI code and create native Figma designs.",
"category": "Design"
}
]
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index d1125dfb..aa24f6f8 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -33,6 +33,14 @@ jobs:
- name: Install browser runtime
run: pnpm --filter @tempad-dev/extension test:setup
+ - name: Check agent plugin
+ run: >-
+ pnpm agent-plugin:dev &&
+ test -z "$(git status --porcelain --untracked-files=all --
+ agent-plugins/tempad-dev
+ .agents/plugins/marketplace.json
+ .claude-plugin/marketplace.json)"
+
- name: Type check
run: pnpm typecheck
diff --git a/.github/workflows/publish-mcp.yml b/.github/workflows/publish-mcp.yml
index 5de2ea44..bef75708 100644
--- a/.github/workflows/publish-mcp.yml
+++ b/.github/workflows/publish-mcp.yml
@@ -2,6 +2,16 @@ name: publish-mcp
on:
workflow_dispatch:
+ inputs:
+ tag:
+ description: npm dist-tag
+ required: true
+ default: latest
+ type: choice
+ options:
+ - latest
+ - next
+ - alpha
permissions:
contents: read
@@ -35,4 +45,8 @@ jobs:
- name: Publish
working-directory: packages/mcp-server
- run: npm publish --access public
+ run: npm publish --access public --tag "${{ inputs.tag }}"
+
+ - name: Verify published version
+ working-directory: packages/mcp-server
+ run: npm view "@tempad-dev/mcp@$(node -p "require('./package.json').version")" version
diff --git a/.gitignore b/.gitignore
index 82a32a28..02c9e332 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,6 +14,7 @@ stats-*.json
.wxt
web-ext.config.ts
dist
+.dev/
coverage
.artifacts/
packages/*/coverage
diff --git a/.lefthook.yml b/.lefthook.yml
index 89dd61e1..1922aa67 100644
--- a/.lefthook.yml
+++ b/.lefthook.yml
@@ -5,10 +5,6 @@ pre-commit:
group:
piped: true
jobs:
- - name: sync-agent-plugin
- glob: '{skill/SKILL.md,agent-plugins/tempad-dev/skills/figma-design-to-code/SKILL.md}'
- run: pnpm sync:agent-plugin
- stage_fixed: true
- name: lint
glob: '*.{ts,js,mjs,cjs,mts,cts,vue}'
run: pnpm exec eslint --fix {staged_files}
diff --git a/AGENTS.md b/AGENTS.md
index 823f76e6..738c1430 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,16 +32,51 @@ Provide a single entry point for coding agents. This file links to package-level
- Test (watch): `pnpm test`
- Test (run): `pnpm test:run`
- Test (coverage): `pnpm test:coverage`
+- Generate the local agent plugin: `pnpm agent-plugin:dev`
- Extension node tests: `pnpm --filter @tempad-dev/extension test:node`
- Extension browser tests: `pnpm --filter @tempad-dev/extension test:browser`
- Extension browser setup: `pnpm --filter @tempad-dev/extension test:setup`
+## Agent plugin workflow
+
+- Before running or reviewing an end-to-end Figma authoring agent test, read
+ `docs/testing/agent-authoring-evaluation.md` and follow its runtime identity,
+ clean-task, evidence-review, and fix-placement rules.
+- `agent-plugins/tempad-dev/` is the tracked release source shared by Codex and Claude. The agent
+ plugin is distributed through the Git marketplace, not npm.
+- `.dev/plugins/tempad-dev-dev/` is the ignored local build. Generate it with
+ `pnpm agent-plugin:dev`; do not edit generated files under `.dev/`.
+- Run `pnpm agent-plugin:dev` after every change that affects the generated `tempad-dev-dev`
+ contents, including the shared skill, agent-plugin manifests, icons, or marketplace metadata.
+ Ordinary `pnpm build` must not modify agent-plugin artifacts.
+- Before asking the user to test a changed development plugin, reinstall the generated cachebuster
+ through the active Desktop host and use a new task. Use the no-restart reinstall path when the
+ host CDP endpoint and plugin runtime are healthy; a skill, manifest, icon, or marketplace change
+ does not itself require restarting Codex. Reserve `--restart-codex` for unavailable CDP, stale or
+ partial host/runtime state, or recovery after the ordinary replacement cannot complete. An
+ external `codex plugin add` call updates the installation on disk, but alone does not prove that
+ a running Desktop host refreshed its plugin cache.
+- `pnpm dev` watches the extension, shared package, and MCP server. The generated development
+ plugin points directly at the current checkout's MCP build, so MCP-only changes require a new
+ agent task or plugin reload, not an agent-plugin rebuild or reinstall.
+- After an extension-side rebuild, refresh the target Figma tab before testing. An open tab can keep
+ its previous page-context runtime even when WXT has emitted the new bundle; reinstalling the Codex
+ agent plugin does not reload that browser runtime. Verify that MCP reconnects before the test.
+- Keep Codex and Claude support equivalent. Both development manifests must launch the same
+ working-tree MCP runtime.
+- Release MCP configuration must use `@tempad-dev/mcp@latest`, never an alpha tag, fixed version,
+ or local path.
+- See `agent-plugins/tempad-dev/README.md` for the Codex and Claude installation commands.
+
## Doc index
- `TESTING.md`
- `docs/testing/architecture.md`
+- `docs/testing/agent-authoring-evaluation.md`
- `docs/extension/mcp-get-code-requirements.md`
- `docs/extension/mcp-get-code-design.md`
+- `docs/extension/mcp-canvas-authoring-design.md`
+- `docs/extension/mcp-canvas-assets-design.md`
- `docs/extension/mcp-browser-gateway-design.md`
- `docs/marketing-screenshots.md`
@@ -115,7 +150,8 @@ Pick the checks that match your change.
- Testing runbook and required checks: `TESTING.md`.
- Testing architecture and coverage model: `docs/testing/architecture.md`.
-- Root coverage scope is configured in `vitest.config.ts` as the single source of truth.
+- Root coverage composition is configured in `vitest.config.ts`; shared thresholds and the extension
+ node source list live in `vitest.coverage.ts`.
- Root coverage excludes build artifacts (`**/dist/**`, `**/.output/**`) to avoid polluted reports.
- Root coverage provider is `istanbul` to avoid V8 remap parse failures under Vite 8 dependency trees.
- Extension browser tests run in Playwright via `packages/extension/vitest.browser.config.ts`.
diff --git a/README.md b/README.md
index a9aeb748..b9f2ac0e 100644
--- a/README.md
+++ b/README.md
@@ -205,14 +205,29 @@ Current available plugins:
TemPad Dev ships an agent integration for coding agents and IDEs. The integration combines:
-- an [MCP](https://modelcontextprotocol.io/) server that lets agents pull code and context directly from the node you have selected in Figma
-- an agent skill that teaches the agent how to interpret that evidence in the current repository
+- an [MCP](https://modelcontextprotocol.io/) server that lets agents inspect Figma and apply
+ declarative canvas results when the current Figma Design file is editable
+- two agent skills: one for implementing Figma evidence in code, and one for designing on the Figma canvas with accessible component definitions and bounded design-system resources
-Figma also provides official [remote and desktop MCP servers](https://developers.figma.com/docs/figma-mcp-server/), with the remote server recommended for most users. TemPad Dev is an open, local-control complement for teams that specifically want an inspectable browser-extension pipeline, the existing read-only inspection workflow, programmable output plugins, canonical agent-facing code/token IR, and an explicit context budget. It provides design evidence and a code starting point; the coding agent remains responsible for adapting that evidence to the repository, validating behavior, and producing the final implementation.
+These portable capabilities are packaged first as an
+[Agent Plugins 1.0](https://agent-plugins.org/) bundle. Its root `plugin.json`, `skills/`, and
+`mcp.json` are the canonical package; client-specific manifests are compatibility layers for
+installers and hosts that do not consume the open format directly.
+
+Figma also provides official [remote and desktop MCP servers](https://developers.figma.com/docs/figma-mcp-server/), with the remote server recommended for most users. TemPad Dev is an open, local-control complement for teams that specifically want an inspectable browser-extension pipeline, local inspection and MCP-gated declarative canvas authoring, programmable output plugins, canonical agent-facing code/token IR, and an explicit context budget. It provides design evidence and a code starting point; the coding agent remains responsible for adapting that evidence to the repository, validating behavior, and producing the final implementation.
With the TemPad Dev panel open and MCP enabled, the MCP server exposes:
- `get_code`: High-fidelity JSX/Vue + TailwindCSS code output by default, plus attached assets and the codegen preset/config used.
+- `get_design_system`: An immutable, deterministic catalog. It returns compact pages of component
+ definitions on accessible pages plus local or directly referenced variable, collection/mode,
+ style, and shader definitions without inspecting canvas usage or loading every page. Cursor
+ continuation exposes omitted definitions; exact-ref lookup returns one bounded definition.
+- `apply_canvas`: One restricted HTML + deterministic Tailwind utility desired result using primitives, catalog
+ component tags, short design-system refs, typed Figma-only state, sanitized SVG, and
+ content-addressed images. The extension resolves, validates, diffs, applies, and structurally
+ verifies the result. Authoring requires edit access to the current Figma Design file.
+- `get_screenshot`: A bounded rendered PNG for selective visual validation.
- `get_structure`: A structural outline (ids, types, geometry) for the current selection.
- Binary assets are returned as metadata + HTTP download URLs (`asset.url`) in tool responses. Asset MCP resources are not exposed.
@@ -224,9 +239,22 @@ With the TemPad Dev panel open and MCP enabled, the MCP server exposes:
-1. Install Node.js 18.20.0 or later with `npx`. Keep TemPad Dev open in the Figma tab you want the agent to inspect, then enable **Preferences → Agent integration → MCP access**. When prompted, allow the loopback connection to `127.0.0.1`.
+1. Install Node.js 18.20.0 or later with `npx`. Keep TemPad Dev open in the Figma tab you want the agent to inspect, then enable **Preferences → Agent integration → MCP access**. When prompted, allow the loopback connection to `127.0.0.1`. Canvas authoring is available while MCP access is enabled and the current Figma Design file is editable.
2. Select **Set up agents**, choose Codex, Cursor, Claude Code, Gemini, VS Code, OpenCode, or TRAE, and follow the displayed path. Use **Other** for another compatible client. The choice only changes the instructions shown; it does not bind or activate an agent.
-3. Prefer the direct action when offered. Every fallback command or config is shown in full for review and copying. Codex and Claude Code plugins include both MCP and the `figma-design-to-code` skill; the other paths show the two required steps separately.
+3. The setup flow installs the portable Agent Plugin first for Codex, Cursor, Claude Code, and VS Code. For Gemini, OpenCode, TRAE, and other clients without compatible plugin installation, it uses the client's MCP flow plus the two standalone skills. Every command or config is shown in full for review and copying.
+
+To install the portable package into all compatible agents detected on your machine:
+
+```bash
+npx plugins add ecomfe/tempad-dev
+```
+
+Pass `--target codex`, `--target cursor`, `--target claude-code`, or `--target vscode` to limit the
+installation to one of the built-in setup targets. Native Codex and Claude marketplace commands,
+plus direct MCP and skill installation, remain documented as compatibility fallbacks in the
+[Agent Plugin guide](./agent-plugins/tempad-dev/README.md).
+
+All plugin and direct `npx`-based setup paths use `@tempad-dev/mcp@latest`.
Keep TemPad Dev open with MCP enabled while using it. If multiple Figma files are connected, click the MCP badge in the panel for the file you want the agent to inspect; that file becomes the active context.
diff --git a/README.zh-Hans.md b/README.zh-Hans.md
index 6a6e63cd..93154cb5 100644
--- a/README.zh-Hans.md
+++ b/README.zh-Hans.md
@@ -201,14 +201,28 @@ sandboxed extension page 内启动一个全新的 Worker，并在完成或五秒
TemPad Dev 内置了面向编码 agent 和 IDE 的 Agent 集成。该集成包含：
-- 一个 [MCP](https://modelcontextprotocol.io/) 服务器，使 agent 可以直接从你在 Figma 中选中的节点拉取代码和上下文
-- 一个 agent skill，用于指导 agent 在当前仓库中理解并使用这些证据
+- 一个 [MCP](https://modelcontextprotocol.io/) 服务器，使 agent 可以检查 Figma，并在当前 Figma Design 文件可编辑时提交声明式画布结果
+- 两个 agent skill：一个用于根据 Figma 证据实现代码，另一个用于基于可访问页面中的组件定义和文件级设计资源在 Figma 画布上进行设计
-Figma 也提供官方的 [remote 与 desktop MCP server](https://developers.figma.com/docs/figma-mcp-server/)，并建议大多数用户优先使用 remote server。TemPad Dev 的定位是一个开放、强调本地控制的补充方案，适合明确需要可审计的浏览器扩展链路、现有只读检查流程、可编程输出插件、规范化的 agent-facing 代码/token IR，以及显式上下文预算的团队。TemPad Dev 提供设计证据与代码起点；最终仍由 coding agent 结合目标仓库完成适配、验证和实现。
+这些可移植能力会优先封装为
+[Agent Plugins 1.0](https://agent-plugins.org/) 插件。根目录的 `plugin.json`、`skills/` 和
+`mcp.json` 是 canonical package；客户端专用 manifest 只作为安装器或尚未直接消费开放
+格式的 host 的兼容层。
+
+Figma 也提供官方的 [remote 与 desktop MCP server](https://developers.figma.com/docs/figma-mcp-server/)，并建议大多数用户优先使用 remote server。TemPad Dev 的定位是一个开放、强调本地控制的补充方案，适合明确需要可审计的浏览器扩展链路、本地检查与由 MCP access 控制的声明式画布创作、可编程输出插件、规范化的 agent-facing 代码/token IR，以及显式上下文预算的团队。TemPad Dev 提供设计证据与代码起点；最终仍由 coding agent 结合目标仓库完成适配、验证和实现。
打开 TemPad Dev 面板并启用 MCP 后，MCP 服务器会暴露以下能力：
- `get_code`：默认输出高保真的 JSX/Vue + TailwindCSS 代码，同时包含相关资源以及使用的 codegen 预设和配置。
+- `get_design_system`：创建不可变、确定性的紧凑目录，按资源类型平衡分页返回可访问页面的
+ 组件定义，以及本地或被定义直接引用的变量、集合/模式、样式和 shader 定义；既不扫描
+ 画布中的使用情况，也不加载所有页面。游标可继续读取遗漏定义；使用同一目录精确查询
+ 某个引用时，返回该资源的有界定义。
+- `apply_canvas`：提交一次受限 HTML + 可确定转换的 Tailwind utility 目标结果，其中可以使用基础元素、
+ 目录组件标签、设计系统短引用、类型化的 Figma 专有状态、经过净化的 SVG 和内容寻址图片。
+ 扩展会在本地解析、验证、计算与实时画布的差异、应用修改并校验结构。画布创作要求当前
+ Figma Design 文件具有编辑权限。
+- `get_screenshot`：返回一张有大小限制的渲染 PNG，用于按需视觉验证。
- `get_structure`：当前选中节点的结构信息（id、类型、几何数据）。
- 二进制资源会通过工具响应中的元数据 + HTTP 下载地址（`asset.url`）提供；MCP 不再暴露 asset 资源模板。
@@ -220,9 +234,22 @@ Figma 也提供官方的 [remote 与 desktop MCP server](https://developers.figm
-1. 安装 Node.js 18.20.0 或更高版本并确保 `npx` 可用。在希望 agent 检查的 Figma 标签页中保持 TemPad Dev 打开，然后启用 **Preferences → Agent integration → MCP access**。出现提示时，请允许连接到 loopback 地址 `127.0.0.1`。
+1. 安装 Node.js 18.20.0 或更高版本并确保 `npx` 可用。在希望 agent 检查的 Figma 标签页中保持 TemPad Dev 打开，然后启用 **Preferences → Agent integration → MCP access**。出现提示时，请允许连接到 loopback 地址 `127.0.0.1`。启用 MCP access 且当前 Figma Design 文件可编辑时，即可进行画布创作。
2. 点击 **Set up agents**，选择 Codex、Cursor、Claude Code、Gemini、VS Code、OpenCode 或 TRAE，然后按界面显示的路径配置。其它兼容客户端请选择 **Other**。这里的选择只会切换说明，不会绑定或激活 agent。
-3. 如果界面提供直接操作，请优先使用。所有备用命令和 config 都会完整显示，便于检查和复制。Codex 与 Claude Code 的 plugin 同时包含 MCP 和 `figma-design-to-code` skill；其它路径会分别展示两个必要步骤。
+3. 对 Codex、Cursor、Claude Code 和 VS Code，配置流程会优先安装可移植的 Agent Plugin。对 Gemini、OpenCode、TRAE 及其它尚无兼容 plugin 安装能力的客户端，则使用对应客户端的 MCP 流程并单独安装两个 skill。所有命令和 config 都会完整显示，便于检查和复制。
+
+要把可移植插件安装到本机检测到的所有兼容 agent，可运行：
+
+```bash
+npx plugins add ecomfe/tempad-dev
+```
+
+使用 `--target codex`、`--target cursor`、`--target claude-code` 或 `--target vscode` 可以只
+安装到内置配置入口中的某一个目标。Codex 与 Claude 的原生 marketplace 命令，以及直接
+安装 MCP 和 skill 的方式，仍作为兼容回退保留在
+[Agent Plugin 指南](./agent-plugins/tempad-dev/README.zh-Hans.md)中。
+
+所有 plugin 和直接使用 `npx` 的配置路径都使用 `@tempad-dev/mcp@latest`。
使用期间请保持 TemPad Dev 打开并启用 MCP。如果连接了多个 Figma 文件，请点击目标文件面板中的 MCP 徽标；该文件会成为 agent 当前访问的上下文。
diff --git a/agent-plugins/tempad-dev/.claude-plugin/plugin.json b/agent-plugins/tempad-dev/.claude-plugin/plugin.json
index bde03b87..fb88b7bb 100644
--- a/agent-plugins/tempad-dev/.claude-plugin/plugin.json
+++ b/agent-plugins/tempad-dev/.claude-plugin/plugin.json
@@ -1,14 +1,23 @@
{
"name": "tempad-dev",
- "version": "0.1.0",
- "description": "Use selected Figma nodes as agent-ready evidence for project-consistent UI implementation.",
+ "version": "0.1.2",
+ "description": "Use TemPad Dev to turn Figma evidence into UI code and create native Figma designs.",
"author": {
"name": "TemPad Dev"
},
"homepage": "https://github.com/ecomfe/tempad-dev#agent-integration",
"repository": "https://github.com/ecomfe/tempad-dev",
"license": "MIT",
- "keywords": ["figma", "mcp", "skill", "agent-integration", "design-to-code", "frontend"],
+ "keywords": [
+ "figma",
+ "mcp",
+ "skill",
+ "agent-integration",
+ "design-to-code",
+ "canvas-authoring",
+ "design-system",
+ "frontend"
+ ],
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}
diff --git a/agent-plugins/tempad-dev/.codex-plugin/plugin.json b/agent-plugins/tempad-dev/.codex-plugin/plugin.json
index a420ad27..a57e4ee9 100644
--- a/agent-plugins/tempad-dev/.codex-plugin/plugin.json
+++ b/agent-plugins/tempad-dev/.codex-plugin/plugin.json
@@ -1,29 +1,47 @@
{
"name": "tempad-dev",
- "version": "0.1.1",
- "description": "Use the TemPad Dev agent integration to turn selected Figma nodes into repo-ready UI code.",
+ "version": "0.1.2",
+ "description": "Use TemPad Dev to turn Figma evidence into UI code and create native Figma designs.",
"author": {
"name": "TemPad Dev"
},
"homepage": "https://github.com/ecomfe/tempad-dev#agent-integration",
"repository": "https://github.com/ecomfe/tempad-dev",
"license": "MIT",
- "keywords": ["figma", "mcp", "skill", "agent-integration", "design-to-code", "frontend"],
+ "keywords": [
+ "figma",
+ "mcp",
+ "skill",
+ "agent-integration",
+ "design-to-code",
+ "canvas-authoring",
+ "design-system",
+ "frontend"
+ ],
"skills": "./skills/",
"interface": {
"displayName": "TemPad Dev",
- "shortDescription": "Use Figma selections as agent-ready design evidence.",
- "longDescription": "TemPad Dev packages the figma-design-to-code agent skill with MCP server configuration so coding agents can inspect selected Figma nodes and implement project-consistent UI code.",
+ "shortDescription": "Read Figma evidence and author native canvas content.",
+ "longDescription": "TemPad Dev packages skills for implementing Figma designs in code and authoring native Figma content with optional accessible design-system resources, together with its MCP server configuration.",
"developerName": "TemPad Dev",
"category": "Design",
- "capabilities": ["Agent integration", "MCP", "Design-to-code", "Frontend"],
+ "capabilities": [
+ "Agent integration",
+ "MCP",
+ "Design-to-code",
+ "Canvas authoring",
+ "Design systems",
+ "Frontend"
+ ],
"websiteURL": "https://github.com/ecomfe/tempad-dev",
"defaultPrompt": [
"Use TemPad Dev to implement the selected Figma node.",
- "Convert this Figma selection into repo-ready UI code.",
- "Inspect the selected Figma node with TemPad Dev."
+ "Inspect the selected Figma node with TemPad Dev.",
+ "Create a native Figma design while following my resource constraints."
],
- "brandColor": "#0098FF"
+ "brandColor": "#0098FF",
+ "composerIcon": "./assets/icon-padded.svg",
+ "logo": "./assets/icon-padded.svg"
},
"mcpServers": "./.mcp.json"
}
diff --git a/agent-plugins/tempad-dev/README.md b/agent-plugins/tempad-dev/README.md
index 3042a180..d5ca9556 100644
--- a/agent-plugins/tempad-dev/README.md
+++ b/agent-plugins/tempad-dev/README.md
@@ -1,29 +1,76 @@
# TemPad Dev Agent Plugin
-This plugin packages the TemPad Dev agent integration for Codex and Claude Code. It bundles:
+[简体中文](./README.zh-Hans.md)
-- the `figma-design-to-code` agent skill
-- the TemPad Dev MCP server configuration for selected-node design evidence
+This directory is the portable TemPad Dev integration for compatible coding agents and IDEs. It
+bundles:
-Install it for Codex:
+- `figma-design-to-code` for turning Figma evidence into project-consistent UI code
+- `figma-canvas-authoring` for grounded native Figma design with accessible component definitions,
+ file resources, and progressive style guidance
+- the TemPad Dev MCP server configuration for design evidence and MCP-gated canvas authoring
+
+The root `plugin.json`, `skills/`, and `mcp.json` follow
+[Agent Plugins 1.0](https://agent-plugins.org/) and are the canonical package contents.
+
+## Install the portable plugin
+
+Install into every compatible agent detected on your machine:
+
+```bash
+npx plugins add ecomfe/tempad-dev
+```
+
+To install into one agent only, pass a target such as:
+
+```bash
+npx plugins add ecomfe/tempad-dev --target codex
+npx plugins add ecomfe/tempad-dev --target cursor
+npx plugins add ecomfe/tempad-dev --target claude-code
+npx plugins add ecomfe/tempad-dev --target vscode
+```
+
+The installer reads the portable package first and adapts it only when the selected client needs a
+client-specific layout.
+
+## Client-specific fallbacks
+
+Use these native marketplace flows only when the portable installer is unavailable or client
+policy requires the native path.
+
+### Codex
```bash
codex plugin marketplace add ecomfe/tempad-dev --ref main
codex plugin add tempad-dev@tempad-dev
```
-You can also install **TemPad Dev** from the Codex app plugin directory after adding the marketplace.
+You can also install **TemPad Dev** from the Codex app plugin directory after adding the
+marketplace.
-Install it for Claude Code CLI and Desktop:
+### Claude Code and Claude Desktop
```bash
claude plugin marketplace add ecomfe/tempad-dev
claude plugin install tempad-dev@tempad-dev
```
-The plugin appears in Claude Desktop after the marketplace is added. Both clients use the same
-skill and MCP server configuration from this directory.
+The plugin appears in Claude Desktop after the marketplace is added.
+
+For clients without Agent Plugin support, follow the direct MCP and standalone skill setup in the
+[complete setup guide](../../README.md#agent-integration).
+
+## Usage
+
+Before using the integration, open TemPad Dev in Figma, then open **Preferences → Agent
+integration** and enable **MCP access**. Canvas authoring is available while the active Figma
+Design file is editable.
-Before using the integration, open TemPad Dev in Figma, then open **Preferences -> Agent integration** and enable **MCP access**.
+## Packaging source of truth
-For app, CLI, direct MCP, and manual fallbacks, see the [complete setup guide](../../README.md#agent-integration).
+- Edit `plugin.json`, `skills/`, and `mcp.json` for portable content.
+- `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`, and `.mcp.json` are compatibility
+ wrappers. Their shared metadata and MCP entries are synchronized from the portable files by
+ `pnpm agent-plugin:dev`.
+- Codex-only interface metadata remains in `.codex-plugin/plugin.json` and is preserved during
+ synchronization.
diff --git a/agent-plugins/tempad-dev/README.zh-Hans.md b/agent-plugins/tempad-dev/README.zh-Hans.md
new file mode 100644
index 00000000..ad9e5a14
--- /dev/null
+++ b/agent-plugins/tempad-dev/README.zh-Hans.md
@@ -0,0 +1,70 @@
+# TemPad Dev Agent Plugin
+
+[English](./README.md)
+
+此目录是面向兼容 coding agent 和 IDE 的可移植 TemPad Dev 集成，其中包括：
+
+- `figma-design-to-code`：根据 Figma 证据实现符合项目约定的界面代码
+- `figma-canvas-authoring`：利用可访问的组件定义、文件资源和渐进式风格指引，在
+ Figma 中创作原生设计
+- TemPad Dev MCP 服务器配置，用于读取设计证据以及通过 MCP 控制画布创作
+
+根目录的 `plugin.json`、`skills/` 和 `mcp.json` 遵循
+[Agent Plugins 1.0](https://agent-plugins.org/)，并作为 canonical package 内容。
+
+## 安装可移植插件
+
+安装到本机检测到的所有兼容 agent：
+
+```bash
+npx plugins add ecomfe/tempad-dev
+```
+
+如果只安装到一个 agent，请指定 target，例如：
+
+```bash
+npx plugins add ecomfe/tempad-dev --target codex
+npx plugins add ecomfe/tempad-dev --target cursor
+npx plugins add ecomfe/tempad-dev --target claude-code
+npx plugins add ecomfe/tempad-dev --target vscode
+```
+
+安装器会优先读取可移植 package，仅在目标客户端需要时转换为客户端专用目录结构。
+
+## 客户端专用回退
+
+仅当可移植安装器不可用，或客户端策略要求使用原生流程时，才使用以下 marketplace
+安装方式。
+
+### Codex
+
+```bash
+codex plugin marketplace add ecomfe/tempad-dev --ref main
+codex plugin add tempad-dev@tempad-dev
+```
+
+添加 marketplace 后，也可以从 Codex 应用的插件目录安装 **TemPad Dev**。
+
+### Claude Code 和 Claude Desktop
+
+```bash
+claude plugin marketplace add ecomfe/tempad-dev
+claude plugin install tempad-dev@tempad-dev
+```
+
+添加 marketplace 后，该插件也会出现在 Claude Desktop 中。
+
+不支持 Agent Plugin 的客户端，请按照
+[完整配置指南](../../README.zh-Hans.md#agent-集成)直接配置 MCP 并安装独立 skill。
+
+## 使用
+
+使用前，请在 Figma 中打开 TemPad Dev，然后进入 **Preferences → Agent integration**
+并启用 **MCP access**。启用后，只要当前 Figma Design 文件可编辑，即可进行画布创作。
+
+## 封装内容源
+
+- 可移植内容请修改 `plugin.json`、`skills/` 和 `mcp.json`。
+- `.codex-plugin/plugin.json`、`.claude-plugin/plugin.json` 和 `.mcp.json` 是兼容封装；
+ `pnpm agent-plugin:dev` 会从可移植文件同步公共 metadata 与 MCP 配置。
+- Codex 专用的 interface metadata 仍保存在 `.codex-plugin/plugin.json` 中，并会在同步时保留。
diff --git a/agent-plugins/tempad-dev/assets/icon-padded.svg b/agent-plugins/tempad-dev/assets/icon-padded.svg
new file mode 100644
index 00000000..bdbdf027
--- /dev/null
+++ b/agent-plugins/tempad-dev/assets/icon-padded.svg
@@ -0,0 +1,16 @@
+
diff --git a/agent-plugins/tempad-dev/assets/icon.png b/agent-plugins/tempad-dev/assets/icon.png
new file mode 100644
index 00000000..67c2135c
Binary files /dev/null and b/agent-plugins/tempad-dev/assets/icon.png differ
diff --git a/agent-plugins/tempad-dev/mcp.json b/agent-plugins/tempad-dev/mcp.json
new file mode 100644
index 00000000..4326590e
--- /dev/null
+++ b/agent-plugins/tempad-dev/mcp.json
@@ -0,0 +1,10 @@
+{
+ "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+ "mcpServers": {
+ "tempad-dev": {
+ "type": "stdio",
+ "command": "npx",
+ "args": ["-y", "@tempad-dev/mcp@latest"]
+ }
+ }
+}
diff --git a/agent-plugins/tempad-dev/plugin.json b/agent-plugins/tempad-dev/plugin.json
new file mode 100644
index 00000000..b3ce3181
--- /dev/null
+++ b/agent-plugins/tempad-dev/plugin.json
@@ -0,0 +1,22 @@
+{
+ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+ "name": "tempad-dev",
+ "version": "0.1.2",
+ "description": "Use TemPad Dev to turn Figma evidence into UI code and create native Figma designs.",
+ "author": {
+ "name": "TemPad Dev"
+ },
+ "homepage": "https://github.com/ecomfe/tempad-dev#agent-integration",
+ "repository": "https://github.com/ecomfe/tempad-dev",
+ "license": "MIT",
+ "keywords": [
+ "figma",
+ "mcp",
+ "skill",
+ "agent-integration",
+ "design-to-code",
+ "canvas-authoring",
+ "design-system",
+ "frontend"
+ ]
+}
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/SKILL.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/SKILL.md
new file mode 100644
index 00000000..ffab85f5
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/SKILL.md
@@ -0,0 +1,329 @@
+---
+name: figma-canvas-authoring
+description: >-
+ Create or update native, editable Figma designs with TemPad Dev MCP. Use for
+ authoring screens, flows, drafts, reusable components, and explicitly
+ requested local design-system resources on a Figma canvas, including an
+ empty document. Do not use for Figma-to-code, critique without edits, or raw
+ Plugin API automation.
+---
+
+# Design on the Figma canvas
+
+Create one native, editable Figma result. Work from intended experience and
+evidence to the Figma artifact model, representation mechanics, serialization,
+and rendered verification. Markup and classes only transport ordinary layer
+hierarchy, layout, spacing, typography, color, and appearance; use native fields
+where meaning depends on Figma node types, resources, or state. Tools, schemas,
+catalogs, and examples support the result but do not determine the design.
+
+Derive product, platform, accessibility, content, and visual requirements from
+the user, permitted evidence, applicable expertise, or targeted research. This
+skill provides a portable floor for composition, asset fidelity, reuse,
+authoring, and verification; unrelated installed skills may deepen judgment but
+must not determine baseline correctness. Identify needed expertise before
+inspecting optional capabilities.
+
+Before authoring, require an editable Figma Design file and an active MCP badge
+in the intended tab. Use only the host's TemPad MCP tools. If they are absent,
+report the integration problem and stop; never bypass the boundary, emit raw
+Plugin API operations, launch the MCP CLI, recreate its transport, or substitute
+shell commands.
+
+## Authority and quality
+
+Apply explicit user requirements first, then applicable evidence, this skill's
+authoring and safety constraints, and situated judgment. Infer low-consequence
+gaps; ask only when a missing choice would materially change the result.
+
+- Ground material decisions in the brief, evidence, targeted research, or a
+ stated low-consequence assumption. Tool availability and examples are not
+ design evidence.
+- Deliver one coherent result whose content, states, assets, and reusable
+ resources agree with the brief and one another.
+- Preserve required sources, assets, representations, and behavior rather than
+ replacing them with easier substitutes.
+- Make the result complete, editable, intentionally structured, and free of
+ observed unintended defects. Disclose accepted limitations.
+
+The brief and its evidence define task-specific quality; establish and verify
+those criteria instead of prescribing their answers here.
+
+## Workflow
+
+1. **Fix scope and evidence.** Determine the smallest complete outcome, create
+ or update target, relevant evidence, content and state distinctions to
+ preserve, and unresolved material decisions. Use `get_code` only when an
+ existing visual composition matters. Use `get_structure` only for hierarchy,
+ ordering, spatial relationships, managed identity uncertainty, or targeted
+ native-state read-back; set `options.native: true` only for masks, IMAGE paint
+ hashes, layout grids, or frame guides. Create on the active page by default.
+ Omit top-level `page` unless the user or evidence requires a specific page;
+ never ask for or invent one merely to place new work.
+
+2. **Resolve material design decisions.** Follow the user and permitted file or
+ project evidence. For net-new screens, flows, or significant visual redesigns
+ without an established composition, read
+ [visual-composition.md](references/visual-composition.md) and
+ [style-grounding.md](references/style-grounding.md). Before markup, inspect
+ credible evidence for every unresolved initial visual, interaction, and
+ detail decision. Search finds candidates; it is not evidence. Open the source
+ or a recoverable artifact and inspect the relevant pixels or specification.
+ Search-result tiles, snippets, style labels, memory, and optional-skill advice
+ do not close the gate. Match source authority to the decision; visual evidence
+ cannot establish unseen behavior. A source may cover several decisions only
+ when it shows or specifies each one. Inspect named precedents even when
+ familiar. Continue bounded research or report the blocked decision rather
+ than authoring from memory.
+
+ Form one product-specific visual thesis from the findings. It must determine
+ hierarchy, composition and document behavior, type and rhythm,
+ surface/edge/shape/depth grammar, interaction vocabulary, and asset
+ treatment; mood words, palettes, or familiar motifs are not a thesis. Use a
+ fit optional capability only for a decision that remains open after evidence;
+ it may deepen, not replace, this gate.
+
+ Before markup, audit each representative screen's material icon candidates:
+ navigation, search, filtering, sorting, save or share, disclosure, status or
+ object categories, and compact utilities. Preserve a conventional icon role
+ when inspected precedent shows it for the same action or object. Choose text
+ instead only for a screen-specific clarity reason recorded in the trace;
+ sourcing effort is not one. Choose icon, text, or both by recognition,
+ scanning, and compactness, without decorative use or quotas. An unresolved
+ conventional role blocks markup.
+
+ Classify every visual mark, including symbols inside labels, by role,
+ subject, medium, source, and Canvas delivery. A character or primitive that
+ communicates an affordance, object, category, or direction remains an icon
+ role beside words. If the result needs any icon, image, illustration,
+ diagram, vector, or exact typeface, read
+ [visual-assets.md](references/visual-assets.md) before selecting or loading
+ an acquisition skill and before search, generation, upload, or markup.
+ Before markup, scan literal text for
+ pictographic Unicode, emoji, or symbols; route
+ each icon through a permitted vector source or omit it when optional. Do not
+ replace an image or icon role with convenient text, primitives, gradients,
+ or invented SVG. Medium and visual consistency do not select an acquisition
+ route; generation requires a named content, fidelity, rights, or import
+ requirement that applicable sourcing cannot satisfy.
+
+ Keep one compact private trace before the first write:
+
+ ```txt
+ Evidence: opened source/artifact -> visual/interaction/detail finding -> decision
+ Visual thesis: product-specific anchor -> hierarchy/composition/document + type/rhythm + surface/edge/shape/depth + interaction/assets
+ Icons: candidate role -> icon/text/both + clarity rationale -> inspected source/rights/visual fit -> delivery
+ Assets: role -> subject -> medium -> decision context -> inspected source/rights -> delivery; generation only for a named unmet requirement
+ Reuse: rank -> responsibility + consumers -> stable anatomy + differences -> Author or Direct + incompatibility
+ Verification: representative pixels and native facts that must hold
+ ```
+
+3. **Model the result and choose a resource path.** Define visible node roles,
+ grouping, layout, spacing, typography, color, appearance, media, states, and
+ editable relationships in Figma terms before writing markup. Separate
+ ordinary Canvas HTML details from native semantics such as exact resources,
+ components, variables, masks, media paints, guides, or node types. Preserve
+ established resource usage on updates, and keep hierarchy and visible states
+ consistent with evidenced order or prerequisites. Do not let available
+ classes or schema choose the medium, structure, or direction.
+
+ Choose **Reuse** when evidence establishes a relevant existing system. For
+ two or more screens or states, or any repeated semantic family, read
+ [component-authoring.md](references/component-authoring.md) and run its gate
+ before markup contains a second consumer, including siblings in one call.
+ Inventory all recurring records and controls, rank them by spread and
+ coordination cost, and resolve every qualifying responsibility; ranking sets
+ implementation order, not scope. Author the highest-ranked first. Bound it
+ at the smallest subtree that owns the complete job and model
+ content, media, state, and label differences. A reusable label, icon, or
+ button does not resolve its repeated parent row or card. Keep a candidate
+ Direct only for a concrete structural, ownership, behavior, or contract
+ incompatibility. Do not impose a quota or invent speculative APIs.
+
+ - **Reuse:** read
+ [design-system-reuse.md](references/design-system-reuse.md) and use only
+ returned resources relevant to the result.
+ - **Direct:** use primitives, literals, and allowed external assets only for
+ local responsibilities. Do not call `get_design_system`, send `catalogId`,
+ or use catalog refs. Excluding existing resources disables Reuse, not
+ Author. Use one collision-resistant authoring-key prefix for task-created
+ resources.
+ - **Author:** when concrete consumers share a responsibility that should
+ evolve together, or the user requires a local resource or system extension,
+ read
+ [design-system-authoring.md](references/design-system-authoring.md). Define
+ native resources, contracts, bindings, and consumers, and track them for
+ reconciliation.
+
+ Treat an explicitly editable diagram as native semantics. Decide its
+ independently editable connectors, nodes, and geometry, then declare matching
+ LINE, ELLIPSE, RECTANGLE, or VECTOR shapes. Canvas HTML may serialize their
+ hierarchy, placeholders, surrounding composition, and labels; styled FRAME
+ rectangles or circles do not prove an editable diagram model.
+
+4. **Load mechanics, then serialize.** Read only references for concepts chosen
+ in step 3. Use Canvas HTML for the ordinary layer tree and typed fields for
+ selected native capabilities; skip Canvas HTML for `markup: null`. For create
+ or structural update, read
+ [canvas-html.md](references/canvas-html.md) in full. For an update with
+ trustworthy markup and unchanged structure, always read
+ [Elements and identity](references/canvas-html.md#elements-and-identity), then
+ only the changed Layout, Appearance, or text section. Preserve every
+ unaffected element, attribute, and class, and leave markup unchanged for a
+ native-only update. Copy complete private-native examples instead of guessing
+ from Plugin API knowledge or validation failures. Treat the supported
+ HTML/Tailwind subset as a transport boundary: never weaken the design or
+ rebuild ordinary web composition in native DSL. Use a supported equivalent
+ only when it preserves intent; otherwise report the missing capability.
+ Read [paints-effects.md](references/paints-effects.md) before applying any
+ nontrivial shadow, blur, glass, texture, noise, layered gradient, or advanced
+ image treatment, including effects expressed only through classes.
+
+5. **Prove one representative composition.** Apply and open the smallest
+ composition that establishes visual language, content density, layout, and
+ native representation before propagation. For net-new multi-screen or flow
+ work, use one materially complete requested screen and inspect its PNG before
+ serializing dependent screens. Do not write a second screen before opening
+ and correcting that PNG; an empty board root or mutation summary does not
+ satisfy this gate. A complete one-root result satisfies this gate
+ only when permitted existing evidence already established both visual
+ language and resource path before serialization. Never create a separate
+ proof, mood board, visual-thesis panel, or unchanged duplicate. Inspect the
+ representative pixels and correct visual language, hierarchy, density, and
+ material treatment before extracting reusable resources or expanding the
+ flow.
+
+ Treat the corrected composition as a flow-wide visual contract. Every
+ dependent screen must carry its relevant hierarchy, media logic, rhythm,
+ material and shape grammar, and interaction or detail treatment. It need not
+ repeat the same hero or asset count, but retaining only palette, type, borders,
+ or isolated motifs while the rest becomes generic is failed propagation.
+
+ On Author, replace representative usages with native instances or bindings
+ and verify their contracts before propagation. Keep definitions in a minimal,
+ separate source area. Verify the most demanding real consumer through its
+ descendants; INSTANCE type and root dimensions alone do not prove wrapping,
+ slot, media, or state content fits. If a real usage disproves a contract,
+ revise its boundary or return it to Direct. Follow
+ [design-system-authoring.md](references/design-system-authoring.md).
+
+6. **Apply the complete result.** Call `apply_canvas` once per coherent root.
+ Split large results at meaningful screen or section boundaries. To keep calls
+ in one movable board, create one fixed Auto Layout parent at its final planned
+ bounds before separate resource roots, then append bounded sections while
+ omitting existing children so updates preserve them. Use independent roots
+ when relative organization is not part of the deliverable. Never scan for
+ free space, maintain a coordinate ledger, or translate a create root; TemPad
+ positions new roots from rendered bounds.
+ Immediately before each Canvas HTML create or structural update, inspect the
+ final markup once as a whole: require a fixed width and height on the root,
+ then trace every `w-full`, `h-full`, and `grow` against its direct parent's
+ axis and the element's required dimensions. Give every absolute node exactly
+ one edge per axis and fixed parent and child dimensions. Correct every
+ violation before calling instead of serializing until the validator reveals
+ them one at a time.
+ At the same checkpoint, reconcile the final markup with the retained icon
+ trace: account for every material candidate as icon, text, or both with its
+ clarity rationale, and bind each selected icon to its inspected vector source.
+ An untraced candidate or unsourced selected icon blocks the call.
+ Reconcile every material content-bearing visualization and asset role with
+ the retained trace; an unresolved or mislabeled proxy blocks the call.
+ For markup with repeated records or controls, rescan the final content and
+ `data-key` families as required by [component-authoring.md](references/component-authoring.md);
+ any recurring responsibility omitted from the ranked trace reopens the gate.
+ A payload containing an unresolved or Author candidate's second consumer
+ must bind every included consumer as native instances or omit the second
+ consumer. Planned later conversion and easier sibling or nested components
+ do not pass.
+ On Author, propagate native instances and bindings—literal lookalikes do not
+ count—and keep main definitions visible as described in
+ [component-authoring.md](references/component-authoring.md).
+
+7. **Verify the delivered result.** After the complete apply, inspect the final
+ board and materially distinct screens. Open `asset.localPath` when present;
+ otherwise download and open the returned resource. Without an opened PNG, do
+ not claim visual verification. Use `get_structure` to compare page-child root
+ bounds when placement matters, a root moved after resizing, or the handoff
+ claims multiple roots do not overlap. Coordinates are relative to each
+ node's actual Figma parent; only page children are page-relative. Also inspect
+ structure when a promise depends on exact native semantics, such as an
+ editable diagram.
+
+ Compare rendered evidence with the brief and every task-relevant line in the
+ retained decision trace. Confirm that materially distinct screens preserve
+ the resolved visual language and asset treatment. Check overlap, clipping
+ including glyph ink, crowding or broken hierarchy and spacing, collapsed or
+ obscured content, inconsistent states, and incorrect bindings. Inspect all
+ visible outer edges and edge-adjacent type or controls in each screenshot
+ before claiming no clipping; apply success is not evidence of intact pixels.
+ Reapply the step 2 classification to each visible mark so its delivered node
+ type cannot redefine the decided representation or asset medium. On Author,
+ confirm visible, readable definitions and native INSTANCE or bound consumers
+ for every selected usage. Test the most demanding real property values and
+ compare instance descendant extents with the root; fix accidental overflow
+ by resizing, adding a truthful variant, or narrowing the component boundary.
+ Before handoff, re-check only previously named component candidates against
+ actual consumers. Author every candidate that now qualifies, or record a
+ concrete structural, ownership, behavior, or contract incompatibility;
+ verification is not a late speculative-discovery pass.
+
+ `verification.nativeFieldsChecked` proves only that declared paint, effect,
+ grid, guide, mask, and managed-SVG fields matched retained Figma state; it does
+ not prove pixels, undeclared native state, or other semantics. When the
+ handoff depends on a mask, IMAGE paint, layout grid, or frame guides, read
+ back `native` fields with `get_structure({ options: { native: true } })`;
+ apply input and mutation success do not establish live state.
+
+ Repair and recheck only affected compositions while preserving unaffected
+ content, state, assets, and relationships. Do not claim verification until
+ every observed defect is corrected, accepted with reason, or disclosed. Skip
+ screenshots for mechanical text, token, prop, or hierarchy-only edits, and
+ never turn the defect inventory into design requirements. A post-write
+ mismatch is implementation evidence, not permission to delete design intent;
+ correct it with an equivalent supported expression or disclose the platform
+ limitation.
+
+## Load references by decision
+
+Load references only after selecting their branch or capability; they provide
+mechanics, not design ideas.
+
+Read each routed reference through EOF at the workflow step that selects it.
+Do not batch later-stage references into an earlier read; a truncated combined
+read leaves every truncated file unresolved until completed.
+
+| Selected decision or capability | Reference |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| Net-new visual composition and anti-generic quality gate | [visual-composition.md](references/visual-composition.md) |
+| Unresolved material design decision | [style-grounding.md](references/style-grounding.md) |
+| Asset role, subject, medium, source, or typeface | [visual-assets.md](references/visual-assets.md) |
+| Existing-system reuse | [design-system-reuse.md](references/design-system-reuse.md) |
+| Local-system authoring | [design-system-authoring.md](references/design-system-authoring.md) |
+| Bounded research, asset, inventory, or visual-QA delegation | [delegation.md](references/delegation.md) |
+| Pages, sections, groups, Booleans, masks, transforms, shapes, or vectors | [document-geometry.md](references/document-geometry.md) |
+| Paints, media, effects, shaders, grids, or guides | [paints-effects.md](references/paints-effects.md) |
+| Exact fonts, rich text, range styles, lists, or hyperlinks | [rich-text.md](references/rich-text.md) |
+| Components, variant sets, properties, or Slots | [component-authoring.md](references/component-authoring.md) |
+| Variables, collections, modes, or bindings | [variables.md](references/variables.md) |
+| Paint, Text, Effect, or Grid styles and bindings | [local-styles.md](references/local-styles.md) |
+| Canvas elements, identity, layout, appearance, and text syntax | [canvas-html.md](references/canvas-html.md) |
+
+## Create and update contract
+
+Create describes one complete root. Update changes only `targetNodeId`; supplied
+fields state desired values and omissions preserve live state. `removeKeys`
+removes owned descendants; `markup: null` removes the update root. Keep
+`data-key` stable and recover it from `get_structure.authoringKey`, not names.
+
+## Safety
+
+- Never write outside scope or use names as identity.
+- Treat an instance as an authoring boundary: update its root or definition,
+ never a definition-derived sublayer.
+- Never remove manual or unkeyed content, external references, unmanaged
+ resources, or a component with surviving instances.
+- Never mutate remote resources, publish, detach or reset instances, or execute
+ arbitrary JavaScript.
+- Use explicit `null` only for supported links or managed resources that the
+ requested result truly removes.
+- Correct validation failures; never imitate an unresolved resource.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/agents/openai.yaml b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/agents/openai.yaml
new file mode 100644
index 00000000..25e5075e
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+ display_name: 'Design in Figma'
+ short_description: 'Create user-directed native Figma designs'
+ icon_small: './assets/icon.svg'
+ icon_large: './assets/icon.svg'
+ brand_color: '#0098FF'
+ default_prompt: 'Use $figma-canvas-authoring to create a native Figma design while following my resource constraints.'
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/assets/icon.svg b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/assets/icon.svg
new file mode 100644
index 00000000..bdbdf027
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/assets/icon.svg
@@ -0,0 +1,16 @@
+
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/canvas-html.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/canvas-html.md
new file mode 100644
index 00000000..8da73714
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/canvas-html.md
@@ -0,0 +1,230 @@
+# Canvas HTML and Tailwind subset
+
+Canvas HTML describes desired state, not browser rendering. Classes do not
+cover every Figma result: use routed native bindings for gradients, media,
+non-shadow effects, masks, transforms, exact fonts, and rich text. Use primitive
+layers only for intended layered geometry, never as a CSS substitute.
+
+One `apply_canvas` markup tree may contain at most 160 elements and 12 levels.
+This is a safety ceiling, not a target. Before calling, count the tree, include
+only assets referenced by that call, and split larger work at meaningful screen
+or section boundaries.
+
+Prefer supported Tailwind utilities; use arbitrary pixels only off the default
+scale. Numeric spacing follows Tailwind v4's `4px` unit. Theme extensions,
+variants, plugins, viewport-dependent utilities, and CSS cascade are unsupported.
+
+## Contents
+
+- [Elements and identity](#elements-and-identity)
+- [Layout](#layout)
+- [Appearance and text](#appearance-and-text)
+
+## Elements and identity
+
+- Use `div`, `span`, or a component tag returned by the active catalog.
+- Give every element one unique `data-key` of letters, numbers, `. / : _ -`.
+- Use `data-node-id` only in update mode to adopt an exact live node; instance
+ sublayers are not authoring targets.
+- Use no arbitrary attributes on `div` or `span`. Common catalog links use
+ `data-var-="vN"` and `data-style-="sN"`; `"none"` explicitly
+ unlinks that field.
+- A `span` contains only text and ` ` or ` ` line breaks. Use
+ `whitespace-pre-wrap` for literal newlines or repeated spaces. A plain `&` is
+ literal unless it forms a semicolon-terminated entity; supported entities
+ decode. Put flex/grid, gaps, padding, borders, corners, and box shadows on a
+ parent `div`, leaving dimensions, shared appearance, and text utilities on
+ the text node.
+- A component tag is childless, includes its returned `data-ref`, and accepts
+ returned props plus the shared class, identity, variable, and style
+ attributes.
+
+Variable attributes use kebab-case native field names: fill, stroke, characters,
+visible, dimensions/bounds, gaps, four paddings/corners/stroke sides, radius,
+stroke weight, opacity, and whole-node font/line-height/letter-spacing/paragraph
+fields. Style attributes are `data-style-fill`, `data-style-stroke`,
+`data-style-text`, `data-style-effect`, and `data-style-grid`. Node-type and
+fallback rules still apply.
+
+Every primitive needs one width and one height. Supported fixed forms are:
+
+- default spacing: `w-N`, `h-N`, `size-N` (`N * 4px`), plus `w-px`, `h-px`, `size-px`
+- default width containers: `w-3xs|2xs|xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl`
+- exact: `w-[Npx]`, `h-[Npx]`, `size-[Npx]`
+- hug: `w-fit`, `h-fit`
+- hug both axes: `size-fit`
+- fill: `w-full`, `h-full`, or `size-full` for both axes
+- bounds: numeric, `px`, or arbitrary-pixel values with `min-w`, `max-w`, `min-h`, or `max-h`;
+ width bounds also accept the default container names; use `min-w-none`, `max-w-none`,
+ `min-h-none`, or `max-h-none` to clear a bound in an update
+
+Text using `w-fit` also needs `h-fit`; prefer `size-fit`. Fixed-width `h-fit`
+remains valid for wrapping text.
+
+Create and update markup roots require fixed width and height; fill, hug, and
+grow are invalid even when the live target has a sized parent.
+
+Use `w-full` only on a `flex-col` cross axis, `h-full` only on a `flex-row`
+cross axis, and `grow` on the main axis; `grow-0` clears growth. `grow` does not
+replace required dimensions—for a row track use `grow w-fit h-[3px]`. Give
+growing text in constrained rows a positive `min-w-*` to prevent collapse.
+Budget fixed Auto Layout main axes as padding + gaps + fixed/minimum child
+extents. Grid children may fill cells. Direct dimension variables require fixed
+fallbacks. Fixed sizes must be at least `0.01px`; native lines use `h-[0px]`.
+
+## Layout
+
+Use Auto Layout for ordinary product UI. `flex` follows CSS's horizontal default;
+use `flex-row` when that direction should be explicit and `flex-col` for a
+vertical stack:
+
+- `flex`, `flex flex-row`, or `flex flex-col`
+- `items-start|center|end|baseline`
+- `justify-start|center|end|between`
+- `flex-wrap`, `flex-nowrap`, `content-between`, `content-normal`
+- `gap-N`, `gap-x-N`, `gap-y-N`, or exact `[Npx]`
+- `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl` with `-N`, `-px`, or `-[Npx]`
+- `box-border`, `box-content`
+
+New Auto Layout frames include inside strokes by default (`box-border`);
+`box-content` excludes them. Center/outside strokes never affect layout, and
+each nested frame owns its setting. Fixed create sizes must cover opposing
+padding plus included inside strokes. Figma determines `FILL` geometry and
+border-box distribution. Derive exact descendant or instance sizes from the
+rendered inner box, not nominal parent size; prefer valid cross-axis fill and
+exceed the box only for intentional bleed or overlap.
+
+`managed-content-overflow` means managed Text or INSTANCE exceeds its direct
+managed Frame or Component, or a native INSTANCE contains descendant content
+beyond its own fixed root. Inspect edges, clipping, rendering, and instance
+bounds; resize or realign accidental overflow and retain only intentional bleed,
+crop, or overlap. Property-driven content outside an INSTANCE root is a broken
+component contract rather than intentional consumer overflow.
+
+`justify-between` uses nonnegative native Auto gap and keeps one child at the
+start. Use negative `figma.autoLayout.itemSpacing` only for intentional overlap.
+Omitting box-sizing on update preserves the live setting.
+
+`hidden` and BOOLEAN visibility remove in-flow children, changing gaps,
+positions, and hug bounds. To preserve geometry, keep a fixed slot and toggle
+its inner child. `absolute left-[Npx] top-[Npx]` maps to Ignore Auto Layout for
+true overlays; it needs fixed offsets, cannot fill/grow, and leaves surrounding
+flow unchanged. Its text and Auto Layout descendants may still hug.
+
+For grid use:
+
+- `grid grid-cols-N`
+- optional `grid-rows-N`
+- custom tracks: `grid-cols-[1fr_240px_fit-content(100%)]`
+- optional `grid-flow-row` or `grid-flow-none`
+- child placement: `col-start-N`, `row-start-N`, `col-span-N`, `row-span-N`
+- child alignment: `justify-self-auto|start|center|end`,
+ `self-auto|start|center|end`
+
+Give manual grid children both row and column starts or neither. Auto-flow uses
+source order without explicit starts. A height-hugging grid cannot use flexible
+or automatic rows; fix either its height or row tracks. Omitting `grid-rows-*`
+creates native automatic content-sized rows. On a fixed-height grid, declare
+row tracks when children should share or fill the available height; increasing
+only the container height does not enlarge automatic rows.
+
+For a coherent board larger than one call, first create one fixed parent:
+
+```json
+{
+ "mode": "create",
+ "markup": ""
+}
+```
+
+Then append one bounded screen per update. Keep the root key and classes stable,
+target its returned ID, and omit previously added children so they remain in
+place:
+
+```json
+{
+ "mode": "update",
+ "targetNodeId": "FrameID:app-board",
+ "markup": "
"
+}
+```
+
+For freeform composition, omit layout classes and give each child `absolute`
+with exactly one horizontal edge (`left-*` or `right-*`) and one vertical edge
+(`top-*` or `bottom-*`), including negative or exact values, or use a native
+relative transform. Edge placement needs fixed parent and child bounds. A plain
+non-flex/grid `div` is freeform even with one child; opt into layout for every
+in-flow child. Absolute children cannot grow or fill; use `static` to return one
+to Auto Layout on update.
+
+## Appearance and text
+
+Frame appearance:
+
+- `bg-transparent|white|black`, or an exact CSS hex value
+- Linear backgrounds use `bg-linear-to-t|tr|r|br|b|bl|l|tl` with exact
+ `from-white|black|[#hex]`, optional `via-white|black|[#hex]`, and required
+ `to-white|black|[#hex]` stops. Stops are fixed at 0, optional 0.5, and 1;
+ `bg-gradient-to-*` is accepted as a legacy alias. Do not combine a gradient
+ with a solid background, direct fill paints, or a fill style/variable.
+- `border`, `border-N`, `border-[Npx]`; use `border-x|y|t|r|b|l` with the same widths
+- `border-white|black`, or an exact CSS hex value
+- `rounded`, `rounded-none|xs|sm|md|lg|xl|2xl|3xl|4xl|full`, or `rounded-[Npx]`;
+ prefix the value with `t`, `r`, `b`, `l`, `tl`, `tr`, `br`, or `bl` for individual sides/corners
+- `overflow-hidden`, `overflow-visible`
+- Exact pixel shadow lists through `shadow-[...]` or `inset-shadow-[...]`.
+ Each layer needs an explicit hex, `rgb()`, or `rgba()` color and two to four
+ pixel lengths; use underscores for spaces, for example
+ `shadow-[0_8px_24px_rgba(0,0,0,0.16)]`.
+- `shadow-none` and `inset-shadow-none` clear their class-owned effect stack.
+ Theme-dependent named scales such as `shadow-md` are unsupported: use an
+ explicit native style or typed effect/variable binding for a reusable token,
+ or resolve the governing theme before applying and provide the exact value.
+
+Figma accepts shadow spread only on rectangles and ellipses, or on frames,
+components, and instances with a visible fill and clipping enabled.
+
+A new border needs weight and paint, literal or bound. Updates may change either
+independently; omission preserves the other.
+
+New frames are transparent when background is omitted, including frames added
+during update. On an existing frame, omission preserves its live background;
+use `bg-transparent` to clear it. Set an explicit background when fill is
+intended.
+
+Shared appearance:
+
+- `opacity-N` (`N%`) or `opacity-[0..1]`, `hidden`, `visible`
+- `rotate-N`, `-rotate-N`, `rotate-none`, or `rotate-[Ndeg]`
+- `mix-blend-` with `pass-through`, `normal`, `darken`, `multiply`,
+ `plus-darker`, `color-burn`, `lighten`, `screen`, `plus-lighter`,
+ `color-dodge`, `overlay`, `soft-light`, `hard-light`, `difference`,
+ `exclusion`, `hue`, `saturation`, `color`, or `luminosity`
+
+Text:
+
+- `font-sans|serif|mono` resolve to an editor-available family in that category,
+ preferring Inter, Noto Serif, and Noto Sans Mono
+- `font-thin|extralight|light|normal|medium|semibold|bold|extrabold|black`
+- `text-xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl` with their default line
+ heights, `text-SIZE/N`, or `text-[Npx]`
+- `leading-none|tight|snug|normal|relaxed|loose`, `leading-N`, `leading-[Npx]`,
+ `leading-[N%]`, or a unitless arbitrary ratio
+- `tracking-tighter|tight|normal|wide|wider|widest`, `tracking-[Npx]`,
+ `tracking-[N%]`, or `tracking-[Nem]`
+- `text-left|center|right|justify`
+- `normal-case`, `uppercase`, `lowercase`, `capitalize`
+- `no-underline`, `underline`, `line-through`
+- `truncate`, `line-clamp-N`, `line-clamp-none`
+- `text-white|black`, an exact CSS hex value, `whitespace-pre-wrap`
+- `text-shadow-[...]` for an exact pixel text-shadow list with a color and two
+ or three pixel lengths; `text-shadow-none` clears it
+
+A `span` is one TEXT node, so `bg-*` and `text-*` share its fill channel. Put
+background on a parent `div` and color on its child `span`.
+
+Shadow classes compile to the native effect stack; never combine them with
+`figma.effects` or an Effect style on that node.
+
+Unknown elements, attributes, classes, CSS, responsive/state prefixes, custom
+themes, margins, percentages, and plugins fail closed.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/component-authoring.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/component-authoring.md
new file mode 100644
index 00000000..82e0d061
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/component-authoring.md
@@ -0,0 +1,310 @@
+# Author reusable components
+
+Use this reference to run the required shared-responsibility gate or after
+selecting a reusable local component. It explains representation, not library
+strategy. New local components need no `get_design_system`; use catalogs only
+for discovery or normalized library props, and exact returned IDs for newly
+authored components.
+
+## Shared-responsibility gate
+
+Run this gate for two or more screens or states, or before a second consumer of
+the same content, control, or system responsibility. Repeated appearance alone
+does not qualify.
+
+Before markup can create the second consumer:
+
+1. List every recurring semantic family: shell, navigation, actions, rows,
+ cards, and other record families. Bound each at the smallest subtree that
+ owns the complete responsibility.
+2. Identify stable anatomy and real differences. Copy, media, availability,
+ state, labels, visibility, swaps, and bounded slot content are contract inputs,
+ not reasons to duplicate.
+3. Rank candidates by consumer spread and coordination cost. Author the
+ highest-ranked qualifying family first. A label, icon, or button component
+ does not close its repeated parent row or card.
+4. Keep a candidate Direct only for a concrete structural, ownership, behavior,
+ or contract incompatibility. Narrow an incompatible boundary once before
+ rejecting it. Different screens, siblings, labels, destinations, or small
+ width changes are not incompatibilities.
+
+Ranking sets order, not scope. Before final markup, resolve every recurring
+family as Author or Direct with a concrete incompatibility. One authored shell,
+navigation, control, or nested child never exempts repeated rows, cards, or
+records.
+
+Keep one ranked trace:
+
+```txt
+rank -> responsibility + consumers -> stable anatomy + differences -> Author or Direct + incompatibility
+```
+
+Build it from planned content and final markup. Scan recurring sibling families,
+cross-screen roles, and patterned `data-key` groups. An unlisted recurring
+family reopens the gate. In the first payload that could contain a candidate's
+second consumer, bind every included Author consumer as a native instance or
+omit the second consumer. Planned later conversion and a nested or lower-ranked
+component do not close the gate.
+
+This is a comparison gate, not a quota. Author nothing when no responsibility
+qualifies. If one representative usage must stabilize first, replace that
+primitive with an instance before adding another consumer. Use the exact
+returned `rootNodeId` or `nodeIdsByKey` entry for every usage; never leave
+primitive lookalikes as final consumers.
+
+A keyed primitive cannot become an INSTANCE in place. Update its bounded
+ancestor, add the instance under a new key, and remove the old key in the same
+call.
+
+Before propagation, create the smallest real definition, instantiate it once,
+and verify the exact reference. Stop component authoring if the ID is missing,
+the instance fails, or the definition is empty, default-sized, or loses
+properties. Do not substitute primitives or claim completion. Continue only
+independent Direct work, report the degraded component result, and remove a
+temporary definition only when unused and safe. Re-read a corrupt definition
+and its intended usage; never rebuild it in place or remove one with instances.
+Recreate only when unused.
+
+Before handoff, reconcile the named candidates with actual consumers. Each
+qualifying family must have native INSTANCE consumers or a recorded concrete
+incompatibility. Inspect the most demanding instance through its descendants;
+root type and size do not prove wrapping, slots, media, or state content fit.
+Revise the contract or boundary when real content breaks it.
+
+Markup-only updates preserve keyed components, sets, instances, and shapes.
+Restate native bindings only when changing native state; new native nodes still
+need declarations or component references.
+
+Copy a complete recipe and change its design facts. Do not infer TemPad's
+component shape from raw Plugin API calls.
+
+## Contents
+
+- [Define the contract from real usages](#define-the-contract-from-real-usages)
+- [Keep source definitions discoverable](#keep-source-definitions-discoverable)
+- [Component and properties](#component-and-properties)
+- [Consume an authored component directly](#consume-an-authored-component-directly)
+- [Variant set](#variant-set)
+- [Slots and instances](#slots-and-instances)
+
+## Define the contract from real usages
+
+Compare every intended usage. Separate stable anatomy from varying content,
+state, or nested substitution; map differences to the smallest supported Text,
+Boolean, Instance Swap, variant, Slot, or nested-composition mechanism. Treat a
+field as invariant only when real usages agree.
+
+Size the contract from real extremes: test the longest wrapping text, widest
+label, largest nested swap, and materially different slots. Compare descendant
+bounds with the INSTANCE root; screenshots can still paint invalid overflow.
+If content exceeds the root, enlarge the definition, add a truthful size
+variant, or move the varying region outside a smaller stable boundary.
+If consumer-specific media cannot be expressed by the available instance
+contract, keep that media direct and componentize the stable surrounding
+responsibility; never freeze one image into every instance to retain a larger
+component boundary.
+
+When stable anatomy should evolve together, expressible state differences
+support a shared contract. Keep it local only when divergence or contract cost
+outweighs coordinated change.
+
+If the contract cannot express a meaningful difference, revise it or keep the
+responsibility local. Never force usages to share placeholder content or an
+accidental default merely because outer geometry repeats.
+
+Model each mutually exclusive categorical concern as one variant axis; do not
+replace it with Booleans that allow impossible combinations. Reserve Booleans
+for independently optional content or behavior.
+
+Expose one choice through both a variant and independent property only when real
+usages vary them independently. Keep each source variant's visible state
+truthful; instance overrides do not repair accidental source defaults.
+
+## Keep source definitions discoverable
+
+Keep main components and sets visible at natural bounds in a clearly named
+source area separate from screens. Never hide, clip, make transparent, or
+invisibly nest them. For several families, use a top-level SECTION with
+`contentsHidden: false`, discoverable definition children, and content-sized
+bounds.
+
+Keep each real definition once, without redundant specimens. Before handoff,
+use `get_structure` to verify every definition is visible and every intended
+consumer is an INSTANCE. Inspect distinct source variants at readable scale;
+names, content, and styling must encode the same state.
+
+Keep the source area operational and visually subordinate: use the smallest
+content-sized container that exposes the definitions, outside the consumer
+board or screen sequence. Do not turn it into a branded artboard, mood board,
+visual-thesis panel, token showcase, or documentation page unless the user asks
+for that deliverable. Product screenshots and presentation framing should stay
+focused on the requested experience.
+
+## Component and properties
+
+This complete call creates a component with TEXT and BOOLEAN properties and
+connects both properties to its label layer.
+
+```json
+{
+ "mode": "create",
+ "markup": "
Continue
",
+ "native": {
+ "button": {
+ "figma": {
+ "name": "Button",
+ "component": {
+ "type": "COMPONENT",
+ "properties": {
+ "label": {
+ "type": "TEXT",
+ "name": "Label",
+ "defaultValue": "Continue"
+ },
+ "show-label": {
+ "type": "BOOLEAN",
+ "name": "Show label",
+ "defaultValue": true
+ }
+ }
+ }
+ }
+ },
+ "button/label": {
+ "figma": {
+ "componentPropertyReferences": {
+ "characters": "label",
+ "visible": "show-label"
+ }
+ }
+ }
+ }
+}
+```
+
+Stable keys such as `label` connect definitions and sublayer references within
+one result; they are not generated Figma property names. Supported property
+types are `BOOLEAN`, `TEXT`, and `INSTANCE_SWAP`, linked through `visible`,
+`characters`, and `mainComponent` respectively.
+
+BOOLEAN properties control visibility, not styling. Hidden in-flow children
+leave Auto Layout. Use this only for intentionally optional content. To preserve
+geometry, toggle an inner layer inside a fixed slot, use `absolute` for a true
+overlay, or use geometry-equivalent variants for whole-state changes.
+
+Treat `layout-affecting-visibility-property` as a contract warning. Fix it when
+geometry must stay stable. Accept intentional reflow only after comparing true
+and false instances for bounds, sibling positions, baselines, and clipping; one
+default-state screenshot is insufficient.
+
+## Consume an authored component directly
+
+Use the exact ID returned by `apply_canvas`. For TemPad-authored components,
+`componentProperties` accepts their stable definition keys. This follow-up
+needs no catalog:
+
+```json
+{
+ "mode": "create",
+ "markup": "
",
+ "native": {
+ "screen/action": {
+ "component": { "id": "ComponentID:created-button" },
+ "componentProperties": { "label": "Save", "show-label": true }
+ }
+ }
+}
+```
+
+Replace the illustrative ID with the returned ID. Never invent IDs or use this
+shortcut for unidentified library components.
+
+## Variant set
+
+This call creates two components in one variant set. Every direct child of a new
+set must be an authored component; names encode axes as `Property=Value`.
+
+```json
+{
+ "mode": "create",
+ "markup": "
Continue
Continue
",
+ "native": {
+ "button-set": {
+ "figma": {
+ "name": "Button",
+ "component": { "type": "COMPONENT_SET" }
+ }
+ },
+ "button/default": {
+ "figma": {
+ "name": "State=Default",
+ "component": { "type": "COMPONENT" }
+ }
+ },
+ "button/hover": {
+ "figma": {
+ "name": "State=Hover",
+ "component": { "type": "COMPONENT" }
+ }
+ }
+ }
+}
+```
+
+Consume the returned set ID and select siblings through variant properties. If
+the call returns the set as `rootNodeId`, this creates Default and Hover:
+
+```json
+{
+ "mode": "create",
+ "markup": "
",
+ "native": {
+ "screen/default": {
+ "component": { "id": "ComponentSetID:created-button-set" }
+ },
+ "screen/hover": {
+ "component": { "id": "ComponentSetID:created-button-set" },
+ "componentProperties": { "State": "Hover" }
+ }
+ }
+}
+```
+
+Replace the ID with returned `rootNodeId`. The set ID creates its default;
+`componentProperties` selects another encoded variant. An exact child ID from
+`nodeIdsByKey` may instantiate that variant directly.
+
+Use `descriptionMarkdown` and `documentationLink` only for real guidance, inside
+`figma.component` beside `type` and `properties`:
+
+```json
+{
+ "figma": {
+ "name": "Button",
+ "component": {
+ "type": "COMPONENT",
+ "descriptionMarkdown": "Primary action"
+ }
+ }
+}
+```
+
+Define shared properties on the component set rather than on one variant.
+
+## Slots and instances
+
+Use `figma.slot` only for an intentional flexible nested-content API. New slots
+must be inside local authored components and include `property.name`; markup
+children become defaults. Optional settings control stretching, empty display,
+child limits, and preferred values.
+
+An `INSTANCE_SWAP` default uses exact live component/set ID `{ "id": "..." }`
+or importable library key `{ "key": "..." }`. Preferred values require
+`{ "type": "COMPONENT" | "COMPONENT_SET", "key": "..." }` and accept neither
+live IDs nor catalog refs. Resolve catalog identity before authoring and never
+invent it. Put advanced state under `figma.instance`; omission preserves normal
+override behavior.
+
+Never edit a remote component, nest a main component inside another main
+component, delete a component with surviving instances, or create properties
+and variants that the requested component API does not need.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/delegation.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/delegation.md
new file mode 100644
index 00000000..181b7cc9
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/delegation.md
@@ -0,0 +1,82 @@
+# Delegate bounded evidence work
+
+Delegate evidence gathering or isolated production, never focal judgment. The
+main agent synthesizes results and remains the only Canvas writer.
+
+## Pass the delegation gate
+
+Delegate only work that is:
+
+1. **Separable:** has a stable objective independent of evolving design choices.
+2. **Compressible:** needs only a compact task-local brief.
+3. **Isolated:** is read-only or produces an isolated artifact without mutating
+ Figma, design-system state, or another agent's files.
+4. **Verifiable:** returns citations, importable asset references, exact facts,
+ or a bounded defect list the main agent can inspect.
+5. **Worth coordinating:** gains enough from parallelism, specialist capability,
+ or independent review to justify handoff and synthesis.
+
+Keep work local if any condition fails. Do not delegate for ritual, convenience,
+or another unsupported aesthetic opinion.
+
+## Write a complete handoff
+
+Give each worker one objective and its relevance, only required task evidence
+and constraints, permitted tools and sources, explicit exclusions including no
+Canvas writes, and an exact output contract and stop condition. The main agent
+must read required Canvas references and set safety boundaries; never delegate
+interpretation of this skill. Prefer fresh or minimum-context workers, pass
+source evidence rather than conclusions, and avoid overlapping assignments.
+
+## Suitable tracks
+
+### Research scout
+
+After framing the design problem, delegate a bounded evidence question. Return:
+
+```txt
+open decision; exact source; applicable finding; relevance; authority boundary
+```
+
+The scout does not choose direction. Combine questions only when their search
+space is shared; use multiple scouts only for independent spaces.
+
+### Asset scout
+
+After fixing asset requirements and import contract, return one importable
+`imageUrl` or `assetHash` per asset plus MIME type, dimensions, provenance, and
+factual description. Return no bytes, rejected candidates, or transcript. The
+main agent owns selection and integration.
+
+### Independent QA scout
+
+After a representative composition exists, provide a fresh worker its
+screenshot and frozen brief without creator rationale or suspected defects. Ask
+for at most eight observations:
+
+```txt
+severity; screen/node or region; observed defect; visible evidence; violated constraint
+```
+
+The scout neither edits nor declares completion; the main agent checks findings
+against the live canvas.
+
+### Inventory scout
+
+Use read-only inventory when independent volume warrants it, such as several
+screens or icon candidates. Require exact findings and references, not a design
+proposal.
+
+## Orchestrate conservatively
+
+- Default to one worker; use at most two concurrent non-overlapping workers.
+- Keep a faster local critical path with the main agent.
+- Only the main agent resolves intent and conflicts, chooses direction, calls
+ `apply_canvas`, and accepts the result.
+- Resolve conflicts from evidence, not voting; discard unverifiable or
+ out-of-scope claims and stop when evidence is sufficient.
+
+Never delegate interdependent page or component construction, component
+authoring plus instance placement, concurrent updates to one root, final
+composition, or final acceptance. These require one ordered mutation stream and
+continuous awareness of the whole.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/design-system-authoring.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/design-system-authoring.md
new file mode 100644
index 00000000..0c126e96
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/design-system-authoring.md
@@ -0,0 +1,81 @@
+# Implement a selected local design system
+
+Use this reference only when the user or resolved plan requires new local
+components, variables, or styles. It translates that plan into native resources
+and verifies delivery; it does not choose component strategy, visual language,
+resource inventory, or token taxonomy.
+
+## Establish the implementation contract
+
+Before writing, identify each selected resource, responsibility, concrete
+consumer, meaningful variation, and exclusion. Resolve any open material
+boundary first. For components, use the gate in
+[component-authoring.md](component-authoring.md); screen count, one-screen scope,
+and visual similarity alone neither establish nor exclude a component.
+
+Keep a private reconciliation map:
+
+```txt
+selected resource -> native representation -> intended consumers
+```
+
+A resource is complete only when its native definition or binding exists and
+every intended consumer uses it. Equivalent primitives or literals are not
+coverage.
+
+## Translate the plan
+
+Use this loop:
+
+1. Stabilize one representative composition.
+2. Author only selected resources with known consumers.
+3. Exercise each contract in that composition.
+4. Propagate native instances and bindings to all intended consumers.
+5. Reconcile the final artifact with the map.
+
+Preserve the decided semantics:
+
+- A variable carries a semantic value consumers must bind and evolve together;
+ name it by role, not literal.
+- A local style carries a reusable paint, text, effect, or grid definition. Do
+ not duplicate one decision across resource types unless required.
+- A component carries a reusable responsibility. Define stable anatomy and
+ expose only variations required by real usages.
+
+Consume a component through a childless instance placeholder without layout or
+appearance classes. Do not make a repeated shell or wrapping top-level subtree
+a component unless every consumer can use that placeholder through supported
+properties. Slots do not permit markup children on instance placeholders; keep
+incompatible wrappers as ordinary structure around a compatible inner boundary.
+
+Map each real component difference to the smallest supported mechanism: Text,
+Boolean, Instance Swap, variant, Slot, or nested composition. Use one variant
+axis per mutually exclusive categorical concern and Booleans only for
+independently optional concerns. Do not encode arbitrary content as variants,
+generate unused combinations, or freeze varying content as invariant.
+
+If supported native mechanisms cannot express a real usage, do not weaken or
+redesign it silently. Choose another valid boundary or report the limitation.
+
+Read [variables.md](variables.md), [local-styles.md](local-styles.md), or
+[component-authoring.md](component-authoring.md) only for selected resource
+types.
+
+## Verify the native handoff
+
+Verify through representative consumers, not definitions alone: inspect native
+bindings, Auto Layout, text resizing, property behavior, and every material
+state. Raw literals and primitive lookalikes do not demonstrate system usage.
+
+For components, verify visible inspectable definitions and native INSTANCE
+consumers using [component-authoring.md](component-authoring.md). For variables
+and styles, inspect live bindings rather than apply input or equal values.
+
+Resolve warnings through real consumers, or remove a resource only when the
+resolved plan no longer includes it. Tool friction, payload size, or an easy
+resource type does not alter the plan. Do not create swatches, specimens,
+definition panels, or redundant examples solely for verification; add
+documentation only when requested.
+
+Finish when selected resources support all requested usages and the live Figma
+structure reconciles with the map. Do not expand for imagined future needs.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/design-system-reuse.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/design-system-reuse.md
new file mode 100644
index 00000000..cd425c60
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/design-system-reuse.md
@@ -0,0 +1,56 @@
+# Reuse an existing design system
+
+Use this reference only when reuse is allowed and relevant. If the user rejects
+a design system, use Direct.
+
+## Discover definitions
+
+Call `get_design_system` without arguments. Its immutable deterministic catalog
+contains:
+
+- a `catalogId` scoping all short refs;
+- component tags, props, source pages, and native sizes;
+- variables, collections, modes, styles, and shaders as refs such as `v1`,
+ `k1`, `m1_2`, `s1`, and `h1`;
+- `omitted` and `nextCursor` when more definitions remain.
+
+The catalog neither scans usage nor loads pages or ranks resources. Select from
+returned names, pages, summaries, props, types, scopes, and defaults. Continue a
+cursor or inspect an exact ref only until evidence is sufficient.
+
+Prefer, in order: catalog component, supported component prop, matching native
+style, semantic variable, then primitive or literal for a real gap.
+
+When variants, anatomy, layout, or semantic meaning affect the result, inspect
+the exact `ref` with the same `catalogId`. Use its `previewNodeId` with
+`get_screenshot` only when appearance affects selection. Read an existing
+composition with `get_code` or `get_screenshot`; catalogs do not reveal usage
+conventions. Never invent refs, IDs, keys, props, or variant values.
+
+## Apply catalog resources
+
+Component tags are childless, include returned `data-ref`, and use exact props.
+Omit size classes to preserve native size. Bind common variables and styles with
+`data-var-="vN"` and `data-style-="sN"`; put collection modes or
+strict native links under `native[data-key]`.
+
+Replace every illustrative ref in this contract with one from the active
+catalog:
+
+```json
+{
+ "mode": "create",
+ "catalogId": "ds_example",
+ "markup": "
Team settings
",
+ "native": {
+ "settings": {
+ "variableModes": { "k1": "m1_1" }
+ }
+ }
+}
+```
+
+If a mandatory component is absent, ask the user to open its definition page;
+otherwise use the normal primitive fallback. An empty canvas does not block
+catalog reuse. When reuse is unavailable, create a small coherent primitive
+draft—never a token or component library solely for one screen.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/document-geometry.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/document-geometry.md
new file mode 100644
index 00000000..ed158572
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/document-geometry.md
@@ -0,0 +1,114 @@
+# Document and native geometry
+
+Use `native[key].figma` only for state HTML and classes cannot express honestly;
+it remains declarative desired state.
+
+## Contents
+
+- [Pages and containers](#pages-and-containers)
+- [Shapes and vectors](#shapes-and-vectors)
+- [Transforms, masks, and native state](#transforms-masks-and-native-state)
+
+## Pages and containers
+
+Top-level `page` can set a name, exact zero-based document index, solid RGBA
+background, ordered guides, and explicit variable modes. In create mode it may
+target an existing `id`, adopt or reuse `pageKey`, or create a named page for a
+missing key. Updates stay on the target node's page.
+
+Use:
+
+- `figma.section: { contentsHidden? }` for canvas organization;
+- `figma.group: true` for an intrinsic group;
+- `figma.booleanOperation: "UNION" | "SUBTRACT" | "INTERSECT" | "EXCLUDE"`
+ for non-destructive geometry.
+
+Sections can be canvas roots or direct children of sections; a frame cannot
+contain a section. Sections require fixed pixel dimensions and freeform
+children. Groups and Booleans use `w-fit h-fit` with freeform children. A new
+group needs one child and a Boolean needs two. When updating an intrinsic
+container's children,
+describe every live direct child because order is semantic.
+
+Sections have no frame clipping, so omit `overflow-hidden` and
+`overflow-visible`. When `targetNodeId` is an existing section, retain
+`figma.section` on the root or the frame-typed markup root is rejected.
+
+## Shapes and vectors
+
+Use a childless `div` with `figma.shape`:
+
+- `{ "type": "RECTANGLE" }`
+- `{ "type": "LINE" }`
+- `{ "type": "ELLIPSE", "arc": { "startAngle", "endAngle", "innerRadius" } }`
+- `{ "type": "POLYGON", "pointCount": 3 }`
+- `{ "type": "STAR", "pointCount": 5, "innerRadius": 0.5 }`
+- `{ "type": "VECTOR", "paths": [...] }`
+- `{ "type": "VECTOR", "network": {...}, "handleMirroring": "..." }`
+
+Use exact uppercase `M L Q C Z` paths for ordinary icons; use a vector network
+only for branching segments, per-vertex state, or region-specific fills or
+styles. Never provide both. New vectors need geometry; omission preserves it on
+update and an empty path or network clears it.
+
+Each path item is an object. `windingRule` is `"NONE"`, `"NONZERO"`, or
+`"EVENODD"`; use `"NONE"` for an open stroked path. Path data uses
+whitespace-separated uppercase commands and numbers.
+
+Figma normalizes path geometry to tight bounds before applying markup size. The
+childless `div` defines final bounds, not a preserved viewport. For alignment,
+offset it by the path's minimum x/y and size it to the x/y spans; otherwise a
+partial-range path stretches to the box. Verify rendered anchors because
+`get_structure` returns node bounds, not path coordinates.
+
+This Direct recipe creates an editable branch curve:
+
+```json
+{
+ "mode": "create",
+ "markup": "
",
+ "native": {
+ "branch": {
+ "figma": {
+ "name": "Branch",
+ "shape": {
+ "type": "VECTOR",
+ "paths": [
+ {
+ "windingRule": "NONE",
+ "data": "M 14 300 C 30 252 52 188 104 20"
+ }
+ ]
+ },
+ "fills": [],
+ "strokes": [{ "type": "SOLID", "color": { "r": 0.447, "g": 0.314, "b": 0.231 } }],
+ "stroke": { "weight": 2, "cap": "ROUND", "join": "ROUND" }
+ }
+ }
+ }
+}
+```
+
+## Transforms, masks, and native state
+
+- `figma.name` sets the display name; `data-key` remains identity.
+- `locked` and `aspectRatioLocked` set interaction state.
+- `relativeTransform` is a complete native 2×3 unit-axis transform; width and
+ height carry scale. Do not combine it with `rotate-*`. On create roots, TemPad
+ preserves rotation and skew but replaces translation with automatic placement.
+- `stroke` carries weights, alignment, caps, joins, miter, and `dashPattern`.
+- `corners` carries radii and smoothing.
+- `mask` is `"ALPHA"`, `"VECTOR"`, `"LUMINANCE"`, or `null`.
+
+Place a mask before masked siblings inside one dedicated frame and describe all
+direct siblings on update. A non-null mask needs a following sibling. Omission
+preserves mask state; `null` disables it.
+
+After changing a mask, layout grid, or frame guide, call `get_structure` with
+`options.native: true` on the smallest relevant root. Verify `native.mask` and
+sibling order, or returned `native.layoutGrids` and `native.guides`; desired
+bindings alone are insufficient.
+
+Use `{ "ref": "…" }` for catalog resources nested in native state and
+`sourceCanvasKey` or `{ "canvasKey": "…" }` for same-result forward node
+references. Never insert raw Plugin API calls.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/local-styles.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/local-styles.md
new file mode 100644
index 00000000..1e36241b
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/local-styles.md
@@ -0,0 +1,57 @@
+# Author local styles
+
+Use this reference only when the user or resolved system plan requires a local
+style. Do not extract styles from an ordinary screen. New local resources need
+no catalog; send `catalogId` only when a nested `{ "ref": "…" }` deliberately
+reuses an existing resource.
+
+Copy this recipe and change its design facts. Style authoring keys persist
+file-wide and are neither names nor IDs. Namespace keys by product and role. In
+shared drafts, also prefix generic visible names that could collide; retain
+established project naming when already clear.
+
+```json
+{
+ "mode": "create",
+ "markup": "
Account
",
+ "styles": {
+ "product/style/surface": {
+ "type": "PAINT",
+ "name": "Product/Color/Surface",
+ "paints": [{ "type": "SOLID", "color": { "r": 1, "g": 1, "b": 1 } }]
+ },
+ "product/style/heading": {
+ "type": "TEXT",
+ "name": "Product/Typography/Heading",
+ "fontName": { "family": "Inter", "style": "Semi Bold" },
+ "fontSize": 20,
+ "lineHeight": { "unit": "PIXELS", "value": 28 }
+ }
+ },
+ "native": {
+ "card": {
+ "styles": {
+ "fill": { "styleKey": "product/style/surface" }
+ }
+ },
+ "card/title": {
+ "styles": {
+ "text": { "styleKey": "product/style/heading" }
+ }
+ }
+ }
+}
+```
+
+Types are `PAINT`, `TEXT`, `EFFECT`, and `GRID`, using `paints`, text fields,
+`effects`, or `layoutGrids` respectively. For exact Paint, Effect, and Grid
+shapes beyond this recipe, read [paints-effects.md](paints-effects.md).
+
+Omission preserves managed state. Top-level `null` removes a managed style only
+when absence is required and all live consumers are cleared or removed in the
+same result. Never mutate remote resources, invent library keys, or create a
+broad style library for one screen.
+
+`unbound-created-style` means a same-call style lacks a `styleKey` consumer.
+Bind it to a representative property performing its named role or remove it. A
+swatch or unrelated binding is not coverage.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/paints-effects.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/paints-effects.md
new file mode 100644
index 00000000..f5b02c24
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/paints-effects.md
@@ -0,0 +1,110 @@
+# Paints, effects, grids, guides, and media
+
+Use this reference whenever the result uses a nontrivial shadow, blur, glass,
+texture, noise, image paint, layered gradient material, or layout aid, including
+effects expressed as Canvas HTML classes. Resolve an image or illustration's
+role, subject, medium, and source through [visual-assets.md](visual-assets.md)
+first. Prefer a matching catalog style; otherwise use direct native arrays.
+
+## Catalog links
+
+```html
+
+```
+
+A style owns its channel. Do not combine a non-null fill or stroke style with a
+whole-node variable on the same paint. Styled strokes still need literal,
+typed, or variable-bound geometry. `null` unlinks; omission preserves.
+
+## Resolve shadow references
+
+Named scales such as `shadow-md` are theme references, not portable geometry:
+
+- Reuse: bind the matching catalog Effect style.
+- Author: create and bind a local Effect style only when the system plan requires
+ it.
+- Direct: use an exact `shadow-[...]` class or typed `figma.effects` value.
+
+Never assume Tailwind defaults or create a token only to resolve a named class.
+`shadow-none`, `inset-shadow-none`, and `text-shadow-none` explicitly clear.
+
+Treat an outer shadow's rendered halo as part of the composition. Inspect the
+final PNG beyond the root edges; visible granular or noisy fringe, or a halo
+that dominates the captured bounds, is a defect even when the frame itself is
+intact. Preserve intended depth by tightening blur, spread, or opacity or using
+smaller layered shadows, then recheck. Do not flatten established material
+treatment merely to hide the defect.
+
+## Native paint and effect stacks
+
+`figma.fills` and `figma.strokes` support ordered solid, linear/radial/angular/
+diamond gradient, image/video, Pattern, and fill-shader paints.
+`figma.effects` supports ordered shadows, normal/progressive blur, noise,
+texture, glass, and effect shaders.
+
+A `SOLID` paint uses RGB `color` and optional paint-level `opacity`; only
+gradient stops use RGBA colors. Keep stroke geometry, including `dashPattern`,
+in `figma.stroke`, not the stroke paint.
+
+Use the exact gradient enum and normalized RGBA stop shape; do not translate
+from CSS or Plugin API names:
+
+```json
+{
+ "figma": {
+ "fills": [
+ {
+ "type": "GRADIENT_LINEAR",
+ "gradientTransform": [
+ [1, 0, 0],
+ [0, 1, 0]
+ ],
+ "gradientStops": [
+ { "position": 0, "color": { "r": 1, "g": 0.43, "b": 0.29, "a": 1 } },
+ { "position": 1, "color": { "r": 0.16, "g": 0.09, "b": 0.24, "a": 1 } }
+ ]
+ }
+ ]
+ }
+}
+```
+
+Other gradient enums are `GRADIENT_RADIAL`, `GRADIENT_ANGULAR`, and
+`GRADIENT_DIAMOND`.
+
+Omission preserves a stack; `[]` clears it. Direct stacks cannot share their
+channel with a literal class, whole-node variable, or style. Use variable refs
+such as `{ "ref": "v1" }` and shader refs such as `{ "ref": "h1" }`; use only
+returned shader property IDs and declared value shapes.
+
+For images, provide exactly one same-file `imageHash`, public HTTP(S) `imageUrl`,
+or call-scoped `assetKey` for a full-SHA-256 Hub IMAGE asset. PNG, JPEG, and GIF
+are limited to 4096×4096. For video, provide exactly one same-file `videoHash` or
+public `videoUrl` for MP4, MOV, or WebM up to 100 MB. URLs must need no
+credentials. Reuse `figmaImageHash`, `figmaImageHashes`, or `figmaVideoHashes`
+from `get_code` only in the same file; they identify native media, not preview
+bytes.
+
+A Pattern uses exactly one existing `sourceNodeId` or same-result
+`sourceCanvasKey`.
+
+## Layout aids
+
+Prefer a matching Grid style. Otherwise `figma.layoutGrids` declares ordered
+row, column, or square grids on frames, components, sets, and instances. Use
+`"AUTO"` for automatic row or column count. Do not bind `sectionSize` with
+`STRETCH` or `offset` with `CENTER`.
+
+`figma.guides` is the complete ordered X/Y guide list: omission preserves and
+`[]` clears. Page guides live under `page.guides`.
+
+For wrapping linear Auto Layout, `figma.autoLayout` may set signed
+`itemSpacing`, positive or synchronized-null `counterAxisSpacing`, and
+`itemReverseZIndex`. Never declare one physical gap in both classes and native
+state.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/rich-text.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/rich-text.md
new file mode 100644
index 00000000..c83a74da
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/rich-text.md
@@ -0,0 +1,52 @@
+# Rich text and hyperlinks
+
+Use this reference for an already chosen typeface or Figma-only text behavior;
+resolve material typeface choices through [visual-assets.md](visual-assets.md).
+Use `span` for editable text. Put whole-node typography in classes, a catalog
+Text style, or semantic variable bindings when possible.
+
+`native[key].figma.text` supports:
+
+- exact whole-node `fontName`, `autoRename`, vertical alignment, and leading
+ trim;
+- paragraph indent/spacing, list spacing, hanging punctuation/list;
+- whole-node hyperlink;
+- ordered rich-text `ranges`.
+
+Do not combine `autoRename: true` with fixed `figma.name`.
+
+When no Text style or typography variable expresses the chosen family and
+style, use the exact available Figma font:
+
+```json
+{
+ "fontName": { "family": "IBM Plex Sans", "style": "Medium" }
+}
+```
+
+Do not combine it with `font-*` classes, linked Text styles, or font family/style
+variables. Never guess family or style availability.
+
+Range `start` and `end` are UTF-16 offsets into final characters. Ranges must be
+ordered, non-overlapping, and set at least one property; split overlapping
+intentions into disjoint intervals. A range may set font name/size, case,
+letter spacing, line height, complete underline state, native fills, Text/Paint
+style, list options, indentation, paragraph spacing, hyperlink, and supported
+text-range variables.
+
+Use `{ "ref": "s1" }` for a catalog range style and `{ "ref": "v1" }` for a
+range variable. `null` unlinks supported styles or hyperlinks; omission
+preserves.
+
+Hyperlinks support URLs and node targets. For a same-result target:
+
+```json
+{
+ "type": "NODE",
+ "value": { "canvasKey": "settings/help" }
+}
+```
+
+The target may appear later in markup; never remove a live hyperlink target. If
+a catalog component exposes text through a prop, set that prop instead of
+editing internal layers.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/style-grounding.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/style-grounding.md
new file mode 100644
index 00000000..c4168453
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/style-grounding.md
@@ -0,0 +1,105 @@
+# Ground material design decisions
+
+Use this evidence process for the initial direction of net-new work or a
+significant visual redesign, and for later material decisions not settled by the
+user or permitted project or Figma evidence. Skip exact reproduction,
+mechanical edits, and choices already grounded by inspected evidence. This is
+not a UX checklist or style guide; the task determines relevant concerns and
+conclusions.
+
+## Isolate the uncertainty
+
+Before research:
+
+1. Inventory available requirements and evidence.
+2. Name only unresolved decisions that could materially change the result.
+3. Separate missing evidence from low-consequence choices that can be stated as
+ assumptions.
+
+Research the decision, not its broad category. Do not promote remembered
+conventions, tool affordances, or skill examples into requirements. Broad
+qualitative words assign a visual decision to the designer. Apply suitable
+expertise to form an explicit, task-specific interpretation; seek more evidence
+only when materially different interpretations remain plausible after that
+reasoning.
+
+For net-new work or a significant visual redesign without a supplied reference
+or established system, inspect a small representative set of real references
+before the first `apply_canvas`. Together they must ground the initial visual
+language, core interaction pattern, and relevant detail or material treatment.
+Use external research when permitted; an inspected current-file composition,
+project evidence, or user-supplied reference can cover the dimensions it
+actually demonstrates. A named style, tradition, period, medium, or body of
+work always requires inspecting representative artifacts from it; familiarity
+or model memory does not satisfy this gate. If no usable evidence is available,
+ask for a reference or disclose the blocked grounding step instead of silently
+inventing a direction.
+
+## Select expertise before availability
+
+Name the professional capability that owns the decision before inspecting
+installed skills or tools. When the host permits discovery or acquisition,
+actively seek one fit candidate and inspect its provenance, complete
+instructions, scope, and fit for the task's platform, medium, domain, and
+deliverable. Installed status or a broad label does not establish fit, and no
+design skill is universal. Use complementary expertise only where needed;
+TemPad still owns Figma execution.
+
+For remote skills, retrieve the complete current source through EOF. A truncated
+response, excerpt, or search result is insufficient; retry through another
+supported route or report that inspection failed.
+
+If suitable expertise is unavailable, use targeted primary guidance or
+inspected visual evidence. Ask the user only when the remaining choice is
+material; otherwise state the assumption. Never copy contextual rules from a
+candidate into this reference or turn missing capability into generic defaults.
+
+## Obtain sufficient evidence
+
+Choose the nearest credible source whose authority covers the decision. Project
+and current-file evidence has the closest context; primary guidance can establish
+requirements; inspected products and artifacts can establish precedent.
+
+A source counts only when all are true:
+
+- the source page or a recoverable artifact is open;
+- the relevant pixels, screen, or specification was inspected;
+- its authority covers the attributed decision;
+- the trace records the finding and resulting decision.
+
+Search pages, image-result tiles, snippets, metadata, and remembered summaries
+only locate candidates. Open the source or a permitted local copy. A content
+image cannot establish surrounding composition or controls; a visual precedent
+cannot establish behavior it does not show or specify.
+
+For named lineage, attribution, or system history, prefer primary, official,
+creator, or institutional evidence when reasonably available. Secondary sources
+support only the visible facts in the inspected artifact. For interaction,
+inspect a real product screen, demo, or specification covering control behavior,
+information choreography, and material state. Screen names, requested fields,
+and task sequence establish scope, not precedent.
+
+Use no source quota. Stop when every unresolved initial visual, interaction, and
+detail decision has applicable inspected evidence. If a material gap remains,
+continue bounded research, ask for the choice, or report the block; do not call
+`apply_canvas` from memory.
+
+## Retain a compact decision trace
+
+Before the first `apply_canvas`, keep only task-relevant lines:
+
+```txt
+Outcome: requested result and scope
+Known: applicable user, project, and file evidence
+Open decision -> source -> applicable finding -> decision
+Assumptions: only unresolved low-consequence choices
+Verification: result-specific evidence to inspect in Figma
+```
+
+This is a working note, not a deliverable or mood board.
+
+## Apply and verify
+
+Translate the decisions into one coherent composition and judge the rendering
+against this task-specific trace. Correct concrete mismatches; research or tune
+further only for remaining material uncertainty or an observed defect.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/variables.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/variables.md
new file mode 100644
index 00000000..f259ba86
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/variables.md
@@ -0,0 +1,127 @@
+# Author local variables
+
+Use this reference only when the user or resolved system plan requires local
+variables. Do not extract tokens from an ordinary screen. New resources need no
+catalog; send `catalogId` only for deliberate nested `{ "ref": "…" }` reuse.
+
+## Contents
+
+- [Author variables](#author-variables)
+- [Bind and verify](#bind-and-verify)
+- [Update and remove](#update-and-remove)
+
+## Author variables
+
+Copy this recipe and change its design facts. Collection and variable authoring
+keys persist file-wide and are neither names nor IDs. Choose one
+collision-resistant prefix for the independent system; recover existing exact
+keys when intentionally updating it. Mode keys are collection-scoped.
+
+```json
+{
+ "mode": "create",
+ "markup": "
Account
",
+ "variableCollections": {
+ "product/theme": {
+ "name": "Theme",
+ "modes": {
+ "light": { "name": "Light" },
+ "dark": { "name": "Dark" }
+ },
+ "variables": {
+ "product/color/surface": {
+ "name": "Color/Surface",
+ "type": "COLOR",
+ "scopes": ["ALL_FILLS"],
+ "values": {
+ "light": { "r": 1, "g": 1, "b": 1 },
+ "dark": { "r": 0.08, "g": 0.09, "b": 0.11 }
+ }
+ },
+ "product/space/md": {
+ "name": "Spacing/Medium",
+ "type": "FLOAT",
+ "scopes": ["GAP"],
+ "values": {
+ "light": 16,
+ "dark": 16
+ }
+ }
+ }
+ }
+ },
+ "native": {
+ "card": {
+ "variables": {
+ "fill": { "variableKey": "product/color/surface" },
+ "gap": { "variableKey": "product/space/md" }
+ },
+ "variableModes": {
+ "product/theme": "dark"
+ }
+ }
+ }
+}
+```
+
+A new collection needs `name` and at least one named mode. Each variable needs
+`name`, `type`, and a value for every mode. Types are `BOOLEAN`, `COLOR`,
+`FLOAT`, and `STRING`. Values may alias another variable:
+
+```json
+{ "variable": { "variableKey": "…" } }
+```
+
+Valid scopes:
+
+- general: `ALL_SCOPES`, `TEXT_CONTENT`, `CORNER_RADIUS`, `WIDTH_HEIGHT`, `GAP`,
+ `OPACITY`;
+- color: `ALL_FILLS`, `FRAME_FILL`, `SHAPE_FILL`, `TEXT_FILL`, `STROKE_COLOR`,
+ `EFFECT_COLOR`;
+- numeric effect/stroke: `STROKE_FLOAT`, `EFFECT_FLOAT`;
+- typography: `FONT_FAMILY`, `FONT_STYLE`, `FONT_WEIGHT`, `FONT_SIZE`,
+ `LINE_HEIGHT`, `LETTER_SPACING`, `PARAGRAPH_SPACING`, `PARAGRAPH_INDENT`.
+
+Use `STROKE_COLOR`, not `ALL_STROKES`. Combine neither `ALL_SCOPES` with other
+scopes nor `ALL_FILLS` with `FRAME_FILL`, `SHAPE_FILL`, or `TEXT_FILL`;
+`ALL_FILLS` may coexist with a non-fill scope such as `STROKE_COLOR`.
+
+## Bind and verify
+
+Bind through `native[key].variables` using the exact supported field, such as
+`fill`, `stroke`, `gap`, `paddingTop`, `width`, `visible`, `fontSize`, or
+`characters`. Retain a matching literal class when Figma needs an initial paint
+or numeric fallback.
+
+Bind each variable to representative fields performing its semantic role.
+Prefer `GAP` for shared gaps/padding, `WIDTH_HEIGHT` for semantic control/icon
+sizes, and `CORNER_RADIUS` for shared radii. Do not tokenize viewport dimensions,
+one-off crops, content-derived geometry, or optical corrections merely because
+numbers repeat.
+
+A representative binding proves usability, not complete coverage. Bind every
+consumer intended to evolve with the role; keep equal peer literals only when
+incidental or independently owned.
+
+`apply_canvas` reports `unbound-created-variable` when a new variable lacks a
+same-result consumer. Bind it to a real consumer or remove it. A staged warning
+may be temporary, but final delivery must show a native binding; equal literals
+do not count.
+
+`variable-fallback-mismatch` means a bound literal matches none of the
+same-call variable's direct or aliased mode values. Align the fallback with a
+real mode or bind the variable that owns the value, or the binding will silently
+change the declared markup.
+
+## Update and remove
+
+After changing a variable value, update and verify every intended consumer that
+cannot carry a native binding, such as `figma.svg.color`; omission leaves its
+old literal in place.
+
+Omission preserves managed state. Top-level `null` removes a managed variable,
+mode, or collection only when absence is required and all consumers are cleared
+or removed in the same result. Never mutate remote resources, invent parent
+collections or library keys, or build a broad token system for one screen.
+Extended collections must inherit a real local or catalog collection and obey
+plan limits.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/visual-assets.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/visual-assets.md
new file mode 100644
index 00000000..349d44ab
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/visual-assets.md
@@ -0,0 +1,215 @@
+# Deliver visual assets in Figma
+
+Use this reference when the result needs icons, an exact typeface, images,
+illustrations, diagrams, or vector art. It governs role, source integrity,
+editability, and Canvas-compatible delivery—not product need or final visual
+choice. After selection, use the routed font, paint, media, or SVG mechanics.
+
+Start from the composition, not an assumed asset slot or available tools.
+Typography, layout, color, negative space, or existing media may already satisfy
+the brief. Add a visual only for an evidenced job: depicting content, signaling
+action, explaining relationships, establishing identity, or expressing an
+intentional visual language. These are cues, not a checklist.
+
+Depiction is a role, not a medium. Choose photo/raster, sourced vector,
+agent-authored vector illustration or diagram, or another medium only when the
+brief, visual evidence, or a low-consequence assumption supports it. Fulfill an
+established raster medium with a supplied, sourced, generated, or current-file
+image—not primitives or invented SVG. Author vector work only when evidence
+establishes vector illustration, diagram, pattern, or decorative geometry.
+Convenience never changes the medium.
+
+Treat a content-bearing visualization—such as a chart, map, waveform, notation,
+document or media preview, or domain instrument—as a first-class
+representation. Preserve its recognizable structure, information density, and
+task role. It is sufficient only when it retains the context needed for the
+decisions it supports; labels or decorative marks cannot promote a simplified
+proxy into that representation. Element limits or easy primitives do not
+justify reduction: split the work or choose an evidence-supported native,
+vector, or raster base, keeping changing overlays editable. When only topology
+or sequence is intended, name and design it as a diagram.
+
+When recognition depends on the subject's real appearance—such as a person,
+product, food, place, room, photograph, cover, or shared-media preview—treat a
+real sourced or generated image as the default candidate. Use vector
+illustration only when the brief or inspected visual evidence establishes an
+illustrated language independently of implementation convenience. Do not call
+the medium low-consequence when changing it would alter credibility, identity,
+appetite, atmosphere, or content distinctions.
+
+Preserve editability semantics: build changing diagram labels, shapes, and
+relationships as native structure; use one opaque SVG only when exact vector
+art is the asset. An SVG wrapper with Vector descendants does not make a diagram
+model editable. Preserve exact encoded geometry as real decodable content,
+never an imitation.
+
+For material assets retain enough evidence for identity/content fidelity,
+provenance and applicable rights, source quality, and Canvas-compatible form.
+Never silently change subject, style, or medium. Report required sources that
+cannot be delivered faithfully. Crops, masks, overlays, and retouching must
+preserve the depicted subject; do not hide distinctive branding or features to
+make one subject represent another.
+
+## Contents
+
+- [Icons](#icons)
+- [Typefaces](#typefaces)
+- [Images and illustrations](#images-and-illustrations)
+
+## Icons
+
+Prefer permitted current-file, catalog, project, or user sources; otherwise use
+a trustworthy brief-compatible source and record material license constraints.
+When inspected evidence establishes an icon family or geometry, use that
+permitted source or a compatible source. A general library is a fallback only
+when its stroke or fill, optical weight, corners, negative space, and platform
+semantics remain coherent. Do not diversify sources by quota.
+Import exact SVG geometry. Never redraw a known icon from memory or replace an
+icon role with Unicode, emoji, TEXT, or assembled primitives. A character,
+shape, or cluster that communicates an affordance, object, or semantic category
+is an icon role even when embedded beside a worded label; removing the words
+does not erase its directional or action meaning. Before markup, scan literal
+text for pictographic Unicode, emoji, and symbols and route each qualifying mark
+to a permitted current-file, catalog, project, user, or trustworthy vector
+source. Omit an optional icon when no faithful source exists. Simple geometry
+remains valid only when it is itself the intended status/data mark, divider,
+decoration, or brand shape.
+
+Verify fetched SVG content rather than trusting its URL or filename. This Direct
+example demonstrates syntax, not design defaults:
+
+```json
+{
+ "mode": "create",
+ "markup": "",
+ "assets": {
+ "search": {
+ "type": "SVG",
+ "svg": ""
+ }
+ },
+ "native": {
+ "search-icon": {
+ "figma": { "svg": { "assetKey": "search", "color": "#334155" } }
+ }
+ }
+}
+```
+
+The childless `div` supplies wrapper geometry. `color` resolves `currentColor`;
+omit it for explicit-color SVGs. Figma may import a Frame with Vector children;
+treat that subtree as one opaque asset and never flatten or reconcile it.
+
+For larger exact SVG, declare this Hub asset using a full lowercase SHA-256:
+
+```json
+{ "type": "SVG", "assetHash": "" }
+```
+
+If no faithful source exists, omit an optional icon or report a required gap
+instead of inventing one.
+
+## Typefaces
+
+Derive typeface from the brief and evidence. Prefer applicable catalog Text
+styles, typography variables, project fonts, or supplied references. Confirm
+each exact Figma family/style; never guess.
+
+Use `figma.text.fontName` for exact whole-node fonts and ranges only for
+intentional mixed typography. Portable `font-sans|serif|mono` utilities resolve
+to an editor-available family in that category, preferring Inter, Noto Serif,
+or Noto Sans Mono. They do not satisfy another named family. For a required
+family, bind its style, variable, or exact font, or leave the brief at the
+supported evidence level.
+
+## Images and illustrations
+
+Treat existing assets, rights-established remote sources, generation, and
+purpose-built vectors as acquisition routes only after role, subject, and medium
+are settled. Choose the nearest route satisfying content, fidelity, rights,
+quality, and import requirements; tools have no global priority. Before
+importing a remote asset, establish its applicable usage rights and a
+recoverable source; a search result, accessible URL, CDN host, or lack of a
+watermark does not establish permission. Confirm Canvas delivery before layout
+depends on the asset.
+
+Do not fall back from established raster media to primitives or SVG. Source or
+generate it, use an explicit neutral placeholder only when outcome is unchanged,
+or disclose the gap. Preserve exact vector art when vector is the real medium.
+For several distinct assets, verify the route preserves content distinctions.
+
+Keep only enough trace to recover material choices, the remote source and its
+applicable terms, or content distinctions. Combine role, evidence, medium,
+source, rights, and import treatment in one short rationale when needed; do not
+create a per-asset ceremony. Record exact creator, license, or attribution only
+when the applicable terms, policy, or handoff requires it; assets sharing one
+route and terms may share a trace.
+
+When medium is unspecified, use nearest visual evidence or ask if the choice is
+material; otherwise state a low-consequence assumption.
+
+Use generation when the decided role requires a bespoke subject, identity,
+composition, or treatment that a supplied or rights-established source cannot
+satisfy. Only a named content, fidelity, rights, or import requirement can show
+that sourcing is inadequate; a missing supplied asset, mood/style adjective, or
+desire for visual consistency cannot. For an ordinary real-world subject likely
+available as reusable stock or CC0 media, inspect a bounded reusable-asset
+search—not only visual-reference results—and name the unmet role requirement
+before generating. A visual-reference search is not a reusable-asset search.
+Do not load or call a generator until the trace maps every planned generated
+asset—not merely the batch—to its role, subject, medium, and unmet source
+requirement. Skip the source search only when the brief requires an unlikely
+combination or sourcing cannot preserve the role. If a source satisfies the
+role, use it; do not generate an alternative by default.
+Compose generation and Hub import in one programmatic execution so image bytes
+never enter prose or expire between calls: pass the generator's `data:` URL
+directly to TemPad's `upload_asset`, read its returned `assetHash`, then declare
+that hash as an IMAGE asset in `apply_canvas`. Do not regenerate an unchanged
+prompt only to recover an importable URL. If generation or `upload_asset` is
+unavailable, choose a rights-established public image source only when it
+preserves the intended medium; otherwise disclose the required gap. Never
+generate first and silently switch medium because import failed.
+
+Use `imageUrl` for a rights-established public IMAGE paint or same-file
+`imageHash` for an existing image. For generated or other local Hub content,
+declare the returned full lowercase SHA-256, then use its alias in a basic fill:
+
+```json
+{
+ "assets": { "photo": { "type": "IMAGE", "assetHash": "" } },
+ "native": {
+ "photo-node": {
+ "figma": { "fills": [{ "type": "IMAGE", "assetKey": "photo", "scaleMode": "FILL" }] }
+ }
+ }
+}
+```
+
+Inline bytes and local paths are unsupported; remote URLs must resolve directly
+to accessible images, not pages or thumbnails.
+
+When the medium must remain a real image, verify with `get_structure` and
+`options.native: true`; `native.imageFills` must contain the expected non-null
+Figma hash. Input URLs, successful mutation, and visually similar screenshots
+are not native read-back.
+
+The main agent owns placement, crop, and final verification. Before markup, map
+each content-bearing image consumer to the subject it claims to depict. Reuse
+one asset and crop only when consumers represent that same subject; distinct
+records require distinct assets or crops that visibly isolate the correct
+subject. A composite scene may serve the composition it depicts, but cannot
+stand in for several named records. Stop and source or generate missing media
+instead of serializing a false mapping.
+
+When a gallery, carousel, or thumbnail set promises several views of one
+subject, every retained view must add distinct, truthful visual information.
+Repeating one unchanged source and crop does not satisfy that role; unrelated
+subjects break identity. Use distinct sourced views, evidence-supported crops,
+or generation/editing only for a named same-subject coverage need that sourcing
+cannot satisfy. Otherwise reduce the views or disclose the gap.
+
+For repeated depictions of the same subject, keep asset identity and crop stable
+unless evidence requires variation. If required media remains unavailable,
+report it; omit optional media or use a neutral slot only when the requested
+outcome is unchanged. A neutral slot is an explicit fallback, not representative
+content or proof of reusable variation.
diff --git a/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/visual-composition.md b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/visual-composition.md
new file mode 100644
index 00000000..480bfdc7
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/visual-composition.md
@@ -0,0 +1,97 @@
+# Resolve a visual composition
+
+Use this portable quality floor for net-new screens and flows without an
+established composition; task evidence and suitable expertise determine style.
+
+## Ground the initial direction
+
+Do not derive a net-new or substantially redesigned composition from prompt
+adjectives, a familiar style label, or model recall alone. Follow
+[style-grounding.md](style-grounding.md) and inspect a small representative set
+of real references before markup. Use that evidence to settle the initial
+visual language, core interaction pattern, and relevant detail or material
+treatment. Translate relationships and principles; do not assemble recognizable
+motifs from the sources.
+
+## Form a testable thesis
+
+Before markup, resolve one composition-level idea and express it through:
+
+- one primary hierarchy and visual anchor;
+- the document model: fixed workspace, scrolling page, or explicit viewport
+ states, with content extent and persistent regions derived from behavior;
+- typography roles, density, and spacing rhythm;
+- a coherent surface, edge, shape, and depth grammar;
+- an interaction vocabulary that decides where sourced icons improve
+ recognition, scanning, or compactness and where text remains clearer;
+- the asset treatment required by the content;
+- the relationship between persistent shell and changing screen content.
+
+The thesis must predict visible choices. A style label, palette, effect list, or
+component collection is insufficient. If it would still fit another product
+after renaming the content, it is not specific enough. Revise the anchor or
+composition before markup.
+
+## Compose before containing
+
+Start with information hierarchy, alignment, scale, whitespace, and media. Add
+a container only when its boundary communicates interaction, state, grouping,
+or material behavior that spacing alone cannot. If removing a card, border, or
+colored strip leaves the meaning unchanged, remove that treatment.
+
+Avoid making every region independently rounded, bordered, shadowed, or filled.
+Build hierarchy with dominant and supporting regions, open space, type scale,
+real content imagery where it belongs, and few consistent material behaviors.
+Do not use a familiar layout grammar as a fallback; every major region and
+material treatment must follow the task-specific thesis or inspected evidence.
+
+Do not use gradients, lines, blobs, or empty geometric panels as stand-ins for
+photos, products, food, people, places, album art, shared media, or other
+content-bearing subjects. Route those roles through `visual-assets.md`.
+
+Treat a viewport as an inspection context, not a document boundary. Before
+sizing a root, decide from actual content: author the full vertical extent when
+the document continues below the fold; for a fixed app shell, identify and size
+its intended scroll container. A fixed viewport with incomplete content and no
+explicit scroll region is invalid. Do not shrink, omit, or crowd content to fit
+a familiar screenshot ratio.
+
+Apply the main skill's blocking icon audit while forming the interaction
+vocabulary. Route every selected icon through `visual-assets.md`; use the
+retained trace to test text-only exceptions and consistency.
+
+## Test the representative screen
+
+Open the first materially complete screen before expanding the flow. Check:
+
+- the primary action and content are legible without reading every label;
+- page extent, persistent regions, and scroll boundaries match the product
+ behavior rather than the screenshot frame;
+- icon and text choices form a coherent interaction vocabulary and support
+ scanning without decorative or primitive substitutes;
+- the chosen visual anchor belongs to this product rather than a generic
+ dashboard template;
+- container count and decoration follow semantic grouping rather than filling
+ empty space;
+- asset roles use the decided medium rather than convenient primitives;
+- depth and material effects support hierarchy without a noisy outer halo;
+- the reference findings survive as macro composition, media hierarchy,
+ spacing rhythm, material and shape grammar, and interaction or detail
+ treatment—not only as palette, type, borders, or isolated motifs;
+- recurring responsibilities are identifiable before a second consumer is
+ serialized.
+
+If only surface motifs survived, revise the thesis before propagation. Otherwise
+correct the thesis or composition now and stop when these relationships are
+clear and the screen has no observed defect; do not keep decorating a
+structurally weak result.
+
+## Propagate the visual system
+
+Treat the representative screen as a contract for the requested flow, not a
+single showcase. Inspect every materially distinct dependent screen and preserve
+the relevant hierarchy, media logic, rhythm, material and shape grammar, and
+interaction or detail treatment. Different screens need not repeat the same hero
+or asset count, but a companion that retains only palette, type, borders, or
+isolated motifs while collapsing into generic filled rectangles has drifted and
+must be revised.
diff --git a/agent-plugins/tempad-dev/skills/figma-design-to-code/SKILL.md b/agent-plugins/tempad-dev/skills/figma-design-to-code/SKILL.md
index a65e8e30..a5bb5f20 100644
--- a/agent-plugins/tempad-dev/skills/figma-design-to-code/SKILL.md
+++ b/agent-plugins/tempad-dev/skills/figma-design-to-code/SKILL.md
@@ -1,392 +1,177 @@
---
name: figma-design-to-code
description: >-
- Implement or update project-consistent UI code from a Figma selection or
- nodeId using TemPad Dev MCP. Use when the user wants visible Figma UI
- recreated, ported, or integrated into the target project's framework,
- styling system, tokens, and existing components when available. Do not use
- for design critique, product invention, generic code review, or for guessing
- hidden states, responsiveness, or behavior not shown in design or project
- evidence.
-metadata:
- version: '4.3'
+ Implement or update project-consistent UI code from a visible Figma selection
+ or nodeId using TemPad Dev MCP. Use when the user wants Figma UI recreated,
+ ported, or integrated into the target project's framework, styling system,
+ tokens, assets, and existing components. Do not use for design critique,
+ product invention, generic code review, or guessing states, responsiveness,
+ or behavior not evidenced by Figma, the project, or the user.
---
-# TemPad Dev: Figma Design to Code
+# Implement Figma design in code
-Use this skill to turn TemPad Dev design evidence into project-consistent UI
-code.
+Turn visible Figma evidence into the smallest project-native implementation
+that preserves the intended result. Keep that result focal: project files,
+TemPad output, rules, and tool calls are evidence for the implementation, not
+deliverables to reproduce mechanically.
-TemPad Dev MCP must be available and able to provide trustworthy design
-evidence for the current selection or provided `nodeId`. If not, stop and tell
-the user to enable or reconnect TemPad Dev MCP.
+Require TemPad Dev MCP to provide trustworthy design evidence for the current
+selection or an exact `nodeId` inside the user's established scope. Never
+reconstruct the design from memory, screenshots alone, or `get_structure`
+metadata.
-Within this skill, TemPad Dev MCP is the authoritative source of design
-evidence. Treat:
+## Evidence and authority
-- project files and project instructions as implementation truth when available
-- TemPad Dev output as design truth
-- the user as the source of truth for missing product or implementation
- decisions
+Use each source only for what it can establish:
-Do not infer project conventions before reading local evidence.
+- **The user** sets scope, requirements, prohibitions, and missing product or
+ implementation decisions.
+- **The project** sets framework, file placement, component boundaries,
+ styling, tokens, assets, dependencies, and verification conventions.
+- **TemPad Dev** sets visible structure and rendered design facts.
-For concerns orthogonal to Figma-to-code translation, follow project
-instruction files such as `AGENTS.md` and other project instructions instead of
-defining new policy in this skill. If such a concern is unspecified there and
-would materially change the implementation, ask the user or stop.
+Follow project instruction files for concerns outside Figma-to-code
+translation. Do not add policy for routing, analytics, i18n, CMS, or other
+orthogonal systems.
-## Evidence model
+TemPad can establish visible hierarchy, layout, spacing, typography, color,
+effects, token references, exported assets, and codegen unit context. It cannot
+establish unevidenced states, responsive behavior, business logic, navigation,
+validation, analytics, or project conventions. Treat `get_structure` as
+hierarchy and geometry evidence only, never as missing style truth.
-Use three evidence channels for different jobs:
+## Workflow
-- **Project evidence**: `AGENTS.md` or equivalent project instruction files,
- design-system docs, token/theme docs, component docs, existing primitives,
- nearby implementations, framework/styling config, asset rules, and project
- scripts
-- **Design evidence**: `tempad-dev:get_code` first for markup, styles, tokens,
- assets, warnings, and codegen facts; `tempad-dev:get_structure` only for
- hierarchy, geometry, overlap, and retry targeting
-- **User input**: missing behavioral intent, responsive intent, target file,
- acceptable tradeoffs, asset or dependency decisions, or other product or
- implementation decisions that cannot be recovered from project or design
- evidence
+### 1. Establish the implementation envelope
-## What TemPad Dev can and cannot prove
+Read only local evidence that can change this implementation, in this order:
-TemPad Dev can prove:
+1. applicable `AGENTS.md` or equivalent instructions;
+2. relevant design-system, token, component, and asset guidance;
+3. the nearest comparable implementation and reusable primitives;
+4. framework, styling, and check configuration needed for this task.
-- the visible structure of the current selection or a provided `nodeId`
-- explicit layout, spacing, typography, color, radius, borders, shadows,
- gradients, masks, filters, compositing, and other rendered visual details
-- token references and values when present
-- exported assets and whether an SVG may safely adopt one contextual color
- channel via `themeable`
-- codegen facts such as actual output language, `cssUnit`, `scale`, and
- `rootFontSize`
+Determine the target file or component boundary, framework, styling method,
+token and asset paths, reuse candidates, dependency constraints, and narrowest
+relevant checks. Inspect Tailwind version and theme scales only when the
+project actually uses Tailwind-compatible tooling.
-TemPad Dev cannot prove:
+Do not inventory the repository broadly after the needed envelope is clear. If
+a missing project decision would materially change the result, ask before
+implementation.
-- hidden, hover, active, loading, error, empty, disabled, or responsive states
- unless separately evidenced
-- non-visual product requirements such as behavior, business logic, validation,
- navigation, or analytics
-- project conventions, file placement, component boundaries, primitive-reuse
- policy, token-mapping policy, or asset workflow beyond what the project
- already establishes
-- missing style truth from `get_structure`; it is only a structure aid
+### 2. Read the design at the requested scope
-## Default operating rules
+Call TemPad Dev's `get_code` before implementing:
-Do not output `data-hint-*` attributes.
+- use `resolveTokens: false` by default;
+- omit `nodeId` for the current single selection; pass one only when the user
+ supplied it or TemPad returned the exact ID for a targeted read inside the
+ user's established scope;
+- set `preferredLang` from the established project target;
+- keep TemPad's default vector behavior unless the user explicitly requests
+ asset-preserving vector fidelity and the active MCP version supports it.
-Never invent visual details or behavior not evidenced, including color,
-typography, spacing, radius, borders, shadows, gradients, opacity, overlays,
-blur, hidden states, responsive behavior, interactions, or asset semantics.
+Use `resolveTokens: true` only when the user explicitly does not want design
+token references. Treat returned `lang` as authoritative because plugin
+configuration may override `preferredLang`.
-Treat advanced or uncommon style output from TemPad Dev as intentional unless
-project constraints force an adaptation.
+Retain the returned `code`, `lang`, `warnings`, `assets`, `tokens`, and
+`codegen` facts that bear on the implementation. Use
+`codegen.config.{cssUnit,rootFontSize,scale}` for exact unit conversion.
-Only ask the user when the answer would materially change the implementation and
-cannot be established from project or design evidence. Typical blockers:
+Prefer one top-level read that preserves the requested composition. If the
+tool is unavailable, points at the wrong file, or returns incomplete evidence,
+read [recovery.md](references/recovery.md) before doing anything else.
-- more than one plausible target file or component boundary
-- more than one plausible existing primitive or abstraction to reuse
-- missing behavior, state, or responsive intent
-- asset, dependency, or token workflow requiring a product decision
+### 3. Separate facts, adaptations, and gaps
-If a gap is minor and non-blocking, proceed with a clearly stated inference.
+Before editing, distinguish:
-Prefer the **smallest safe change**. Do not perform unrelated refactors or add
-new abstractions unless project patterns clearly call for them.
+- **design facts** to preserve;
+- **project-native adaptations** supported by existing components, tokens,
+ utilities, or asset conventions;
+- **unevidenced product decisions** that must remain unimplemented or be asked.
-Do not enter open-ended visual tuning loops without new evidence. If remaining
-differences cannot be proved from project or design evidence, warn clearly and
-stop or hand off for user validation.
+Map by rendered value and semantics, not by a convenient name. A familiar
+component or token is a candidate, not proof of equivalence. If more than one
+material implementation path remains equally plausible, ask the user. Infer
+only low-consequence details and report any inference that affects the result.
-## Workflow
+### 4. Implement the smallest coherent change
+
+- Keep the established framework, styling system, file placement, imports, and
+ abstraction level. Do not introduce a parallel system.
+- Reuse an existing primitive only when its semantics and rendered behavior fit
+ without guessing. Do not force reuse that erases design facts.
+- Preserve exact rendered values unless project evidence proves an equivalent
+ token, utility, or component. For `rem` output, convert with TemPad's actual
+ `cssUnit`, `rootFontSize`, and `scale`.
+- Preserve intentional uncommon output, including pseudo-elements, filters,
+ masks, blend and backdrop effects, gradients, and non-default compositing,
+ unless a documented project constraint requires an adaptation.
+- Implement only evidenced states and responsiveness. Do not invent hover,
+ loading, error, empty, disabled, or responsive behavior.
+- Use native semantic elements and preserve keyboard access and accessible
+ names when an established primitive does not already provide them.
+- Add no runtime or build dependency without user approval unless the user has
+ explicitly waived that constraint.
+- Keep `data-hint-*` attributes out of shipped code.
+
+When TemPad returns relevant entries, load only the matching protocol:
+
+- assets: read [Assets](references/assets-and-tokens.md#assets) and follow the
+ project's asset delivery path;
+- token references: read [Tokens](references/assets-and-tokens.md#tokens) and
+ follow the project's token workflow.
+
+Read both when both are present and skip both when neither is present.
+
+Do not enter a visual tuning loop. Change the implementation again only when
+new project, design, tool, or verification evidence identifies a concrete
+defect.
+
+### 5. Verify in the project's real workflow
+
+Run the narrowest relevant checks defined by project instructions and scripts.
+Repair implementation failures and rerun the affected checks. Use an existing
+preview, screenshot, or comparison workflow when available; do not invent a
+universal verification matrix.
+
+If no runnable check exists, report the implementation as unverified. Do not
+claim visual completion without a real project comparison path; ask the user
+to confirm the rendered result against Figma.
+
+## Hard stops
+
+Stop instead of shipping when:
-### 1. Read local evidence first
+- TemPad is unavailable, unauthorized, inactive on the intended file, or
+ cannot provide a trustworthy visible parent composition;
+- the target is unreadable or not visible;
+- project, design, and user evidence still conflict after targeted recovery;
+- a missing decision would materially change behavior, structure, dependency,
+ asset delivery, or token mapping;
+- required assets cannot be retrieved or stored under project policy.
-Read local evidence before implementing. Prioritize, in order:
+If blocked, give at most three concrete actions that would unblock the task.
-1. `AGENTS.md` or equivalent project instruction files
-2. relevant design-system, token, and component docs
-3. existing primitives/components and nearby implementations
-4. config files and scripts that constrain output
+## Handoff
-Establish at least:
+Report:
-- framework/runtime and file conventions
-- styling rules, including whether utilities are used and how classes are
- ordered or formatted
-- token/theme system and mode handling
-- asset and icon pipeline
-- reusable primitives/components, file placement, and import path conventions
-- the narrowest established project checks for this change, if any
+- what changed and where;
+- only the relevant adaptation, inference, warning, asset/token handling, or
+ residual visual risk;
+- checks run, their result, and what remains unverified.
+
+Keep absent concerns absent from the handoff. Do not produce a compliance
+checklist for branches the task never used.
-Only if the project actually uses Tailwind or Tailwind-compatible tooling,
-detect Tailwind version and config before changing class syntax or ordering.
+## Decision example
-For Tailwind projects, also inspect the local theme scales relevant to exact-
-value mapping, especially spacing, sizing, radius, and typography.
-
-If a material implementation constraint is still missing after local evidence,
-ask the user instead of inferring it.
-
-### 2. Fetch the top-level design snapshot
-
-Call `tempad-dev:get_code` first.
-
-Use these defaults:
-
-- `resolveTokens: false`
-- pass `nodeId` only when the user provided one; otherwise use the current
- selection
-- set `preferredLang` to match the project target, such as `jsx` or `vue`
-
-Use TemPad's default vector behavior unless the user explicitly asks for
-asset-preserving vector fidelity and the current MCP version clearly supports
-it.
-
-Use `resolveTokens: true` only when the user explicitly does not want
-design-token usage.
-
-Treat returned `lang` as authoritative because TemPad Dev plugin or config may
-override `preferredLang`.
-
-Record these as design facts:
-
-- `code`
-- `lang`
-- `warnings`
-- `assets`, if present
-- `tokens`, if present
-- `codegen`
-
-Use `codegen.config.{cssUnit,rootFontSize,scale}` as the authoritative unit
-context for exact-value mapping.
-
-Prefer fetching the full requested top-level selection first so parent
-composition and containment are not lost.
-
-### 3. Resolve incomplete or conflicting evidence before implementing
-
-If `get_code` warns or fails, narrow uncertainty instead of guessing.
-
-- **`depth-cap`**: keep the returned top-level result as the source of parent
- layout and composition, then use returned `data-hint-id` values to choose
- narrower `get_code` follow-ups for the subtrees you still need.
-- **budget overflow or shell response**: keep the returned parent shell as the
- composition source of truth, then fetch omitted child subtrees separately and
- fill them into that known shell. Prefer the smallest parent container that
- still preserves the shared layout for the child subtrees you must assemble.
- Do not treat plain string truncation as usable evidence.
-- **layout, hierarchy, or overlap uncertainty**: call
- `tempad-dev:get_structure`, but use it only to resolve hierarchy or geometry,
- or to choose a narrower parent-shell retry target. Do not treat it as
- missing style truth.
-- **remaining contradiction**: if project evidence, design evidence, and
- structure evidence still conflict after narrowing, stop.
-- **untrustworthy parent recovery**: if you still cannot obtain a trustworthy
- parent shell or parent composition via `get_code`, stop full implementation
- and ask the user to narrow scope or choose the highest-priority subtree.
-
-Retry policy:
-
-- retry once only for transient transport or connectivity failures
-- do not blind-retry deterministic issues such as invalid selection, hidden
- node, wrong file, `depth-cap`, budget overflow, or unreadable target; change
- scope or inputs first
-
-If TemPad MCP appears unavailable, inactive, or pointed at the wrong file, stop
-and tell the user to:
-
-- enable MCP access in TemPad Dev Preferences > Agent integration
-- keep the correct TemPad Dev / Figma tab active
-- use the MCP badge in the TemPad Dev panel to activate the correct file if
- multiple Figma tabs are open
-
-If asking the user to narrow scope because of budget overflow, report the
-current consumption, limit, and overage from the error text.
-
-### 4. Implement code in the established project style
-
-Translate TemPad Dev output into the implementation's established patterns.
-
-- Reuse existing primitives and abstractions when they fit **without guessing**.
-- Keep the established framework and styling system. Do not introduce a second
- one.
-- Follow established file placement and import conventions.
-- If the implementation is utility-first, keep utilities and match existing
- conventions. Otherwise translate generated utilities into the established
- styling approach while preserving values.
-- Preserve exact values. Do not coarsen arbitrary values such as `py-[4px]`,
- `text-[12px]`, or `font-[600]` into named utilities unless local project
- evidence proves the same rendered value; for `rem` output, use
- `codegen.config.{cssUnit,rootFontSize,scale}` to convert exactly. Apply this
- to spacing, sizing,
- inset, gap, radius, `font-size`, `line-height`, `letter-spacing`, and
- `font-weight`.
-- Implement the base state only unless variants, interactions, or responsive
- behavior are evidenced.
-- Preserve emitted pseudo-elements. If TemPad output includes `before:`,
- `after:`, `content-*`, or equivalent CSS, keep them or use an established
- equivalent with the same rendered result.
-- Preserve other high-fidelity details from `get_code`, including pseudo-
- classes, filters, masks, blend or backdrop effects, and other non-default
- visual properties, unless implementation constraints require adaptation.
-- New runtime or build dependencies require user confirmation unless explicitly
- waived.
-- Extract new abstractions only when repetition plus established patterns
- justify it.
-- If multiple plausible primitives, layout abstractions, or delivery strategies
- fit and evidence does not decide, ask the user instead of guessing.
-
-#### Assets
-
-Follow the established asset policy first.
-
-- Download bytes only from TemPad-provided `asset.url`. Never substitute public
- internet assets.
-- Treat assets as files to save or reference, not as text evidence to parse.
-- If policy forbids storing assets, you may reference TemPad URLs, but you must
- warn that the output depends on the local TemPad asset server.
-- If a vector is emitted as `
-1. Install Node.js 18.20.0 or later with `npx`. Keep TemPad Dev open in the Figma tab you want the agent to inspect, then enable **Preferences → Agent integration → MCP access**. When prompted, allow the loopback connection to `127.0.0.1`.
+1. Install Node.js 18.20.0 or later with `npx`. Keep TemPad Dev open in the Figma tab you want the agent to inspect, then enable **Preferences → Agent integration → MCP access**. When prompted, allow the loopback connection to `127.0.0.1`. Canvas authoring is available while MCP access is enabled and the current Figma Design file is editable.
2. Select **Set up agents**, choose Codex, Cursor, Claude Code, Gemini, VS Code, OpenCode, or TRAE, and follow the displayed path. Use **Other** for another compatible client. The choice only changes the instructions shown; it does not bind or activate an agent.
-3. Prefer the direct action when offered. Every fallback command or config is shown in full for review and copying. Codex and Claude Code plugins include both MCP and the `figma-design-to-code` skill; the other paths show the two required steps separately.
+3. The setup flow installs the portable Agent Plugin first for Codex, Cursor, Claude Code, and VS Code. For Gemini, OpenCode, TRAE, and other clients without compatible plugin installation, it uses the client's MCP flow plus the two standalone skills. Every command or config is shown in full for review and copying.
+
+To install the portable package into all compatible agents detected on your machine:
+
+```bash
+npx plugins add ecomfe/tempad-dev
+```
+
+Pass `--target codex`, `--target cursor`, `--target claude-code`, or `--target vscode` to limit the
+installation to one of the built-in setup targets. Native Codex and Claude marketplace commands,
+plus direct MCP and skill installation, remain documented as compatibility fallbacks in the
+[Agent Plugin guide](./agent-plugins/tempad-dev/README.md).
+
+All plugin and direct `npx`-based setup paths use `@tempad-dev/mcp@latest`.
Keep TemPad Dev open with MCP enabled while using it. If multiple Figma files are connected, click the MCP badge in the panel for the file you want the agent to inspect; that file becomes the active context.
diff --git a/README.zh-Hans.md b/README.zh-Hans.md
index 6a6e63cd..93154cb5 100644
--- a/README.zh-Hans.md
+++ b/README.zh-Hans.md
@@ -201,14 +201,28 @@ sandboxed extension page 内启动一个全新的 Worker，并在完成或五秒
TemPad Dev 内置了面向编码 agent 和 IDE 的 Agent 集成。该集成包含：
-- 一个 [MCP](https://modelcontextprotocol.io/) 服务器，使 agent 可以直接从你在 Figma 中选中的节点拉取代码和上下文
-- 一个 agent skill，用于指导 agent 在当前仓库中理解并使用这些证据
+- 一个 [MCP](https://modelcontextprotocol.io/) 服务器，使 agent 可以检查 Figma，并在当前 Figma Design 文件可编辑时提交声明式画布结果
+- 两个 agent skill：一个用于根据 Figma 证据实现代码，另一个用于基于可访问页面中的组件定义和文件级设计资源在 Figma 画布上进行设计
-Figma 也提供官方的 [remote 与 desktop MCP server](https://developers.figma.com/docs/figma-mcp-server/)，并建议大多数用户优先使用 remote server。TemPad Dev 的定位是一个开放、强调本地控制的补充方案，适合明确需要可审计的浏览器扩展链路、现有只读检查流程、可编程输出插件、规范化的 agent-facing 代码/token IR，以及显式上下文预算的团队。TemPad Dev 提供设计证据与代码起点；最终仍由 coding agent 结合目标仓库完成适配、验证和实现。
+这些可移植能力会优先封装为
+[Agent Plugins 1.0](https://agent-plugins.org/) 插件。根目录的 `plugin.json`、`skills/` 和
+`mcp.json` 是 canonical package；客户端专用 manifest 只作为安装器或尚未直接消费开放
+格式的 host 的兼容层。
+
+Figma 也提供官方的 [remote 与 desktop MCP server](https://developers.figma.com/docs/figma-mcp-server/)，并建议大多数用户优先使用 remote server。TemPad Dev 的定位是一个开放、强调本地控制的补充方案，适合明确需要可审计的浏览器扩展链路、本地检查与由 MCP access 控制的声明式画布创作、可编程输出插件、规范化的 agent-facing 代码/token IR，以及显式上下文预算的团队。TemPad Dev 提供设计证据与代码起点；最终仍由 coding agent 结合目标仓库完成适配、验证和实现。
打开 TemPad Dev 面板并启用 MCP 后，MCP 服务器会暴露以下能力：
- `get_code`：默认输出高保真的 JSX/Vue + TailwindCSS 代码，同时包含相关资源以及使用的 codegen 预设和配置。
+- `get_design_system`：创建不可变、确定性的紧凑目录，按资源类型平衡分页返回可访问页面的
+ 组件定义，以及本地或被定义直接引用的变量、集合/模式、样式和 shader 定义；既不扫描
+ 画布中的使用情况，也不加载所有页面。游标可继续读取遗漏定义；使用同一目录精确查询
+ 某个引用时，返回该资源的有界定义。
+- `apply_canvas`：提交一次受限 HTML + 可确定转换的 Tailwind utility 目标结果，其中可以使用基础元素、
+ 目录组件标签、设计系统短引用、类型化的 Figma 专有状态、经过净化的 SVG 和内容寻址图片。
+ 扩展会在本地解析、验证、计算与实时画布的差异、应用修改并校验结构。画布创作要求当前
+ Figma Design 文件具有编辑权限。
+- `get_screenshot`：返回一张有大小限制的渲染 PNG，用于按需视觉验证。
- `get_structure`：当前选中节点的结构信息（id、类型、几何数据）。
- 二进制资源会通过工具响应中的元数据 + HTTP 下载地址（`asset.url`）提供；MCP 不再暴露 asset 资源模板。
@@ -220,9 +234,22 @@ Figma 也提供官方的 [remote 与 desktop MCP server](https://developers.figm