Foundations
Color
语义色、baseColor 预设、tone 与图表色
颜色分三层:核心语义色 → 状态 tone → 图表/内容色。组件只读语义 token,不直接写色值。
核心语义色
| Token | 典型用途 |
|---|---|
background / foreground | 页面底与主文字 |
card / card-foreground | 卡片 |
popover / popover-foreground | 浮层 |
primary / primary-foreground | 主操作 |
secondary / secondary-foreground | 次操作 |
muted / muted-foreground | 弱化底与弱文字 |
accent / accent-foreground | 悬停/选中底 |
destructive / destructive-foreground | 危险操作 |
border / input / ring | 描边、输入框、焦点环 |
<Button>主操作</Button>
<Button variant="outline">次操作</Button>
<Button variant="destructive">危险</Button>baseColor 预设
通过 data-theme-base 切换:neutral / slate / zinc / stone / gray。
<html data-theme-base="zinc" class="dark">也可单独引入 @mox-hub/ui/themes/zinc.css。完整预设见主题页的编辑器。
Tone 五档
状态色唯一链路:业务状态 → Tone → TONE_CLASS。
| Tone | 色 |
|---|---|
default | muted-foreground |
info | accent-blue |
warning | accent-yellow |
success | accent-green |
danger | accent-red |
import { TONE_CLASS } from '@mox-hub/ui/components/tone'语义软底(accent-*-soft)
大面积状态底色用 accent-*-soft + 配套 accent-*-soft-foreground,不要再写
dark:bg-accent-*-light/10 这类覆盖:
<div className="rounded-md bg-accent-green-soft px-2 py-1 text-accent-green-soft-foreground">
定稿
</div>| Token 对 | 浅色 | 暗色 | 高对比度 |
|---|---|---|---|
accent-green-soft / accent-green-soft-foreground | 淡绿底 + 深绿字 | 深绿底 + 亮绿字 | 自动覆盖 |
accent-yellow-soft / accent-yellow-soft-foreground | 淡黄底 + 深黄字 | 深黄底 + 亮黄字 | 自动覆盖 |
accent-blue-soft / accent-blue-soft-foreground | 淡蓝底 + 深蓝字 | 深蓝底 + 亮蓝字 | 自动覆盖 |
accent-red-soft / accent-red-soft-foreground | 淡红底 + 深红字 | 深红底 + 亮红字 | 自动覆盖 |
accent-purple-soft / accent-purple-soft-foreground | 淡紫底 + 深紫字 | 深紫底 + 亮紫字 | 自动覆盖 |
accent-orange-soft / accent-orange-soft-foreground | 淡橙底 + 深橙字 | 深橙底 + 亮橙字 | 自动覆盖 |
- 成对使用才能保证正文对比度 ≥ 4.5:1;
accent-*-light是历史浅底 token,继续保留但不再作为新代码的语义底色。 - 明暗切换由
.dark块完成,消费方不需要dark:覆盖;高对比度值来自theme/contrast.json。 - JS / Canvas 场景可直接用
colors.successSoft、colors.successSoftForeground(另有infoSoft/warningSoft及配套前景)。
遮罩
浮层统一使用模式不变的 scrim,共两档语义 token(暗色自动加深):
<DialogOverlay className="bg-scrim-overlay" />
<AlertDialogOverlay className="bg-scrim-strong" />--color-scrim-overlay:普通浮层(Dialog / Sheet / Drawer / Command),浅色 30%、暗色 60%。--color-scrim-strong:危险确认(AlertDialog),浅色 55%、暗色 75%。--color-scrim是模式不变的黑色基色,仅在需要自定义透明度时使用;不要再用bg-black。
图表色
--chart-1..8 是序列色序,顺序即色序,不得跨图乱序;--chart-grid 供坐标网格线使用:
import { chartColors, chartGrid } from '@mox-hub/ui/tokens'
chartColors[1] // 'hsl(var(--chart-1))'
chartColors[8] // 'hsl(var(--chart-8))'
chartGrid // 'hsl(var(--chart-grid))'图表壳在 @mox-hub/ui/components/chart 子路径导出(recharts 为 optional peer,根入口不引入);旧的 @mox-hub/patterns/components/chart 继续 re-export。
规则
- 禁止
bg-blue-500/text-white/#hex/rgb()直接进组件;lint:palette会拦。 - 状态色不要只靠颜色传达,配合文字、图标或
aria-label。 - 语义底色用
bg-accent-*-soft+text-accent-*-soft-foreground;不要写dark:覆盖,也不要只铺accent-*-light后叠透明度当文字底。 --interactive-*与--text-md已标 deprecated,包内零消费,0.3.0 移除。content-*是 patterns 语义层专用口径,值不与核心 token 完全等价;核心组件新增用色优先background/foreground/muted。