可访问性与高对比度
高对比度 token、forced-colors 强制色与 en-XA 伪语言的接入与验证方式。
可访问性与高对比度
Ordo UI 在主题层提供三档可访问性能力,不要求组件逐个改造:
| 能力 | 入口 | 适用场景 |
|---|---|---|
| 高对比度 | theme={{ contrast: 'high' }} 或根元素 data-contrast="high" | 低视力、强光环境、合规验收 |
| 强制色 | 系统级 forced-colors: active | Windows 高对比度模式 |
| 伪语言 | 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--ringoutline; 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-ltrdark-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 开启像素对比。