taste-code-craft

taste-code-craft

经过设计的页面，就是经过设计的代码库。DOM 是你编写的第一层布局——要像设计布局一样组织它。

1. 语义化 HTML（DOM 即设计）

• 每个页面只有一个 <h1>；标题级别逐级递减，不得跳级（h1 → h2 → h3，不能在单独的 h4 后直接出现 h2）。
• 使用语义与内容相符的元素：<nav>、<main>、<section aria-labelledby>、<figure>、<time>、<button>（不要使用带点击处理器的 <div>）、导航使用 <a href>。
• 列表使用 <ul>/<ol>——一行功能项就是一个列表，不要用五个 <div>。
• 每个 <img> 都有 alt（仅装饰性图片使用空 alt=""），并明确设置 width/height，避免布局偏移。
• 标签：每个 <input> 都有可见的 <label>（或 aria-labelledby）；绝不能只用 placeholder 作为标签。
• 如果页面没有 <main>、有一个没有标题的 <section>，或有可点击的 <div>，就不合格。

2. 优先使用设计令牌，而非字面值（代码中的设计系统）

• 每种颜色、间距值、圆角、阴影和字号都必须来自变量——组件规则中不得出现任何硬编码的十六进制值。字面值 #000 或 padding: 13px 出现三次，就说明缺少设计令牌。
• 代码中的调色板必须与设计稿完全一致：不要自行添加额外的灰色（例如设计稿指定 #F4F1EA，却用了 #F7F8FA），也不要使用未选定的品牌色十六进制值。
• 字体使用声明的字号比例（rem/流体 clamp），不要为各组件临时指定像素字号。
• 断点遵循统一的媒体查询规范（宽度只定义一套，并记录一次），不要在各组件中使用魔法数字。
• 如果已有设计系统（taste-design-system），组件应使用语义令牌——绝不能绕过它们直接使用基础令牌。

3. 特异性与 CSS 架构

• 不使用 !important——如果需要它，说明选择器模型有问题。
• 不按 ID 设置样式，不使用会产生副作用的裸元素选择器（section { }），也不要使用超出单个 box-sizing 重置规则的 * { } 重置。
• 嵌套深度最多为 2 层（或遵循框架自身规范）；需要 4 层以上的选择器，说明应当建立相应的组件边界。
• 如果配置已令牌化且类名数量清晰易读，工具类/内联系统（Tailwind）可以使用；但不要让单个元素堆满 30 个类名。
• 删除无用规则：在交付前，删除所有无法匹配标记的 CSS 规则——页面交付时不得有未使用的选择器。
• 组件应职责单一：每个 UI 组件对应一个文件/代码块，不要让一个组件同时负责 hero、footer 和 modal。

4. 禁止内联样式（以下三种情况除外）

• 禁止将内联 style="..." 用于布局、颜色和字体——这些应该使用类名。
• 允许的例外（谨慎使用，并注释说明原因）：动态值（从 JS 状态注入 CSS 变量，例如进度值）、需要新增类名才能实现的单个静态元素的一次性对齐、SVG 表现属性。
• 审查时会统计内联样式；一个页面超过约 5 处，就说明架构正在偏离规范。

5. 代码卫生与交付

• 不要留下无用标记：未使用的包装 div、空元素、旧代码注释、console.log、遗留在生产环境中的 TODO。
• 不要使用占位资源：不要有 lorem 文本、不要用 https://placehold.co、不要无明确意图地使用 unsplash URL，也不要使用会返回 404 的图片。
• 要交付的文件：每种字体只加载一次（参见 taste-web-performance），每个样式表都实际使用，不要因复制粘贴而产生重复的字体链接。
• 格式保持一致（统一引号风格、统一尾随逗号策略）——运行格式化工具；跳过格式化的 Agent，也可能跳过了其他事情。
• 不要在标记中引入无障碍回归：可聚焦元素应可访问，不要对可聚焦内容应用 aria-hidden，按钮不能嵌套在按钮中。

6. 检查清单（出现以下情况即判定代码不合格……）

• 应该使用 <button>/<a>/<ul> 的元素却使用了 <div>。
• 在令牌集之外硬编码了颜色、间距、圆角或字号。
• 使用了任何 !important、ID 样式，或 4 层及以上的嵌套。
• 使用了三种例外情况之外的任何内联样式。
• 发布了未使用的 CSS 规则、无用标记或 console.log。
• 跳过了标题级别，或存在重复的 h1。
• 图片没有替代文本和明确的尺寸。
• 代码看起来像是由未阅读设计系统的 Agent 生成的。