web-css

Web CSS 技能

版本： 1.0 技术栈： 原生 CSS 与 CSS 变量

不使用预处理器或实用工具框架的整洁、易维护 CSS。通过 CSS 变量定义设计令牌。

问题

AI 生成的 CSS 会逐渐偏离。由于会话之间没有记忆，相似组件最终会出现细微差异：内边距、颜色、间距和圆角都不尽相同——这不是设计使然，而是各自独立编写的结果。偏差本身不是问题，问题在于之后每次编辑都只能部分修正：你修改了 .card 的背景色，但 .panel 使用 #fff，.info-box 使用 white，而 .content-block 使用 rgb(255,255,255)——颜色相同，格式不同，因此只有一个会被更新。这些标准将值集中到令牌中，让一次修改能在各处生效。

使用方式

• 构建者： 编写任何 CSS 前先阅读 ## Builder Checklist。每个值都必须使用令牌；每个文件都必须遵循 5 文件架构。
• 重构者： 使用 ## Enforced Rules 查找硬编码值和结构违规。阅读说明章节，了解令牌命名和文件组织指南。
• 两者皆适用： 说明章节是权威标准。清单和规则表是对相同内容的精简呈现。

---

范围与边界

本技能涵盖：

• 设计令牌实现（:root 中的 CSS 变量）
• 令牌类别（颜色、排版、间距、边框、阴影、动画、z-index）
• 使用 CSS 变量实现深色模式
• CSS 文件组织和导入顺序
• 受 BEM 启发的命名约定
• 移动端优先的响应式断点
• 布局模式（使用 Grid 构建结构，使用 Flexbox 控制流向）
• 组件状态实现
• CSS 属性排序
• CSS 反模式

遵循其他技能的规范：

• design：设计系统理念、何时使用 Grid 或 Flexbox、高级 UI 原则
• web-accessibility：焦点指示器模式、减少动态效果媒体查询、屏幕阅读器辅助工具

在以下情况下使用本技能： 需要 CSS 架构、令牌实现或响应式模式时。 在以下情况下使用 design： 需要设计原则、布局理念或组件状态要求时。 在以下情况下使用 web-accessibility： 需要符合 WCAG 标准或无障碍专用 CSS 模式时。

---

核心原则

1. 优先使用设计令牌 —— 所有值都来自 CSS 变量。
2. 限定组件作用域 —— CSS 与其组件放在一起。
3. 移动端优先 —— 移动端使用基础样式，再逐步增强。
4. 不使用魔法数字 —— 每个值都有明确用途，并且来自系统。
5. 可读性胜过炫技 —— 直观的代码胜过巧妙的代码。
6. 整合，不要重复 —— 创建新样式前先检查现有样式。

---

编写新 CSS 之前

这是必须通过的关卡，不是建议。 每个重复现有模式的新类都会产生一个变体。每个变体都意味着未来的修改只能部分生效——你修正了 .card，却漏掉 .panel 和 .info-box，因为它们是各自独立编写的，对相同意图使用了不同的值。这就是 CSS 变成打地鼠游戏的原因。现在做好预防，能省下之后数小时的清理工作。

编写任何值之前

1. 先检查 global.css —— 是否已有适用于此值的令牌？有就使用。若已有 var(--space-4)、var(--color-primary) 或 var(--radius-md) 这样的令牌，绝不要直接写 16px、#3b82f6 或 8px。
2. 搜索相似样式 —— 是否已有能实现此效果的按钮、卡片或布局模式？重复使用。
3. 检查是否有近似匹配项 —— 现有类是否稍作调整或添加修饰符后就能适用？
4. 出现重复时进行提取 —— 如果第二次写下相同属性，请停下来，将其合并为一个类。

/* BAD — new class that duplicates existing .btn-primary */
.modal-submit-btn {
  padding: var(--space-2) var(--space-4);
  background: var(--color-primary);
  border-radius: var(--radius-md);
}

/* GOOD — reuse existing class, add modifier only for what's truly different */
.modal-footer .btn-primary {
  /* Only add what's actually different */
}

什么会导致偏差

模式	为什么危险
使用原始值而非令牌	一处用 16px，另一处用 1rem —— 数值相同，却无法通过查找和替换统一
为现有模式新建类	.btn-primary 已经能实现相同功能，却又创建 .action-button
复制粘贴后再修改	将 .card 样式粘贴到 .panel 中并修改一个属性 —— 现在它们会各自独立地逐渐偏离
颜色格式不一致	这里用 #fff，那里用 white，别处用 rgb(255,255,255) —— 它们都表示相同颜色，但查找和替换只能匹配其中一种

规则

如果已有令牌，就使用它。如果已有类，就扩展它。只有在没有任何现有方案适用时，才创建新内容。

---

设计令牌

所有设计值都以 CSS 变量的形式存放在 styles/global.css 的 :root 中。令牌类别：

类别	示例	刻度
颜色 — 语义色	--color-primary、--color-error	按用途命名
颜色 — 中性色	--color-neutral-50 至 --color-neutral-900	10 级刻度
字体排版	--font-size-xs 至 --font-size-3xl	基于 rem
间距	--space-1 至 --space-16	以 4px 为基准，按 8px 递增
边框	--radius-sm 至 --radius-full	基于 rem
阴影	--shadow-sm 至 --shadow-xl	按尺寸分级
Z-index	--z-dropdown 至 --z-toast	100–600
动画	--duration-fast 至 --duration-slow	基于 ms

完整的令牌定义和值，请参阅 assets/token-reference.md。

深色模式： 在 [data-theme="dark"] 上覆盖语义颜色令牌。组件会自动适配。实现方法请参阅 assets/token-reference.md。

---

文件组织

5 文件架构

所有项目都恰好使用 5 个 CSS 文件，并按级联顺序加载：

styles/
├── reset.css       # 1. Browser normalization — clean slate
├── global.css      # 2. Design tokens (:root) + element defaults
├── layouts.css     # 3. Page scaffolding, grids, containers
├── components.css  # 4. All component styles (BEM)
└── overrides.css   # 5. Exceptions — one-offs, page-specific, utilities

检查规则： check.js 中的规则 css-file-count（超过 5 个时警告，超过 7 个时错误）和 css-file-names（未找到规范名称时警告）。

各文件的详细说明（包含什么、不包含什么、内部组织方式），请参阅 references/file-architecture.md。

模板

预构建的模板文件定义了每个 CSS 文件的规范分节结构。项目可以覆盖值，但不能更改结构。

templates/
├── reset.css       # Full reset (deterministic, same for every project)
├── global.css      # Token skeleton (:root with 9 categories) + element defaults
├── layouts.css     # Section headers only (project-specific content)
├── components.css  # Pattern template (Base → Variants → States per component)
└── overrides.css   # Section headers + accessibility utilities

脚手架命令： node scaffold-css.js <target-directory> 会复制全部 5 个模板。绝不会覆盖现有文件。

检查规则： check.js 中的规则 css-section-order（主要分节不符合规范顺序时发出警告）和 token-category-order（global.css 的 :root 中令牌子类别顺序不正确时发出警告）。

应该放在哪里？

问问自己……	答案 → 文件
这是不带任何设计倾向的浏览器重置吗？	reset.css
这是 CSS 变量或裸元素默认样式吗？	global.css
它控制页面上各元素的位置吗？	layouts.css
这是采用 BEM 命名的可复用 UI 组件吗？	components.css
这是例外、一次性规则或单属性覆盖吗？	overrides.css
我是不是要创建第 6 个文件？	停下。 它应该属于这 5 个文件之一。

---

命名约定

BEM 风格（简化版）

.product-card { }          /* Block */
.product-card__image { }   /* Element (child of block) */
.product-card--featured { } /* Modifier (variation) */
.product-card.is-loading { } /* State (JS-toggled) */

命名规则

类型	约定	示例
块	kebab-case	.user-profile
元素	__element	.user-profile__avatar
修饰符	--modifier	.user-profile--compact
状态	.is-state	.is-active、.is-loading
工具类	u-utility	.u-visually-hidden

---

响应式设计

• 仅采用移动优先： 使用 min-width 断点。绝不使用 max-width。
• 标准断点： 640px（sm）、768px（md）、1024px（lg）、1280px（xl）
• 用 Grid 构建结构，用 Flexbox 控制流动布局。
• 所有交互元素都需要 5 种状态： 默认、悬停、激活、焦点可见、禁用。

代码示例（断点、容器模式、Grid/Flexbox 布局、组件状态、无障碍模式），请参阅 assets/css-patterns.md。

---

反模式

反模式	问题	修复方法
硬编码值	缺乏一致性，难以换用其他主题	使用设计令牌
到处使用 !important	引发优先级之争	修正选择器优先级
嵌套层级过深	难以覆盖，且有优先级问题	最多 3 层
使用 ID 选择器设置样式	过于具体	使用类
在 JS 中编写样式	样式关注点分散	将 CSS 文件与组件放在一起
全局元素选择器	影响所有内容	将作用域限定在组件类中
max-width 媒体查询	桌面优先思维	使用 min-width（移动优先）
字体大小使用像素单位	忽略用户偏好	使用 rem
使用 Float 布局	过时且脆弱	使用 Grid 或 Flexbox
用外边距控制相邻元素间距	间距会累加，难以管理	在父元素上使用 gap

---

属性顺序

按组整理属性。共 5 组，始终按以下顺序排列：

.component {
  /* 1. Positioning */
  position: relative;
  top: 0;
  z-index: var(--z-dropdown);

  /* 2. Box Model */
  display: flex;
  grid-template-columns: 1fr 1fr;
  width: 100%;
  padding: var(--space-4);
  margin: 0;

  /* 3. Typography */
  font-family: var(--font-sans);
  font-size: var(--font-size-base);
  color: var(--color-text);

  /* 4. Visual */
  background-color: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);
  transform: translateY(0);

  /* 5. Animation */
  transition: box-shadow var(--duration-fast);
}

强制执行方式： check.js 中的 css-property-order 规则（警告）。

---

构建者检查清单

在编写受此规范约束的 CSS 之前，请根据以下约束检查你的计划。构建者在编写代码前应阅读本节；重构者则应参阅“强制规则”表和完整说明。

设计令牌

• 所有颜色都使用 CSS 变量
• 所有间距都使用 CSS 变量
• 所有字体大小都使用 CSS 变量
• 所有阴影都使用 CSS 变量
• 组件 CSS 中没有硬编码的十六进制颜色
• 没有硬编码的像素值（边框除外）

组织

• 在中央文件中定义令牌
• CSS 与组件放在一起
• 使用 BEM 风格命名
• 不使用 ID 选择器设置样式

响应式

• 移动优先（仅使用 min-width 查询）
• 使用标准断点
• 在所有断点下进行测试

无障碍

• 焦点指示器清晰可见
• 遵循减少动态效果的偏好设置
• 颜色对比度符合 WCAG AA
• 不单独依赖颜色传达信息

---

不使用 Tailwind，不使用 PostCSS

此设计系统使用原生 CSS 和设计令牌。不使用构建工具、实用类框架或预处理器。

为什么不使用 Tailwind？ 它会将样式决策转移到 HTML 中，产生臃肿的类名（class="flex items-center gap-4 p-6 rounded-lg bg-white shadow-md"），既难以浏览和搜索，也无法在一个地方统一更新。我们的设计系统通过将样式放在合适的位置——CSS 变量和语义类名中——来解决同样的问题：保持一致性。

为什么不使用 PostCSS？ 现代 CSS 原生支持变量、嵌套、@layer、color-mix() 和容器查询。对于浏览器已经支持的功能，PostCSS 只会增加构建步骤和工具复杂性。

如果项目已经在使用 Tailwind 或 PostCSS：

1. 不要再添加 Tailwind 实用类或 PostCSS 插件
2. 新 CSS 应写入原生 .css 文件，并使用 5 文件架构和设计令牌
3. 修改现有 Tailwind 组件时，将实用类链提取为 components.css 中的语义类，并引用令牌
4. 逐步迁移——不要一次性重写所有内容，但也不要继续沿用旧模式

---

强制规则

这些规则由 check.js（clean-team）确定性检查。更新这些标准时，请同步更新对应的 check.js 规则，反之亦然。

规则 ID	严重性	检查内容
no-hardcoded-color	error	var(--color-*) 之外的十六进制／rgb／hsl／命名颜色
no-hardcoded-spacing	warn	var(--space-*) 之外的原始 px 间距（>=4px）
no-hardcoded-font-size	warn	var(--font-size-*) 之外的字体大小
no-hardcoded-radius	warn	var(--radius-*) 之外的边框圆角
no-hardcoded-shadow	warn	var(--shadow-*) 之外的框阴影／文本阴影
no-hardcoded-z-index	warn	var(--z-*) 之外的 Z-index
css-property-order	warn	属性未按分组顺序排列（定位 > 盒模型 > 排版 > 视觉 > 动画）
css-import-order	warn	@import／<link> 顺序与层叠顺序不一致
css-section-order	warn	文件中的主要章节标题未按规范顺序排列
token-category-order	warn	global.css :root 中的令牌子类别顺序错误
mobile-first	warn	使用 max-width 媒体查询，而非 min-width
no-important	warn	使用 !important
no-id-selector	warn	使用 #id 选择器（特异性冲突）
unit-zero	warn	使用 0px／0rem，而非无单位的 0
css-file-count	warn/error	CSS 文件超过 5 个（警告）或 7 个（错误）
css-file-names	warn	未使用规范的 CSS 文件名（reset/global/layouts/components/overrides）

---

参考资料

• references/file-architecture.md — 各 CSS 文件的详细说明
• assets/token-reference.md — 完整的令牌定义、用法示例和深色模式
• assets/css-patterns.md — 响应式、布局、状态和无障碍代码示例