Next UI Design Tokens Specification
本规范定义了 Next UI 的核心设计变量（Design Tokens），采用 “前缀镜像（Prefix-Mirroring）” 策略，在命名上与 Microsoft Fluent UI 保持一致，但视觉表现可完全独立定制。
1. 命名规则 (Naming Strategy)
1.1 前缀映射
- Fluent UI:
--ms-[Name] - Next UI:
--sx-[Name](如：--sx-colorNeutralBackground1)
1.2 语义化命名
变量名应反映其用途（Semantic），而非具体的颜色值。
Background: 用于背景Foreground: 用于文字/图标Stroke: 用于边框/分割线Brand: 品牌色
2. 核心颜色令牌 (Core Color Tokens)
2.1 中性色 (Neutral Colors)
| 变量名 | 默认值 (Light) | 默认值 (Dark) | 用途描述 |
|---|---|---|---|
--sx-colorNeutralBackground1 |
#ffffff |
#161616 |
页面主背景 |
--sx-colorNeutralBackground2 |
#fafafa |
#1f1f1f |
次级背景（如卡片、测边栏） |
--sx-colorNeutralForeground1 |
#242424 |
#ffffff |
主要文字颜色 |
--sx-colorNeutralForeground2 |
#424242 |
#d6d6d6 |
次要文字颜色 |
--sx-colorNeutralStroke1 |
#d1d1d1 |
#444444 |
标准边框颜色 |
2.2 主题色/重点色 (Primary Color Palette)
主题色支持动态生成完整调色板（P50-P900），可通过 ThemeState 或 ThemeRuntime 动态设置任意颜色作为主题色。
| 变量名 | 默认值 (Light) | 默认值 (Dark) | 用途描述 |
|---|---|---|---|
--sx-primary-seed |
#3B82F6 |
#3B82F6 |
主题色种子（用户可自定义） |
--sx-primary-50 |
#EFF6FF |
#EFF6FF |
最浅色（背景/高亮） |
--sx-primary-100 |
#DBEAFE |
#DBEAFE |
浅色（悬浮背景） |
--sx-primary-200 |
#BFDBFE |
#BFDBFE |
浅色（次要背景） |
--sx-primary-300 |
#93C5FD |
#93C5FD |
中浅色 |
--sx-primary-400 |
#60A5FA |
#60A5FA |
中色 |
--sx-primary-500 |
#3B82F6 |
#479ef5 |
基准色（主要按钮/链接） |
--sx-primary-600 |
#2563EB |
#6cb8f6 |
中深色（悬浮状态） |
--sx-primary-700 |
#1D4ED8 |
#1D4ED8 |
深色（激活状态） |
--sx-primary-800 |
#1E40AF |
#1E40AF |
更深色 |
--sx-primary-900 |
#1E3A8A |
#1E3A8A |
最深色（强调） |
语义化别名（向后兼容）：
--sx-colorBrandBackground1:var(--sx-primary-500)- 品牌背景色（Button Primary）--sx-colorBrandBackground2:var(--sx-primary-600)- 品牌背景色（悬浮）--sx-colorBrandForeground1:var(--sx-primary-500)- 品牌前景色（Action）
注意：主题色调色板由运行时动态生成，默认值会在页面加载时被覆盖。调色板生成算法与 ThemeState.GeneratePalette() 保持一致。
3. 图标皮肤化令牌 (Icon Tokens)
兼容 Font Awesome 6 Pro，并支持通过变量控制视觉风格。
| 变量名 | 默认值 | 用途描述 |
|---|---|---|
--sx-icon-size |
1rem |
默认图标大小 |
--sx-icon-weight |
400 |
图标线条粗细（兼容 Light/Regular/Thin） |
--sx-icon-primary-opacity |
1.0 |
双色图标主层不透明度 |
--sx-icon-secondary-opacity |
0.4 |
双色图标次层不透明度 |
4. 布局密度与间距 (Layout Density & Spacing)
4.1 布局密度 (Layout Density)
支持全局布局密度调整，类似 Gmail 的密度设置。所有间距基于密度因子动态缩放。
| 变量名 | 默认值 | 用途描述 |
|---|---|---|
--sx-density-scale |
1.0 |
布局密度缩放因子（用户可自定义，如 0.6, 0.8, 1.0, 1.3, 1.6） |
预设密度级别：
- Extra Tight (0.6): 特别紧凑，适合数据表格、工作台
- Compact (0.8): 紧凑，适合邮件列表、任务管理
- Comfortable (1.0): 正常（默认），平衡信息密度和可读性
- Spacious (1.3): 宽松，适合阅读、浏览
- Extra Spacious (1.6): 特别宽松，适合演示、展示
注意：--sx-density-scale 由运行时动态注入，默认值会在页面加载时被覆盖。
4.2 基础间距 (Base Spacing)
基础间距值不受密度影响，作为计算的基准值：
| 变量名 | 默认值 | 用途描述 |
|---|---|---|
--sx-spacing-base-xs |
0.25rem |
基础极小间距 |
--sx-spacing-base-sm |
0.5rem |
基础小间距 |
--sx-spacing-base-md |
0.75rem |
基础中等间距 |
--sx-spacing-base-lg |
1rem |
基础大间距 |
--sx-spacing-base-xl |
1.5rem |
基础超大间距 |
4.3 应用间距 (Applied Spacing)
应用间距基于基础间距和密度因子动态计算，推荐在组件中使用这些变量：
| 变量名 | 计算公式 | 用途描述 |
|---|---|---|
--sx-spacing-xs |
calc(var(--sx-spacing-base-xs) * var(--sx-density-scale, 1)) |
极小间距 |
--sx-spacing-sm |
calc(var(--sx-spacing-base-sm) * var(--sx-density-scale, 1)) |
小间距 |
--sx-spacing-md |
calc(var(--sx-spacing-base-md) * var(--sx-density-scale, 1)) |
中等间距 |
--sx-spacing-lg |
calc(var(--sx-spacing-base-lg) * var(--sx-density-scale, 1)) |
大间距 |
--sx-spacing-xl |
calc(var(--sx-spacing-base-xl) * var(--sx-density-scale, 1)) |
超大间距 |
4.4 语义化间距 (Semantic Spacing)
语义化间距变量提供更明确的用途表达，自动应用密度缩放：
| 变量名 | 对应值 | 用途描述 |
|---|---|---|
--sx-spacing-none |
0 |
无间距 |
--sx-spacing-component-padding |
var(--sx-spacing-md) |
组件内边距 |
--sx-spacing-component-gap |
var(--sx-spacing-sm) |
组件内部间距 |
--sx-spacing-layout-gap |
var(--sx-spacing-lg) |
布局间距 |
--sx-spacing-section-gap |
var(--sx-spacing-xl) |
区块间距 |
--sx-spacing-list-item-gap |
var(--sx-spacing-sm) |
列表项间距 |
--sx-spacing-list-section-gap |
var(--sx-spacing-md) |
列表区块间距 |
4.5 方向性间距 (Directional Spacing)
保持向后兼容的方向性间距变量：
| 变量名 | 对应值 | 用途描述 |
|---|---|---|
--sx-spacingHorizontalSmall |
var(--sx-spacing-sm) |
水平小间距 |
--sx-spacingHorizontalMedium |
var(--sx-spacing-md) |
水平中等间距 |
--sx-spacingVerticalSmall |
var(--sx-spacing-xs) |
垂直小间距 |
--sx-spacingVerticalMedium |
var(--sx-spacing-sm) |
垂直中等间距 |
4.6 形状 (Shape)
圆角大小不受密度影响，保持视觉一致性：
| 变量名 | 默认值 | 用途描述 |
|---|---|---|
--sx-borderRadiusSmall / --sx-radius-sm |
0.25rem |
小圆角 |
--sx-borderRadiusMedium / --sx-radius-md |
0.5rem |
标准圆角 (Button, Input, Card) |
--sx-borderRadiusLarge / --sx-radius-lg |
0.75rem |
大圆角 |
--sx-radius-xl |
1rem |
超大圆角 |
4.7 控件尺寸 (Control Dimensions)
控件高度受密度部分影响（80%-100% 范围），既保持可点击性，又体现密度差异：
| 变量名 | 计算公式 | 用途描述 |
|---|---|---|
--sx-control-height-sm |
calc(1.75rem * (0.8 + 0.2 * var(--sx-density-scale, 1))) |
小控件高度 |
--sx-control-height-md |
calc(2.25rem * (0.8 + 0.2 * var(--sx-density-scale, 1))) |
标准控件高度 |
--sx-control-height-lg |
calc(3rem * (0.8 + 0.2 * var(--sx-density-scale, 1))) |
大控件高度 |
--sx-controlMinHeight |
var(--sx-control-height-md) |
控件最小高度（向后兼容） |
5. 字体与排版 (Typography)
5.1 字体缩放 (Font Scale)
支持全局字体缩放，所有字体大小基于 --sx-font-scale 动态计算。
| 变量名 | 默认值 | 用途描述 |
|---|---|---|
--sx-font-scale |
1.0 |
字体缩放因子（用户可自定义，如 0.8, 1.0, 1.2, 1.5） |
注意：--sx-font-scale 由运行时动态注入，默认值会在页面加载时被覆盖。
5.2 字体大小 (Font Sizes)
所有字体大小变量基于 --sx-font-scale 动态计算，确保缩放时整体界面协调变化。
| 变量名 | 计算公式 | 用途描述 |
|---|---|---|
--sx-font-size-base |
calc(1rem * var(--sx-font-scale, 1)) |
基准字体大小 |
--sx-font-size-xs |
calc(0.75rem * var(--sx-font-scale, 1)) |
极小字体（辅助文字） |
--sx-font-size-sm |
calc(0.875rem * var(--sx-font-scale, 1)) |
小字体（标准正文/控件） |
--sx-font-size-lg |
calc(1.125rem * var(--sx-font-scale, 1)) |
大字体（标题/强调） |
--sx-font-size-xl |
calc(1.5rem * var(--sx-font-scale, 1)) |
超大字体（主标题） |
字体粗细：
| 变量名 | 默认值 | 用途描述 |
|---|---|---|
--sx-font-weight-normal |
400 |
正常粗细 |
--sx-font-weight-semibold |
600 |
半粗体 |
--sx-font-weight-bold |
700 |
粗体 |
6. CSS 隔离规范
- 全局: 只允许引用
sx-tokens.css（包含以上变量）。 - 局部: 组件样式必须使用
.sx-前缀，并配合 Blazor CSS 隔离或 Shadow DOM。
7. 动态变量说明
以下变量由运行时（ThemeRuntime 或 SxThemeProvider）动态注入，默认值仅作为初始值：
- 主题色调色板 (
--sx-primary-*): 由用户选择的主题色动态生成 - 字体缩放 (
--sx-font-scale): 由用户偏好设置动态设置 - 布局密度 (
--sx-density-scale): 由用户偏好设置动态设置
这些变量的值会在页面加载时从 localStorage 读取并注入到 CSS，确保用户偏好设置能够持久化并跨页面同步。
7.1 密度与字体缩放的关系
- 独立：密度缩放和字体缩放是独立的设置
- 协同：可以同时使用，例如：
- 大字体 + 宽松布局 = 适合阅读场景
- 小字体 + 紧凑布局 = 适合工作台场景