Upgrading to the v26 Design System
DWC 26 引入了全新的设计系统。此次更新是增量式的，而非完全重写：大多数 v25 的 CSS 变量仍然可用，主题引擎的公共 API 保持不变，现有的自定义设置无需更改即可继续使用。
本指南记录了变化内容、视觉输出的不同之处，以及当应用依赖于特定 v25 行为时所需的升级步骤。
快速评判
| 场景 | 预期效果 |
|---|---|
| 使用默认样式 | 视觉更新。默认调色板色相已经重新调整（例如，主色从 h: 211 / s: 100% 移动到 h: 223 / s: 91%），阴影看起来更分层，组件感觉更圆润。无需代码更改，但品牌默认颜色会有所变化。 |
重写 --dwc-color-{name}-h 和 -s | 仍然有效。HSL 种子路径保持不变。 |
单个调色板步骤重写（例如 --dwc-color-primary-40） | 数字可能解析为不同的颜色。请参阅 颜色调色板。 |
依赖于 --dwc-color-{name}-c | 删除。现在根据每个阴影自动计算浅/深文本翻转。 |
引用命名字体大小标记（--dwc-font-size-m、-l 等） | 尺度向下移动了一档。m 现在是 14px，而不是 16px。请参阅 排版。 |
使用 --dwc-font-weight-semibold 获取 500 权 重 | semibold 现在是 600。切换到新的 --dwc-font-weight-medium 以获取 500。 |
使用 --dwc-focus-ring-width 来保留可聚焦元素周围的填充 | 现在环有一个间隙。将 --dwc-focus-ring-gap 添加到该填充，否则环会溢出。请参阅 焦点环。 |
| 自定义按钮悬停/涟漪效果 | 涟漪效果已经消失。按压反馈现为小范围缩小。 |
如果上述情况都不适用，您可以在此停止阅读。您的升级已经完成。
新功能一览
- 现代色彩引擎。 调色板使用 OKLCH 代替 HSL 生成。亮度级别是感知均匀的（相邻步骤看起来像相邻步骤），暗模式不再翻转调色板。
- 通过一个变量实现暗模式。
--dwc-dark-mode: 1翻转整个用户界面。模式适应发生在变体层，而不是通过重新映射每个步骤。 - 自动
on-text颜色。 每个调色板步骤都有一个--dwc-color-on-{name}-text-{step}伴随值，符合该阴影的 WCAG AA 对比度要求。您无需手动计算对比度。 - 直接种子重写。 将任何 CSS 颜色（十六进制、
rgb()、oklch()、lab()等）传入--dwc-color-{name}-seed，整个调色板将从中重新生成。 - 重新调整的阴影。 仍然有六个级别（
xs到2xl），现 在具有逼真的层次衰减，并通过--dwc-shadow-strength自动增强暗模式强度。 - 表面和
default使用自己的亮度曲线。 现在两者都通过--dwc-dark-mode和一个小主色调进行适应，而不是在暗主题中重新定义表面并将default别名为调色板步骤。 - 缩小按压反馈。 涟漪由按压时的小范围缩小替代。标记：
--dwc-scale-press、--dwc-scale-press-deep。 - 带间隙的焦点环。 环现在有一个小的表面颜色间隙（
--dwc-focus-ring-gap），在有色阴影之前保持可见，以便在实心按钮和紧凑布局中保持可见。 - 边框半径被种子化。 改变
--dwc-border-radius-seed，则s到4xl步骤将成比例缩放（2xs和xs保持在固定像素值）。新增3xl和4xl步骤。
颜色系统
这是内部最大的变化。您应该熟悉看到的行为，内部结构有所不同。
定义颜色的两种方式
您可以像以前一样继续使用色相 + 饱和度，或直接重写种子为任何 CSS 颜色。
/* 色相 + 饱和度（仍为默认路径） */
:root {
--dwc-color-primary-h: 223;
--dwc-color-primary-s: 91%;
}
/* 直接种子 - 任何 CSS 颜色格式 */
:root {
--dwc-color-primary-seed: #6366f1;
}
如果您已经在使用 -h 和 -s，则无需进行任何操作。种子重写是直接品牌颜色的新路径。
颜色调色板：第 5 步始终是最暗的
在 v25 中，调色板在暗模式下翻转（在 光线中第 5 步最暗，在暗中最亮）。在 v26 中，第 5 步始终是最暗的阴影，第 95 步始终是最亮的，无论模式如何。模式适应现在发生在一个层次的顶部，在变体标记中：
/* v26 - 变体指向固定步骤 */
--dwc-color-primary-dark: var(--dwc-color-primary-45);
--dwc-color-primary: var(--dwc-color-primary-50);
--dwc-color-primary-light: var(--dwc-color-primary-55);
| 场景 | 更改内容 |
|---|---|
使用 --dwc-color-primary（或 -dark、-light、-text） | 无变化。变体在各模式间仍表现相同。 |
硬编码步骤如 --dwc-color-primary-40 | 该步骤现在在两种模式下解析为相同的 OKLCH 亮度。您在暗模式中看到的颜色来自不同的步骤。如果希望支持模式迁移，请切换到变体标记。 |
直接编写 hsl(var(--dwc-color-primary-h), ...) | 仍然有效。HSL 种子仍然由 h + s 构造。 |
颜色是派生的，而不是承诺的
您设置的色相是一个 种子，而不是目标。您通过 --dwc-color-{name}-h / -s（或 -seed）传递的颜色不一定会出现在第 50 步。
由于调色板使用绝对 OKLCH 亮度来表示每一步，您的种子落在哪一步取决于其自然亮度。明亮的色相（青色、黄色）具有高 OKLCH 亮度，通常在第 80-85 步附近。较暗的色相（蓝色）碰巧位于第 50 步附近。
如果您需要确切的颜色在确切的步骤下，请显式设置该步骤：
:root {
--dwc-color-primary-50: #1d4ed8;
}
--dwc-color-{name}-c 已消失
在 v25 中，-c 是对比阈值：伴随文字颜色从白色翻转为黑色的背景亮度阈值。值为 50 表示，在 50% 更暗的背景上文字是白色，而在 50% 更亮的背景上文字是黑色。
在 v26 中，您不再选择翻转点。每个步骤都有一个经过自动计算的着色的 on-text 颜色。这样得到的结果始终达到 WCAG AA 仅安全，同时保留搭配色调的暗示，而不是落入纯黑或纯白。
如果您有任何 --dwc-color-{name}-c 的重写，可以将其删除，因为没有效果。
文字和 on-text 颜色
v25 有每个步骤一个文字标记，--dwc-color-{name}-text-{step}，该标记是从 -c 阈值计算的纯黑或白色，旨在用作该步骤作为背景里的文字。
v26 保留相同的标记名称，但其含义发生变化，并增加第二个每步的标记：
| 标记 | v25 含义 | v26 含义 |
|---|---|---|
--dwc-color-{name}-text-{step} | 纯黑/白，旨在作为该阴影里的背景文字 | 着色的 表面安全 文字，在中性页面背景上可读 |
--dwc-color-on-{name}-text-{step} | （未作为每步标记存在） | 着色的文字用于 在 那一步做背景 |
v26 两个标记都根据其预期背景的 WCAG AA 对比度进行限制。如果您将 --dwc-color-{name}-text-{step} 作为有色背景上的前景，请切换到 --dwc-color-on-{name}-text-{step}（新的 on-text 标记）以保持该语义。
着色和边框
生成器现在为每个调色板发出三个标记 ，一个真正的新标记，一个新变体，以及一个移动了源的标记：
| 标记 | v25 | v26 |
|---|---|---|
--dwc-color-{name}-tint | （未存在） | 种子透明度 12%，用于替代背景 |
--dwc-border-color-{name}-emphasis | （未存在） | 更强的模式感知边框，用于悬停/聚焦/激活 |
--dwc-border-color-{name} | 在每个变体中设置为 var(--dwc-color-{name})（饱和色调） | 在生成器中计算：模式感知的轻度种子色调 |
如果您的 CSS 读取 --dwc-border-color-primary 期待饱和的主色，视觉效果现在变成了细微的分隔线色调。如果您特意想要饱和的外观，请直接切换到 --dwc-color-primary。
暗模式
暗模式由一个变量 --dwc-dark-mode 控制。设置为 1 为暗模式，0 为亮模式：
html[data-app-theme='my-dark-theme'] {
--dwc-dark-mode: 1;
color-scheme: dark;
}
它参与整个系统中的 calc() 表达式，它是模式适应传播到表面、阴影、边框和文本颜色的方式。
在 v25 中，内置的 dark 和 dark-pure 主题必须手动重新定义表面、阴影和许多调色板变体。在 v26 中，所有这些内容都从 --dwc-dark-mode 和种子颜色派生。典型的自定义暗主题，过去需要 20 行的重写，现在能简化为：
html[data-app-theme='my-dark-theme'] {
--dwc-dark-mode: 1;
--dwc-color-primary-h: 280;
color-scheme: dark;
}
如果您有从 v25 结构复制的自定义暗主题，通常可以删除大部分内部块，只保留种子和暗模式标志。
表面和 default
在 v25 中，表面被定义了两次，一次在 :root 中用于亮模式（hsl(default-h, default-s, 96%) 等），一次在暗主题中（hsl(default-h, default-s, 8%) 等）。default 变体指向调色板步骤，并且同样需要暗主题的重写。
在 v26 中，两个都只计算一次，并在亮度计算中融合了 --dwc-dark-mode 术语，这确保了：
- 表面总是稍微低于
default，因此卡片在页面上视觉上浮动。 - 在两种模式下都对主色调应用了一点轻微的色调。
dark-pure主题设置--dwc-color-default-s: 0%，自动将色调降低至零。
如果您的应用重写了 --dwc-surface-1（或其他任何表面）为固定颜色，它仍然有效；您只是选择退出了自动模式适应。
--dwc-color-{name}-alt 标记的源也发生变化：
| 标记 | v25 | v26 |
|---|---|---|
--dwc-color-{name}-alt | 调色板步骤 95（接近白色背景） | 种子透明度 12%（半透明色调） |
如果您将 -alt 用作实心的接近白色背景，它现在将读取为半透明着色的叠加。您可以选择特定的步骤（--dwc-color-{name}-95）或围绕半透明语义设计。
阴影
六级缩放（xs、s、m、l、xl、2xl）的名称和数量保持不变，但层偏移已重新构建，以实现更真实的衰减，且暗模式阴影现在通过 --dwc-shadow-strength 自动增强 5 倍，因为暗表面需要更多对比度来传达深度。
如果您只使用 var(--dwc-shadow)，则获取的是重新调整后的中等阴影，其他内容没有变化。--dwc-shadow-color 变量仍然会被生成，但其值格式已更改：
| v25 | v26 | |
|---|---|---|
--dwc-shadow-color | HSL 三元组（h, s%, l%） | 完整的 OKLCH 颜色 |
如果您的 CSS 使用了旧三元组形式，比如 hsla(var(--dwc-shadow-color), 0.07)，请切换到完整的阴影标记（var(--dwc-shadow-m)）或用 oklch(from var(--dwc-shadow-color) l c h / 0.07) 进行重写。
排版
组件大小标记（--dwc-size-*）保持不变。字体比例重新调整，以将 m 级固定在其他 DWC 标记中使用的相同轻体大小，因此名称级别向下移动了一步：
| 标记 | v25 | v26 |
|---|---|---|
--dwc-font-size-3xs | 10px | 10px |
--dwc-font-size-2xs | 12px | 11px |
--dwc-font-size-xs | 13px | 12px |
--dwc-font-size-s | 14px | 13px |
--dwc-font-size-m | 16px | 14px |
--dwc-font-size-l | 18px | 16px |
--dwc-font-size-xl | 22px | 20px |
--dwc-font-size-2xl | 28px | 26px |
--dwc-font-size-3xl | 36px | 34px |
默认的 --dwc-font-size 仍解析为 14px，只是通过 --dwc-font-size-m（v26）而不是 --dwc-font-size-s（v25）到达。
如果您的 CSS 通过名称引用字体大小标记（例如 font-size: var(--dwc-font-size-l)），则 v26 中可见结果将较小。请向上跳一档以保持 v25 尺寸。
字体权重添加了三个标记（thin、medium、black），一个现有标记发生了变化：
| 标记 | v25 | v26 |
|---|---|---|
--dwc-font-weight-semibold | 500 | 600 |
--dwc-font-weight-medium | （未存在） | 500 |
如果您使用 --dwc-font-weight-semibold 获取 500 权重文本，请切换到新的 --dwc-font-weight-medium。
行高级别与字体大小同样向下移动；默认的 --dwc-font-line-height 仍解析为 1.25。
--dwc-font-family-sans 和 --dwc-font-family-mono 已现代化地使用 system-ui 和 ui-monospace 堆栈。如果您从旧堆栈中针对特定命名字体（如 Dank Mono、Operator Mono、Roboto 等）想要恢复，设置 --dwc-font-family 为您控制的堆栈。
间距
空间比例从 xs 开始保持不变。只有最小的两个标记被四舍五入为整像素值：
| 标记 | v25 | v26 |
|---|---|---|
--dwc-space-3xs | 1.2px | 1px |
--dwc-space-2xs | 2.4px | 2px |
几乎没有任何应用需要采取行动。
边框半径
边框半径现在被种子化。更改 --dwc-border-radius-seed，并且每个步骤（s、m、l、xl、2xl、3xl、4xl）都会成比例缩放。2xs 和 xs 步骤仍保持在固定的像素值（太小而无法有效派生）。
变化有三个：
| v25 | v26 | |
|---|---|---|
| 单位 | em（与父字体大小一起缩放） | rem（与根字体大小一起缩放） |
默认 --dwc-border-radius | --dwc-border-radius-s（4px） | --dwc-border-radius-seed（8px） |
| 可用步骤 | 最高 2xl | 添加 3xl、4xl |
组件感觉在默认情况下更圆润。如果一个嵌套在较大文本中的组件以前通过 em 继承更大的半径，现在不再发生缩放，半径现在固定在根级别。如果要恢复 v25 的默认大小，请将种子减半：
:root {
--dwc-border-radius-seed: 0.25rem; /* 4px，使整个比例减半 */
}
缓和
缓和目录基本保持不变，并为常见情况提供了新的快捷标记：--dwc-ease、--dwc-ease-in、--dwc-ease-out、--dwc-ease-outGlide。请参阅 过渡和缓和 页面以获取完整列表。
过渡
过渡持续时间经过重新平衡以获得更快的感觉：
| 变量 | v25 | v26 |
|---|---|---|
--dwc-transition-slow | 500 ms | 300 ms |
--dwc-transition-medium | 250 ms | 250 ms |
--dwc-transition-fast | 150 ms | 150 ms |
--dwc-transition-x-fast | 50 ms | 100 ms |
如果您依赖特定持续时间，请在 :root 中覆盖它。
焦点环
焦点环现在使用双环模式：一个小的表面颜色间隙，然后是彩色环。这使得在实心按钮和密集布局上保持环可读。
| 变量 | v25 | v26 |
|---|---|---|
--dwc-focus-ring-width | 3px | 2px |
--dwc-focus-ring-a | 0.4 | 0.75 |
--dwc-focus-ring-gap | （无） | 2px |
--dwc-focus-ring-l | 45% | （删除，亮度根据模式计算） |
如果您用 padding: var(--dwc-focus-ring-width) 保留可聚焦元素周围的空间，请将间隙添加到该填充中，以便新的环有空间呈现：
/* v25 */
dwc-button { padding: var(--dwc-focus-ring-width); }
/* v26 */
dwc-button {
padding: calc(var(--dwc-focus-ring-width) + var(--dwc-focus-ring-gap));
}
互动反馈
不再使用 DWC 组件的素材风格涟漪效果。任何可点击元素的新反馈是微小的缩小：
--dwc-scale-press: 0.97; /* 标准的 3% 缩小 */
--dwc-scale-press-deep: 0.93; /* 按钮的深层 7% 缩小 */
ripple SCSS 混合和 --dwc-ripple-color CSS 变量仍然存在于构建中，但默认情况下没有任何导入。如果您的组件选择了混合，请切换到按压缩放标记以匹配新的感觉。
浏览器支持
新系统使用两种 CSS 特性，其浏览器兼 容性表可在 MDN 查看：
- OKLCH 颜色空间，包括相对颜色语法 (
oklch(from ...)) color-mix()
两者均已在常青版本的 Chrome、Edge、Firefox 和 Safari 中发布。
实用的升级检查清单
- 搜索
--dwc-color-*-c并删除这些声明。 - 搜索
hsla(var(--dwc-shadow-color)并替换为阴影标记（var(--dwc-shadow-m)）或以oklch(from ...)进行重写。 - 搜索直接调色板步骤引用（
--dwc-color-{name}-{number}）。如果任何内容提供专门针对暗模式的样式，请切换到变体标记（--dwc-color-{name}、-dark、-light）。 - 搜索命名字体大小引用（
--dwc-font-size-m、-l等）。如果您想要 v25 大小，请向上移动一档。 - 搜索
--dwc-font-weight-semibold。如果您想要 500，请切换到--dwc-font-weight-medium。 - 如果您使用
--dwc-focus-ring-width保留可聚焦元素周围的空间，请将--dwc-focus-ring-gap添加到填充中。 - 打开应用，四处点击。大多数应用不需要其他步骤。