品牌手册 · 下载 · 界面组件规范
Croprix UI 组件规范 v1.2.0
components.css 只引用 tokens/dist/tokens.css 的 --cx-* 变量,不写死色值;components.html 把每个组件的全部变体与状态并排渲染,右上角切换亮/暗主题。依赖顺序:
<link rel="stylesheet" href="tokens/dist/tokens.css" />
<link rel="stylesheet" href="assets/fonts/fonts.css" />
<link rel="stylesheet" href="assets/icons/icons.css" />
<link rel="stylesheet" href="assets/ui/components.css" />
<body class="cx-ui">
…
</body>
- 根元素需要
data-theme="light|dark"(参考做法:读用户上次的选择,没有则跟随系统 prefers-color-scheme)。少数暗色专用规则(次级按钮 hover、选中行、任务卡图标底)依赖这个属性。
- 图标用
assets/icons/sprite.svg:<svg class="cx-icon"><use href="assets/icons/sprite.svg#cx-icon-check"/></svg>(sprite 内联在页面里时写 href="#cx-icon-check"),见图标集。
- 命名:
cx-<组件>,修饰符 --,子元素 __,状态 is-* 或 ARIA 属性([aria-selected]、[aria-current]、[disabled])。
通用规则
| 项目 |
规则 |
| 焦点环 |
所有可聚焦元素:outline: 2px solid var(--cx-focus-color); outline-offset: 2px(:focus-visible);标签页内嵌时 offset: -2px。--cx-focus-color 亮色 leaf.700(对 Sand-50 4.85:1),暗色 leaf.600(对 navy.950 4.95:1);toast 与 inverse 导航栏这类反色底上自动换成另一档,任何底上都 ≥ 3:1。 |
| 触控目标 |
可点击元素 ≥ 44 × 44 px。可见尺寸小于 44 的(sm 按钮 32、复选/单选 20、开关 24、分页 36)通过 .cx-hit::before 或组件自带的 ::before 扩出命中区。 |
| 对比度 |
文字 ≥ 4.5:1,大字与图形 ≥ 3:1。主按钮小字用 accent-fg(navy.950,对 accent 亮 4.95:1 / 暗 5.57:1);白字只允许 ≥ 18.66 px 且字重 700(按钮默认字重 600 不满足,需显式设 700);danger 按钮白字/crimson.700 = 5.9:1。 |
| 状态表达 |
状态不能只靠颜色:error/success 提示带图标,状态点带文字,表格选中行同时改字重或加勾。 |
| 键盘 |
按钮、链接、输入、标签页、分页、模态内控件全部可 Tab 到达;标签页用 ← → Home End 切换(components.html 有参考实现);模态打开后焦点困在对话框内,Esc 关闭。 |
| 动效 |
颜色/描边 fast 120ms,位移/开关 base 200ms,进入 enter 400ms;状态变化 ease.standard、进入 ease.enter;面板 / 模态 / toast 退出用 base 200ms + ease.exit;prefers-reduced-motion 下过渡归零、spinner 与骨架屏静止。 |
| RTL |
用逻辑属性(inset-inline-start、margin-inline-end);带方向的图标加 .cx-icon--rtl(arrow-left / arrow-right / external-link;icons.css 与 lang.css 用同一个类)。 |
组件规格
按钮 .cx-btn
| 尺寸 |
高度 |
内边距(左右) |
字号 |
圆角 |
--sm |
32 |
12 |
sm 14 |
sm 4 |
| 默认 md |
40 |
16 |
md 16 |
sm 4 |
--lg |
48 |
24 |
lg 20 |
sm 4 |
--icon |
与高度同宽的正方形 |
0 |
— |
sm 4 |
字重 600,描边 1.5 px(thin),图标 1.25em。
| 变体 |
default |
hover |
active |
--primary |
底 accent,字 accent-fg |
底 accent-hover |
底 leaf.700,白字,下移 1 px |
--secondary |
底 bg-raised,描边+字 brand |
底 navy.50(暗:navy.800) |
底 navy.100(暗:navy.700) |
--ghost |
透明,字 brand |
底 bg-sunken |
底 border |
--danger |
底 danger,白字(暗:crimson.400 底,crimson.950 字) |
crimson.800(暗:300) |
crimson.900(暗:200) |
disabled:primary、secondary、danger 统一为底 bg-sunken、描边 border、字 fg-subtle;ghost 保持透明底,字 fg-subtle。
is-loading:文字透明、cursor: progress、居中 1em 双弧 spinner 800 ms 匀速;配 aria-busy="true"。每页只有一个 primary;danger 只用于不可逆操作,且需二次确认(模态)。
表单
| 组件 |
尺寸 |
内边距 |
描边 |
圆角 |
说明 |
.cx-input / .cx-select |
高 40(sm 32 / lg 48) |
8 × 12 |
1.5 px border-strong |
sm |
底 bg-sunken;hover 描边 fg-muted;focus 描边 accent + 焦点环,底转 bg-raised |
.cx-textarea |
最小高 96,可竖向拉伸 |
8 × 12 |
同上 |
sm |
行高 1.6 |
.cx-check / .cx-radio |
20 × 20 |
— |
1.5 px border-strong |
xs / full |
选中底 accent,勾/点 accent-fg;支持 indeterminate |
.cx-switch |
40 × 24,滑块 18 |
— |
无 |
full |
轨道 border-strong → accent;滑块白 + shadow.sm |
- 包裹:
.cx-field > .cx-field__label + 控件 + .cx-field__hint。--error 描边与提示文字改 danger,控件加 aria-invalid="true" 且 aria-describedby 指向提示;--success 改 success。提示前放图标。
- 单位后缀用
.cx-input-group + .cx-input-group__unit;数字输入 inputmode="decimal"。
- 禁用:字
fg-subtle、描边 border、cursor: not-allowed;只读用虚线描边。
标签 chip · 状态点 · 徽章
| 组件 |
尺寸 |
内边距 |
圆角 |
颜色 |
.cx-chip |
高 28,字 sm |
0 × 12 |
full |
底 bg-raised + border;--accent = accent-soft/success;--brand = navy.100/900;选中 brand 底反白 |
.cx-status |
点 8 px |
— |
full |
--running success · --idle fg-subtle · --warning warning · --error danger · --info info;running 点每 2 s 脉冲一次 |
.cx-badge |
高 20,最小宽 20 |
0 × 8 |
full |
底 brand 反白;--danger、--accent、--muted;--label 改 xs 圆角 + 大写 |
状态点只用语义色四种 + info,不新增颜色;始终带文字。
卡片 · 表格 · 列表
.cx-card:底 bg-raised,描边 1 px border,圆角 lg 12,内边距 24,阴影 sm。--sm 内边距 16 圆角 md;--flat 无阴影;--raised shadow.md;--interactive hover 升到 shadow.md、描边 border-strong;--selected accent 描边 + 1 px 环。子元素 __header、__title(lg 600 brand)、__eyebrow、__footer。
.cx-table(包在 .cx-table-wrap,圆角 md、可横滚):字号 sm;单元格内边距 8 × 12(--dense 4 × 8);表头 bg-sunken、xs 大写 600 fg-muted、sticky;--striped 偶数行 bg-sunken;行 hover accent-soft;tr.is-selected navy.100(暗 navy.800);数值列加 .num(右对齐 + tabular-nums + 不换行);排序列用 aria-sort;<caption> 放数据说明与单位。
.cx-list:条目高 ≥ 48、内边距 12 × 16、分隔线 border;图标 brand;链接条目 hover bg-sunken。
导航栏 · 标签页 · 面包屑 · 分页
| 组件 |
尺寸 |
当前项 |
.cx-navbar |
高 56,左右 24,标志高 28 |
字 brand + 底部 2 px accent 线;--inverse 底 bg-inverse,线 leaf.500 |
.cx-tabs |
项高 44,左右 12,字 sm 500 |
底边 2 px accent;--pill 高 36 圆角 full,选中 brand 反白 |
.cx-breadcrumb |
字 sm,链接高 32 |
分隔符 / fg-subtle;当前页 fg 500 |
.cx-pagination |
项 36 × 36 + 上下 4 px 扩展 |
brand 反白;禁用 fg-subtle;摘要 fg-muted |
提示条 · toast · 模态 · 工具提示
| 组件 |
尺寸 |
颜色 |
.cx-alert |
内边距 12 × 16,圆角 md,1 px 描边取语义色 40% |
info sky.50/info · success leaf.50/success · warning harvest.50/warning · danger crimson.50/danger;暗色底统一 bg-raised;图标 20 px |
.cx-toast |
宽 ≤ 360,内边距 12 × 16,圆角 md,shadow.lg |
底 bg-inverse、字 fg-inverse;图标 leaf/harvest/crimson/sky 400(暗 700);进入 400 ms ease.enter,右下堆叠 z.toast |
.cx-modal |
对话框宽 ≤ 560,圆角 lg,shadow.lg;页眉 20/24/12,正文 0/24/16,页脚 16/24/20 |
遮罩 navy.950 60%(z.overlay),对话框 z.modal;标题 xl 600 brand |
.cx-tooltip |
气泡最大宽 240,内边距 4 × 8,圆角 sm,字 xs |
底 bg-inverse;箭头 8 px;hover / focus-within 120 ms 淡入 + 2 px 上移;--bottom 变体 |
- 提示条
role="status"(info/success)或 role="alert"(warning/danger);toast 同理。
- 模态
role="dialog" aria-modal="true" aria-labelledby;打开时页面 inert,关闭后焦点回到触发按钮。
- 工具提示
role="tooltip",触发元素 aria-describedby;不能承载操作。
进度条 · 骨架屏 · 空状态
.cx-progress:高 8(--sm 4),圆角 full;轨道 leaf.100(暗 leaf.900),填充 accent;--warning harvest.100/warning,--danger crimson.100/danger;宽度经 --cx-progress 变量驱动,320 ms 过渡;--indeterminate 40% 段往返。必须带 role="progressbar" + aria-valuenow/min/max + aria-label。
.cx-skeleton:bg-sunken ↔ border 三段渐变 1.6 s 横向流动;--text(0.9em)、--title、--circle 40、--rect 120;容器 aria-busy="true";reduced-motion 下静止为 bg-sunken。
.cx-empty:虚线描边 border-strong、圆角 lg、内边距 40 × 24、居中;图标 48 px fg-subtle(描边 1.25,取图标尺寸档的最大一档);标题 lg 600;正文 sm fg-muted ≤ 36em;一个 primary 按钮作下一步。
机器人任务卡 .cx-task(业务示例)
网格三列:图标 44 × 44(圆角 22%,底 navy.50 / 暗 navy.800,图标 brand 24 px);名称 600 + 类别 xs 大写;右上状态点;进度条 + 百分比;底部时间/路线元数据(xs,mono 用于时间)。状态只由状态点与进度条(--warning / --danger)表达,卡片描边统一 border,不加侧边色条。整卡 aria-label 概括名称、作业与状态。
可访问性检查清单
- 每个交互元素有可见焦点环(不用
outline: none)。
- 触控目标 ≥ 44 px,命中区不重叠。
- 文字对比 ≥ 4.5:1,图标/描边 ≥ 3:1(语义色核验结果见对比度核验报告)。
- 状态、错误、成功均有图标或文字,不只靠颜色。
- 表单控件有
<label>;错误信息通过 aria-describedby 关联。
- 动态区域用
role="status"/alert 或 aria-live。
prefers-reduced-motion: reduce 下无位移、无循环动画。
- RTL 环境逻辑属性生效,方向性图标镜像。