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..8639b2f5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,16 +32,48 @@ 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
+ in the active host and use a new task. `codex plugin add tempad-dev-dev@tempad-dev-dev` updates
+ the installation on disk, but an external CLI call 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 +147,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..e7672087
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/SKILL.md
@@ -0,0 +1,319 @@
+---
+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
+
+Turn product intent into one native, editable Figma result. Reason in this
+order: intended experience and evidence, the Figma-native artifact model,
+representation-specific mechanics, serialization, then rendered verification.
+Treat markup and classes as a transport for ordinary layer hierarchy, layout,
+spacing, typography, color, and appearance after the Figma result is decided;
+they are not the design medium or proof of native editability. Use native fields
+for capabilities whose meaning depends on Figma node types, resources, or
+state. Keep the result focal; schema fields, catalog entries, examples, and tool
+calls are subsidiary means, not design evidence or a checklist to maximize.
+
+Derive product-domain, platform, accessibility, content, and visual-design
+requirements from the user, permitted evidence, an applicable skill, or
+targeted research. Examples explain mechanics only.
+
+This skill is called by a general-purpose agent to deliver a Figma artifact. It
+owns the reliable design-in-Figma workflow: artifact modeling, representation,
+scoped authoring, reconciliation, and verification. Product-design method,
+visual direction, and component strategy come from the user, applicable
+evidence, research, or professional design expertise. The host always needs the
+current Figma context and TemPad tools; other evidence, skills, discovery, and
+acquisition capabilities may vary. Decide the expertise needed before looking
+at what is available, and do not copy another skill's contextual design rules
+into this one.
+
+Require the intended Figma tab's MCP badge to be active and the current Figma
+Design file to be editable. Never bypass that boundary or emit raw Plugin API
+operations.
+
+Use only the TemPad MCP tools supplied by the host. If those tools are absent
+from the task's tool namespace, report the integration problem and stop before
+authoring; do not launch the MCP CLI, recreate its stdio or JSON-RPC transport,
+or use shell commands as a substitute.
+
+## Authority and quality
+
+Apply explicit user requirements first, then applicable evidence, this skill's
+authoring and safety constraints, and situated design judgment. Infer
+low-consequence gaps; ask only when a missing choice would materially change the
+deliverable.
+
+- Ground material design decisions in the brief, applicable evidence, targeted
+ research, or an identified 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 established brief and with one another.
+- Preserve supplied or selected sources. Do not replace a required asset,
+ representation, or behavior with something easier for the toolchain.
+- Make the result complete, editable, intentionally structured, and free of
+ observed unintended visual or structural defects. Disclose accepted
+ limitations instead of redefining them as intent.
+
+The brief and its evidence determine task-specific quality criteria; this skill
+requires establishing and verifying them, not prescribing their answers.
+
+## Workflow
+
+1. **Fix the scope and evidence.** Determine the requested outcome, smallest
+ complete scope, create or update target, relevant evidence, content and
+ state distinctions that must survive, and unresolved material decisions. Use
+ `get_code` only when 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 when masks, IMAGE paint hashes, layout grids, or
+ frame guides must be confirmed from the live result. Create on the active
+ page by default. Omit top-level `page` unless the user or established task
+ evidence requires a specific page operation; never ask for or invent a page
+ merely to place new work.
+2. **Resolve material design decisions.** Follow the user and permitted file or
+ project evidence. When a material decision remains unresolved, name the
+ professional capability needed before choosing from the host's available
+ skills or tools; availability is not design evidence. Read
+ [style-grounding.md](references/style-grounding.md) when a material decision
+ remains unresolved; it routes applicable professional expertise, targeted
+ research, and clarification without turning those methods into TemPad rules.
+ For net-new work without a concrete visual reference or a representative
+ established screen or system, treat the direction-defining visual language
+ as unresolved even when the brief supplies only broad qualitative words.
+ Do not assume the composition needs a separate visual asset. Decide first
+ what, if anything, must be depicted, signaled, identified, or merely
+ accented. Read
+ [visual-assets.md](references/visual-assets.md) only when the result needs an
+ icon, image, illustration, diagram, vector artwork, or exact typeface
+ decision; skip it when no asset choice remains. Available search,
+ catalog, and generation routes are downstream acquisition options, not
+ evidence that imagery belongs in the result. Retain only the evidence needed
+ to recover a material choice; do not create an explanation ceremony for
+ settled or low-consequence decisions.
+ A character or primitive mark that communicates an interface affordance,
+ object, or semantic category is an icon role, not ordinary text or geometry;
+ route that decision through the visual-assets reference.
+3. **Form the desired result and translation plan.** Model the decided content,
+ states, and relationships in Figma terms before writing markup: visible node
+ roles, grouping, layout behavior, spacing, typography, color, ordinary
+ appearance, media placement, and every relationship whose editability
+ matters. Then separate the ordinary layer details Canvas HTML can serialize
+ from semantics that must use native fields, such as exact Figma resources,
+ components, variables, masks, media paints, guides, or node types. Name
+ provisional resources and their real consumers; do not let the currently
+ available classes or native schema choose the medium, structure, or design
+ direction. Preserve established resource usage on updates. When evidence
+ establishes an order or prerequisite, keep the visible hierarchy and shown
+ states consistent with it. Before the first write for new work, select Reuse
+ when permitted evidence establishes a relevant existing system, or Author
+ when the user or evidence already establishes a reusable local resource.
+ Otherwise keep Direct and Author provisional only while their planned
+ consumers are not concrete enough to judge. Resolve them at the earliest
+ evidence point: before serialization when the desired-result plan already
+ identifies actual consumers, or at the representative gate in step 5. Do not
+ serialize a dependent consumer while the path remains provisional. Identify
+ provisional shared responsibilities and their planned consumers, but do not
+ let the easiest resource to define fix the boundary.
+ Treat an explicitly editable diagram as native semantics: decide its
+ independently editable connectors, nodes, and authored geometry before
+ serialization, then declare them as the matching LINE, ELLIPSE, RECTANGLE,
+ or VECTOR shapes. Use Canvas HTML only to serialize their hierarchy,
+ placement placeholders, surrounding composition, and labels. Styled FRAME
+ rectangles and circles do not prove an editable diagram model.
+ Ask only when a material boundary cannot be inferred.
+ - **Reuse:** read
+ [design-system-reuse.md](references/design-system-reuse.md), then use only
+ returned resources relevant to the result.
+ - **Direct:** use primitives, literal values, and allowed external assets
+ when the resolved plan has no responsibility that should remain shared
+ across consumers.
+ Do not call `get_design_system`, send `catalogId`, or use catalog refs.
+ A request to limit design evidence to the current page or avoid
+ pre-existing file resources disables Reuse, not Author; create an
+ explicitly requested independent system without inspecting other pages or
+ pre-existing resources. Local variables and styles are still file-wide
+ Figma resources, and internal identity checks may remain file-wide; use one
+ collision-resistant authoring-key prefix for resources created by this
+ task.
+ - **Author:** enter when the user or the resolved, evidence-backed design
+ plan requires a reusable local resource or design-system extension. Read
+ [design-system-authoring.md](references/design-system-authoring.md) and
+ translate the selected resource plan into native definitions, contracts,
+ bindings, and consumers. Repetition, screen count, examples, and tool
+ affordances do not independently establish a resource boundary. Track the
+ selected definitions and their intended consumers for reconciliation.
+4. **Load mechanics, then serialize.** Read only the references for the Figma
+ concepts selected in step 3. Then use Canvas HTML to serialize the ordinary
+ layer tree and typed fields for the selected native capabilities. Skip Canvas
+ HTML for `markup: null`. For a create or an update that changes element
+ structure, 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
+ read only the changed Layout or Appearance and text section. Preserve every
+ unaffected element, attribute, and class; leave markup unchanged for a
+ native-only update. Copy complete private-native examples instead of guessing
+ shapes from Plugin API knowledge or validation failures. Treat the supported
+ HTML/Tailwind subset as a transport boundary, not a reason to weaken the
+ design or rebuild ordinary web composition in native DSL. Use a supported
+ equivalent only when it preserves the intended result; otherwise report the
+ missing capability rather than silently redefining the design.
+5. **Prove one representative composition.** Apply and open the smallest
+ composition that can establish the chosen visual language, content density,
+ layout behavior, and native representation before propagating dependent
+ screens. A complete one-root result may itself satisfy this gate only when
+ its Direct or Author path was resolved from concrete planned consumers before
+ serialization; otherwise apply only the representative composition first.
+ Do not create a separate proof artifact or reapply an unchanged root. On the
+ Author path, stabilize the representative composition with ordinary local
+ structure by default; author a resource earlier only when it is required to
+ construct that composition. If Direct and Author remain provisional, compare
+ the representative composition with its planned consumers now. Select Author
+ when a responsibility should remain shared and evolve across consumers, even
+ when their literal content or state differs; select Direct when a material
+ difference in structure, behavior, ownership, expected evolution, or
+ abstraction cost keeps it local. Counts, visual similarity, duplication
+ convenience, and an empty page do not decide the path. On Author, rank
+ qualifying still-local responsibilities by stable anatomy breadth, consumer
+ spread, and supported content or state variation. Establish the
+ highest-coordination relationship, replace its representative local usage
+ with native instances or bindings, and verify its definition, contract,
+ consumers, and warnings before propagation; an easier definition does not
+ close this gate. If a real usage disproves the selected contract, revise its
+ boundary or return that responsibility to Direct. Remove resources no longer
+ present in the resolved plan rather than creating specimens to justify them.
+ Follow
+ [design-system-authoring.md](references/design-system-authoring.md).
+6. **Apply the complete desired result.** Call `apply_canvas` once per coherent
+ root. If a large result must be split, use meaningful screen or section
+ boundaries. To keep several calls in one movable board, create one fixed Auto
+ Layout parent and append bounded sections to that same stable root; omit
+ existing children so updates preserve them. Use independent roots when their
+ relative organization is not part of the deliverable. Never scan for free
+ space, maintain a coordinate ledger, or translate a create root for
+ placement; TemPad Dev positions new roots from their rendered bounds. On the
+ Author path, propagate selected definitions through native instances and
+ bindings; literal lookalikes do not count as resource coverage. Keep authored
+ main definitions visible and discoverable as described in
+ [component-authoring.md](references/component-authoring.md).
+7. **Verify the delivered result.** Read structural verification. For a new
+ composition or material visual change, the representative gate in step 5
+ must already have occurred before propagation. After the complete apply,
+ inspect the final board and materially distinct screens. Open
+ `asset.localPath` directly when present; otherwise download and open the
+ returned resource. If the PNG cannot be opened, do not claim visual
+ verification. Use `get_structure` to compare page-child root bounds when
+ placement matters, a root was resized after placement, or the handoff claims
+ that multiple roots do not overlap. Every `x` and `y` is relative to the
+ node's actual Figma parent, including an outlined root; only page children
+ are page-relative. Also use it when a promised outcome depends on exact
+ native layer semantics such as an editable diagram rather than one imported
+ asset. Compare rendered evidence with the brief; check unintended overlap,
+ clipping including glyph ink, unintended crowding or breaks in the
+ composition's established hierarchy and spacing, collapsed or obscured
+ content, mismatches with the resolved visual direction, substitutions for an
+ established asset role or medium, inconsistent states, and incorrect native
+ bindings. The resolved design determines the intended role and medium; this
+ skill verifies that the Figma result preserves them.
+ On the Author path, use `get_structure` to confirm that every selected main
+ component or component set is visible in the named source area, readable at
+ its natural bounds, and consumed by native INSTANCE nodes at every usage
+ recorded for reconciliation. A hidden definition, an uninspectable
+ storage node, a primitive lookalike, or an instance of a different nested
+ resource does not close that selected usage.
+ Before closing new work, repeat the path choice once against the actual final
+ consumers, starting with the still-local responsibility with the greatest
+ coordination cost. If it now qualifies under step 5 and no authored resource
+ covers it, the path is incomplete unless a concrete contract limitation keeps
+ it Direct.
+ `verification.nativeFieldsChecked` counts the declared paint, effect, grid,
+ guide, mask, and managed-SVG assertions that TemPad compared with retained
+ Figma state. It is translation evidence only: it does not prove pixels,
+ semantics outside those assertions, or native state omitted from the desired
+ result.
+ When the handoff depends on a mask, real IMAGE paint, layout grid, or frame
+ guides, call `get_structure` with `options.native: true` after the write and
+ verify the returned `native` fields; the apply input and mutation success do
+ not establish live state.
+ Preserve unaffected content, state, assets, and relationships while repairing;
+ concealing one defect by weakening them creates another. Correct and recheck
+ only affected compositions. 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
+ this defect inventory into task-specific design requirements.
+ Treat a post-write verification mismatch as implementation evidence, not as
+ permission to delete the affected design intent. Correct the reported state
+ when an equivalent supported expression exists; otherwise preserve the
+ intended result and disclose the platform limitation.
+
+Do not turn this workflow into repeated API-like mutations.
+
+## Load references by decision
+
+Route an established design decision to its Figma concept, then to Canvas
+serialization. These references supply mechanics; do not browse them as a menu
+of design ideas. Load each only after its branch or capability is selected.
+Resolve every relative link from the directory containing this `SKILL.md`.
+
+Design decisions and evidence:
+
+- unresolved material design decisions:
+ [style-grounding.md](references/style-grounding.md)
+- asset role, subject, medium, source, or typeface choice:
+ [visual-assets.md](references/visual-assets.md)
+- existing-system reuse:
+ [design-system-reuse.md](references/design-system-reuse.md)
+- selected local-system authoring from the user or resolved design plan:
+ [design-system-authoring.md](references/design-system-authoring.md)
+- bounded research, asset, inventory, or visual-QA delegation:
+ [delegation.md](references/delegation.md)
+
+Figma-native representation and authoring:
+
+- pages, sections, groups, Booleans, masks, transforms, shapes, or vectors:
+ [document-geometry.md](references/document-geometry.md)
+- applying paints, media, effects, shaders, grids, or guides:
+ [paints-effects.md](references/paints-effects.md)
+- applying an exact font, rich text, range styles, lists, or hyperlinks:
+ [rich-text.md](references/rich-text.md)
+- authored components, variant sets, properties, or Slots:
+ [component-authoring.md](references/component-authoring.md)
+- local variables, collections, modes, or bindings:
+ [variables.md](references/variables.md)
+- authored Paint, Text, Effect, or Grid styles and bindings:
+ [local-styles.md](references/local-styles.md)
+
+Canvas serialization after representation is chosen:
+
+- Canvas elements, identity, layout, appearance, and text syntax:
+ [canvas-html.md](references/canvas-html.md)
+
+## Create and update contract
+
+- Create describes one complete new root.
+- Update changes only `targetNodeId`; supplied fields state desired values and
+ omissions preserve live children and fields.
+- `removeKeys` explicitly removes owned descendants. `markup: null` removes the
+ managed update root itself.
+- Keep `data-key` stable across calls; names are presentation only. After
+ context loss, recover managed keys from `get_structure.authoringKey`.
+
+## Safety
+
+- Never write outside the target 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 unkeyed or manual content, externally referenced nodes,
+ unmanaged resources, or a component that still has 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.
+- Treat validation failure as evidence to correct the desired result, not
+ permission to 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..6ec4b663
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/canvas-html.md
@@ -0,0 +1,245 @@
+# Canvas HTML and Tailwind subset
+
+Canvas HTML is a desired-result language, not browser rendering.
+
+Class coverage is not Figma result coverage. Use the routed typed native
+bindings for gradients, media, non-shadow effects, masks, transforms, exact
+fonts, and rich text. Use primitive layers only when the intended result is
+actually layered geometry, not as a substitute for missing browser CSS.
+
+One `apply_canvas` markup tree may contain at most 100 elements and 12 levels.
+Split larger work only at meaningful screen or section boundaries.
+
+Prefer the supported native Tailwind utilities below; use arbitrary pixel values
+only when the result is off the default scale. Numeric spacing utilities use
+Tailwind v4's default `4px` unit. Theme extensions, variants, plugins, and
+utilities whose meaning depends on a browser viewport or CSS cascade remain
+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.
+- A plain ` ` or ` ` inside `span` text creates a line break. For literal
+ source newlines or repeated spaces, add `whitespace-pre-wrap` instead.
+- 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 text and optional line breaks only. Add
+ `whitespace-pre-wrap` when repeated spaces or literal source newlines are
+ intentional. A plain `&` is literal when it does not form
+ a semicolon-terminated entity; supported named and numeric entities still
+ decode normally. Do not put layout or frame-appearance utilities such as
+ flex, grid, gap, padding, borders, corners, or box shadows on a `span`; put
+ those on a parent `div` and keep 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 attribute names are the native field in kebab case: fill, stroke,
+characters, visible, width/height and min/max bounds, gap and grid/counter
+gaps, four paddings, corner radius and four corners, stroke weight and four
+sides, opacity, and the whole-node font/line-height/letter-spacing/paragraph
+fields. Style attributes are `data-style-fill`, `stroke`, `text`, `effect`,
+and `grid`. Node-type and fallback requirements 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
+
+When text uses `w-fit`, it must also use `h-fit`; prefer `size-fit`. A fixed-width
+`h-fit` text node remains valid when its lines should wrap within that width.
+
+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 the cross axis of `flex-col`, `h-full` only on the cross
+axis of `flex-row`, and `grow` on the main axis; use `grow-0` to clear growth.
+`grow` sets native main-axis growth but does not replace the required width and
+height classes: for example, use `grow w-fit h-[3px]` for a horizontal track in
+a row. Give growing text in a fixed or otherwise constrained row a meaningful
+positive `min-w-*`; `grow w-fit` text can otherwise collapse before Figma
+resolves the remaining width. Before applying a fixed Auto Layout frame, budget
+its main axis as padding + gaps + fixed/minimum child extents so content cannot
+overrun the container. Grid children may fill their cell. Direct width and height variables
+require fixed-size fallbacks. Fixed sizes are 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 use Figma's CSS-aligned model: inside strokes participate
+in layout by default (`box-border`), while `box-content` explicitly excludes
+them. Center and outside strokes never affect padding, spacing, or fill math,
+even with `box-border`; each nested frame owns its own stroke setting. Fixed
+create sizes must be large enough for opposing padding and any explicitly
+included inside stroke. Figma owns the final geometry of `FILL` children,
+including border-box distribution between multiple fill siblings.
+Derive an exact in-flow descendant or instance size from that rendered inner
+box, not from the parent's nominal size; when it should track the inner box,
+prefer valid cross-axis fill. Let it exceed the inner box only as an intentional
+bleed or overlap.
+
+Treat `managed-content-overflow` as a structural-verification warning: a
+managed Text or INSTANCE extends beyond its direct managed Frame or Component
+parent. Inspect the reported edges, clipping state, and rendered result. Resize
+or realign accidental overflow; retain it only after confirming the bleed,
+crop, or overlap is intentional.
+
+`justify-between` uses native Auto gap: its effective gap never becomes negative
+and a single child stays at the start. Use an explicit negative native
+`figma.autoLayout.itemSpacing` only when overlap is intentional. On update,
+omitting `box-border` and `box-content` preserves the live frame's setting.
+
+`hidden` and BOOLEAN component-property visibility remove an in-flow child from
+Auto Layout, so gaps, sibling positions, and hug dimensions can change. For a
+purely visual state that must preserve geometry, keep a fixed outer slot in the
+flow and toggle only its inner child. `absolute left-[Npx] top-[Npx]` maps to
+Figma's Ignore Auto Layout behavior and is appropriate for a true overlay; it
+must have fixed offsets, cannot fill or grow, and surrounding content will
+ignore it. Text and Auto Layout frames may still hug their own content.
+
+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 a manual grid child both row and column starts or neither. Auto-flow
+children use source order and cannot set explicit starts.
+A grid that hugs its height cannot use flexible or automatic row tracks. Give
+the grid a fixed height or use fixed row tracks.
+
+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 deliberate freeform composition, omit layout classes and give every described child
+`absolute` with exactly one horizontal edge (`left-*` or `right-*`) and one vertical edge
+(`top-*` or `bottom-*`), including negative forms and exact `[Npx]` values, or use a native
+relative transform. Edge-relative placement requires fixed parent and child bounds. A plain `div`
+without `flex` or `grid` is freeform even when it has only one child; opt into `flex-row`,
+`flex-col`, or grid for any in-flow child, including a partial-width fill inside a track.
+An absolute child cannot grow or fill an axis. Use `static` to return an existing absolute child to
+Auto Layout during an 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 both a weight and a paint source, supplied literally or by a
+native binding. During update, either side may change independently; omitting
+the other preserves its live value or binding.
+
+A newly created frame is transparent when its background is omitted, including
+when the frame is introduced by an update. Use an explicit background class
+when the frame should render a fill.
+
+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`, `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 Figma TEXT node, so `bg-*` and `text-*` both target that node's
+single fill channel. For colored text on a background, put the background on a
+parent `div` and the text color on its child `span`.
+
+Shadow classes compile to the node's native Figma effect stack. Do not combine
+them with a direct `figma.effects` binding or an Effect style on the same node;
+use one source for that stack.
+
+Unknown elements, attributes, classes, CSS, responsive/state prefixes, custom theme names, margins,
+percentage sizing, and plugins fail closed instead of being ignored.
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..5531c87b
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/component-authoring.md
@@ -0,0 +1,284 @@
+# Author reusable components
+
+Use this reference when the user or resolved design plan selects a reusable
+local component. This reference explains representation; it does not select a
+component boundary or justify a component library. New local components do not require
+`get_design_system`. Use a catalog when discovery or normalized library props
+are useful; use an exact returned live ID for a component the agent just
+authored.
+
+When a composition uses a new component, its final usage nodes must be native
+Figma instances. Either:
+
+- author the component first, then use its returned `rootNodeId` or exact entry
+ from `nodeIdsByKey` in the composition;
+- stabilize the composition first, then author the component and replace each
+ managed primitive usage. Give a replacement a new `data-key` when needed and
+ list the old key in `removeKeys`.
+
+Never leave a visually equivalent primitive copy as the final usage.
+If a representative instance is later replaced to fit real content or geometry,
+the selected responsibility is no longer closed. Revise the component contract
+or instance sizing and restore the usage; if the contract no longer earns its
+cost, safely remove the now-speculative definition instead of reporting it as a
+reusable deliverable.
+
+Before expanding a composition around a new component, create the smallest real
+definition needed and use its exact returned `rootNodeId` or `nodeIdsByKey`
+entry in one representative native instance. Continue only after structural
+verification confirms that component reference. If the tool does not return an
+exact ID, rejects the instance, or cannot verify its reference, stop creating
+component resources. Never represent a failed instance with a primitive or
+claim the component deliverable is complete. Continue independent Direct screen
+work only when it remains a valid requested outcome and explicitly report the
+degraded component delivery; if a reusable component is itself required, that
+part of the task remains incomplete. Remove an unused temporary definition only
+when safe and not itself a requested deliverable.
+
+If a verified definition becomes empty, default-sized, or loses properties,
+treat it as transaction corruption. Do not rebuild it in place: update preserves
+its page coordinates. Re-read the definition and intended usage, then stop and
+report it. With a fixed MCP session, remove and recreate it only when unused;
+never remove or substitute a definition with instances.
+
+Markup-only updates preserve existing keyed components, component sets,
+instances, and shape nodes, so an ancestor layout repair does not need to
+restate their native declarations or instance component references. Include a
+binding only when the call changes native state; new native nodes still need an
+explicit declaration or component reference.
+
+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
+
+Before creating a definition, compare every intended usage and separate stable
+anatomy from differing content, state, or nested substitution. Map each real
+difference to the smallest supported mechanism: Text, Boolean, Instance Swap,
+a variant, a Slot, or nested composition. Treat a field as invariant only when
+the concrete usages agree.
+
+When stable anatomy is expected to evolve together, a state difference that a
+supported property or variant can express is evidence for the shared contract,
+not a reason to keep copies local. Keep the responsibility local only when
+consumer divergence or contract cost outweighs that coordinated change.
+
+If a meaningful usage difference cannot be expressed by the proposed contract,
+revise the component structure or keep the responsibility local. Do not publish
+a reusable definition that makes different usages share placeholder content or
+an accidental default merely because its outer geometry repeats.
+
+Model one mutually exclusive categorical concern as one variant axis. Do not
+replace it with independent Boolean properties whose combinations permit no
+active value or several active values when those states are not real usages.
+Use Boolean properties for independently optional content or behavior.
+
+Do not expose one semantic choice through both a variant axis and an independent
+property unless real usages can vary them separately. When a visible value is
+determined by a variant state, keep each main variant truthful; do not give all
+source variants one accidental default and repair only their instances with
+overrides.
+
+## Keep source definitions discoverable
+
+Keep main components and component sets visible at natural bounds in a clearly
+named source area separate from consumer screens. Never hide, clip, make
+transparent, or invisibly nest a main definition. For several component
+families, use a top-level native SECTION with `contentsHidden: false`; keep the
+definitions as discoverable children and size the section to their content.
+
+The source area contains the real definitions once, not redundant specimens.
+Before handoff, use `get_structure` to confirm every selected definition is
+visible and each intended consumer is an INSTANCE. Inspect materially distinct
+source variants at a readable scale and confirm their names, visible content,
+and styling encode the same state; instance overrides do not repair an
+incorrect source contract.
+
+## 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 property keys such as `label` connect definitions and sublayer
+references inside the same result. They are not the generated Figma property
+names. Supported authored property definitions are `BOOLEAN`, `TEXT`, and
+`INSTANCE_SWAP`. Link sublayers with `visible`, `characters`, or
+`mainComponent` respectively.
+
+BOOLEAN properties control layer visibility, not visual styling. Figma removes
+a hidden in-flow child from Auto Layout as if it were absent. Use that behavior
+for intentionally optional content. When a state decoration must not move text
+or siblings, bind `visible` to an inner layer inside an always-present fixed
+slot, or make the decoration `absolute` when overlay positioning is the real
+semantics. Use geometry-equivalent variants when the whole visual state changes.
+
+Treat `layout-affecting-visibility-property` as a state-contract warning. Fix it
+when geometry should remain stable. Accept it only when reflow is intentional,
+after creating representative true and false instances and comparing their
+bounds, sibling positions, text baselines, and clipping. A screenshot of only
+the default property state is not component verification.
+
+## Consume an authored component directly
+
+Use the exact live ID returned by the component's `apply_canvas` result. For a
+TemPad-authored component, `componentProperties` accepts the same stable
+property keys used in its definition. This complete follow-up call 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 exact returned ID. Do not invent a live
+ID or use this shortcut for an unidentified library component.
+
+## Variant set
+
+This complete call creates two components and combines them into one variant
+set. Direct children of a new set must all be authored components. Variant
+names encode axes using Figma's `Property=Value` convention.
+
+```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 directly and select a sibling through its variant
+property. For example, if the call above returns the set as `rootNodeId`, this
+follow-up creates one default and one Hover instance:
+
+```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 illustrative ID with the exact returned `rootNodeId`. The set ID
+creates its default variant; `componentProperties` selects another real variant
+by its encoded axis. An exact child ID from `nodeIdsByKey` may instead create
+that variant directly.
+
+Use `descriptionMarkdown` and `documentationLink` only for real guidance. Both
+belong inside `figma.component`, beside `type` and `properties`; they are not
+siblings of `figma.component`:
+
+```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 when flexible nested content is an intentional component
+API. A new slot must be inside a local authored component and must include
+`property.name`; its existing markup children become default slot content.
+Optional settings cover stretching, empty display, child limits, and preferred
+values.
+
+An `INSTANCE_SWAP` default uses a design reference with an exact live component
+or set ID (`{ "id": "..." }`) or an importable library key (`{ "key": "..." }`).
+Each preferred value instead requires the strict shape
+`{ "type": "COMPONENT" | "COMPONENT_SET", "key": "..." }`; it does not accept
+a live ID or catalog ref. Resolve catalog entries to the supported identity
+before authoring and never invent one. Advanced instance state belongs under
+`figma.instance`; omission preserves normal Figma 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..05cdcbac
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/delegation.md
@@ -0,0 +1,98 @@
+# Delegate bounded evidence work
+
+Design judgment is partly tacit: no handoff fully encodes the user, product,
+canvas, references, and emerging composition. Delegate evidence and isolated
+production, never focal judgment. The main agent synthesizes and remains the
+only Canvas writer.
+
+## Pass the delegation gate
+
+Spawn the smallest useful number of subagents only when every condition holds:
+
+1. **Separable:** the work has a stable objective and does not depend on an
+ evolving design decision.
+2. **Compressible:** the relevant context fits in a compact task-local brief
+ without recreating the main conversation.
+3. **Isolated:** the work is read-only or produces an isolated artifact; it
+ never mutates the shared Figma canvas, design-system state, or another
+ agent's files.
+4. **Verifiable:** the result can return as citations, an importable asset
+ reference, exact facts, or a bounded defect list that the main agent can
+ inspect.
+5. **Worth coordinating:** parallelism, specialized capability, or an
+ independent perspective materially outweighs handoff and synthesis cost.
+
+Keep work local when any condition fails. Do not delegate for ritual,
+convenience, or another unsupported aesthetic opinion.
+
+## Write a complete handoff
+
+Give each subagent:
+
+- one objective and why it matters to the composition;
+- only the established task, evidence, and resource constraints needed for that
+ objective;
+- permitted tools, sources, and artifacts;
+- explicit exclusions and the no-Canvas-write boundary;
+- an exact output contract and stop condition.
+
+The main agent reads required Canvas references and sets resource and safety
+boundaries; never delegate this skill's interpretation. Use a fresh or
+minimum-context worker when possible, send source evidence rather than the main
+agent's conclusion, and avoid overlapping assignments.
+
+## Delegate only suitable tracks
+
+### Research scout
+
+Delegate a bounded evidence question after the main agent frames the design
+problem. Return only:
+
+```txt
+open decision; exact source; applicable finding; relevance; authority boundary
+```
+
+The scout does not choose the direction. One may cover several explicit
+questions when their search space is shared; use multiple scouts only for
+independent search spaces.
+
+### Asset scout
+
+Delegate generation or source exploration only after establishing the asset's
+task-specific requirements and import contract. Return one importable `imageUrl`
+or `assetHash` per requested asset, with MIME type, dimensions, provenance, and
+a factual description. Return no bytes, discarded candidates, or transcript.
+The main agent owns integration and judgment.
+
+### Independent QA scout
+
+After the representative composition exists, give a fresh worker its screenshot
+and the frozen brief without the creator's rationale or suspected defects. Ask
+for at most eight factual observations:
+
+```txt
+severity; screen/node or region; observed defect; visible evidence; violated constraint
+```
+
+The scout does not edit, redesign, or declare completion. The main agent checks
+each observation against the live canvas.
+
+### Inventory scout
+
+Delegate read-only inventory only when enough independent material makes it
+worthwhile, such as checking several screens or icon candidates. Return exact
+findings and references, not a design proposal.
+
+## Orchestrate conservatively
+
+- Default to one worker and at most two concurrent, non-overlapping workers.
+- Keep the main agent productive; do not delegate a faster local critical path.
+- Only the main agent interprets ambiguous intent, resolves conflicts, chooses
+ the direction, and calls `apply_canvas`.
+- Resolve conflicts from evidence, not voting. Discard unverifiable or
+ out-of-scope claims, and stop when evidence is sufficient.
+
+Never delegate interdependent page/component construction, component
+authoring plus instance placement, updates to the same root, final composition,
+or final acceptance. These require the main agent's continuous awareness of the
+whole and a single ordered mutation stream.
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..b93b7dbd
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/design-system-authoring.md
@@ -0,0 +1,101 @@
+# Implement a selected local design system
+
+Read this reference only when the user or the resolved design plan requires new
+local components, variables, or styles. This reference translates that plan
+into native Figma resources and verifies the handoff. It does not decide the
+product's component strategy, visual language, resource inventory, or token
+taxonomy.
+
+## Establish the implementation contract
+
+Before writing, identify only what the resolved plan establishes:
+
+- the screens or usage cases in scope;
+- each selected resource and the design responsibility it represents;
+- its concrete consumers and meaningful content, state, or substitution
+ differences;
+- anything the user or governing evidence excludes.
+
+If a material resource boundary is still undecided, return to the core
+workflow's design-resolution step. Do not derive a component library from UI
+category, visual similarity, repetition, screen count, an example in this
+skill, or the currently supported tool schema.
+
+Keep a private implementation map:
+
+```txt
+selected resource -> native representation -> intended consumers
+```
+
+This is a reconciliation aid, not canvas documentation. A selected resource is
+closed only when the native definition or binding exists and every intended
+consumer uses it. A visually equivalent primitive or literal is not coverage.
+
+## Translate the selected plan
+
+Use a concrete-to-reusable implementation loop:
+
+1. Stabilize one representative composition before propagating dependent work.
+2. Author only selected resources whose real consumers are known.
+3. Exercise each contract in that representative composition.
+4. Propagate native instances and bindings to every intended consumer.
+5. Reconcile the final artifact with the implementation map.
+
+Choose the Figma representation that preserves the already-decided semantics:
+
+- A variable carries a selected semantic value that consumers need to bind and
+ evolve together. Name it by role, not its current literal.
+- A local style carries a selected reusable native paint, text, effect, or grid
+ definition. Do not duplicate the same decision as unrelated resource types
+ unless the plan requires both.
+- A component carries a selected reusable responsibility. Define its stable
+ anatomy and expose only content, state, or nested substitution required by
+ real usages.
+
+Canvas HTML consumes a component through a childless instance placeholder with
+no layout or appearance classes. Do not select a repeated product shell or
+other wrapping top-level subtree as a component unless every intended consumer
+can use that placeholder through supported component properties. An authored
+Slot does not allow markup children on the instance placeholder. Otherwise keep
+the wrapper as ordinary structure and select a compatible inner component
+boundary.
+
+For a selected component, map each real difference to the smallest supported
+mechanism: Text, Boolean, Instance Swap, a variant, a Slot, or nested
+composition. Model one mutually exclusive categorical concern as one variant
+axis; use Boolean properties only for independently optional concerns. Do not
+encode arbitrary content as variants, generate unused combinations, or freeze a
+varying field as accidental invariant content.
+
+If the selected contract cannot express a real usage through supported native
+mechanisms, do not weaken or silently redesign it. Return to the governing
+design decision when an alternative boundary is valid; otherwise report the
+authoring limitation.
+
+Read [variables.md](variables.md), [local-styles.md](local-styles.md), or
+[component-authoring.md](component-authoring.md) only for the resource types in
+the selected plan.
+
+## Verify the native handoff
+
+Judge resources through representative consumers, not definitions alone.
+Verify native bindings, Auto Layout, text resizing, property behavior, and each
+materially distinct state. Equivalent raw literals and primitive lookalikes do
+not demonstrate system usage.
+
+For components, follow the discoverability and source-state checks in
+[component-authoring.md](component-authoring.md). Main definitions must remain
+visible and inspectable, and final usages must be native instances. For
+variables and styles, inspect representative live bindings rather than relying
+on apply input or equal values.
+
+Resolve authoring warnings through real consumers or remove a resource only
+when the resolved plan no longer includes it. Tool friction, payload size, or
+the existence of one easy resource does not change the plan. Do not create a
+swatch, specimen, definition panel, or redundant example solely for
+verification; include documentation only when the requested handoff calls for
+it.
+
+Finish when the selected resources support the requested usage cases and the
+implementation map reconciles with the live Figma structure. Do not expand the
+system 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..f2017987
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/design-system-reuse.md
@@ -0,0 +1,68 @@
+# Reuse an existing design system
+
+Read this reference only when reuse is allowed and relevant to the requested
+result. If the user rejects a design system, use the Direct path instead.
+
+## Discover definitions
+
+Call `get_design_system` without arguments. It returns an immutable,
+deterministic catalog of definitions already accessible to Figma:
+
+- `catalogId` scopes all short refs;
+- components provide a tag, props, source page, and native size;
+- variables, collections, modes, styles, and shaders use short refs such as
+ `v1`, `k1`, `m1_2`, `s1`, and `h1`;
+- `omitted` and `nextCursor` mean more definitions remain in the same catalog.
+
+The catalog does not scan canvas usage, load pages, or rank resources for the
+task. Select only from names, source pages, summaries, props, types, scopes,
+and default values. Continue a cursor or inspect an exact ref only until enough
+evidence exists.
+
+Use this preference order:
+
+1. real catalog component;
+2. supported component prop;
+3. matching native style;
+4. semantic variable;
+5. primitive or literal for a real gap.
+
+When valid variants, component anatomy, layout, or semantic meaning affects
+the result, call `get_design_system` again with the exact `ref` and same
+`catalogId`. Use its `previewNodeId` with `get_screenshot` only when visual form
+affects the choice. Read an existing composition with `get_code` or
+`get_screenshot`; the catalog cannot infer usage conventions.
+
+Do not invent refs, native IDs, keys, component props, or variant values.
+
+## Apply catalog resources
+
+Component tags are childless, include the returned `data-ref`, and use exact
+returned prop names and values. Omitted size classes preserve native component
+size. Bind common variables and styles beside the affected element with
+`data-var-="vN"` and `data-style-="sN"`. Put collection modes or
+strict native links in `native[data-key]`.
+
+This complete example illustrates the contract; replace every illustrative ref
+with one returned by the active catalog:
+
+```json
+{
+ "mode": "create",
+ "catalogId": "ds_example",
+ "markup": "
Team settings
",
+ "native": {
+ "settings": {
+ "variableModes": { "k1": "m1_1" }
+ }
+ }
+}
+```
+
+If an exact required component is absent, do not assume it exists on an
+unloaded page. Ask the user to open its definition page when that design system
+is mandatory; otherwise use the normal primitive fallback.
+
+An empty canvas is not a blocker. Reuse discoverable definitions when allowed;
+otherwise create a small coherent primitive draft. Do not create a token or
+component library merely to make 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..114acc7c
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/document-geometry.md
@@ -0,0 +1,116 @@
+# Document and native geometry
+
+Use `native[key].figma` only for native state that HTML and classes cannot
+express honestly. This remains declarative desired state.
+
+## Page 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/reuse `pageKey`, or create a named page for a
+missing key. Updates stay on the target node's page.
+
+Use:
+
+- `figma.section: { contentsHidden? }` for native canvas organization;
+- `figma.group: true` for an intrinsic layer group;
+- `figma.booleanOperation: "UNION" | "SUBTRACT" | "INTERSECT" | "EXCLUDE"`
+ for non-destructive geometry.
+
+Sections use fixed pixel dimensions and freeform children. Groups and Boolean
+operations use `w-fit h-fit`; their direct children are freeform. A new group
+needs one child and a new Boolean operation needs two. When supplying children
+of an existing intrinsic container, describe every live direct child because
+order is semantic.
+
+Sections do not expose frame clipping, so omit `overflow-hidden` and
+`overflow-visible` from a section root.
+
+When `targetNodeId` is an existing section, keep `figma.section` on the update
+root even when its native section fields are unchanged. Without that desired
+root-type declaration, the markup root is a frame and the update 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 vector paths with uppercase `M L Q C Z` for ordinary icons. Use a
+vector network only for branching segments, per-vertex state, or
+region-specific fills/styles. Do not supply paths and a network together. New
+vectors need geometry; omission preserves it on update and an empty
+path/network clears it.
+
+Each `paths` item is an object, not a raw path string. `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 the vector node's tight bounds before the
+markup dimensions are applied. Treat the childless `div`'s position and size as
+the vector's final bounding box, not as a preserved coordinate viewport. When
+the path must align with surrounding content, offset the `div` by the path's
+minimum x/y and size it to the path's x/y spans; otherwise a partial-range path
+is stretched to fill the declared box. Verify the rendered anchors after
+authoring because `get_structure` reports node bounds, not path coordinates.
+
+This complete Direct recipe creates one native 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" }
+ }
+ }
+ }
+}
+```
+
+## Transform, masks, and native state
+
+- `figma.name` sets the display-layer name; `data-key` remains identity.
+- `locked` and `aspectRatioLocked` set native interaction state.
+- `relativeTransform` is a complete native 2×3 unit-axis transform. Width and
+ height carry scale. Do not combine it with `rotate-*`. On a create root,
+ TemPad Dev preserves rotation and skew axes but replaces translation with its
+ automatic non-overlapping page placement.
+- `stroke` carries weight(s), alignment, caps, joins, miter, and dashes.
+- `corners` carries radius/radii and smoothing.
+- `mask` is `"ALPHA"`, `"VECTOR"`, `"LUMINANCE"`, or `null`.
+
+Put a mask before the siblings it masks, keep the mask group in one dedicated
+frame, and describe every direct sibling during an update. A non-null mask
+must have at least one following sibling. Omission preserves mask state; null
+disables it.
+
+After a mask, layout grid, or frame-guide change, use `get_structure` with
+`options.native: true` on the smallest relevant root. Confirm the mask's
+`native.mask` value and following-sibling order, or the root's returned
+`native.layoutGrids` and `native.guides`; do not infer those states from the
+desired binding alone.
+
+Use `{ "ref": "…" }` for catalog resources nested in advanced native state.
+Use `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..e7b4067b
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/local-styles.md
@@ -0,0 +1,62 @@
+# Author local styles
+
+Use this reference only when the user explicitly requests a local style or a
+design-system extension that needs one. Do not extract styles from an ordinary
+screen. New local resources do not require a catalog; use `catalogId` only when
+a nested `{ "ref": "…" }` deliberately reuses an existing catalog resource.
+
+Copy this complete recipe and change its design facts. Style authoring keys
+persist file-wide so later calls can recover the same resources; they are not
+Figma names or IDs. Namespace them by product and role. In a shared draft,
+also prefix human-visible style names when a generic name such as
+`Typography/Body` would collide with independent work; keep established
+project naming when it already provides a clear namespace.
+
+```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" }
+ }
+ }
+ }
+}
+```
+
+Style types are `PAINT`, `TEXT`, `EFFECT`, and `GRID`. Use the matching native
+definition: `paints`, text fields, `effects`, or `layoutGrids`. Exact Paint,
+Effect, and Grid shapes live in [paints-effects.md](paints-effects.md); read it
+when the requested definition goes beyond the simple recipe above.
+
+Omitted fields preserve managed resource state. A top-level `null` removes a
+managed style only when the user explicitly requires absence and every live
+consumer is cleared or removed in the same result. Never mutate or delete a
+remote resource, invent a library key, or create a broad style library for a
+one-off screen.
+
+A style created without a same-result `styleKey` reference returns
+`unbound-created-style`. Treat it as unfinished authoring: bind the style to a
+representative consumer whose property performs its named role, or remove the
+speculative definition. A swatch or unrelated binding does not close 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..19e97327
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/paints-effects.md
@@ -0,0 +1,86 @@
+# Paints, effects, grids, guides, and media
+
+Use this reference to encode a chosen Figma appearance or layout aid. When an
+image or illustration's role, subject, medium, or source is unresolved, decide
+that first through [visual-assets.md](visual-assets.md). Prefer a matching
+catalog style; use direct native arrays only when no style expresses the
+required state.
+
+## Catalog links
+
+Keep common refs on the element:
+
+```html
+
+```
+
+A style owns its channel. Do not combine a non-null fill/stroke style with a
+whole-node variable on the same paint. A styled stroke still needs literal,
+typed, or variable-bound geometry. `null` unlinks; omission preserves.
+
+## Resolve shadow references before applying
+
+A named scale such as `shadow-md` refers to its governing theme; it is not
+portable effect geometry. Resolve that reference before writing the desired
+result:
+
+- on Reuse, bind the matching catalog Effect style;
+- on Author, create and bind a local Effect style only when the requested
+ system justifies that reusable resource;
+- on Direct, use an exact `shadow-[...]` class or typed `figma.effects` value.
+
+Do not assume Tailwind defaults or create a token merely to make a named class
+resolvable. `shadow-none`, `inset-shadow-none`, and `text-shadow-none` remain
+explicit clear operations.
+
+## Native paint and effect stacks
+
+`figma.fills` and `figma.strokes` support ordered native:
+
+- solid paints;
+- linear, radial, angular, and diamond gradients;
+- image and video paints;
+- Pattern paints;
+- fill shaders.
+
+`figma.effects` supports ordered shadows, normal/progressive blur, noise,
+texture, glass, and effect shaders.
+
+Omission preserves a stack; `[]` clears it. A direct stack cannot share its
+channel with a literal class, whole-node variable, or native style.
+
+Use `{ "ref": "v1" }` for nested color/effect variables and
+`{ "ref": "h1" }` for a shader ID. Use only returned shader property IDs and
+declared value shapes.
+
+For images use exactly one same-file `imageHash`, HTTP(S) `imageUrl`, or
+call-scoped `assetKey` declared as a full-SHA-256 Hub IMAGE asset. PNG, JPEG,
+and GIF retain Figma's 4096×4096 limit. For videos use exactly one same-file
+`videoHash` or HTTP(S) `videoUrl` for MP4, MOV, or WebM up to 100 MB. URLs must
+be fetchable without credentials. Reuse `figmaImageHash`,
+`figmaImageHashes`, or `figmaVideoHashes` from `get_code` only in the same
+Figma file; these identify native media, not preview bytes.
+
+A Pattern uses exactly one existing `sourceNodeId` or same-result
+`sourceCanvasKey`.
+
+## Layout aids
+
+Use a catalog Grid style when one matches. Otherwise `figma.layoutGrids`
+declares ordered row, column, or square grids on frames, components, component
+sets, and instances. Use `"AUTO"` for automatic row/column count. Do not bind
+`sectionSize` with `STRETCH` or `offset` with `CENTER`.
+
+`figma.guides` carries the complete ordered X/Y guide list. Omission preserves;
+`[]` clears. Page guides live under top-level `page.guides`.
+
+On wrapping linear Auto Layout, `figma.autoLayout` may set signed
+`itemSpacing`, positive or synchronized-null `counterAxisSpacing`, and
+`itemReverseZIndex`. Do not declare the same physical gap in 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..566b5efe
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/rich-text.md
@@ -0,0 +1,61 @@
+# Rich text and hyperlinks
+
+Use this reference to encode an already chosen typeface or Figma-only text
+behavior. Resolve a material typeface choice through
+[visual-assets.md](visual-assets.md) first. Use a `span` for editable text;
+whole-node typography normally belongs in classes, a catalog Text style, or
+semantic variable bindings.
+
+`native[key].figma.text` carries Figma-only state:
+
+- exact whole-node `fontName`, `autoRename`, vertical alignment, leading trim;
+- paragraph indent/spacing, list spacing, hanging punctuation/list;
+- whole-node hyperlink;
+- ordered rich-text `ranges`.
+
+Do not combine `autoRename: true` with a fixed `figma.name`.
+
+Use an exact whole-node font when no catalog Text style or typography variable
+expresses the intended family and style:
+
+```json
+{
+ "fontName": { "family": "IBM Plex Sans", "style": "Medium" }
+}
+```
+
+Do not combine it with `font-*` classes, a linked Text style, or font family or
+style variables. Figma must have the exact family and style available.
+
+Range `start` and `end` are UTF-16 offsets into the final span characters.
+Ranges must be ordered, non-overlapping, and contain at least one actual
+property. Split overlapping intentions into non-overlapping intervals.
+
+A range can set:
+
+- font name/size, case, letter spacing, line height;
+- complete underline state;
+- native fills;
+- Text/Paint style;
+- list options, indentation, and paragraph spacing;
+- hyperlink;
+- supported text-range variables.
+
+Use `{ "ref": "s1" }` for a catalog range style and `{ "ref": "v1" }` for
+a range variable. `null` unlinks a supported style or hyperlink; omission
+preserves live state.
+
+Hyperlinks support URL and node targets. For a same-result node target, use:
+
+```json
+{
+ "type": "NODE",
+ "value": { "canvasKey": "settings/help" }
+}
+```
+
+The target may appear later in markup. Do not remove a node that remains a
+hyperlink target.
+
+If a component exposes text through a catalog prop, set the component prop
+instead of reaching into its internal text 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..a9f1c4c9
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/style-grounding.md
@@ -0,0 +1,112 @@
+# Ground unresolved design decisions
+
+Use this reference only when a material design decision is not established by
+the user, permitted project or Figma evidence, or suitable professional
+expertise. Skip exact reproduction, mechanical edits, and decisions already
+settled by sufficient evidence.
+
+This reference defines an evidence process, not a UX checklist or style guide.
+It does not prescribe which product concerns must matter, how many sources to
+inspect, or what conclusion to reach. Determine those from the actual task.
+
+## Isolate the uncertainty
+
+Before research:
+
+1. inventory the requirements and evidence already available;
+2. name only the unresolved decisions that could materially change the result;
+3. separate missing evidence from low-consequence choices the agent can make and
+ identify as assumptions.
+
+Do not research a broad category when one decision is unresolved. Do not turn a
+remembered convention, a tool affordance, or an example from this skill into a
+requirement.
+
+Broad qualitative words can state an intended effect without determining the
+choices that produce it. When materially different interpretations remain
+plausible, the decision is still unresolved.
+
+For a net-new result without a concrete reference or representative established
+screen or system, the direction-defining visual language is material. Giving the
+agent creative latitude assigns that decision to the agent; it does not make the
+decision low-consequence. This calls for the smallest evidence that resolves the
+choice, not a survey of the category.
+
+## Select expertise before availability
+
+Name the professional capability that owns the unresolved decision before
+examining installed skills or tools. Then, when the host permits it, discover or
+acquire a candidate and inspect its provenance, instructions, stated scope, and
+fit for the task's platform, medium, domain, and deliverable. Installed status
+or a broad label such as “frontend” does not establish suitability, and no one
+design skill is a universal default. Use complementary expertise only where the
+task needs it; TemPad remains responsible for Figma execution.
+
+When the selected candidate is a remote skill, retrieve its complete current
+instructions through a path that reaches the end of the source. A truncated
+response, excerpt, or search result is not the skill; retry through another
+supported path or report that the candidate could not be inspected.
+
+If the host cannot supply suitable expertise, use targeted primary guidance or
+inspected visual evidence. Ask the user when the remaining choice would
+materially change the result. Never copy one candidate's contextual rules into
+this reference or silently turn missing environment capability into generic
+design defaults.
+
+## Obtain sufficient evidence
+
+For each unresolved decision, choose the nearest credible source whose authority
+actually covers that decision. Project and current-file evidence usually has the
+closest product context; external primary guidance may establish scoped
+requirements; inspected products or visual artifacts may establish applicable
+precedent. These are possible evidence roles, not a mandatory source list.
+
+Start with the closest candidate and inspect one representative source or
+artifact. Seek another only when the first leaves a material conflict or gap;
+the objective is to settle the decision, not accumulate inspiration. Search
+snippets and remembered summaries are discovery leads, not inspected evidence.
+Record:
+
+- the exact source or artifact identity;
+- the requirement or principle it supports;
+- why it applies here and where its authority stops;
+- the resulting decision or remaining uncertainty.
+
+Use as many distinct sources as the unresolved decision genuinely needs—no
+fixed minimum or comparison ceremony. Stop when the material uncertainty is
+resolved. If required evidence is unavailable or prohibited, ask the user when
+the choice would materially change the deliverable; otherwise state the
+assumption.
+
+Match the evidence medium to the decision. Textual guidance, including generic
+guidance from another skill, may establish a workflow or behavioral principle;
+a direction-defining visual decision needs an inspected visual artifact or an
+exact visual specification. Search results, product descriptions, and prose
+about navigation do not by themselves establish composition, typography, color,
+density, or imagery.
+
+Judge sufficiency per decision. Evidence about an asset, isolated convention,
+or tool constraint does not ground unrelated composition or visual-language
+choices.
+
+## Retain a compact decision trace
+
+Keep a short working note before the first `apply_canvas` call:
+
+```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
+```
+
+Include only lines the current task needs. This note is not a deliverable or a
+mood board.
+
+## Apply and verify
+
+Translate the decisions into one coherent composition. Judge the rendered
+artifact against the task-specific trace, not against generic advice in this
+skill. Correct concrete mismatches; do not add more research or continue tuning
+without a remaining material uncertainty or 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..9804cf80
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/variables.md
@@ -0,0 +1,129 @@
+# Author local variables
+
+Use this reference only when the user explicitly requests a local variable or
+design-system extension that needs one. Do not extract tokens from an ordinary
+screen. New local resources do not require a catalog; use `catalogId` only when
+a nested `{ "ref": "…" }` deliberately reuses an existing catalog resource.
+
+## Contents
+
+- [Author variables](#author-variables)
+- [Bind and verify](#bind-and-verify)
+- [Update and remove](#update-and-remove)
+
+## Author variables
+
+Copy this complete recipe and change its design facts. Collection and variable
+authoring keys persist file-wide so later calls can recover the same resources;
+they are not Figma names or IDs. Before the first write, choose one
+collision-resistant prefix for this independent system and reuse it across
+calls. A generic product prefix may already belong to another system in the
+file; when intentionally updating one, recover its exact keys instead. Mode
+keys are scoped to their collection.
+
+```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. A variable needs
+`name`, `type`, and a value for every mode. Types are `BOOLEAN`, `COLOR`,
+`FLOAT`, or `STRING`. Values may alias another variable with
+`{ "variable": { "variableKey": "…" } }`.
+
+Variable scopes use only these exact values:
+
+- 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 effects and strokes: `STROKE_FLOAT`, `EFFECT_FLOAT`;
+- typography: `FONT_FAMILY`, `FONT_STYLE`, `FONT_WEIGHT`, `FONT_SIZE`, `LINE_HEIGHT`,
+ `LETTER_SPACING`, `PARAGRAPH_SPACING`, `PARAGRAPH_INDENT`.
+
+Use `STROKE_COLOR` for a stroke color; `ALL_STROKES` is not a valid scope.
+`ALL_SCOPES` cannot be combined with another scope. `ALL_FILLS` cannot be
+combined with `FRAME_FILL`, `SHAPE_FILL`, or `TEXT_FILL`; it may coexist with a
+non-fill color scope such as `STROKE_COLOR`.
+
+## Bind and verify
+
+`native[key].variables` binds variables by their file-wide authoring key. Use the exact supported
+field name, such as `fill`, `stroke`, `gap`, `paddingTop`, `width`, `visible`,
+`fontSize`, or `characters`. Keep the matching literal class when Figma needs
+an initial paint or numeric fallback.
+
+When a design system is requested, authoring the definition is only half of the
+contract. Bind each variable to the representative component or screen fields
+that express its semantic role. Prefer `GAP` variables for recurring gaps and
+padding, `WIDTH_HEIGHT` for repeated semantic control or icon sizes, and
+`CORNER_RADIUS` for repeated radius roles. Do not turn viewport dimensions,
+one-off media crops, content-derived geometry, or isolated optical corrections
+into global tokens merely because their numbers repeat.
+
+A representative binding proves that the variable is usable, but does not
+finish an intended shared role by itself. Once the role is chosen, bind the
+concrete consumers meant to change with it; leave a peer literal only when its
+similar value is incidental or the peer intentionally owns a different role.
+
+`apply_canvas` warns when a variable created by that call has no reference in
+the same desired result. Treat `unbound-created-variable` as unfinished
+design-system work: bind the variable to a real consumer or remove it. A staged
+definition may temporarily warn, but the final delivered composition must close
+the warning and demonstrate the native binding; an equal literal is not enough.
+
+It also reports `variable-fallback-mismatch` when a literal property bound to a
+variable authored in the same call matches none of that variable's direct mode
+values, including values reached through same-call aliases. Align the literal
+fallback with a real mode or bind the variable that actually owns the value;
+otherwise the native binding silently changes the declared markup result.
+
+## Update and remove
+
+Omitted fields preserve managed resource state. A top-level `null` removes a
+managed variable, mode, or collection only when the user explicitly requires
+absence and every live consumer is cleared or removed in the same result.
+Never mutate remote resources, invent a parent collection or library key, or
+create a broad token system for a one-off screen. Extended collections must
+inherit from a real local or catalog collection and remain subject to 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..dfce4d6f
--- /dev/null
+++ b/agent-plugins/tempad-dev/skills/figma-canvas-authoring/references/visual-assets.md
@@ -0,0 +1,185 @@
+# Deliver visual assets in Figma
+
+Use this reference when the result needs icons, an exact typeface decision,
+images, illustrations, diagrams, or vector artwork. It governs asset role,
+source integrity, native editability, and an importable form; it does not define
+the product need or the final visual choice. After choosing the asset, use the
+routed native reference for exact font, paint, media, or SVG application
+mechanics.
+
+Start with the composition, not an assumed asset slot or a comparison of
+available tools. Typography, layout, color, negative space, or existing media
+may already fulfill the brief. Add a distinct visual only when it performs a
+job established by the brief or applicable evidence, such as depicting
+content, signaling an action, explaining a relationship, establishing identity,
+or contributing an intentional visual language. These are recognition cues,
+not a taxonomy to complete. If no distinct job exists, do not add an asset to
+make the result feel more designed.
+
+Depiction is a visual job, not a medium. Choose photographic or raster imagery,
+sourced vector artwork, an authored vector illustration or diagram, or another
+medium only after the brief, applicable visual evidence, or an identified
+low-consequence assumption supports it. When the established medium is
+photographic or raster imagery, fulfill it with a sourced, generated, supplied,
+or current-file asset; do not assemble it from Figma primitives or newly
+invented SVG. Use agent-authored vector work only when the user or applicable
+visual evidence independently establishes vector illustration, diagram,
+pattern, or decorative geometry as the medium. Never reclassify imagery as one
+of those media because drawing it is easier. Implementation convenience does
+not establish the intended medium.
+
+Preserve the semantics that earn native editability. Build an authored diagram
+whose labels, shapes, or relationships are expected to change as native Figma
+structure. Import one opaque SVG only when exact vector artwork is itself the
+asset; an SVG wrapper with Vector descendants does not preserve an editable
+diagram model.
+
+When a visual's function depends on exact encoded geometry, preserve real
+decodable content in a Canvas-accepted asset form; never imitate it with
+decorative primitives or invented vectors.
+
+For material assets, preserve enough evidence for the intended use:
+
+- identity and content fidelity;
+- provenance and applicable usage rights;
+- sufficient source quality;
+- a delivery form accepted by Canvas.
+
+Do not silently change an asset's subject, style, or medium because another
+route is easier to import. If a required source cannot be delivered faithfully,
+report the limitation instead of disguising a substitute as intent.
+
+A crop, mask, overlay, or retouch may support the composition only while it
+preserves what the asset depicts. Do not conceal distinctive branding or
+features to make one subject represent another; choose a neutral, matching, or
+generated source instead.
+
+## Contents
+
+- [Icons](#icons)
+- [Typefaces](#typefaces)
+- [Images and illustrations](#images-and-illustrations)
+
+## Icons
+
+Use an applicable current-file, catalog, project, or user-supplied source when
+permitted. Otherwise select a trustworthy source that satisfies the established
+brief and record any license constraint. Import its exact SVG geometry; do not
+redraw a known icon from memory or replace an established icon-asset role with a
+text character, including a Unicode symbol or emoji.
+Treat a text character or primitive shape or cluster as an icon role when its
+form communicates an affordance, object, or semantic category; use the selected
+icon asset or component rather than TEXT or newly assembled primitives. Simple
+geometry remains valid when the mark itself is intended, such as a status or
+data mark, divider, or decorative or brand shape, not when it substitutes for
+an icon.
+Before declaring a fetched SVG, verify that the response is SVG content rather
+than a redirect, error document, or missing-asset message; a plausible URL or
+filename does not establish a valid asset.
+
+This complete Direct call demonstrates SVG import mechanics. Its content,
+dimensions, and color are syntax examples, not design defaults:
+
+```json
+{
+ "mode": "create",
+ "markup": "",
+ "assets": {
+ "search": {
+ "type": "SVG",
+ "svg": ""
+ }
+ },
+ "native": {
+ "search-icon": {
+ "figma": { "svg": { "assetKey": "search", "color": "#334155" } }
+ }
+ }
+}
+```
+
+The matching `div` is childless and supplies wrapper geometry. `color` resolves
+SVG `currentColor`; omit it for complete explicit-color SVGs. Figma may import
+one SVG as a Frame with Vector descendants. Treat that editable subtree as one
+opaque asset; do not flatten or reconcile it.
+
+Use a Hub `{ "type": "SVG", "assetHash": "" }`
+declaration for larger exact SVG content. If no faithful source is available,
+omit a nonessential icon or report a required gap rather than inventing one.
+
+## Typefaces
+
+Derive typeface choice from the established brief and evidence. Reuse an
+applicable catalog Text style, typography variable, project font, or supplied
+reference when available. Confirm that every exact Figma family and style is
+available; never guess style names.
+
+Express exact whole-node fonts through `figma.text.fontName` and use ranges only
+for intentional mixed typography. Load the exact whole-node font reference
+routed by `SKILL.md` when applying one. A generic `font-sans` class does not
+prove delivery of a named family: bind the actual style, variable, or exact
+native font, or leave the brief at the level the evidence supports.
+
+## Images and illustrations
+
+Treat an existing asset, licensed remote source, generation, or purpose-built
+vector work as acquisition routes after the visual role, subject, and medium
+are established. Search and image-generation tools are not competing defaults,
+and the skill assigns no global priority to them. Use situated judgment to take
+the nearest route that satisfies the relevant content, fidelity, rights,
+quality, and import requirements; do not perform an option-ranking ceremony
+when the evidence already makes one route suitable. Before layout depends on
+the asset, confirm that the chosen result is deliverable through Canvas.
+
+Treat the medium as part of the material decision. An established photographic
+or raster medium does not fall back to agent-authored primitives or SVG when its
+intended asset is missing; source or generate the image, use an explicit neutral
+placeholder when that does not change the outcome, or disclose the gap. Exact
+supplied or sourced vector art remains valid when vector is the asset's actual
+medium. When several assets represent distinct content, verify that the
+selected route preserves the distinctions the composition depends on.
+
+Keep only enough working evidence to recover a material choice or verify a
+distinction the composition depends on. A short rationale may combine the
+visual job, governing evidence, medium, source, and import treatment; this is
+not a mandatory field sequence or a per-asset reporting ceremony.
+
+Require an exact asset page, creator record, license record, or attribution only
+when the source terms, user or project policy, or requested handoff makes that
+detail material. Do not turn ordinary draft imagery into a per-asset citation
+exercise. Assets that share one recoverable route and the same applicable terms
+may share a trace when individual identity is not material.
+
+If no evidence or explicit brief decision establishes a medium, judge whether
+the choice would materially change the result. Resolve a material choice from
+the nearest relevant visual evidence or ask the user; make a low-consequence
+choice as an identified assumption.
+
+When generation is the established route, resolve how its output will reach a
+Canvas-accepted form before invoking the image-generation skill or tool. A local
+path alone is not importable by Canvas. If the current environment has no bridge,
+choose another brief-compatible image source before generating, or disclose the
+gap when generation itself is required. Do not generate first and then silently
+switch to a different medium or generic source because the result cannot be
+uploaded.
+
+Apply a public image as an IMAGE paint using `imageUrl`; an existing current-file
+`imageHash` is also valid. For content already in the local Hub, declare
+`{ "type": "IMAGE", "assetHash": "" }` and use its
+alias as the paint's `assetKey`. Inline bytes and local-only paths are not
+supported. Remote URLs must resolve directly to an accessible image rather than
+to a webpage or thumbnail.
+
+When the delivered medium must remain a real image, verify the live image node
+with `get_structure` and `options.native: true`. Its `native.imageFills` must
+contain the expected non-null Figma image hash; the supplied `imageUrl`, a
+successful apply summary, or a screenshot that merely resembles the source is
+not native-state read-back.
+
+The main agent owns placement and crop and verifies the delivered asset in the
+final composition. Keep identity and crop stable across repeated usages unless
+the brief establishes a real variation. If required media remains unavailable,
+report the gap; omit optional media or use a neutral slot only when doing so does
+not change the requested outcome. A neutral slot is an explicit fallback, not
+representative content or proof that a reusable content contract supports real
+variation.
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