> 本文为IB-1.1完整摘录/规范化收录。与本包[统一基线](../../docs/baseline.html)和[冲突裁定](../../docs/decisions.html)配套执行；旧来源状态不代表软件完成。

# 组件与 Design Token 规范

版本：D2.0  
适用范围：风暴扑克 Web 客户端（Telegram适配后置）设计稿。  
实现基准：[styles.css](../../ui/player/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 优先用于图标；信息图像必须有替代文本，装饰图像使用空替代文本。
- 资源变更与页面版本一起发布，不能由开发自行替换近似素材。
