HTML / CSS / 系统课时
建立前端交付规范
建立前端交付规范
本课把零散的样式约定整理成可执行的交付体系:用设计令牌统一视觉来源,用组件合同限制用法,用固定命令完成质量门禁,并用检查清单和维护文档保证后续迭代仍可复现。
学习目标
- 能定义设计令牌、组件规范和构建产物之间的责任边界。
- 能建立可重复执行的 lint、test、build 交付门禁。
- 能编写简洁的验收清单与维护记录,降低团队协作成本。
把交付物组织成一条链

交付规范不应只是一个 README。它至少要连接五类事实:视觉值从哪里定义、组件允许哪些变体、项目用什么命令验证、什么条件算通过、变更后由谁更新文档。任何一项只存在于口头约定中,都会在多人协作或版本升级时失效。
建议把令牌文件、组件说明、验证脚本、验收清单和变更记录全部纳入版本控制。合并请求只能引用仓库中的规则,避免设计稿、聊天记录和代码各自维护一套不一致的标准。
固化令牌与组件合同
设计令牌应表达稳定语义,而不是页面位置。例如使用 --color-primary、--surface-card 和 --radius-control,不要使用 --home-blue 或 --sidebar-radius。Tailwind 类负责组合布局和状态,令牌负责提供可统一替换的值。
:root {
--color-primary: #0369a1;
--color-danger: #dc2626;
--surface-card: #ffffff;
--radius-control: 0.5rem;
}
.theme-dark {
--surface-card: #0f172a;
}这是配置片段。生效后,组件应通过 bg-[var(--surface-card)]、text-[var(--color-primary)] 等方式消费语义值;验证时切换主题并检查按钮、卡片和表单是否同步变化,而不是逐个组件修改颜色。
组件合同只记录外部可用能力,例如 variant、size、disabled、loading 和插槽结构,同时明确禁止调用者覆盖的内部细节。每新增一个变体,都要补充默认状态、悬停、键盘聚焦、禁用、暗色模式和响应式表现,防止只完成“静态可见”这一种状态。
建立可执行的质量门禁
将检查顺序固定为 lint、test、build,前一步失败就立即停止。下面的 Node.js 脚本可跨常见开发环境运行;它依赖项目已经定义 lint、test 和 build 三个 npm 脚本。
import { spawnSync } from "node:child_process";
const steps = [
["lint", "npm run lint"],
["test", "npm run test"],
["build", "npm run build"]
];
for (const [name, command] of steps) {
const result = spawnSync(command, {
shell: true,
encoding: "utf8"
});
if (result.status !== 0) {
process.stderr.write(result.stdout || "");
process.stderr.write(result.stderr || "");
console.error(`${name}: failed`);
process.exit(result.status ?? 1);
}
console.log(`${name}: passed`);
}将文件保存为 scripts/verify-delivery.mjs 后执行:
node scripts/verify-delivery.mjs预期输出
lint: passed
test: passed
build: passed任何一步失败时,脚本会输出原命令日志并以非零状态结束,持续集成平台即可阻止交付。构建通过后还要确认产物目录存在、静态资源路径正确、未提交调试开关,并在受支持视口检查关键页面。
用清单和文档完成验收
交付清单应短而可判定,避免“页面正常”“体验良好”这类无法复核的描述。每次发布至少检查:令牌是否来自统一来源、组件状态是否齐全、断点是否覆盖、键盘焦点是否可见、构建是否通过、产物是否可部署、变更记录是否包含影响范围和回退方式。
维护文档只保留当前有效规则,并为破坏性变更记录日期、原因、迁移步骤和负责人。旧方案应明确标记为废弃并给出替代路径。这样新成员可以从仓库得到同一答案,出现问题时也能追溯是哪次令牌、组件或构建规则变化造成的。