Appearance
Semantic Token
每个 Token 都表达用途,而不是某个固定颜色。切换 Latte / Macchiato 时,业务 utility 不变。
使用规则
- 页面、容器和浮层分别使用
background、surface、surface-elevated,层级同时依赖 tone、border 与 shadow。 primary是最高优先级行为;accent只负责 hover、selection 和轻量选中。ring专用于focus-visible,不与primary强制相等。error是颜色语义,组件层的destructive行为映射到它。tip是无状态的建议;有明确系统状态时使用info。
完整规范
下表由 packages/ui 直接渲染,因此文档值与发布包不会漂移。实心背景与 foreground pairing 需达到 WCAG AA;subtle 组合按正文场景检查。
| Token | 语义 / 使用边界 | Foreground | Latte | Macchiato | UnoCSS |
|---|---|---|---|---|---|
background | 页面最底层画布。应用和完整页面背景。避免:不要用来模拟悬浮层。 | foreground | #eff1f5 | #181926 | bg-backgroundvar(--pd-color-background) |
foreground | 页面默认文字和图标。正文及高优先级内容。避免:不要用于彩色实心背景。 | — | #4c4f69 | #cad3f5 | text-foregroundvar(--pd-color-foreground) |
surface | 普通区域容器。侧栏、面板和分组区域。避免:不要替代页面背景。 | surface-foreground | #e6e9ef | #1e2030 | bg-surfacevar(--pd-color-surface) |
surface-foreground | 区域容器内的默认文字。侧栏与面板的正文和标题。避免:不要用于容器之外的页面级文字。 | — | #4c4f69 | #cad3f5 | text-surface-foregroundvar(--pd-color-surface-foreground) |
surface-subtle | 弱化的次级表面。表头、分组和禁用区域。避免:不要承载最高优先级操作。 | — | #dce0e8 | #24273a | bg-surface-subtlevar(--pd-color-surface-subtle) |
surface-elevated | 视觉层级更高的表面。菜单、对话框和浮层。避免:不要仅靠阴影表达层级。 | — | #ffffff | #363a4f | bg-surface-elevatedvar(--pd-color-surface-elevated) |
card | 承载一组内容的卡片表面。指标卡、列表项和表单分组。避免:不要在卡片内再嵌套同级卡片。 | card-foreground | #ffffff | #24273a | bg-cardvar(--pd-color-card) |
card-foreground | 卡片表面上的默认文字。卡片标题与正文。避免:不要用在卡片之外的表面。 | — | #4c4f69 | #cad3f5 | text-card-foregroundvar(--pd-color-card-foreground) |
popover | 脱离文档流的浮层表面。菜单、下拉、Tooltip 与对话框。避免:不要用于静态布局分块。 | popover-foreground | #ffffff | #363a4f | bg-popovervar(--pd-color-popover) |
popover-foreground | 浮层内的默认文字。菜单项、命令面板与对话框文本。避免:不要用于页面内联内容。 | — | #4c4f69 | #cad3f5 | text-popover-foregroundvar(--pd-color-popover-foreground) |
primary | 最高优先级行为和品牌表达。主按钮、关键选中态。避免:不要铺满大面积背景。 | primary-foreground | #006b67 | #69c7bd | bg-primaryvar(--pd-color-primary) |
primary-foreground | primary 实心背景上的文字与图标。主按钮标签和 primary 徽标。避免:不要当作独立文字色用在浅色背景上。 | — | #ffffff | #181926 | text-primary-foregroundvar(--pd-color-primary-foreground) |
primary-strong | primary 的加深变体。主按钮 hover 与 pressed 态。避免:不要与 primary 并列为两个品牌色。 | — | #005450 | #8bd5ca | bg-primary-strongvar(--pd-color-primary-strong) |
secondary | 次级交互表面。次按钮和弱选中态。避免:不要与 primary 竞争。 | secondary-foreground | #e2e7f0 | #363a4f | bg-secondaryvar(--pd-color-secondary) |
secondary-foreground | 次级交互表面上的文字。次按钮标签与弱选中态文字。避免:不要用于主操作。 | — | #414559 | #cad3f5 | text-secondary-foregroundvar(--pd-color-secondary-foreground) |
accent | 短暂或轻量强调。hover、selection、active。避免:不等同于品牌主色。 | accent-foreground | #d8dce7 | #41455c | bg-accentvar(--pd-color-accent) |
accent-foreground | accent 背景上的文字。hover 行与选中行的文字。避免:不要替代 foreground 承担正文。 | — | #4c4f69 | #cad3f5 | text-accent-foregroundvar(--pd-color-accent-foreground) |
muted | 弱内容背景。占位、禁用和辅助区域。避免:不要用于关键状态。 | muted-foreground | #e6e9ef | #24273a | bg-mutedvar(--pd-color-muted) |
muted-foreground | 弱化的辅助文字。说明、时间戳和次要元信息。避免:不要承载正文主体内容。 | — | #5c5f77 | #a5adcb | text-muted-foregroundvar(--pd-color-muted-foreground) |
border | 默认结构边界。卡片、分隔和控件边缘。避免:不要承担焦点指示。 | — | #bcc0cc | #494d64 | border-bordervar(--pd-color-border) |
border-muted | 最弱的分隔边界。表格行与列表项之间的浅分隔。避免:不要用于控件轮廓。 | — | #dce0e8 | #363a4f | border-border-mutedvar(--pd-color-border-muted) |
border-strong | 加强的结构边界。需要明确分界的容器与分隔线。避免:不要用于文字或图标。 | — | #9ca0b0 | #6e738d | border-border-strongvar(--pd-color-border-strong) |
input | 输入控件边界。表单控件静止态。避免:不要用于 focus ring。 | — | #c6cad4 | #5b6078 | border-inputvar(--pd-color-input) |
ring | 键盘焦点指示。focus-visible 外环。避免:不要用 hover 代替。 | — | #008080 | #8bd5ca | ring-ringvar(--pd-color-ring) |
info | 明确的信息状态。同步、运行、版本提示。避免:不要用于普通技巧。 | info-foreground | #1e66f5 | #8aadf4 | bg-infovar(--pd-color-info) |
info-foreground | info 实心背景上的文字。实心信息徽标与提示条文字。避免:不要当作文字色用在浅色背景上。 | — | #ffffff | #18203b | text-info-foregroundvar(--pd-color-info-foreground) |
info-subtle | info 的浅色背景。信息提示条与状态标签底色。避免:不要用于大面积页面背景。 | info-subtle-foreground | #dce8ff | #293a58 | bg-info-subtlevar(--pd-color-info-subtle) |
info-subtle-foreground | info 浅色背景上的文字。提示条正文与状态标签文字。避免:不要与 info 实心色互换使用。 | — | #17407f | #b8d4ff | text-info-subtle-foregroundvar(--pd-color-info-subtle-foreground) |
info-border | info 状态区域的边界。提示条与状态卡片的描边。避免:不要用于普通结构边界。 | — | #8eb2fa | #5276a8 | border-info-bordervar(--pd-color-info-border) |
warning | 需要注意、仍可继续的状态,作为实心背景使用。实心警告按钮、徽标与 Toast 底色。避免:不要当作浅色背景上的文字色——文字请用 warning-subtle-foreground。 | warning-foreground | #f0b429 | #eed49f | bg-warningvar(--pd-color-warning) |
warning-foreground | warning 实心背景上的文字,用深色以承载浅琥珀底。实心警告按钮、徽标与 Toast 的文字。避免:不要用在 warning 之外的其他背景上。 | — | #5c3d00 | #3a2c16 | text-warning-foregroundvar(--pd-color-warning-foreground) |
warning-subtle | warning 的浅色背景。风险提示条与待复核标签底色。避免:不要用于已失败状态。 | warning-subtle-foreground | #fff0d1 | #4a3c28 | bg-warning-subtlevar(--pd-color-warning-subtle) |
warning-subtle-foreground | warning 浅色背景上的文字。风险提示正文。避免:不要表达错误结论。 | — | #8a5600 | #ffe2a8 | text-warning-subtle-foregroundvar(--pd-color-warning-subtle-foreground) |
warning-border | warning 状态区域的边界。风险提示条与待复核卡片描边。避免:不要用于普通结构边界。 | — | #dfa94f | #7c6841 | border-warning-bordervar(--pd-color-warning-border) |
error | 错误和失败的颜色语义。校验失败和危险结果。避免:destructive 应在组件层映射到它。 | error-foreground | #bc2446 | #ed8796 | bg-errorvar(--pd-color-error) |
error-foreground | error 实心背景上的文字。实心错误徽标与危险按钮标签。避免:不要当作文字色用在浅色背景上。 | — | #ffffff | #3b1821 | text-error-foregroundvar(--pd-color-error-foreground) |
error-subtle | error 的浅色背景。错误提示条与危险操作 hover 底色。避免:不要用于成功反馈。 | error-subtle-foreground | #ffe0e7 | #4a2934 | bg-error-subtlevar(--pd-color-error-subtle) |
error-subtle-foreground | error 浅色背景上的文字。错误提示正文与校验失败文案。避免:不要用于中性警告。 | — | #81243b | #ffb8c2 | text-error-subtle-foregroundvar(--pd-color-error-subtle-foreground) |
error-border | error 状态区域的边界。错误提示条与校验失败描边。避免:不要用于普通结构边界。 | — | #e59aaa | #84515f | border-error-bordervar(--pd-color-error-border) |
success | 成功完成的状态。保存、同步、检查通过。避免:不要用于普通品牌强调。 | success-foreground | #347827 | #a6da95 | bg-successvar(--pd-color-success) |
success-foreground | success 实心背景上的文字。实心成功徽标文字。避免:不要当作文字色用在浅色背景上。 | — | #ffffff | #1e301d | text-success-foregroundvar(--pd-color-success-foreground) |
success-subtle | success 的浅色背景。成功提示条与已完成标签底色。避免:不要用于进行中状态。 | success-subtle-foreground | #ddf2d7 | #2d4430 | bg-success-subtlevar(--pd-color-success-subtle) |
success-subtle-foreground | success 浅色背景上的文字。成功提示正文与已完成标签文字。避免:不要用于品牌强调。 | — | #315d28 | #c3edb5 | text-success-subtle-foregroundvar(--pd-color-success-subtle-foreground) |
success-border | success 状态区域的边界。成功提示条与已完成卡片描边。避免:不要用于普通结构边界。 | — | #8bc47e | #57795a | border-success-bordervar(--pd-color-success-border) |
tip | 无状态性质的建议和技巧。推荐、辅助说明、轻量高亮。避免:不要表达系统信息状态。 | tip-foreground | #006b67 | #69c7bd | bg-tipvar(--pd-color-tip) |
tip-foreground | tip 实心背景上的文字。实心建议徽标文字。避免:不要当作文字色用在浅色背景上。 | — | #ffffff | #182725 | text-tip-foregroundvar(--pd-color-tip-foreground) |
tip-subtle | tip 的浅色背景。建议、推荐与轻量高亮底色。避免:不要表达系统状态。 | tip-subtle-foreground | #d8f2ef | #274340 | bg-tip-subtlevar(--pd-color-tip-subtle) |
tip-subtle-foreground | tip 浅色背景上的文字。建议与辅助说明正文。避免:不要用于信息或错误状态。 | — | #174f4c | #b6e9e2 | text-tip-subtle-foregroundvar(--pd-color-tip-subtle-foreground) |
tip-border | tip 区域的边界。建议卡片与提示条描边。避免:不要用于普通结构边界。 | — | #79bdb7 | #4f7772 | border-tip-bordervar(--pd-color-tip-border) |