HTML / CSS / 系统课时

建立前端交付规范

建立前端交付规范

本课把零散的样式约定整理成可执行的交付体系:用设计令牌统一视觉来源,用组件合同限制用法,用固定命令完成质量门禁,并用检查清单和维护文档保证后续迭代仍可复现。

学习目标

  • 能定义设计令牌、组件规范和构建产物之间的责任边界。
  • 能建立可重复执行的 lint、test、build 交付门禁。
  • 能编写简洁的验收清单与维护记录,降低团队协作成本。

把交付物组织成一条链

前端交付规范的组成与反馈关系

交付规范不应只是一个 README。它至少要连接五类事实:视觉值从哪里定义、组件允许哪些变体、项目用什么命令验证、什么条件算通过、变更后由谁更新文档。任何一项只存在于口头约定中,都会在多人协作或版本升级时失效。

建议把令牌文件、组件说明、验证脚本、验收清单和变更记录全部纳入版本控制。合并请求只能引用仓库中的规则,避免设计稿、聊天记录和代码各自维护一套不一致的标准。

固化令牌与组件合同

设计令牌应表达稳定语义,而不是页面位置。例如使用 --color-primary、--surface-card 和 --radius-control,不要使用 --home-blue 或 --sidebar-radius。Tailwind 类负责组合布局和状态,令牌负责提供可统一替换的值。

css
: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 脚本。

js
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 后执行:

bash
node scripts/verify-delivery.mjs

预期输出

text
lint: passed
test: passed
build: passed

任何一步失败时,脚本会输出原命令日志并以非零状态结束,持续集成平台即可阻止交付。构建通过后还要确认产物目录存在、静态资源路径正确、未提交调试开关,并在受支持视口检查关键页面。

用清单和文档完成验收

交付清单应短而可判定,避免“页面正常”“体验良好”这类无法复核的描述。每次发布至少检查:令牌是否来自统一来源、组件状态是否齐全、断点是否覆盖、键盘焦点是否可见、构建是否通过、产物是否可部署、变更记录是否包含影响范围和回退方式。

维护文档只保留当前有效规则,并为破坏性变更记录日期、原因、迁移步骤和负责人。旧方案应明确标记为废弃并给出替代路径。这样新成员可以从仓库得到同一答案,出现问题时也能追溯是哪次令牌、组件或构建规则变化造成的。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立前端交付规范

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通