企业官网建设流程全解析

1. 从“impeccable”这个词说起：它到底想解决什么问题

第一次看到“impeccable”这个项目名，我脑子里蹦出来的不是词典释义，而是一个很具体的场景：你让 AI 帮你写一段前端代码，它噼里啪啦吐出来一大坨，结构看着像那么回事，但真丢进项目里跑一遍，间距是乱的、颜色对比度不够、响应式断点全崩、无障碍属性基本靠猜。你反复调 prompt，它反复给你“差不多但就是不对”的东西。这个痛点，凡是重度使用 AI coding agents 做前端的人都懂。

“impeccable”这个词本身是“无可挑剔的、完美的”意思。放在这个项目语境里，它瞄准的其实是前端设计质量的可控性——让 AI 生成或辅助生成的前端界面，从“能跑”提升到“经得起看、经得起用、经得起审”。它不是一个单纯的代码生成器，而更像是一套围绕前端设计质量做约束、校验和增强的工具链思路，核心载体是 CLI，同时延伸到 browser extension 这类贴近真实渲染环境的形态。

我把它拆成三个层面来理解。第一层是设计规范的显性化：把那些平时藏在资深前端脑子里的隐性标准（间距节奏、字号阶梯、色彩对比、焦点态、hover 反馈）变成可被工具读取和检查的规则。第二层是与 AI coding agents 的协同：让 agent 在生成代码时就有明确的“审美约束”和“质量红线”，而不是生成完再靠人肉 review。第三层是闭环验证：通过 CLI 在本地跑检查，通过 browser extension 在真实浏览器里看效果，形成“生成—检查—修正”的循环。

这套东西适合谁？我觉得有三类人最该关注。一是独立开发者和小团队，没有专职设计师，但又不想做出来的东西一眼“AI 味”；二是前端工程师，日常要接 AI 生成的代码，需要一套快速判断“这坨代码能不能用”的标准；三是产品经理和设计偏执狂，他们不一定写代码，但需要一种方式把设计意图固化下来，让 AI 和工程师都照着执行。接下来我会从整体设计思路、核心细节、实操流程、常见问题几个角度，把“impeccable”这套东西掰开揉碎讲清楚。

2. 整体设计思路：为什么是 CLI 加 browser extension 的组合

2.1 为什么不做成纯 Web 工具或纯插件

我一开始也疑惑，为什么这类工具偏爱 CLI 作为主入口。后来自己折腾了几个项目才想明白：前端设计质量的检查，本质上是一个需要嵌入开发流程的动作，而不是一个“打开网页点一下”的动作。你不可能每次改完代码都手动上传到某个网站去检查，那太割裂了。CLI 的好处是它能进 package.json 的 scripts，能进 pre-commit hook，能进 CI，能在你git commit的那一刻就告诉你“这次改动让对比度掉到了 3.8:1，不达标”。

而 browser extension 解决的是另一个维度的问题：真实渲染环境。CLI 再强，它大多时候是在静态分析代码或跑 headless 检查，但真实浏览器里的字体渲染、图片加载后的布局回流、不同缩放比例下的表现，这些只有真正在浏览器里跑起来才看得准。所以“CLI 做流程嵌入和批量检查，extension 做真实环境验证和即时反馈”，这个组合是有内在逻辑的，不是随便堆两个形态。

提示：如果你只想要其中一个，我的建议是优先上 CLI。因为流程嵌入带来的收益是持续的，而 extension 更多是辅助验证，属于锦上添花。

2.2 与 AI coding agents 的协同逻辑

现在大家用 AI coding agents（不管是哪家的）写前端，最大的问题不是“写不出来”，而是“写出来质量不稳定”。同一个 prompt，今天生成的按钮间距是 16px，明天变成 12px，后天又变成 20px。这种不一致性在单页面上不明显，但页面一多，整个产品就显得“东拼西凑”。

“impeccable”这类工具的思路，是把设计约束前置到 agent 的工作流里。具体来说有两种协同方式。一种是在 agent 的上下文里注入一份“设计规则文件”，让它在生成时就遵守；另一种是在 agent 生成之后，用 CLI 跑一遍检查，把不达标的地方反馈回去让它重写。前者是预防，后者是治疗，实际用下来两者结合效果最好。我个人的习惯是：项目初期用规则注入，快速建立基线；项目中期用 CLI 检查，防止回归；上线前用 extension 做一轮真实环境走查。

2.3 核心设计原则：可检查、可量化、可复现

这套东西能成立，靠的是把“好看”这种主观感受，尽量翻译成客观指标。比如“间距舒服”翻译成“间距值落在 4px 的倍数网格上”；“颜色清晰”翻译成“文本与背景对比度不低于 4.5:1”；“交互明确”翻译成“所有可点击元素必须有可见的 focus 态和 hover 态”。这些指标不一定能覆盖全部审美，但能覆盖 80% 的“一眼就不对”的问题。

可量化带来的直接好处是可复现。你把这套规则写进配置文件，团队里任何人、任何 agent 跑出来的结果都遵循同一套标准。新人接手不会跑偏，agent 换版本也不会突然“审美漂移”。这是我认为这套思路最有价值的地方——它把设计质量从“依赖某个人”变成了“依赖一套规则”。

3. 核心细节解析：设计规则到底该怎么定

3.1 间距系统：4px 网格不是教条，但它是好起点

间距是最容易出问题、也最容易标准化的部分。我的做法是强制所有 margin、padding、gap 都落在 4px 的倍数上。为什么是 4 而不是 8？因为 8px 网格在移动端太粗，很多紧凑布局需要 4px 的微调空间；而 4px 网格既能覆盖紧凑场景，又能通过倍数关系自然形成 8、12、16、24、32 这样的节奏。

具体到配置，我会在规则文件里定义一组“允许的间距值”，比如[0, 4, 8, 12, 16, 24, 32, 48, 64]，然后让 CLI 去扫描代码里所有间距相关的属性，凡是出现不在这个列表里的值就报警。实测下来，这条规则能干掉一大半“看起来乱”的问题。你可能会问，那 20px 这种值怎么办？我的经验是，如果 20px 反复出现，说明你的网格该调整了，而不是给 20px 开绿灯。

注意：不要一上来就把规则定得太死。我见过有人把间距限制到只有 5 个值，结果复杂布局根本没法做，最后只能到处写例外，规则形同虚设。留一点弹性，比如允许在特定组件内使用局部变量，但全局必须收敛。

3.2 色彩与对比度：别只盯着主色

色彩这块，新手最容易犯的错是只检查主色和背景的对比度，忽略了次要文本、禁用态、placeholder、边框这些“边缘角色”。而这些恰恰是 AI 生成代码的重灾区——它经常给你一个#999的 placeholder，在白底上对比度只有 2.8:1，肉眼看着就费劲。

我的规则里会明确要求：正文文本对比度不低于 4.5:1，大号文本（18px 以上或 14px 加粗）不低于 3:1，所有交互元素的边框和图标不低于 3:1。这些数字不是拍脑袋来的，是行业通行的无障碍基线。CLI 检查时会把所有颜色对提取出来算对比度，不达标的直接列出来。这里有个实操技巧：把品牌色和中性色分开管理，品牌色允许有“装饰性使用”的例外，但中性色必须严格达标。

3.3 交互状态：focus 态是最容易被忽略的

AI 生成的前端代码，hover 态通常会给，但 focus 态十有八九是缺失的。而 focus 态恰恰是键盘用户和辅助技术的生命线。我的规则里把 focus 态列为强制项：所有可聚焦元素必须有可见的 focus 样式，且 focus 样式不能只是outline: none了事。

具体检查时，CLI 会扫描所有button、a、input、select、textarea以及带tabindex的元素，确认它们有对应的:focus或:focus-visible样式定义。browser extension 则更进一步，可以在真实页面里用 Tab 键走一遍，看焦点是否可见、顺序是否合理。这个环节我踩过的坑是：有些组件库自带的 focus 样式被全局 reset 覆盖了，CLI 静态扫描看不出来，只有 extension 在真实环境里才能发现。

3.4 响应式断点：收敛比丰富更重要

响应式这块，我的建议是断点数量宁少勿多。很多 AI 生成的代码会给你五六个断点，每个断点下的布局逻辑还不一致，维护起来是灾难。我的规则里通常只保留三个断点：移动端（<768px）、平板（768px–1024px）、桌面（>1024px）。所有组件的响应式行为都围绕这三个断点定义。

CLI 检查时会统计代码里出现的媒体查询断点值，如果超出预设集合就报警。这条规则的价值在于强制一致性——当所有组件都用同一套断点，整个产品的响应式行为就是可预测的。browser extension 则可以在真实窗口缩放时观察布局是否出现溢出、重叠、文字截断等问题，这些是静态检查覆盖不到的。

4. 实操过程：从零搭起一套可用的检查流程

4.1 环境准备与 CLI 安装

假设你已经有一个前端项目，Node 环境是现成的。第一步是安装 CLI 工具。不同项目的 CLI 命名可能不同，但安装方式大同小异，通常是全局安装或作为 devDependency 安装。我的习惯是装在项目本地，写进devDependencies，这样团队里每个人、CI 环境里用的都是同一个版本，避免“我这儿能跑你那儿报错”。

# 作为开发依赖安装到项目本地 npm install --save-dev <cli-package-name> # 或者用 yarn yarn add --dev <cli-package-name>

安装完之后，先跑一次--help或--version确认装上了。这一步看似废话，但我见过太多人装完直接跑检查，结果因为版本不对或路径问题折腾半天。确认命令可用之后，在项目根目录初始化配置文件。大多数这类工具会提供一个init命令，生成一份默认规则文件，你在此基础上改。

# 初始化配置文件，生成默认规则 npx <cli-command> init

生成的配置文件通常是 JSON 或 YAML 格式，里面包含间距、颜色、断点、交互状态等几个大类。我建议第一次不要急着改，先拿默认规则跑一遍现有代码，看看报了多少问题，心里有个底。

4.2 规则文件的定制与调优

跑完第一遍，你会得到一份问题清单。这时候别慌，也别想着一次性全修完。我的做法是分优先级处理：先修对比度和 focus 态这类“硬伤”，再修间距和断点这类“一致性问题”，最后处理那些“风格偏好”类的告警。

规则文件里我通常会调整几个地方。一是把项目里已经形成习惯的间距值加进白名单，比如你们团队一直用 20px 做卡片内边距，那就把它加进去，而不是强行改成 24px 引发大面积返工。二是把某些第三方组件库的目录排除在检查范围外，因为那些代码你改不了，检查了也是徒增噪音。三是针对特定文件或目录设置不同的规则强度，比如设计系统目录用严格模式，业务页面用宽松模式。

{ "spacing": { "allowedValues": [0, 4, 8, 12, 16, 20, 24, 32, 48, 64], "strict": true }, "contrast": { "normalText": 4.5, "largeText": 3, "uiComponents": 3 }, "exclude": ["node_modules", "dist", "src/vendor/**"] }

这份配置是我常用的一个起点，你可以根据自己的项目情况调整。关键是要让规则可执行且不扰民——如果一条规则天天报警但没人修，那它还不如没有。

4.3 接入开发流程：pre-commit 与 CI

规则调好之后，下一步是让它“自动跑起来”。最有效的两个接入点是 pre-commit hook 和 CI。pre-commit 的好处是问题在提交前就被拦住，不会污染主分支；CI 的好处是兜底，防止有人绕过本地 hook。

pre-commit 我一般用 husky 加 lint-staged 的组合，只检查本次改动涉及的文件，这样速度快，不会因为全量检查拖慢提交。CI 里则跑全量检查，作为合并前的门禁。这里有个细节：CI 里的检查结果要输出成可读的报告，最好能直接定位到文件和行号，方便快速修复。

# pre-commit 里只检查暂存的文件 npx <cli-command> check --staged # CI 里跑全量检查并输出报告 npx <cli-command> check --all --reporter=json > report.json

实测下来，这套流程能把“设计回归”的概率压得很低。以前靠人肉 review 容易漏的对比度、focus 态问题，现在基本在提交阶段就被拦住了。

4.4 browser extension 的真实环境验证

CLI 跑通之后，extension 是补充验证的一环。安装方式通常是从浏览器的扩展商店装，或者加载本地解压的扩展目录。装好之后，打开你的项目页面，extension 会在页面上叠加一层检查结果，或者通过弹出面板展示当前页面的问题清单。

我常用 extension 做三件事。一是键盘走查：用 Tab 键从头到尾走一遍，看焦点是否可见、顺序是否符合视觉顺序。二是缩放测试：把浏览器缩放到 200%，看布局是否崩坏、文字是否溢出。三是对比度实测：在真实渲染环境下，有些颜色因为透明度叠加，实际对比度和代码里写的不一样，extension 能算出真实值。

提示：extension 的检查结果不要当成唯一标准，它更多是“发现异常”的工具。有些告警是误报，比如装饰性元素本来就不需要高对比度，这时候在规则里加例外即可，不必强行修改设计。

5. 常见问题与排查技巧实录

5.1 检查报了一大堆问题，从哪儿下手

这是新手最常问的。我的建议是先看对比度和 focus 态，再看间距，最后看断点。原因是对比度和 focus 态直接影响可用性，属于“必须修”；间距影响观感一致性，属于“应该修”；断点问题往往牵涉布局重构，属于“计划修”。按这个顺序，你能在最短时间内让产品“看起来靠谱”。

另外，善用 CLI 的过滤功能。大多数工具支持按规则类型过滤，比如只看对比度问题，或者只看某个目录的问题。先集中火力解决一类，比东一榔头西一棒子效率高得多。

5.2 规则和现有代码冲突怎么办

冲突是必然的，尤其是接手老项目的时候。我的处理原则是新代码严格、老代码渐进。具体做法是在配置里对老代码目录降低规则强度，或者用注释的方式在文件级别豁免。同时定一个“只减不增”的目标：老代码的问题数量只能减少不能增加，新代码必须零告警。这样既不会因为一次性大改引发风险，又能保证质量逐步提升。

5.3 AI agent 生成的代码总是过不了检查

这个问题很典型。AI agent 不知道你的规则，它按自己的“常识”生成，自然容易踩线。解决办法有两个。一是把规则文件的内容作为上下文喂给 agent，让它在生成时就遵守。二是把 CLI 的检查结果反馈给 agent，让它根据具体报错重写。前者成本低但效果有限，后者效果好但需要多轮交互。我的经验是两者结合：先用规则注入建立基线，再用检查反馈做精修。

还有个小技巧：把常见的报错模式和对应的修正方式整理成一份“修正指南”，也喂给 agent。比如“对比度不足时，优先调整文字颜色而不是背景色”“间距不在网格上时，就近取整到最近的允许值”。这样 agent 的修正会更有方向，减少来回折腾。

5.4 extension 装了但看不到检查结果

这种情况通常是几个原因。一是扩展没有在当前页面启用，需要在扩展管理里确认权限。二是页面是本地文件或特殊协议，扩展默认不注入，需要在扩展设置里开启“允许访问文件 URL”。三是页面本身有 CSP 限制，阻止了扩展脚本注入，这种情况比较麻烦，通常需要调整页面的安全策略或换用 CLI 检查。

排查顺序我一般是：先看扩展图标是否高亮，再看控制台有没有报错，最后看扩展的权限设置。大部分问题在前两步就能定位。

5.5 团队协作中规则怎么统一

规则文件一定要进版本控制，这是底线。然后是在 README 或贡献指南里写清楚：提交前必须跑检查，CI 不通过不允许合并。新人入职第一件事就是装 CLI、跑一遍检查、看一遍规则文件。我还会定期组织“规则评审”，把大家觉得不合理的规则拿出来讨论调整，避免规则变成“某个人拍脑袋定的”。

注意：规则不是越多越好。我见过团队定了上百条规则，结果没人记得住，最后全靠 CI 报错才知道。规则要精，要少，要每条都有明确的理由。宁可只有十条被严格执行的规则，也不要一百条被无视的规则。

6. 我踩过的坑和几条实在建议

先说一个我印象最深的坑。有次我给一个项目配了严格的间距规则，结果发现某个第三方图表库内部用了大量非网格间距，导致每次检查都报几百条告警。我一开始试图改图表库的样式，折腾半天发现根本改不动，还引入了新 bug。后来学乖了，直接在配置里把整个图表库目录排除掉。这件事教会我：规则是为了服务项目，不是项目为了服务规则。该豁免就豁免，别跟工具较劲。

第二个坑是关于 focus 态的。我曾经为了“视觉干净”，把全局 focus 样式设成了很淡的阴影，CLI 检查通过了，但实际用键盘操作时几乎看不见焦点在哪。后来才明白，focus 态的可见性不能只看“有没有定义”，还要看“实际对比度够不够”。现在我的规则里会额外检查 focus 样式的对比度，确保它在各种背景下都清晰可见。

第三个坑是断点。我早期喜欢给每个组件单独定断点，觉得这样“精细”。结果项目大了之后，同一个页面里不同组件的断点不一致，窗口缩放时有的先变有的后变，视觉上非常割裂。后来统一成三个全局断点，所有组件都遵循，问题迎刃而解。一致性比精细更重要，这是我用血泪换来的教训。

最后分享一个我觉得很实用的小技巧：把 CLI 检查结果和 browser extension 的检查结果做交叉比对。CLI 报的问题 extension 没报，可能是静态分析的误报；extension 报的问题 CLI 没报，可能是真实环境才暴露的问题。两者都报的，基本就是必须修的真问题。这个交叉验证的方法，能帮你快速判断哪些告警值得花时间，哪些可以先放一放。

这套围绕“impeccable”思路搭建的检查流程，我从去年开始在自己的几个项目里用，最大的感受是：它不能让你变成设计师，但能让你不犯低级错误。对于大量依赖 AI coding agents 做前端的团队来说，这种“守住下限”的能力，往往比追求上限更实际。毕竟，一个没有明显硬伤的产品，已经赢过一大半同行了。