Ordo UI
Foundations

可访问性与高对比度

高对比度 token、forced-colors 强制色与 en-XA 伪语言的接入与验证方式。

可访问性与高对比度

Ordo UI 在主题层提供三档可访问性能力,不要求组件逐个改造:

能力入口适用场景
高对比度theme={{ contrast: 'high' }} 或根元素 data-contrast="high"低视力、强光环境、合规验收
强制色系统级 forced-colors: activeWindows 高对比度模式
伪语言I18nProvider locale="en-XA"视觉回归、文案变长/截断检查

高对比度

<ThemeProvider theme={{ baseColor: 'neutral', contrast: 'high' }}>
  <App />
</ThemeProvider>

ThemeProvider 会把 data-contrast="high" 写到 <html>。CSS-only 接入也可以直接挂属性:

<html data-contrast="high" data-theme-base="neutral">

覆盖范围

高对比度只覆盖语义 token,不修改任何组件类:

  • 背景/前景固定为纯白/纯黑,muted-foreground、content-text-muted 等弱文本仍保持 ≥ 4.5:1。
  • 边框、输入框、焦点环提高到非文本 3:1 以上;--ring 使用深蓝/亮蓝而不是中性灰。
  • 图表 8 色与网格线切换为高对比色板,保证图形对象可分辨。
  • 组件行为层另加三条规则:
    • 所有 :focus-visible 增加 3px --ring outline;
    • button / 表单控件 / checkbox / radio / switch 边框加粗到 2px;
    • disabled / data-disabled / aria-disabled="true" 的透明度从 0.5 提到 0.7,避免弱到不可读。

token 数据源是 packages/ui/src/theme/contrast.json,CSS 由 scripts/gen-contrast.mjs 生成到 src/styles/themes/contrast.css。修改 token 后运行:

pnpm --filter @mox-hub/ui gen:contrast
pnpm --filter @mox-hub/ui lint:contrast   # CI 对账

src/theme/contrast.test.ts 会逐对计算 WCAG 对比度:文本 token ≥ 4.5:1,边框/焦点/图表 token ≥ 3:1。新增 token 时请同时补 pair。

品牌色注意事项

brand.primary / brand.ring 由 ThemeProvider 写成内联 CSS 变量,优先级高于高对比样式表。高对比度不会自动校正品牌色,接入方需保证:

  • primary 与 primaryForeground ≥ 4.5:1(内置 ordo 品牌为 4.67:1);
  • ring 与背景 ≥ 3:1。

若品牌色无法满足,建议在高对比模式下不传 brand,使用高对比语义 token。

forced-colors 强制色

无需额外配置。theme.css 在 @media (forced-colors: active) 下:

  • 把按钮、输入框、选择器、checkbox/radio/switch 的边框改为系统 ButtonText,避免 border-transparent 在强制色下消失;
  • 焦点环改为 Highlight,保证键盘位置可见;
  • checkbox 选中/半选、switch 选中状态使用 Highlight / HighlightText,图标只依赖 currentColor;
  • disabled 控件使用 GrayText 并恢复 opacity: 1。

Playwright 可用 page.emulateMedia({ forcedColors: 'active' }) 回归;视觉矩阵最后一条用例覆盖了边框与焦点可见性。

伪语言 en-XA

import { I18nProvider } from '@mox-hub/ui/i18n'

<I18nProvider locale="en-XA">
  <App />
</I18nProvider>

en-XA 由内置 en-US 目录派生:

  • ASCII 字母替换为带重音字形;
  • 可见长度至少扩展 30%,尾部用 · 补齐,并加 [] 边界;
  • {{name}} 插值占位符原样保留;
  • 函数类文案(如 dataTable.range)在调用后处理返回值;
  • useFormatters() 的数字/日期格式回落到 en-US,避免 Intl 缺失伪语言数据。

也可以对自定义 catalog 生成伪语言:

import { createPseudoCatalog } from '@mox-hub/ui/i18n'

const pseudo = createPseudoCatalog(myCatalog)

en-XA 只用于开发与视觉回归,不要作为生产语言发布。

视觉回归

apps/docs/e2e/visual.spec.ts 的矩阵包含:

  • light-neutral-md-comfortable-en-xa-ltr
  • dark-neutral-md-comfortable-en-xa-rtl
  • 4 组 contrast: 'high' 用例

伪语言用例会检查 [data-pseudo-probe] 元素:除显式 text-overflow: ellipsis 外,不允许 scrollWidth > clientWidth;同时断言页面没有横向溢出。

pnpm exec playwright test apps/docs/e2e/visual.spec.ts

截图作为 CI artifact 保留;Linux 基线就绪后设置 VISUAL_SNAPSHOTS=1 开启像素对比。