主题定制
ThemeConfig、Provider、预设、暗色、圆角、字体、i18n 与 RTL
Ordo UI 的主题控制面分三层:
- Token 层:
theme.css里的 CSS 变量(颜色 / 圆角 / 字体 / 动效 / z-index)。 - 配置层:
ThemeConfig+defineTheme+ 5 套 baseColor + ordo 品牌预设。 - 运行时:可选的
ThemeProvider/ThemeScript与I18nProvider。
不包 Provider 也能用:消费方仍可直接覆盖 :root 变量,行为与旧版本一致。
主题编辑器
下面这块是真实组件预览。改控件即可看到颜色、圆角、暗色、对比度、动效、RTL 与语言同时变化。
- 所有配置会写入 URL,复制分享链接即可复现同一份主题。
- 预设画廊提供 5 套 baseColor 与 ordo 品牌一键应用。
- 可在 ThemeConfig JSON / CSS 变量 / React 三种格式之间切换并复制;JSON 导入会用 P2-B 的
theme.schema.json校验。 - 底部「变体 Playground」按
registry.variantAxes枚举变体,实时渲染并生成可复制的 JSX。
预设画廊
5 套 baseColor + ordo 品牌加载中…primary / muted / border / radius 都来自当前配置。
暂无数据
变体 Playground
枚举来自 registry.variantAxes;切换后可直接复制 JSX。
<Button>Button</Button>{
"baseColor": "neutral",
"radius": "md",
"density": "comfortable",
"motion": "full",
"contrast": "normal",
"direction": "ltr",
"locale": "zh-CN"
}导入 ThemeConfig JSON
快速开始
CSS-only(不引入 React Provider)
@import 'tailwindcss';
@import '@mox-hub/ui/theme.css';
@source '../node_modules/@mox-hub/ui/dist';
:root {
--radius: 0.5rem;
--primary: 217 91% 60%;
--primary-foreground: 0 0% 100%;
--font-user-sans: 'Inter Variable';
--font-user-mono: 'JetBrains Mono Variable';
}暗色只需在根元素切 .dark:
<html className={theme === 'dark' ? 'dark' : ''} />React Provider(推荐)
import { ThemeProvider, ThemeScript } from '@mox-hub/ui/theme'
import type { ThemeConfig } from '@mox-hub/ui/theme'
const theme: ThemeConfig = {
baseColor: 'zinc',
radius: 'md',
brand: { primary: '217 91% 60%' },
font: { sans: 'Inter Variable' },
}
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="zh-CN" suppressHydrationWarning>
<head>
<ThemeScript theme={theme} />
</head>
<body>
<ThemeProvider theme={theme} defaultMode="system" disableTransitionOnChange>
{children}
</ThemeProvider>
</body>
</html>
)
}ThemeScript 在首帧前写入 .dark / color-scheme / CSS 变量,避免闪烁;CSP 场景传 nonce。
ThemeConfig
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
baseColor | neutral | slate | zinc | stone | gray | neutral | 5 套基础色;通过 data-theme-base 切换 |
brand | { primary; primaryForeground?; ring? } | — | HSL 三元组;覆盖主色 |
radius | none | sm | md | lg | xl | md | 只改 --radius 一个根 |
font | { sans?; mono?; heading? } | — | 写 --font-user-* |
density | compact | comfortable | spacious | comfortable | 覆盖控件高度与间距 token |
motion | full | reduced | none | full | reduced 关闭动画/过渡 |
contrast | normal | high | normal | 高对比语义 token + 焦点/边框加粗;见可访问性 |
direction | ltr | rtl | ltr | 写 dir 并驱动 Base UI DirectionProvider |
locale | string | zh-CN | 写 lang;只区分 zh* / en*;en-XA 为伪语言 |
defineTheme(config) 是纯函数,返回:
{
cssVars: { '--radius': '0.75rem', '--primary': '217 91% 60%', ... },
attributes: {
'data-theme-base': 'zinc',
'data-density': 'comfortable',
'data-motion': 'full',
'data-contrast': 'normal',
dir: 'ltr',
lang: 'zh-CN',
},
}预设
baseColor
theme.css 已内置 5 套颜色变量。引入后只需设置 data-theme-base:
<html data-theme-base="zinc" class="dark">也可以单独引入:
@import '@mox-hub/ui/themes/zinc.css';| 预设 | 适用 |
|---|---|
neutral | 默认,纯中性 |
slate | 冷灰,偏蓝 |
zinc | 现代灰,shadcn 默认常用 |
stone | 暖灰 |
gray | Tailwind gray 基线 |
ordo 品牌
@import '@mox-hub/ui/themes/ordo.css';ordo.css 在任意 baseColor 之上覆盖 --primary / --ring;导入顺序放在 base-colors.css 之后。
圆角
圆角只有一个根 --radius,其余全部派生:
| token | 公式 | 默认(--radius: 0.75rem) |
|---|---|---|
--radius-control | calc(--radius - 0.125rem) | 10px |
--radius-sm | calc(--radius - 0.25rem) | 8px |
--radius-md | var(--radius-control) | 10px |
--radius-lg | var(--radius) | 12px |
--radius-xl | calc(--radius + 0.25rem) | 16px |
--radius-xs | max(0rem, calc(--radius - 0.625rem)) | 2px |
--radius-2xs | calc(--radius / 3) | 4px |
所以改一个值,Button / Input / Select / Checkbox / Card / Dialog / Toast 全部一起变。
字体
:root {
--font-user-sans: 'Inter Variable';
--font-user-mono: 'JetBrains Mono Variable';
--font-user-heading: 'Inter Display';
}库不捆绑字体;建议消费方自装 fontsource,禁 CDN(宪法 §2.2)。
暗色模式
theme.css 使用 class 策略:在根元素加 .dark 即整站翻转。ThemeProvider 已内置:
light/dark/system三档;system监听prefers-color-scheme;localStorage持久化,跨标签页同步;disableTransitionOnChange切换瞬间关闭过渡;color-scheme同步,原生控件/滚动条跟随主题。
const { mode, resolvedMode, setMode } = useTheme()不包 Provider 时,消费方自行切 .dark 即可;theme-mode-card 可以接 useTheme:
<ThemeModeCard value={mode} onChange={setMode} title="主题模式" options={options} />i18n 与 RTL
@mox-hub/ui/i18n 提供全局语言、文案目录与格式化:
import { I18nProvider } from '@mox-hub/ui/i18n'
<I18nProvider locale="en-US" direction="rtl">
<App />
</I18nProvider>- 内置
zh-CN/en-US目录;未包 Provider 时回落zh-CN。en-US为参考翻译,不承诺最终翻译质量。 locale="en-XA"使用伪语言(+30% 长度、重音字符),仅用于视觉回归;见可访问性。- 组件级
labels/translateprop 优先级最高;其次是 Provider 目录;最后是组件内置默认。 useT()支持点路径与{{name}}插值。useFormatters()提供 number / compact / percent / currency / date / dateTime / time / relative。direction="rtl"通过 Base UIDirectionProvider驱动浮层方向;应用壳仍需在<html>或容器上设置dir。
RTL 写作约定
- 间距/对齐一律用逻辑属性:
ms-*/me-*/ps-*/pe-*、start-*/end-*、text-start/text-end、rounded-s-*/rounded-e-*、border-s/border-e。 - 方向性图标加
rtl:-scale-x-100(Chevron、Arrow、子菜单箭头);数字、时间、代码保持 LTR。 - 以下场景保留物理值:居中定位(
left-1/2 -translate-x-1/2)、Toast 的position="left/right"、Drawer 的 swipe direction、Tabs 指示器的像素测量。 lint:rtl扫描ui与patterns的组件源码,新增物理类会直接失败。
文案覆盖审计
pnpm i18n:coverage # 生成 docs/i18n-coverage-YYYY-MM-DD.md
pnpm lint:i18n # 有「中文文案但无覆写入口」时失败审计会扫描 ui / patterns 的 TSX AST,区分 Provider、labels / translate / translator 与 *Label props,并列出缺口。
语义层(patterns)扩展目录:
<I18nProvider
locale="en-US"
messages={{
approvalCard: { riskHigh: 'High risk' },
decisionQueuePanel: { title: 'Your turn' },
}}
>Token 注册纪律(护栏强制)
- 颜色只走语义 token:
bg-primary/text-accent-blue;原生色板类被lint:palette拦截。 - 字阶只用
3xs/2xs/xs/sm/md/base/lg/xl/2xl(lint:spacing)。 - 动效时长只用
duration-fast/normal/slow。 - z-index 七档:
z-base … z-toast。 - 新类名未注册,
lint:undefined的幽灵类探针会拦下。 - 主题 CSS 由
gen-themes从base-colors.json生成;lint:themes校验漂移。
迁移与排查
- 圆角不变:检查改的是
--radius还是旧的--radius-control;现在后者是派生值。 - 暗色闪烁:确认
ThemeScript在<head>内同步执行,且<html suppressHydrationWarning>。 - 颜色不生效:确认
@source指向包产物或源码,且theme.css在 Tailwind 之后引入。 - 中文没切英文:检查是否包了
I18nProvider,以及组件是否显式传了labels/translate(prop 优先)。 - 旧项目:不包 Provider 时行为与旧版本一致;可逐页迁移。