组件与 Design Token 规范
版本:D2.0
适用范围:风暴扑克 Web 客户端(Telegram适配后置)设计稿。
实现基准:styles.css。本文记录语义和验收要求,CSS 是当前原型实现,不替代正式前端组件库。
1. 视觉原则
- 暗色、克制、单一荧光绿强调色;不使用纯黑作为主背景。
- 合法主操作、本人手牌、当前行动和资金结果保持第一视觉层级。
- 错误、禁用、成功、等待和座位状态同时使用文字、形状或边框,不只依赖颜色。
- 玩家产品界面使用实用文案,不显示设计评论、技术实现或运营后台说明。
2. 核心 Token
| Token | 当前值 | 用途 |
|---|---|---|
--bg |
#06150f |
工作台深色背景 |
--bg-deep |
#03100b |
最深层背景 |
--surface |
#0b241a |
内容表面 |
--surface-2 |
#102e22 |
次级表面 |
--text |
#effff5 |
主要文字 |
--muted |
#a9beb3 |
辅助文字 |
--subtle |
#839f91 |
低优先级元数据 |
--lime |
#9cf51c |
主操作、焦点、当前状态 |
--lime-soft |
#c9ff72 |
强调文字 |
--gold |
#f2cf6b |
金额提示、警告、牌局投入 |
--red |
#ff745f |
错误与危险动作 |
--blue |
#71b7ff |
技术验证标签 |
--line |
rgba(201,255,226,.13) |
默认分隔线 |
--line-strong |
rgba(201,255,226,.24) |
强分隔线与控件边界 |
--radius |
18px |
默认圆角 |
--safe-top |
18px |
原型安全区占位;生产使用 浏览器/系统实际值,后续适配TG |
--safe-bottom |
18px |
原型安全区占位;生产使用 浏览器/系统实际值,后续适配TG |
正式实现应将语义 Token 与具体色值分离。业务组件只引用 text-primary、action-primary、state-danger 等语义变量,不能散落硬编码颜色。
3. 排版与间距
- 字体:系统字体栈;不依赖在线字体。
- 正文最小 12px;关键正文建议 13px;低频元数据不得低于 10px。
- 页面标题 18–34px,按层级使用,不以字重和字号同时制造多套竞争层级。
- 常用间距采用 4 / 6 / 8 / 10 / 12 / 14 / 16 / 18 / 22 / 24px 序列。
- 内容左右安全边距默认 22px;360px 以下可降至 16px。
- 正文行高不低于 1.5;说明与规则正文建议 1.6–1.75。
4. 组件状态
| 组件 | 必须状态 | 核心要求 |
|---|---|---|
| 主按钮 | 默认、按压、焦点、禁用、提交中 | 高度≥52px;提交中防重复;禁用仍可辨认文案 |
| 次按钮 | 默认、按压、焦点、禁用 | 不得与主按钮争夺视觉层级 |
| 图标按钮 | 默认、焦点、禁用 | 点击区≥44×44px;必须有可访问名称 |
| 输入框 | 空、已输入、焦点、错误、禁用 | 错误文字靠近字段;不只红边;保留用户合法输入 |
| 滑杆 | 默认、焦点、拖动、禁用 | 有名称、当前值、最小值、最大值;键盘方向键可操作 |
| 座位 | 可选、已选、已占、业务锁定 | 文字+边框+底纹;aria-pressed;不可用座位禁用 |
| 房间列表项 | 可进入、满桌、关闭、受限 | 状态与人数可扫读;整行点击区≥44px |
| Bottom Nav | 默认、当前、焦点 | 三栏固定;当前项具文字和底纹反馈;内容预留底部空间 |
| Toast | 成功、失败、提示 | 单次短消息使用 role=status;不播报整页 |
| 状态通知 | 警告、错误、成功、等待 | 标题说明发生了什么,正文说明影响和下一步 |
| 抽屉/Dialog | 打开、滚动、关闭 | 底层 inert;焦点循环;Esc/遮罩关闭;焦点返回入口 |
| 牌桌动作 | 弃牌、跟注/过牌、加注/下注、禁用 | 跟注/过牌为主操作;目标额与本次投入不得混淆 |
5. 页面布局
- 产品画布在 320 / 360 / 390 / 430px 下不得横向滚动。
- 独立预览在宽屏最大 430px 并居中;这只是验收容器,不是生产桌面布局承诺。
- 可滚动页面使用内容区滚动;Bottom Nav 和粘性 CTA 不遮挡末尾内容与焦点。
- 牌桌为固定画布:行动 Dock、本人手牌和牌桌区域不得重叠;公共牌、底池和当前行动者优先。
- TG 顶部栏、系统安全区和软键盘必须以运行时数据处理,不能只使用原型固定值。
6. 动效
- 页面和抽屉过渡控制在 120–250ms;动效只用于层级、进入和反馈。
- 业务结果必须由服务端状态驱动,动效不得先行制造成功。
- 动作气泡不得遮挡手牌、公共牌或合法动作。
prefers-reduced-motion: reduce时关闭非必要动画,保留状态变化本身。
7. 无障碍验收
- 正文对比度≥4.5:1,重要标题和关键状态目标≥7:1。
- 主要触控目标≥44×44px;焦点环至少 2px,当前原型为 3px。
- 所有操作使用原生按钮/输入控件或提供等价语义。
- 页面标题在路由变化后获得程序焦点;路由变化通过单次礼貌播报通知。
- Dialog 提供名称、
aria-modal、焦点陷阱和关闭后焦点恢复。 - 金额、倒计时和牌局状态不能依靠颜色区分;读屏文本必须包含单位和状态。
8. 资源交付
- Logo、图标、四种牌面和品牌素材必须记录来源、授权、格式、尺寸和版本。
- 演示文本、人员、房间号、邀请码和 TEST 金额不得进入生产种子数据。
- SVG 优先用于图标;信息图像必须有替代文本,装饰图像使用空替代文本。
- 资源变更与页面版本一起发布,不能由开发自行替换近似素材。