CANON：为AI编码工具注入设计规范，提升前端代码质量与一致性

1. 项目概述：CANON——为AI编码工具注入设计规范

如果你和我一样，每天都要和Cursor、Claude Code、GitHub Copilot这些AI编码助手打交道，那你肯定也遇到过这样的场景：你让AI帮你写一个按钮组件，它生成的代码功能上没问题，但样式总透着一股“AI味儿”——间距不统一、颜色对比度不够、交互状态缺失，或者干脆不符合任何已知的设计系统。你不得不花大量时间手动调整，把AI的“草稿”打磨成能上线的产品级代码。这种反复的“生成-修正”循环，极大地消耗了开发效率。

CANON项目就是为了终结这种局面而生的。它不是一个传统意义上的UI组件库，而是一套面向AI的“设计规范语言”。简单来说，CANON将人类设计师和前端工程师积累的最佳实践（比如WCAG无障碍标准、Material Design 3、苹果人机界面指南等）转化成了52条机器可读的“技能”和89条“检测规则”。当你把这些技能“喂”给你的AI编码工具（目前支持包括Cursor、Claude Code、Copilot在内的15种主流工具），AI在生成代码时就会主动遵循这些规则，产出的代码从一开始就具备良好的设计一致性和可访问性。

它的核心价值在于将设计智能前置到了代码生成环节。我们不再需要事后用Lint工具去检查问题，而是让AI在创作时就直接“知道”什么是对的。这对于前端开发者、全栈工程师以及任何希望提升AI辅助编码产出质量的团队来说，都是一个能显著提升质效的利器。

1.1 核心需求解析：为什么我们需要AI设计规范？

在深入CANON之前，我们先要理解它要解决的根本问题。AI编码工具基于海量代码训练，它能学会语法和常见模式，但它缺乏对“好设计”的系统性认知和量化标准。这导致了几个典型痛点：

1. 不一致性：AI可能会为同一个项目生成风格迥异的组件，因为它没有“项目级设计系统”的概念。
2. 可访问性缺失：AI很少会主动考虑键盘导航、屏幕阅读器支持、颜色对比度等无障碍需求，因为这些规则在训练数据中并非总是显式体现。
3. “生成感”过强：产出的UI往往布局生硬、动效突兀，缺乏经过打磨的、人性化的交互细节。
4. 修正成本高昂：开发者需要具备足够的设计洞察力才能发现问题，并手动重写AI的代码，这违背了使用AI提升效率的初衷。

CANON的应对策略不是提供一个庞大的、需要接入的运行时库，而是采用了一种更轻量、更本质的“规则注入”方式。它把设计知识封装成一个个独立的“技能包”（Skill），直接植入到AI工具的上下文中。当AI在编写一个按钮时，相关的canon-buttons技能会提供具体的规则，例如：“按钮内边距应在垂直方向为12px，水平方向为24px”、“主要按钮与背景的颜色对比度至少应达到4.5:1”、“必须包含:hover、:focus、:active三种状态的样式定义”。AI基于这些明确的指令生成代码，自然就规避了上述问题。

2. 核心架构与设计哲学拆解

CANON不是一个黑盒魔法，它的强大源于其清晰、严谨的架构设计。理解这套架构，能帮助我们在使用中更好地发挥其威力，甚至在必要时进行定制扩展。

2.1 基于“技能”的模块化知识体系

CANON最核心的概念是“技能”。52个技能被分门别类地组织在7个大类中，这种分类方式本身就体现了一种完整的前端设计知识图谱：

• 基础类：包含typography（排版）、color（色彩）、spatial（间距系统）等。这是构建任何视觉语言的基石。例如，spatial技能会规定使用4px或8px作为基础间距单位，所有组件的margin、padding都应基于此单位的倍数。
• 组件类：针对具体UI元素，如buttons、modals、tables。这里的规则最为具体。以modals为例，规则可能包括：模态框必须有ESC键关闭支持、点击遮罩层应关闭、焦点必须被锁定在模态框内、标题应使用<h2>标签等。
• 主题与无障碍类：这是CANON区别于普通样式指南的深层价值所在。dark-mode技能不仅要求提供深色主题，还会规定如何平滑过渡、如何确保两种模式下的可读性。keyboard、screen-reader等技能则将WCAG标准转化为了可操作的代码级约束。
• 工程类：这部分超越了纯视觉设计，关注性能与最佳实践，如bundle-size（打包体积）、fonts-loading（字体加载策略）。这体现了现代前端开发中“设计”与“性能”不可分割的理念。

每个技能都不是模糊的建议，而是由多条可检测的规则构成。这些规则都有据可查，溯源至WCAG、Material Design等权威来源，并且所有阈值都被量化。例如，规则不会是“颜色对比度要足够高”，而是“文本与背景的颜色对比度必须≥4.5:1 (WCAG AA级)”。这种量化使得“检测”成为可能，也是canon detect命令工作的基础。

2.2 双引擎驱动：检测器与命令集

CANON通过两个核心“引擎”来发挥作用：静态检测器和动态命令集。

静态检测器是一个独立的CLI工具。它的工作原理类似于ESLint或StyleLint，但专注于设计规则。你运行npx canon-design detect ./src，它会扫描你的源代码，根据89条内置规则进行审计，并输出一份报告，指出哪些地方违反了CANON规范。这对于在已有项目中推行规范，或者在代码评审中自动化检查设计质量，具有巨大价值。

实操心得：将canon detect集成到你的CI/CD流水线中是一个绝佳实践。可以设置一个门禁，当检测到severity=high（高严重性）的问题时，流水线失败，从而强制团队在合并代码前修复关键的设计和无障碍缺陷。使用--json参数可以方便地输出结构化数据供CI工具解析。

动态命令集则是与AI交互的桥梁。19个形如/audit、/polish、/layout的命令，本质上是预定义的、高度优化的提示词模板。当你把这些技能包部署到你的AI编码工具（如Cursor）后，你就可以在编辑器中直接调用这些命令。例如，你选中一段粗糙的HTML代码，输入/polish，AI会结合typography、spatial、color等技能，将这段代码重构得更加优雅、规范。

这两者相辅相成：命令集用于“创作时指导”，检测器用于“完成后验证”，形成了一个完整的设计质量保障闭环。

2.3 与AI编码工具的集成原理

CANON的“分发物”是一系列针对不同AI工具的配置文件包。以Cursor为例，CANON提供了一个.cursor目录，里面包含了预定义的规则、提示词和上下文设置。当你通过cp -r dist/cursor/.cursor your-project/将其复制到项目根目录时，你就相当于为Cursor这个“副驾驶”安装了一个“设计规范导航仪”。

此后，Cursor在分析你的项目上下文和响应你的指令时，会优先参考CANON注入的这些规则。它并没有修改AI模型本身，而是巧妙地利用了这些工具允许用户提供自定义上下文（Custom Instructions）或系统提示词（System Prompt）的特性。这种方式非常轻量，无需网络请求，没有运行时依赖，实现了“开箱即用”的体验。

3. 从零开始：完整集成与实操指南

理论说得再多，不如亲手实践。下面我将以最流行的Cursor和VS Code Copilot为例，带你走一遍完整的集成和使用流程。

3.1 环境准备与工具安装

首先，确保你的开发环境已经安装了Node.js（建议版本16以上）和npm。然后，你有两种方式使用CANON的检测功能：

全局安装（推荐用于频繁检测）：

npm install -g canon-design

安装后，你可以在任何项目的终端中直接使用canon命令。

使用npx（免安装，每次从网络拉取最新版）：

npx canon-design detect ./src

对于只想尝试或在不常使用的机器上执行，这种方式更干净。

接下来，选择你要集成的AI编码工具。这里以Cursor为例，因为它对自定义上下文的支持非常友好。

3.2 为Cursor注入CANON设计技能

1. 定位你的项目：在终端中，进入你想要应用CANON规范的项目根目录。
2. 复制技能包：运行以下命令。这个操作会将CANON为Cursor预配置的所有规则和提示词复制到你项目的.cursor隐藏文件夹中。

   cp -r node_modules/canon-design/dist/cursor/.cursor ./

   如果全局安装后找不到dist目录，你可以直接从CANON的GitHub仓库Release中下载发行包，或者使用npx临时执行一个复制脚本（假设项目提供了）。更直接的方法是使用项目README中提到的命令，从源码构建后的dist目录复制。
3. 验证集成：打开Cursor，在项目中新建或打开一个前端组件文件（如Button.jsx或button.vue）。尝试让Cursor生成一个按钮，观察其输出的代码。你应该能注意到，生成的代码会自然地包含合理的间距、颜色变量、以及完整的交互状态。你还可以在Cursor的聊天框中输入/，看看是否出现了/audit、/polish等CANON命令的提示。

为VS Code + GitHub Copilot集成：对于使用VS Code原生Copilot的用户，CANON提供了.github目录的配置。将其复制到项目根目录，可能会影响Copilot在解决代码注释提示时参考的规则。

cp -r node_modules/canon-design/dist/vscode-copilot/.github ./

注意事项：集成操作本质上是向你的项目添加配置文件。建议将这些复制的配置文件（如.cursor目录）添加到你的.gitignore文件中，避免将个人/团队的AI工具配置提交到代码仓库，除非你希望统一团队规范。更好的做法是，在团队内部创建一个共享的“开发环境配置”仓库，包含这些标准化配置。

3.3 核心命令实战演示

集成成功后，让我们来实际体验几个核心命令，看看它们如何改变我们的工作流。

场景一：代码审查与审计 (/audit)你刚刚收到一段由另一位开发者（或AI）编写的Card组件代码，感觉有些凌乱。

// 原始代码 const Card = ({title, children}) => { return <div style={{border: '1px solid grey', margin: '10px', padding: '15px'}}> <h3>{title}</h3> {children} </div> }

在Cursor中，选中这段代码，然后输入/audit命令。AI会基于CANON的cards、spatial、typography等技能进行分析，并可能给出如下反馈：

“审查发现：1. 使用了内联样式，不利于维护和主题化。2. 间距值（10px,15px）不是基于4px或8px基准单位的倍数，可能导致视觉不一致。3. 边框颜色grey对比度可能不足，且未定义悬停状态。4. 标题层级<h3>在此上下文中是否语义化需根据页面结构判断。建议使用CSS类、设计令牌，并遵循spacing-2(8px)、spacing-3(12px)等标准间距。”

场景二：代码美化与强化 (/polish,/harden)接着上面的例子，我们想让这段代码变得更好。对同一段代码使用/polish命令。AI可能会将其重构成：

// 重构后代码 const Card = ({ title, children }) => { return ( <div className="card"> <h2 className="card__title">{title}</h2> <div className="card__body">{children}</div> </div> ); }; // 并附带建议的CSS // .card { border: 1px solid var(--color-border); border-radius: var(--radius-md); padding: var(--spacing-4); background: var(--color-surface); } // .card__title { font: var(--font-heading-sm); color: var(--color-text-primary); margin-bottom: var(--spacing-3); } // .card:hover { box-shadow: var(--shadow-sm); }

/harden命令则更侧重于可访问性和健壮性，它可能会为卡片添加tabIndex、role属性，并确保焦点管理。

场景三：设计令牌生成 (/colorize,/normalize)如果你有一个设计稿，里面定义了主色#007AFF、错误色#FF3B30，但代码里还是散落着十六进制值。你可以选中这些颜色值，运行/colorize命令。AI会建议你创建或更新一个设计令牌系统：

/* 建议生成的设计令牌 */ :root { --color-primary: #007AFF; --color-error: #FF3B30; --color-surface: #FFFFFF; --color-text-primary: #1D1D1F; /* ... 并自动替换代码中的硬编码值 */ }

/normalize命令则擅长将杂乱无章的尺寸、颜色、字体大小统一到一套设计系统的规范值上。

4. 深度定制：打造属于团队的设计技能库

CANON开箱即用的52个技能已经非常全面，但真正的威力在于它的可扩展性。每个团队或产品都有自己独特的设计语言和业务规范，你可以基于CANON创建自定义技能。

4.1 技能与规则的文件结构

CANON的源码结构非常清晰。所有技能都定义在source/skills/目录下。每个技能是一个独立的文件夹，例如source/skills/buttons/。里面通常包含：

• skill.json: 定义技能元数据，如名称、描述、所属类别。
• rules/目录：包含多条具体的检测规则文件（.json或.js）。
• prompts/目录：存放与该技能相关的、用于AI命令的提示词模板。

一条规则的核心结构如下（以检查按钮颜色对比度的规则为例）：

{ "id": "button-contrast-ratio", "name": "按钮颜色对比度", "description": "主要按钮文本与背景的对比度至少应达到4.5:1 (WCAG AA)。", "severity": "high", // 严重级别：low, medium, high, critical "selector": "button.btn-primary, .button--primary", // CSS选择器，用于定位元素 "test": "color-contrast", // 检测函数名 "params": { "threshold": 4.5 }, "source": "WCAG 2.1 Success Criterion 1.4.3" }

4.2 创建自定义技能：以“品牌按钮圆角”为例

假设你的产品设计规范要求所有主要按钮的圆角必须是12px，而CANON的默认buttons技能可能规定的是8px。我们来创建一个自定义技能来强化这条规则。

1. 克隆并进入CANON源码：

   git clone https://github.com/Dragoon0x/canon cd canon npm install

2. 创建自定义技能目录：在source/skills/下创建一个新文件夹，例如my-brand-buttons。

3. 定义技能元数据(skill.json)：

   { "id": "my-brand-buttons", "name": "品牌按钮规范", "category": "components", "description": "适用于我们品牌的特定按钮样式规则，特别是圆角。", "version": "1.0.0" }

4. 创建检测规则(rules/border-radius.json)：

   { "id": "brand-button-border-radius", "name": "品牌按钮圆角", "description": "所有主要按钮的border-radius必须为12px。", "severity": "medium", "selector": ".btn-primary, [type='submit'].btn, button.primary", "test": "css-property", "params": { "property": "border-radius", "expected": "12px", "allowEquivalent": ["0.75rem"] // 如果使用rem，也允许 } }

5. 创建AI提示词(prompts/enhance.md)：这个文件用于/polish或/craft命令时，AI如何应用这条规则。

   当你处理按钮时，请遵循以下品牌规范： - 主要按钮 (`btn-primary`) 的圆角必须设置为 `12px`。 - 这是为了保持我们品牌独特的柔和视觉风格。

6. 构建并应用：运行npm run build，CANON会将你的自定义技能编译到dist/目录下各个工具的配置包中。然后，你可以像之前一样，将更新后的dist/cursor/.cursor等目录复制到你的项目中。

通过这种方式，你可以将任何团队内部的UI规范、甚至业务逻辑约束（如“所有价格都必须用<span class=\"price\">包裹”）转化为CANON技能，让AI在编码时自动遵守。

5. 常见问题与效能优化实录

在实际使用和向团队推广CANON的过程中，我遇到并总结了一些典型问题和优化技巧。

5.1 集成与使用问题排查

问题1：复制技能包后，AI工具（如Cursor）没有反应，命令不生效。

• 检查位置：确保.cursor文件夹被复制到了项目的根目录，而不是子目录。
• 检查Cursor版本：某些旧版本可能对自定义规则的加载支持不完全。尝试更新Cursor到最新版本。
• 重启Cursor：复制配置文件后，完全关闭并重新打开Cursor，以确保它重新加载上下文。
• 验证配置：检查.cursor目录下是否有rules、prompts等子文件夹和文件，确保复制过程完整。

问题2：canon detect命令运行缓慢，或对某些框架（如Vue单文件组件、Svelte）支持不佳。

• 性能：检测器需要解析和遍历文件。对于大型项目，可以指定特定目录而非整个./src，或使用.canonignore文件（如果支持）忽略node_modules、dist等目录。
• 框架支持：CANON的解析器可能主要针对JSX/HTML/CSS。对于Vue/Svelte，其检测深度可能有限。可以关注项目Issue和更新，社区可能正在完善对它们的支持。目前，可以尝试先对编译后的输出或模板部分进行检测。

问题3：AI生成的代码虽然规范，但显得有些“模板化”，缺乏创意。

• 这是预期之内的权衡：CANON的首要目标是保证基础质量和一致性。它解决的是“及格线”问题。
• 组合使用命令：不要只依赖/polish。先用/craft让AI自由发挥创意，再用/audit检查问题，最后用/normalize或/harden进行规范化和加固。将CANON视为“质检员”和“规范执行者”，而非“创意总监”。
• 调整技能权重：在自定义技能中，你可以通过规则的severity级别和提示词的措辞，来调整AI对某条规则的遵循严格程度。

5.2 提升效能的进阶技巧

1. 创建项目预设：不要为每个新项目都手动复制配置文件。可以创建一个项目模板（Boilerplate）或使用degit等工具，将CANON配置、你的自定义技能以及ESLint、Prettier等工具配置一并初始化。
2. 与现有工具链结合：
   • 与ESLint/Prettier共存：CANON检测的是设计规则，ESLint检测的是代码质量规则，两者互补。可以在package.json中配置脚本：

     "scripts": { "lint": "eslint .", "lint:design": "canon detect ./src", "lint:all": "npm run lint && npm run lint:design" }

   • 在Git Hooks中运行：在pre-commit钩子中运行canon detect ./src --severity=high --quiet，只阻止高严重性问题被提交，既保证质量又不至于太过严格。
3. 团队协作与知识沉淀：将团队内部达成的、经过验证的自定义技能（如“我们的数据表格交互规范”、“弹窗动画曲线”）沉淀到CANON技能库中。这相当于将团队的UI设计知识进行了“代码化”和“自动化”传承，新成员通过AI生成的代码就能自然符合团队规范，极大降低了培训成本和设计走样风险。
4. 选择性应用技能：不是所有项目都需要52个技能全开。对于一个后台管理系统，>