ub-css

UB CSS

概述

运用现代 CSS 平台特性，实现可预测的层叠控制、由令牌驱动的样式和渐进增强。将设计令牌视为系统契约，保持选择器和优先级易于维护，并优先使用原生 CSS 特性，而非沿用旧式 Sass 变通方案。

按需加载参考资料

• 调整路由指南或跨技能编写约定时，阅读 ../ub-authoring/references/authoring-conventions.md。
• 阅读 references/modern-css-source.md，了解可直接复制的模式和框架衔接方案（Vue/Nuxt/Quasar/Tailwind）。
• 决定回退策略或特性门控时，阅读 references/browser-support-baseline.md。

不适用场景

• 如果主要变更涉及 Tailwind 工具类工作流、Tailwind 设置或 Tailwind 迁移，请勿使用此技能；根据 CSS 架构是否仍是首要关注点，搭配使用或改用 ub-tailwind。
• 如果主要问题涉及 Nuxt 运行时行为、应用结构或 Nitro/服务器相关事项，请勿使用此技能；改用 ub-nuxt。
• 如果 CSS 相较于组件架构只是次要因素，请勿将此技能用于一般的 Vue 组件逻辑。

核心工作流

1. 确认令牌的唯一事实来源（DTCG JSON 或现有令牌注册表）。
2. 将令牌映射到运行时 CSS 自定义属性和语义别名。
3. 使用 @layer 定义层叠顺序，并将供应商 CSS 隔离在供应商层中。
4. 使用原生嵌套、现代选择器和容器查询实现组件样式。
5. 添加流体尺寸、逻辑属性和现代颜色/主题基础功能。
6. 使用 @supports 和明确的回退行为，为支持不完整的特性设置门控。
7. 检查无障碍性、动态效果偏好和面向性能的 CSS 特性。

现代 CSS 规则

1. 将设计令牌作为唯一事实来源（优先采用 DTCG）

• 首选 DTCG 令牌格式作为规范令牌数据（$value、$type、$description、别名引用）。
• 将规范令牌映射到全局和语义作用域中的 CSS 自定义属性。
• 保持语义令牌名称稳定；允许其背后的值变动。
• 除非有意使用一次性值并记录说明，否则避免在组件中使用硬编码值。

{
  "color": {
    "brand": {
      "primary": { "$type": "color", "$value": "oklch(62% 0.2 256)" }
    },
    "surface": {
      "default": { "$type": "color", "$value": "#ffffff" }
    }
  }
}

:root {
    --color-brand-primary   : oklch(62% 0.2 256);
    --color-surface-default : #ffffff;
    --space-4               : 1rem;
    --radius-md             : 0.5rem;
}

2. 将令牌接入框架 CSS 管线

• Vue/Nuxt/Quasar：在 SFC 样式块中直接使用 CSS 变量；仅对组件响应式值使用 v-bind()。
• Tailwind（最新稳定版）：将令牌保留在 @theme 中，并与 CSS 变量保持命名一致，使工具类和原生 CSS 共用相同的值来源。
• 保持令牌映射确定一致，让设计、应用 CSS 和工具类保持同步。

@theme {
    --color-brand-primary : oklch(62% 0.2 256);
    --spacing-4           : 1rem;
    --radius-md           : 0.5rem;
}

3. 使用 @layer 可预测地控制层叠

• 仅声明一次全局层顺序。
• 将第三方 CSS 导入专用的供应商层。
• 使用层来避免优先级不断升级。

@layer reset, vendor, tokens, base, components, utilities, overrides;
@import url("vendor.css") layer(vendor);

4. 使用原生嵌套，但保持浅层结构

• 对状态选择器、局部后代选择器和就近定义的查询使用原生嵌套。
• 嵌套深度保持在 <= 3 层。
• 避免与 DOM 结构深度耦合的选择器。

5. 使用容器查询实现组件响应式布局

• 在组件边界设置 container: <name> / inline-size（或 container-type + container-name）。
• 组件内部优先使用容器查询；视口媒体查询用于页面外壳布局。
• 当尺寸应随容器宽度/高度变化时，使用容器查询单位（cqw、cqh、cqi、cqmin、cqmax）。

6. 有针对性地使用现代选择器

• 在能简化标记/JS 的情况下，使用 :has() 实现由父级/状态驱动的样式。
• 使用 :is() 以常规优先级组合选择器变体。
• 使用 :where() 设置零优先级的默认样式。
• 始终使用 :focus-visible 提供无障碍的键盘焦点状态。

7. 优先使用现代布局、尺寸和国际化原语

• 使用 Grid/Flex 和 gap，而不是基于 margin 的间距变通方案。
• 使用 clamp()、min()、max() 和 calc() 实现流畅的尺寸调整。
• 优先使用逻辑属性（padding-inline、border-inline-start、inset-block），而不是物理方向的 left/right 属性。
• 使用 aspect-ratio，而不是基于 padding-box 的比例变通方案。

8. 使用现代颜色和主题原语

• 优先使用感知均匀的颜色空间（oklch）作为令牌值。
• 使用 color-mix() 派生变体，而不是手动重复定义调色板。
• 需要支持双主题行为时，使用 color-scheme 和 light-dark()。
• 将 accent-color 视为增强手段，而非正确性关键样式。

9. 有意识地处理动效、交互和性能

• 尊重用户偏好（prefers-reduced-motion，以及适用时的对比度和强制颜色模式）。
• 将 @starting-style、transition-behavior: allow-discrete 和 popover 钩子用作增强模式。
• 对长列表和大量屏幕外内容使用 content-visibility 和 containment。
• 使用 scrollbar-gutter: stable，减少滚动条出现时的布局偏移。

渐进增强策略（分层现代优先）

• 安全默认：默认使用广泛支持的现代功能。
• 增强层级：必须使用 @supports 保护，并确保回退行为可接受。
• 有限/实验性层级：仅在有明确理由且易于回退时使用。

文档、组织与格式

组织

• 代码库规模适合时，按职责拆分样式：
  • styles/tokens.css
  • styles/base.css
  • styles/components/*.css
  • styles/utilities.css
• 实际可行时，将组件样式放在组件附近。
• 集中定义全局令牌，减少偏差。

文档

• 对不明显的意图、回退方案的理由或兼容性限制添加简短注释。
• 说明使用部分支持功能的原因。
• 注释应聚焦于“为什么”，而非“是什么”。

格式

• 按逻辑顺序排列属性：
  1. 布局（display、position、grid/flex、z-index）
  2. 盒模型（inline-size/block-size、margin、padding、border）
  3. 排版（font-*、line-height、text-*）
  4. 视觉效果（background、color、box-shadow、opacity、filter）
  5. 动效（transform、transition、animation）
• 保持间距和对齐方式一致。
• 优先使用小型、单一用途的选择器块。

完成检查清单

• 已定义令牌模型，并清晰映射到 CSS 自定义属性。
• 尽量减少硬编码值，并为保留的硬编码值说明理由。
• 明确指定层顺序，并隔离厂商 CSS。
• 嵌套层次浅且易读。
• 在能简化代码时使用容器查询和现代选择器。
• 无障碍状态包含 :focus-visible，并尊重动效偏好。
• 通过回退方案保护增强功能和有限支持的功能。
• 注释简洁且聚焦于意图。

版本与调研策略

• 在推荐 CSS 功能或为其设置保护条件之前，使用网络搜索核实当前浏览器支持情况。
• 检查宿主仓库中的 AGENTS.md 或等效说明（如果存在），了解项目特定的版本策略和工具；不要假定其中包含本目录的默认设置。
• 不要在生成的指导中硬编码快照日期或版本号，以保持建议长期适用。

输出要求

生成或审查 CSS 指导时，须包含：

1. 令牌说明：令牌的事实来源，以及它们如何映射到运行时 CSS。
2. 层叠说明：层顺序和选择器特异性策略。
3. 增强说明：哪些功能属于基线，哪些通过 @supports 保护。
4. 无障碍说明：焦点、动效、对比度和强制颜色方面的考量。
5. 验证说明：实际使用的 lint、构建、浏览器支持或手动验证步骤。