Ordo UI

主题定制

ThemeConfig、Provider、预设、暗色、圆角、字体、i18n 与 RTL

Ordo UI 的主题控制面分三层:

  1. Token 层:theme.css 里的 CSS 变量(颜色 / 圆角 / 字体 / 动效 / z-index)。
  2. 配置层:ThemeConfig + defineTheme + 5 套 baseColor + ordo 品牌预设。
  3. 运行时:可选的 ThemeProvider / ThemeScript 与 I18nProvider。

不包 Provider 也能用:消费方仍可直接覆盖 :root 变量,行为与旧版本一致。

主题编辑器

下面这块是真实组件预览。改控件即可看到颜色、圆角、暗色、对比度、动效、RTL 与语言同时变化。

  • 所有配置会写入 URL,复制分享链接即可复现同一份主题。
  • 预设画廊提供 5 套 baseColor 与 ordo 品牌一键应用。
  • 可在 ThemeConfig JSON / CSS 变量 / React 三种格式之间切换并复制;JSON 导入会用 P2-B 的 theme.schema.json 校验。
  • 底部「变体 Playground」按 registry.variantAxes 枚举变体,实时渲染并生成可复制的 JSX。
主题编辑器
所有配置写入 URL,可分享/回放;支持 ThemeConfig JSON、CSS 变量与 React 代码导出,并能用 P2-B schema 校验后导入。

预设画廊

5 套 baseColor + ordo 品牌
neutraldefaultnormalradius: mddensity: comfortablelocale: zh-CN44 个 CSS 变量
分享链接加载中…
Badge次要
控件
Card
主题 token 实时生效

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
使用 theme.schema.json 校验;导入不会修改 URL 中的模式。

快速开始

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

字段类型默认值说明
baseColorneutral | slate | zinc | stone | grayneutral5 套基础色;通过 data-theme-base 切换
brand{ primary; primaryForeground?; ring? }—HSL 三元组;覆盖主色
radiusnone | sm | md | lg | xlmd只改 --radius 一个根
font{ sans?; mono?; heading? }—写 --font-user-*
densitycompact | comfortable | spaciouscomfortable覆盖控件高度与间距 token
motionfull | reduced | nonefullreduced 关闭动画/过渡
contrastnormal | highnormal高对比语义 token + 焦点/边框加粗;见可访问性
directionltr | rtlltr写 dir 并驱动 Base UI DirectionProvider
localestringzh-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暖灰
grayTailwind gray 基线

ordo 品牌

@import '@mox-hub/ui/themes/ordo.css';

ordo.css 在任意 baseColor 之上覆盖 --primary / --ring;导入顺序放在 base-colors.css 之后。

圆角

圆角只有一个根 --radius,其余全部派生:

token公式默认(--radius: 0.75rem)
--radius-controlcalc(--radius - 0.125rem)10px
--radius-smcalc(--radius - 0.25rem)8px
--radius-mdvar(--radius-control)10px
--radius-lgvar(--radius)12px
--radius-xlcalc(--radius + 0.25rem)16px
--radius-xsmax(0rem, calc(--radius - 0.625rem))2px
--radius-2xscalc(--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 / translate prop 优先级最高;其次是 Provider 目录;最后是组件内置默认。
  • useT() 支持点路径与 {{name}} 插值。
  • useFormatters() 提供 number / compact / percent / currency / date / dateTime / time / relative。
  • direction="rtl" 通过 Base UI DirectionProvider 驱动浮层方向;应用壳仍需在 <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 时行为与旧版本一致;可逐页迁移。