audit-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Audit Design System

设计系统审核

Review a Figma node for evidence that the design is not properly integrated with the design system.

This skill is read-only. When the user wants a write action afterward, downstream skills should use

use_figma

through a

figma-use

-style helper when the host environment requires one.

检查Figma节点，寻找设计未与设计系统正确集成的迹象。

该Skill为只读模式。如果用户后续需要执行写入操作，当宿主环境有要求时，下游Skill应通过

figma-use

风格的工具调用

use_figma

。

Output Format Selection

输出格式选择

Explicit user request wins:
- If the user asks for
```
--json
```
  or JSON, output raw JSON (no markdown fences, no prose).
- If the user asks for
```
--markdown
```
  , markdown, or a specific human-readable format, output the human-readable markdown report.
Codex Desktop app: Output raw JSON by default.
Codex CLI and other chat-style environments: Output the human-readable markdown report by default.
Machine-consumed review surfaces: Output raw JSON by default.
Ambiguous environment: If the environment is unclear, output markdown by default.

明确的用户请求优先:
- 如果用户要求
```
--json
```
  或JSON格式，输出原始JSON（无markdown围栏，无额外说明文字）。
- 如果用户要求
```
--markdown
```
  、markdown格式或特定的人类可读格式，输出人类可读的markdown报告。
Codex桌面应用: 默认输出原始JSON。
Codex CLI及其他聊天式环境: 默认输出人类可读的markdown报告。
机器消费型审核界面: 默认输出原始JSON。
环境不明确时: 如果环境无法确定，默认输出markdown格式。

Workflow

工作流程

Parse the Figma input. Accept a full Figma URL, or a
```
fileKey
```
and
```
nodeId
```
. Normalize node IDs from
```
72-293
```
to
```
72:293
```
when needed.
Pull the minimum required evidence with Figma MCP read tools. Call
```
get_design_context
```
for the exact node under review. Call
```
get_screenshot
```
for visual confirmation. Call
```
get_variable_defs
```
to see which variables are actually bound. Call
```
get_code_connect_map
```
when relevant. Call
```
get_metadata
```
when the reviewed node is large, repeated, or board-like and you need to map nested instances before drilling in. Call
```
search_design_system
```
when you have identified a likely non-systemized primitive and there is a realistic chance of suggesting a concrete replacement from the audited design system.
Review for systemization failures, not visual taste. Look for places where the design should probably inherit from the design system but is locally constructed instead. Base every finding on structure visible in Figma: instances, duplicated frames, raw values, variant drift, or missing token bindings. Prefer omissions over weak findings.
When the evidence is strong enough, suggest a replacement candidate. After identifying a likely custom primitive, use
```
search_design_system
```
to find the closest matching component family from the audited design system. Include a candidate only when the match is credible from structure and naming, not just screenshot similarity. If search results are noisy or ambiguous, omit the candidate instead of guessing.
Present findings in the appropriate format based on the environment. Use JSON for Codex Desktop and machine-consumed review surfaces, markdown for Claude Code CLI and other chat-style environments (see Output Format Selection above).
When the user wants a fix, route to the right downstream skill. Prefer fix-design-system-finding when one specific offending node should be repaired. Prefer apply-design-system when the user wants a broader screen-wide pass, multiple sections need coordinated remediation, or the review is being used to define scope before writing.

解析Figma输入。接受完整的Figma URL，或
```
fileKey
```
和
```
nodeId
```
。必要时将节点ID从
```
72-293
```
标准化为
```
72:293
```
。
使用Figma MCP读取工具获取最少必要的证据。调用
```
get_design_context
```
获取待审核节点的精确上下文。调用
```
get_screenshot
```
进行视觉确认。调用
```
get_variable_defs
```
查看实际绑定的变量。相关时调用
```
get_code_connect_map
```
。当待审核节点较大、重复或类似看板结构，且需要在深入检查前映射嵌套实例时，调用
```
get_metadata
```
。当识别到可能的非系统化基础元素，且有合理机会从已审核的设计系统中建议具体替代方案时，调用
```
search_design_system
```
。
审核系统化失败情况，而非视觉偏好。寻找设计本应继承自设计系统但却通过本地构建实现的地方。每个发现都基于Figma中可见的结构：实例、重复框架、原始值、变体偏差或缺失的token绑定。优先忽略证据不足的发现，只保留明确的遗漏问题。
当证据足够充分时，建议替代候选方案。在识别到可能的自定义基础元素后，使用
```
search_design_system
```
从已审核的设计系统中找到最匹配的组件系列。仅当匹配在结构和命名上可信时才纳入候选方案，而非仅基于截图相似性。如果搜索结果杂乱或模糊，应省略候选方案而非猜测。
根据环境选择合适的格式呈现发现结果。 Codex桌面应用和机器消费型审核界面使用JSON格式，Claude Code CLI及其他聊天式环境使用markdown格式（见上方输出格式选择）。
当用户需要修复时，路由至正确的下游Skill。当需要修复单个特定违规节点时，优先使用fix-design-system-finding。当用户需要对整个界面进行全面检查、多个部分需要协同修复，或审核用于在执行写入操作前定义范围时，优先使用apply-design-system。

What To Flag

需要标记的问题

Shared UI primitives recreated as ad-hoc frames instead of component instances. Common targets: buttons, icon buttons, cards, alerts, pills, chips, avatars, stat tiles, tab bars, nav bars, FABs, list rows.
Repeated sibling structures that should clearly collapse into one reusable primitive. Example: three nearly identical stat tiles with different content.
Hard-coded visual values where the rest of the design system uses variables. Common targets: fills, strokes, text colors, radius, spacing, typography, shadows. Only flag this when the evidence is concrete, such as a raw hex value or bespoke geometry sitting beside tokenized peers.
Global navigation or other high-leverage patterns built from custom frames instead of system components. Flag these aggressively because drift there scales across many screens.
Variant drift inside a nominal component. Example: a local edit button with unusual size, stroke width, or radius that does not match the expected icon-button primitive.

共享UI基础元素被重新创建为临时框架而非组件实例。常见目标：buttons、icon buttons、cards、alerts、pills、chips、avatars、stat tiles、tab bars、nav bars、FABs、list rows。
重复的同级结构明显应合并为一个可复用的基础元素。示例：三个内容不同但几乎完全相同的stat tiles。
设计系统其余部分使用变量，但此处使用硬编码视觉值。常见目标：填充色、描边、文字颜色、圆角、间距、排版、阴影。仅当有确凿证据时才标记此类问题，例如在已使用token的元素旁出现原始十六进制值或定制几何形状。
全局导航或其他高影响力模式通过自定义框架构建而非使用系统组件。应主动标记此类问题，因为此处的偏差会在多个界面中扩散。
名义组件内的变体偏差。示例：本地编辑按钮的尺寸、描边宽度或圆角不符合预期的icon-button基础元素。

What Not To Flag

无需标记的内容

Purely aesthetic preferences.
Copywriting or product decisions.
Layout choices that can reasonably remain screen-specific.
One-off compositions when the underlying primitives are already componentized and tokenized.
Claims that require undocumented assumptions about a design library.

纯粹的审美偏好。
文案或产品决策。
可合理保留为界面特定的布局选择。
底层基础元素已组件化和token化的一次性组合。
需要对设计库进行 undocumented 假设的断言。

Evidence Standard

证据标准

Every finding must answer both questions:

What concrete Figma evidence shows this is not systemized correctly?
Why does that matter for propagation, consistency, theming, or maintenance?

Good evidence includes:

a node is a plain frame when it should be an instance
several siblings duplicate the same structure
raw color or geometry values appear where variables or standard primitives should apply
a global pattern is custom-built

Weak evidence includes:

"this looks custom"
"I would normally make this a component"
any statement based only on screenshot aesthetics without structural support

每个发现必须回答以下两个问题：

哪些具体的Figma证据表明该元素未被正确系统化？
这对传播性、一致性、主题化或维护有何影响？

合格的证据包括：

节点本应是实例却为普通框架
多个同级节点重复相同结构
在应使用变量或标准基础元素的地方出现原始颜色或几何值
全局模式为自定义构建

薄弱的证据包括：

“这看起来是自定义的”
“我通常会把这个做成组件”
任何仅基于截图美学而非结构支持的陈述

Replacement Suggestion Rule

替代建议规则

When a finding is about a missing shared primitive, try to attach one likely replacement suggestion.

Use

search_design_system

after you already know what category of thing is missing, for example:

custom avatar cluster
bespoke stat tile
local alert card
hand-built navigation item

Only suggest a replacement when:

the node's role is clear
the search result belongs to the relevant library or audited file context
the candidate is structurally plausible for the finding

Good suggestion language:

This custom avatar frame could likely be replaced with Avatar from library X.

These repeated stat tiles appear to map to Metric item from library X.

Do not overstate:

do not claim the suggested component is definitely correct unless the evidence is explicit
do not force a replacement candidate into every finding
do not recommend a component from an unrelated library just because search returned it first

当发现涉及缺失共享基础元素时，尝试附上一个可能的替代建议。

在明确缺失元素的类别后使用

search_design_system

，例如：

自定义avatar集群
定制stat tile
本地alert card
手动构建的导航项

仅在以下情况下建议替代方案：

节点的作用明确
搜索结果属于相关库或已审核文件上下文
候选方案在结构上与发现的问题匹配

合格的建议表述：

This custom avatar frame could likely be replaced with Avatar from library X.

These repeated stat tiles appear to map to Metric item from library X.

不要过度表述：

除非证据明确，否则不要声称建议的组件绝对正确
不要强行给每个发现添加替代候选方案
不要仅因为搜索结果排在首位就推荐来自无关库的组件

Output Format

输出格式

JSON Output

JSON输出

When the selected output format is JSON, return this exact JSON shape with no markdown fences and no extra prose:

json

{
  "findings": [
    {
      "title": "<= 80 chars, imperative>",
      "body": "<valid Markdown explaining why this is a problem>",
      "confidence_score": 0.0,
      "priority": 0,
      "code_location": {
        "absolute_file_path": "/figma/<fileKey>/nodes/<nodeId>",
        "line_range": {
          "start": 1,
          "end": 1
        }
      }
    }
  ],
  "overall_correctness": "patch is correct" | "patch is incorrect",
  "overall_explanation": "<1-3 sentence summary>",
  "overall_confidence_score": 0.0
}

Schema notes:

Use
```
overall_correctness: "patch is incorrect"
```
whenever you found one or more design-system integration issues.
Use
```
overall_correctness: "patch is correct"
```
only when there are no findings.

For each finding, set

code_location.absolute_file_path

/figma/<fileKey>/nodes/<nodeId>

using the most specific offending node.

Always set
```
line_range.start
```
and
```
line_range.end
```
to
```
1
```
.

当选择JSON输出格式时，返回以下精确的JSON结构，无markdown围栏和额外文字：

json

{
  "findings": [
    {
      "title": "<= 80 chars, imperative>",
      "body": "<valid Markdown explaining why this is a problem>",
      "confidence_score": 0.0,
      "priority": 0,
      "code_location": {
        "absolute_file_path": "/figma/<fileKey>/nodes/<nodeId>",
        "line_range": {
          "start": 1,
          "end": 1
        }
      }
    }
  ],
  "overall_correctness": "patch is correct" | "patch is incorrect",
  "overall_explanation": "<1-3 sentence summary>",
  "overall_confidence_score": 0.0
}

架构说明：

只要发现一个或多个设计系统集成问题，就设置
```
overall_correctness: "patch is incorrect"
```
。
仅当没有发现问题时，设置
```
overall_correctness: "patch is correct"
```
。
对于每个发现，将
```
code_location.absolute_file_path
```
设置为
```
/figma/<fileKey>/nodes/<nodeId>
```
，使用最具体的违规节点。
始终将
```
line_range.start
```
和
```
line_range.end
```
设置为
```
1
```
。

Human-Readable Markdown Report

人类可读Markdown报告

When the selected output format is markdown, present a formatted markdown report with:

Header section:
- File name and node being reviewed
- Overall verdict: ✅ Passes / ⚠️ Needs Work / ❌ Significant Issues
- Confidence percentage
Summary: 2-3 sentences explaining the overall state
Findings table: Quick overview with priority indicators
- 🔴 Critical (priority 3): severe library-level or navigation-level issues
- 🟠 High (priority 2): important reusable primitive or tokenization issues
- 🟡 Medium (priority 1): moderate system drift
- ⚪ Low (priority 0): nits or low-impact consistency issues
Details section: Expand each finding with:
- What's wrong (concrete evidence from Figma structure)
- Why it matters (maintenance, consistency, theming impact)
- Likely replacement, when supported by
```
search_design_system
```
- Affected node IDs for reference
Recommendations: Prioritized action items

当选择markdown输出格式时，呈现格式化的markdown报告，包含：

头部区域：
- 待审核的文件名和节点
- 整体结论：✅ 通过 / ⚠️ 需要优化 / ❌ 存在严重问题
- 置信度百分比
摘要： 2-3句话解释整体状态
发现结果表格： 带有优先级标识的快速概览
- 🔴 严重（优先级3）：严重的库级或导航级问题
- 🟠 高优先级（优先级2）：重要的可复用基础元素或token化问题
- 🟡 中等优先级（优先级1）：中度系统偏差
- ⚪ 低优先级（优先级0）：细微问题或低影响一致性问题
详情区域： 展开每个发现，包含：
- 问题所在（来自Figma结构的具体证据）
- 影响原因（对维护、一致性、主题化的影响）
- 可能的替代方案（当
```
search_design_system
```
  支持时）
- 供参考的受影响节点ID
建议： 按优先级排序的行动项

Output Rules

输出规则

Keep findings focused on the highest-signal issues. Usually 0-6 findings.
Keep titles imperative and under 80 characters.
Always anchor each finding to a specific node ID so users can locate it in Figma.
For JSON output, do not invent filesystem paths. Use
```
/figma/<fileKey>/nodes/<nodeId>
```
exactly.
When a replacement suggestion is credible, include it in the finding body.

聚焦于最高信号的问题，通常为0-6个发现。
标题使用祈使语气且不超过80个字符。
每个发现都必须锚定到特定的节点ID，以便用户在Figma中定位。
JSON输出时，不要虚构文件系统路径，严格使用
```
/figma/<fileKey>/nodes/<nodeId>
```
格式。
当替代建议可信时，将其包含在发现内容中。

Review Heuristics

审核启发式规则

Use

priority

like this:

```
0
```
: nit or low-impact consistency issue
```
1
```
: moderate system drift
```
2
```
: important reusable primitive or tokenization issue
```
3
```
: severe library-level or navigation-level issue likely to propagate widely

Use

confidence_score

like this:

```
0.9-1.0
```
: direct structural evidence
```
0.7-0.89
```
: strong inference from repetition and nearby token usage
```
0.5-0.69
```
: plausible but incomplete evidence; prefer omitting instead

按以下方式使用

priority

：

```
0
```
：细微问题或低影响一致性问题
```
1
```
：中度系统偏差
```
2
```
：重要的可复用基础元素或token化问题
```
3
```
：严重的库级或导航级问题，可能广泛传播

按以下方式使用

confidence_score

：

```
0.9-1.0
```
：直接结构证据
```
0.7-0.89
```
：从重复情况和附近token使用得出的强推论
```
0.5-0.69
```
：合理但不完整的证据；优先忽略而非标记

Board And Screen Scope

看板与界面范围

For a single screen:

inspect the root node
drill into repeated or high-leverage children
anchor findings to the most specific offending node

For a board or larger page:

use
```
get_metadata
```
first to identify candidate screens or repeated modules
review only the most relevant nodes instead of trying to audit everything
keep findings scoped and evidence-backed

对于单个界面：

检查根节点
深入检查重复或高影响力的子节点
将发现锚定到最具体的违规节点

对于看板或更大的页面：

先使用
```
get_metadata
```
识别候选界面或重复模块
仅审核最相关的节点，而非尝试审核所有内容
保持发现结果范围明确且有证据支持

Example Trigger Phrases

触发短语示例

"Review this Figma screen for design-system integration"
"Audit this board for missing component usage"
"Check whether this design uses tokens correctly"
"/audit-design-system https://figma.com/design/..."
"/audit-design-system --json https://figma.com/design/..." (for JSON output)

"Review this Figma screen for design-system integration"
"Audit this board for missing component usage"
"Check whether this design uses tokens correctly"
"/audit-design-system https://figma.com/design/..."
"/audit-design-system --json https://figma.com/design/..."（用于JSON输出）

Handoff Guidance

交接指引

Use this routing rule after the review:

one concrete finding with a narrow write scope: use fix-design-system-finding
several findings that collapse into a broader screen or section reconciliation pass: use apply-design-system

Do not force every review result through the single-finding fix skill. Some reviews are better used as scope discovery for a broader apply pass.

审核完成后使用以下路由规则：

单个具体发现且写入范围狭窄：使用fix-design-system-finding
多个发现需要对整个界面或部分进行协调修复：使用apply-design-system

不要强行将所有审核结果通过单发现修复Skill处理。有些审核更适合作为全面应用修复的范围发现环节。