OpenPencil CLI 设计审计指南：用 analyze 命令分析颜色、排版、间距与重复结构

前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载openpencil analyze是 OpenPencil 命令行工具中面向设计系统审计的一组子命令它读取整个.fig文档从终端直接回答“这个文件里用了哪些颜色、哪些字体组合、间距是否符合栅格、哪些结构可以抽成组件”等问题。读完本文你将掌握全部analyze子命令的用法、参数语义与输出解读并能通过--json把审计结果接入 CI 或自定义脚本形成可持续的设计规范校验流程。analyze 命令家族一次审计四类维度analyze是 CLI 中的一个命令组由packages/cli/src/commands/analyze/index.ts定义通过 citty 框架注册了五个子命令子命令用途对应实现文件colors统计填充、描边颜色用量识别近似色packages/cli/src/commands/analyze/colors.tstypography统计字体族、字号、字重组合及其频率packages/cli/src/commands/analyze/typography.tsspacing审计自动布局 frame 的间距与内边距packages/cli/src/commands/analyze/spacing.tsclusters发现可抽取为组件的重复节点结构packages/cli/src/commands/analyze/clusters.tsoverlaps检测视觉重叠与布局溢出CLI 层新增维度packages/cli/src/commands/analyze/overlaps.ts所有子命令共用同一种调用形态openpencil analyze subcommand file.fig [选项]file是位置参数指向.fig文件路径省略该参数时命令会改为连接正在运行中的 OpenPencil 应用详见后文“与运行中的应用协同”一节。颜色分析analyze colorsanalyze colors会遍历文档中所有节点的填充、描边与效果颜色按使用次数排序并输出可视化直方图openpencil analyze colors design.fig输出示例来自官方文档#1d1b20 ██████████████████████████████ 17155× #49454f ██████████████████████████████ 9814× #ffffff ██████████████████████████████ 8620× #6750a4 ██████████████████████████████ 3967×常用参数参数默认值说明--limit n30直方图最多展示的颜色数量--threshold n15颜色聚类阈值取值范围 0–50用于把“几乎相同”的颜色归为一组--similar关开启后额外输出“近似色簇”提示哪些颜色可以考虑合并--json关以 JSON 格式输出便于机器处理阅读输出直方图与汇总直方图之外命令还会输出一段汇总将颜色区分为“来自变量”与“硬编码”两类并给出唯一颜色总数unique colors: 128 from variables: 96 hardcoded: 32这是审计设计系统一致性最有价值的信息硬编码颜色占比越高说明设计 token 的落地越不彻底。开启--similar后还会列出可合并的近似色簇例如Similar colors (consider merging) 1. #1d1b20, #1e1b22 — suggest: #1d1b20 (total 18211×)底层实现颜色如何被收集与聚类analyze colors本身是 CLI 壳层真正的统计逻辑在 RPC 层packages/core/src/rpc/analyze-commands.ts的analyze_colors命令中实现collectColors遍历场景图所有节点CANVAS除外收集可见的 SOLID 填充、可见描边与可见效果的颜色同时检查boundVariables中与 fill/stroke/color 相关的字段把颜色映射到其绑定的变量名见 packages/core/src/rpc/analyze-commands.ts 中collectColors函数。clusterColors按使用次数降序迭代用colorDistance计算颜色距离距离不超过threshold的颜色被归入同一近似色簇并选出使用量最大的颜色作为suggestedHex建议合并目标。排版分析analyze typographyanalyze typography列出文档中每一种“字体族 × 字号 × 字重”组合及其使用次数用于发现只出现一两次的孤立文本样式openpencil analyze typography design.fig输出示例Typography styles Inter 16px Regular / 24 ██████████████████ 420× Inter 14px Medium / 20 ██████████████ 310× Roboto 12px Regular ████████ 88× ...每行的“/ 24”代表 lineHeight行高lineHeight 为auto时该段会被省略见 packages/cli/src/commands/analyze/typography.ts 中s.lineHeight ! auto的判断。分组查看--group-by默认输出是“样式全集”也可以按单一维度聚合# 按字体族聚合 openpencil analyze typography design.fig --group-by family # 按字号聚合 openpencil analyze typography design.fig --group-by size # 按字重聚合 openpencil analyze typography design.fig --group-by weightfamily输出字体族直方图按使用次数降序size输出字号直方图如16px按字号升序weight输出字重直方图并附带人类可读的名称如400 Regular、700 Bold字重名称映射见weightName函数100为 Thin700为 Bold800为 Black。输出末尾的汇总行会给出unique styles唯一样式数与text nodes文本节点总数。若文档没有任何文本节点命令会输出No text nodes found.。审计思路频率极低如 1–2 次的孤立样式往往是应该并入设计系统字体规范的“漏网之鱼”。间距分析analyze spacinganalyze spacing专门审计自动布局auto-layoutframe的 gap子项间距与 padding内边距取值并对照一个基准栅格标记“出格”的值openpencil analyze spacing design.fig输出分两段直方图gap 与 padding 各自统计凡是不能被栅格整除的值都会带⚠标记Gap values 8px ████████████████████████████ 152× 16px ████████████████████████ 98× 24px ██████████ 41× 13px █ 3× ⚠下方会汇总所有 off-grid偏离栅格的取值⚠ Off-grid values (not ÷8px) Gaps: 13px Paddings: 6px这正是文档中“在 8/16/24 的间距体系里出现一个孤立的 13px”场景——一眼即可定位到需要修正的节点。常用参数参数默认值说明--grid n8基准栅格尺寸像素用于判断哪些值偏离体系直方图默认各展示前 15 个值。若文档中没有带间距的自动布局节点输出No auto-layout nodes with spacing found.。重复结构分析analyze clustersanalyze clusters扫描文档中相似的节点层级找出那些“几乎一样、可以抽成组件”的重复结构并输出匹配度、尺寸与结构签名openpencil analyze clusters design.fig输出示例来自官方文档3771× frame container (100% match) size: 40×40, structure: Frame [Frame] 2982× instance Checkboxes (100% match) size: 48×48, structure: Instance [Frame]第一行N× 类型 名称 (置信度% match)该结构出现的次数与平均匹配置信度置信度由calcClusterConfidence计算见 packages/cli/src/commands/analyze/clusters.ts 的导入size各实例的平均宽高若实例间尺寸波动超过 ±4px会显示为40×40 (±5px)形式structure由结构签名格式化的层级描述如Frame [Frame, Text×2]表示“一个 Frame 内含 1 个 Frame 和 2 个 Text”examples最多列出 3 个示例节点的 ID方便回到编辑器中定位。末尾汇总输出 clusters 数量、文档总节点数与被聚类节点数clusters: 12 total nodes: 12345 clustered: 6800常用参数参数默认值说明--limit n20最多展示的聚类数量--min-size n30参与聚类的最小节点尺寸像素--min-count n2形成聚类所需的最少重复次数调整--min-count是控制“召回率”的关键设为3可以只关注真正高频复用的结构调大--min-size则可以忽略小图标等细碎节点。重叠与溢出检测analyze overlaps作为analyze家族在 CLI 层的扩展overlaps子命令检测节点间的视觉重叠与父容器溢出问题完整参数见 packages/cli/src/commands/analyze/overlaps.tsopenpencil analyze overlaps design.fig其关键参数如下参数默认值说明--scope sall检查哪些节点对all、same-parent、cross-parent、top-level、inside-parent--category c无逗号分隔的类别过滤sibling-overlap、parent-overflow、overlay--severity sinfo最低严重级别critical、major、minor、info--min-area n无重叠面积下限平方像素--min-ratio r无相对较小节点的重叠比例下限0.0–1.0--include-hidden/--include-locked/--include-absolute关是否把隐藏、锁定或绝对定位节点纳入分析--page name/--page-id id无限定某个页面--type t无逗号分隔的节点类型过滤如FRAME,TEXT--limit n100最多展示的发现条数每条发现包含严重级别、类别、重叠面积与比例、两个参与节点类型、名称、ID以及修复建议。输出末尾按类别与严重级别分别汇总计数。注意该命令会在 CLI 层对参数做严格校验如--min-ratio必须落在 0.0–1.0、--limit必须是正整数非法取值会直接报错退出。JSON 输出接入 CI 与自定义规则所有analyze子命令都支持--json输出结构化结果openpencil analyze colors design.fig --json输出是带缩进的 JSON内部经JSON.stringify(data, null, 2)生成可直接用jq做管道处理例如只取硬编码颜色openpencil analyze colors design.fig --json \ | jq -r .colors[] | select(.variableName null) | .hex在 CI 中作为设计 token 预算检查例如“硬编码颜色数 阈值”即失败供自定义脚本把每次审计结果归档、对比版本间差异。以 JSON 模式运行与普通模式共用同一套 RPC 数据只是省略了终端直方图渲染对应各命令中if (args.json)提前 return 的分支。与运行中的应用协同省略 file 参数file参数描述为 “.fig file path (omit to connect to running app)”即省略文件路径时命令会连接正在运行的 OpenPencil 应用。此时可以通过两个附加参数定位目标参数说明--document-id id目标文档/标签页 ID--page-id id目标页面 ID这两个选项由 packages/cli/src/app-target.ts 中的appTargetOptions统一提供会被转换成 RPC 参数document_id/page_id。也就是说analyze 既可以在命令行离线审计.fig文件也可以直接审计当前编辑器里打开的文档。只读审计分析与变换的边界需要特别强调的是所有analyze命令都是只读的——它们只统计和报告绝不修改文件本身。这一点既体现在 CLI 层的loadRPCData调用方式上也体现在 RPC 层analyze_*命令仅基于场景图执行计算见 packages/core/src/rpc/analyze-commands.ts的设计上。当你完成审计、确认需要实际修改文档时应转向eval脚本命令中文用户可参考同目录的 scripting.md它支持用脚本对文档执行变换。审计analyze与变换eval的分工让“发现问题 → 制定规则 → 批量修复”的流程可以在同一套 CLI 中闭环且每一步都可回放、可验证。小结openpencil analyze把设计系统的体检工作搬进了终端colors暴露调色板用量与近似色typography揪出孤立文本样式spacing对照栅格标记出格间距clusters定位可组件化的重复结构overlaps捕捉布局重叠与溢出。配合统一的--json输出、可省略的文件参数与只读保证它既可以作为设计师日常自查工具也能无缝嵌入 CI成为团队设计规范落地的基础设施。赞分享前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载相关推荐OpenPencil CLI analyze 命令实战从终端审计设计系统中的颜色、排版、间距与重复结构OpenPencil CLI analyze 命令实战从终端审计设计系统中的颜色、排版、间距与重复结构 analyze 系列子命令是 OpenPencil C前端桌面应用AI 应用MCP 服务用 OpenPencil CLI 审计设计系统analyze 命令解析与实战用 OpenPencil CLI 审计设计系统analyze 命令解析与实战 导读 OpenPencil 是一个开源的 AI native 设计编辑器Fig前端桌面应用AI 应用MCP 服务OpenPencil CLI 设计审计实战用 analyze 命令从 .fig 文件提取色彩、排版与组件模式OpenPencil CLI 设计审计实战用 analyze 命令从 .fig 文件提取色彩、排版与组件模式 openpencil analyze 系列命令让前端桌面应用AI 应用MCP 服务上一篇如何快速上手Bongo Cat5个步骤将普通键盘变成音乐创作神器下一篇Docker容器的CPU调度baseimage-docker的CPU份额配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考