№ · UI 规范 CH.06.22
主页 · 🎨 UI 规范 · Web 横屏 UI 迭代规范（v1）

Web 横屏 UI 迭代规范（v1）

📅 2026-06-22 · 📦 15.9 KB · 🎨 UI 规范 · 📝 MD 文档 🏷️ 装备🏷️ 规范🏷️ 联机

说明：本文结合当前项目的桌面端代码结构整理，重点参考 src/App.tsx 的 Web 壳、src/components/InnCourt.tsx 的核心视口、RecipeTab / BaggageTab / LedgerSummaryTab / FacilitiesTab / PeerLobby 等模块。当前未直接看到你的横屏标注图，凡涉及截图专属细节的部分都应按“需确认”处理。

适用边界

  • Web 横屏与桌面端优先。
  • 目标屏宽以 1280px+ 为主，主容器上限以 1680px 为参考。
  • 竖屏移动端不套用本规范；竖屏单独遵守 docs/mobile-portrait-rulebook.md 与对应竖屏迭代规范。
  • 共享组件只承载内容，不承载整页布局决策。

当前项目的 Web 端形态

  • 当前 Web 壳已经是双栏思路：左侧核心场景，右侧控制台。
  • InnCourt 是核心经营视口，但目前仍偏“静态大画布”，缺少缩放、平移、复位等桌面级交互。
  • LedgerSummaryTab、RecipeTab、BaggageTab、PeerLobby、FacilitiesTab 都是高信息密度模块，适合做渐进式披露。
  • 日志、卡片、tab、统计块都已存在，但密度和层级需要统一收口。

A. 问题诊断表

| 分类 | 现状描述 | 根因判断 | 影响范围 | 优先级 | | --- | --- | --- | --- | --- | | 信息密度与悬浮提示 | 解释性文案、公式、历史说明容易直接堆在卡片内，首屏视觉压力偏大。 | 缺少统一 tooltip / progressive disclosure 规则。 | 统计卡、食谱、装备、联机、设施。 | P0 | | 核心视口与画布交互 | 大堂是核心玩法区，但目前更像静态场景，不支持桌面端常见的 zoom / pan / reset。 | 核心视口没有被定义成可操作画布，外围控制区也未能折叠。 | InnCourt、场景卡、布局壳。 | P0 | | 消息通知与轻重缓急 | 江湖消息、普通日志、紧急警报混在一起，底部持续占空间。 | 消息没有分级，承载通道也没有分层。 | 日志条、提示条、浮层、toast。 | P0 | | 卡片视觉效率 | 食谱、行囊、设施、联机等模块偏纵向，留白多，单屏行数少。 | 卡片排版仍偏移动端堆叠思维。 | RecipeTab、BaggageTab、FacilitiesTab、PeerLobby。 | P1 | | 侧栏与模块页收纳 | 右侧控制台可继续承载信息，但需要可折叠、可聚焦。 | 桌面壳没有把“主视口”和“控制台”彻底分工。 | 整个 Web 壳。 | P1 | | 文本与数值密集组件 | 数值、标签、专有名词容易并排过密，按钮文案偶尔过长。 | 没有统一文本尺度和 formatter 约束。 | HUD、tab、chip、按钮、标签。 | P1 |

B. 逐项修复方案

1. 信息密度与悬浮提示

分类归纳

  • 解释性信息
  • 算法说明
  • 历史记录
  • 次级属性

现状描述

  • 卡片内常把“核心值 + 说明 + 背景故事 + 计算结果”一次展示出来。
  • 桌面端虽然有 hover 空间，但目前没有统一 tooltip 承接机制。

预期效果

  • 默认只展示核心属性、决策动作、状态标签。
  • 所有说明、公式、来源、历史细节进入 tooltip 或侧边抽屉。
  • 鼠标 hover、键盘 focus、移动端长按都能拿到同一份信息。

提炼规则

  • 渐进式信息披露原则：先决策，后解释。
  • 非核心信息默认隐藏。
  • 名词解释和计算过程必须可按需打开，不能常驻占位。

修改建议

  • 统一做 Tooltip / HelpPopover 组件，不要每个模块单独写。
  • 数值、专有名词、缩写、稀有状态旁边补 ? 或 i 入口。
  • tooltip 使用 z-index 独立层级，避免被卡片遮住。
  • 长说明只保留一行摘要，其余放入 tooltip / drawer。

2. 核心视口与无限画布

分类归纳

  • 核心经营视口
  • 场景交互
  • 画布级操作

现状描述

  • InnCourt 是当前项目最重要的玩法区，但桌面端还没有被定义成“可缩放、可平移、可聚焦”的核心画布。
  • 周边控制台虽然信息多，但缺少“收起后把视觉资源让给核心画布”的机制。

预期效果

  • 核心视口在横屏下始终是第一视觉中心。
  • 支持滚轮缩放、按住拖拽平移、一键复位、全屏/收起侧栏。
  • 主视口占比可在 50% ~ 95% 间切换。

提炼规则

  • 核心视口聚焦规范：经营地图必须支持视口级交互。
  • 非操作性控制台必须可折叠。
  • 场景容器必须是“画布”，不是普通卡片。

修改建议

  • 场景容器使用 position: relative + overflow: hidden + touch-action: none。
  • 视口缩放用统一控制条，不要分散在多个模块里。
  • 视口内部元素用相对坐标系统，避免缩放后错位。
  • 加入 Reset、Fit、Collapse Sidebar 三个标准控制。
  • 画布内容应支持鼠标悬停提示，但不应该依赖 hover 才能理解布局。

3. 消息通知与轻重缓急

分类归纳

  • 紧急警报
  • 常规系统日志
  • 历史记录

现状描述

  • 当前日志区域固定占据较多空间，且不同紧急程度的消息混在一条通道里。
  • 重要事件没有足够明显的广播方式。

预期效果

  • P0 级事件第一时间抢占注意力。
  • P1 级事件保留轻量存在感。
  • P2 级历史日志默认收纳，不干扰主视口。

提炼规则

  • 消息分级分流规范：
    • P0：全局 toast / 顶部广播 / 强提醒。
    • P1：单条摘要 / 淡入淡出 / 侧边条。
    • P2：日志面板 / drawer / 历史记录中心。

修改建议

  • 用 severity + channel 作为日志模型字段。
  • 紧急事件改为顶部广播或短时 toast。
  • 常规日志保留最近 1~2 条摘要。
  • 完整日志收进侧边 drawer，支持筛选、搜索、按类型折叠。
  • 如果条数持续增长，日志列表要支持虚拟滚动。

4. 卡片组件的视觉效率

分类归纳

  • 食谱卡
  • 装备卡
  • 设施卡
  • 联机卡

现状描述

  • 当前部分卡片仍是偏纵向的“说明书式”布局，留白较多，横屏利用率不高。
  • 食谱与装备这类列表本应更适合 grid / row 结构。

预期效果

  • 桌面端单屏能容纳更多有效行。
  • 卡片默认更紧凑，动作更集中。
  • 重要状态与动作始终在可视范围内。

提炼规则

  • 网格自适应与视觉比重规范：
    • 列表类组件优先用 grid。
    • 卡片优先做“图标/头像 + 文本 + 动作”三段式。
    • 详情不在首层卡片里堆满。

修改建议

  • RecipeTab 改为响应式网格，卡片用横向 row 结构承载“名称 + 标签 + 售价/升级动作”。
  • BaggageTab 改为“左侧装备格 + 右侧详情面板”，当前选中项高亮，详情独立承载。
  • FacilitiesTab 的设施项保持纵向信息，但按钮和成本区要更紧凑。
  • PeerLobby 改为“双列操作面板 + 下方状态流”，避免表单和日志互相挤压。

5. 侧栏与模块页收纳

分类归纳

  • 控制台
  • 模块页
  • 折叠侧栏

现状描述

  • Web 壳已有左主视口 + 右控制台，但折叠状态和密度切换还不够明确。

预期效果

  • 默认以核心视口为主，控制台为辅。
  • 右侧栏可折叠到图标轨道或变成 drawer。
  • 每个模块页都能明确“摘要层”与“详情层”。

提炼规则

  • 单页只允许一个主视觉中心。
  • 辅助控制区必须可收纳。
  • 详情层不能抢占主视口。

修改建议

  • 右侧栏设三态：展开、压缩、隐藏。
  • 1200px 以下优先压缩侧栏，保留核心视口。
  • 模块内部继续使用 accordion / tabs / drawer 做二次分层。

6. 文本、数值与动态文案

分类归纳

  • HUD 数值
  • 按钮文案
  • 动态标签
  • 状态说明

现状描述

  • 同一层级文本的字号和行高还不完全统一。
  • 动态文案存在直接拼接风险，容易出现括号、分隔符、单位不整齐。

预期效果

  • 同级文本字号一致。
  • 长文本不被压成单字。
  • 动态文本格式稳定、可预测。

提炼规则

  • 文本先定层级，再定字号。
  • 动态文案必须走 formatter。
  • 标签优先完整语义，不能为了省空间压成单字。

修改建议

  • 统一字号阶梯：标题、正文、辅助、徽章、微注释。
  • 所有 flex 文本容器补 min-width: 0。
  • 单行文本用 text-overflow: ellipsis。
  • 中文长词用 word-break: keep-all; overflow-wrap: anywhere;。
  • 状态变化使用统一的 formatPercent / formatCoins / formatRoomId / formatCountLabel。

C. Design Tokens + Guidelines

C1. 容器与布局 Token

| Token | Value | 用途 | 适用场景 | 禁用场景 | | --- | --- | --- | --- | --- | | container-shell-web | min(1680px, 100%) | 页面主容器 | Web 桌面主壳 | 手机竖屏 | | container-core | minmax(0, 1.18fr) | 核心视口轨道 | 左侧主场景 | 纯表单页 | | container-rail | minmax(520px, 1fr) | 控制台轨道 | 右侧模块区 | 需要极窄模式时 | | rail-collapsed | 72px | 图标轨道 | 折叠侧栏 | 常规阅读模式 | | viewport-min | 50% | 核心视口最小占比 | 双栏布局 | 默认桌面展开态 | | viewport-max | 95% | 核心视口最大占比 | 聚焦模式 / 全屏 | 常驻双栏 | | content-min | 0 | 允许收缩 | flex / grid 子项 | 所有文本容器 | | touch-target-min | 44px | 触达高度 | 按钮、可点卡片 | 小徽章 |

C2. Spacing Token

| Token | Value | 用途 | 适用场景 | 禁用场景 | | --- | --- | --- | --- | --- | | space-1 | 4px | 最小间距 | chip、图标与文字 | section 间距 | | space-2 | 8px | 基础间距 | 列表项、按钮内边距 | 大面板留白 | | space-3 | 12px | 轻量分隔 | 卡片内部组块 | 章节大分割 | | space-4 | 16px | 标准间距 | 模块内边距、内容间距 | 过密列表主轴 | | space-5 | 20px | 中等留白 | 页内 section 间距 | 信息密集卡 | | space-6 | 24px | 大间距 | 模块分区 | 卡片内局部布局 | | space-8 | 32px | 结构留白 | 页面级布局、双栏间隔 | 组件级 padding |

C3. Radius Token

| Token | Value | 用途 | 适用场景 | 禁用场景 | | --- | --- | --- | --- | --- | | radius-1 | 4px | 微小圆角 | 极小标签、徽章 | 主卡片 | | radius-2 | 8px | 默认圆角 | 普通卡片、按钮 | 大型面板 | | radius-3 | 12px | 中层圆角 | drawer、浮层 | 微型 chip | | radius-4 | 16px | 大容器圆角 | modal、核心面板 | 高频按钮 | | radius-pill | 9999px | 胶囊圆角 | 筛选 chip、状态条 | 需要明确边界的容器 |

C4. Typography Token

| Token | Value | 用途 | 适用场景 | 禁用场景 | | --- | --- | --- | --- | --- | | text-title-1 | 24px / 32px | 页面级大标题 | 顶部品牌名、核心页标题 | 辅助信息 | | text-title-2 | 20px / 28px | 模块主标题 | LedgerSummaryTab、RecipeTab 标题 | 徽章 | | text-section | 16px / 24px | 分区标题 | 分栏标题、卡片标题 | 表格注释 | | text-body | 14px / 22px | 正文 | 说明、日志摘要、内容页正文 | 主按钮 | | text-meta | 12px / 18px | 辅助文本 | 标签、数值说明、状态条 | 主信息 | | text-micro | 11px / 16px | 极短注释 | 角标、单位、极短状态 | 正文、长按钮 | | text-metric | 18px / 22px | 核心数值 | 铜钱、声望、收益 | 长文本 |

C5. Z-index Token

| Token | Value | 用途 | 适用场景 | 禁用场景 | | --- | --- | --- | --- | --- | | z-base | 0 | 基础内容层 | 常规卡片 | 浮层 | | z-content | 10 | 常规内容层 | 模块正文 | 遮罩 | | z-header | 20 | 顶部状态层 | 顶栏、HUD | 模态框 | | z-dock | 40 | 工具栏层 | 侧栏、底栏、工具条 | modal 之上 | | z-drawer | 50 | 抽屉层 | 日志 drawer、模块 drawer | 背景内容 | | z-modal | 60 | 模态层 | 弹窗、确认框 | 普通卡片 | | z-toast | 70 | 临时提示层 | 警报、短时广播 | 常驻 UI |

C6. Text Rules

  • 主信息不低于 14px。
  • 模块主标题不低于 16px。
  • 辅助信息不低于 12px。
  • 11px 只允许用于徽章、角标、极短状态。
  • 不允许用 10px 或更小字号作为常规信息。
  • 按钮文案优先完整语义，不要压成单字。
  • 长文本先改语义，再决定是否截断。
  • 单行用 ellipsis，多行用 line-clamp。
  • 中文长词优先 word-break: keep-all，避免拆成单字列。

C7. Tooltip / Canvas / Notification Guidelines

  • Tooltip：
    • 默认只放解释性、补充性、低频信息。
    • 使用统一触发器 ? 或 i。
    • 触发器需支持 hover、focus、键盘。
    • Tooltip 不得遮挡主操作。
  • Canvas：
    • 核心视口必须支持缩放、平移、复位。
    • 容器必须 overflow: hidden，内部视图用 transform / coordinate system。
    • 画布上控制件只能做聚焦控制，不做信息堆砌。
  • Notification：
    • P0：toast / 广播。
    • P1：摘要条 / 状态条。
    • P2：drawer / 历史中心。
    • 不同等级不得混在同一条视觉通道里。

D. 验收清单

  • [ ] 1280px+ 横屏下主视口与侧栏分工清晰。
  • [ ] InnCourt 可作为核心视口聚焦，不被控制台压住。
  • [ ] 360px 宽度对应的竖屏规则不被 Web 规范污染。
  • [ ] 信息说明默认收纳，悬浮提示可用。
  • [ ] P0 / P1 / P2 消息通道分开。
  • [ ] 食谱、装备、设施、联机卡片在桌面端更紧凑。
  • [ ] 同级文本字号统一。
  • [ ] 长文本不出现单字截断。
  • [ ] 动态文本括号成对完整。
  • [ ] 圆角、层级、间距统一。
  • [ ] 没有横向溢出。
  • [ ] 无不必要的页面级纵向滚动。

最小改动清单

必须改

  • 给核心视口补 zoom / pan / reset 交互规范。
  • 给消息系统补 severity / channel 分层。
  • 给长文本和动态文案补 formatter 与 token。
  • 给卡片布局补统一的 grid / row 规则。
  • 给右侧控制台补折叠状态。

建议改

  • 把 App.tsx 的 Web 壳拆成可复用的 CoreViewportShell 与 ControlRailShell。
  • 统一 Tooltip、Drawer、Toast 组件。
  • 把 RecipeTab、BaggageTab 做成更适合桌面的紧凑视图。
  • 给 LedgerSummaryTab / PeerLobby 增加信息层次切换。

可后置

  • 更进一步的拖拽排序和布局记忆。
  • 画布更强的惯性、缩放手感优化。
  • 更多桌面分辨率的回归记录。

给 AI 的提问 Prompt 模板

Role: Senior Web/Game UI/UX Designer & Frontend Engineer

Task:
我正在将《同福客栈挂机游戏》的 Web 端横屏界面做系统化重构。当前项目已经存在核心视口、右侧控制台、日志、食谱、行囊、设施、联机等模块，但信息密度、核心视口聚焦、消息分级、卡片效率和文本规则仍需要统一。

请基于当前项目结构，针对以下 4 个部分分别输出：
1. 具体的 UI 重构方案（从布局、交互、组件占比说明）。
2. 对应的 Web 横屏设计规范（Design Rules），用 token + guideline 输出。

请严格按照以下顺序组织内容：
分类归纳 -> 现状描述 -> 预期效果 -> 提炼规则

重点检查：
- 信息密度与悬浮提示（Tooltip / Progressive Disclosure）
- 核心视口与画布交互（Zoom / Pan / Reset / Collapsible Sidebar）
- 消息通知与轻重缓急分类（P0 / P1 / P2）
- 卡片组件的视觉效率（Grid / Row / Compact Card）

约束：
- 结合项目已有组件：`InnCourt`、`LedgerSummaryTab`、`RecipeTab`、`BaggageTab`、`FacilitiesTab`、`PeerLobby`
- 必须明确写出 `min-width: 0`、`overflow`、`line-clamp`、`word-break`、`z-index`、`safe-area-inset-bottom` 等实现约束
- 不要只给审美描述，必须给可验证、可落地、可复用的规则
- 对于不确定的信息，标注“需确认”

结论

这份规范的核心不是“把桌面页修得更满”，而是把 Web 横屏里的主视口、控制台、日志、卡片和提示系统拆开，并用统一 token 控住空间、字号、圆角、层级和文本规则。后续所有 Web 端迭代都应先过这套约束，再进组件实现。