playX/docs/UI_REDESIGN_REQUIREMENTS.md

界面改版需求说明

1. 文档目的

本文档用于定义当前项目界面调整阶段的强制性约束、实现规则、范围边界与验收标准。

本阶段的目标不是从零开始重新设计产品，而是在现有橙色加液态玻璃视觉语言基础上，对当前界面进行优化与打磨，提升整体一致性，替换图标，并在不改变现有信息架构和核心布局结构的前提下，使界面完整适配桌面端、平板端与移动端。

2. 当前项目约束

以下约束为强制要求，在界面调整过程中不得违反：

1. src/components/button/index.tsx 中的按钮组件样式必须保持不变。
2. 现有的橙色加液态玻璃风格是基础视觉方向，必须保留。
3. 页面整体结构、内容层级与布局逻辑必须保持不变。
4. 仅允许在细节层面进行视觉优化，例如间距、排版节奏、图标使用、对齐、交互状态与响应式表现。
5. 所有新增或调整后的样式都必须使用 Tailwind CSS 工具类实现，已存在的 button-play 与 liquid-glass-bg 样式除外。

3. 不可协商的技术规则

3.1 按钮组件冻结规则

src/components/button/index.tsx 中按钮组件的实现与视觉样式必须视为冻结状态。

允许：

• 复用该按钮组件。
• 在组件外部添加与布局相关的包裹类名。
• 在有需要时传入额外的 className 用于控制尺寸或位置，但前提是 button-play 的基础视觉样式不能变化。

不允许：

• 修改 button-play 样式。
• 将按钮重做为另一套视觉体系。
• 用其他基础组件替换当前按钮。

3.2 仅使用 Tailwind CSS 的样式规则

所有页面级与组件级样式都必须通过 Tailwind CSS 工具类表达。

允许的例外：

• 已存在的 .button-play
• 已存在的 .liquid-glass-bg

不允许：

• 为常规界面样式新增自定义 CSS 代码块
• 为布局或装饰样式新增 SCSS 或 CSS Module
• 除非技术上无法避免，否则不允许新增内联样式对象

推荐做法：

• 使用 Tailwind 工具类处理间距、尺寸、对齐、排版、边框、不透明度、阴影、过渡与响应式行为。
• 如果出现重复使用的视觉规则，应优先通过可复用组件组合解决，而不是新增 CSS。
• 现有进度条样式也应纳入本次整理范围，迁移为 Tailwind CSS 实现，不再继续依赖独立的 .progress-bar、.progress-bar__fill 或常规内联宽度样式写法。

3.3 响应式设计规则

整个项目必须在以下设备类型上保持可用且具备良好的响应式表现：

• 移动端网页
• 平板设备
• 桌面端设备

响应式实现必须使用 Tailwind CSS 的断点机制。

推荐的断点策略：

• base：默认采用移动端优先
• md：适配平板
• lg 及以上：增强桌面端体验

实现要求：

• 先保证移动端布局默认安全可用。
• 在更大断点下逐步调整间距、排版、宽度与对齐方式。
• 避免在小屏设备上出现内容溢出、裁切或点击区域不可用的问题。
• 在不同断点下调整密度与比例，但必须保持现有布局结构不变。

4. 视觉方向

4.1 风格基线

项目必须继续沿用当前视觉语言：

• 橙色作为主要强调色
• 液态玻璃背景处理
• 深色半透明面板氛围
• 主要操作具备更明亮的视觉强调

这意味着本次改版应当呈现为现有界面的升级版本，而不是另一款全新产品。

4.2 可优化内容

在不违反布局保持规则的前提下，可以优化以下视觉细节：

• 内部间距一致性
• 纵向节奏
• 文本层级与可读性
• 图标一致性
• 按钮分组与对齐
• 卡片头部、主体、底部的间距
• 表单间距与字段分组
• 表格可读性
• 弹窗操作区的平衡感
• 悬停、激活、聚焦等状态细节
• 移动端与平板端的密度调整

4.3 禁止变更内容

除非后续得到明确批准，否则以下内容必须保持稳定：

• 页面结构
• 主要区块顺序
• 现有功能模块
• 现有流程与交互逻辑
• 核心的橙色加液态玻璃品牌感受

5. 图标迁移规范

5.1 核心规则

在可行的情况下，项目中的 SVG 图像图标应替换为 lucide-react。

包括但不限于：

• 静态 SVG 资源导入
• 内联 SVG 的使用
• 当前界面中缺少清晰图标支持但实际上适合补充图标的场景

以下内容不属于本次 lucide-react 替换范围：

• 浏览器 favicon
• 品牌 logo
• 不承担界面交互语义的纯装饰性或品牌型图形资源

5.2 当前已观察到的 SVG 使用情况

根据当前代码扫描，项目中已存在以下 SVG 来源：

• src/assets/account.svg
• src/assets/record.svg
• public/icons.svg
• public/favicon.svg

当前在页面层级观察到的 SVG 资源使用位置如下：

• src/views/home/index.tsx

5.3 迁移规则

允许：

• 将现有 SVG 图标替换为语义合适的 Lucide 图标。
• 在导航、操作按钮、区块标题、空状态、状态区域或表单辅助位置补充 Lucide 图标，以提升信息清晰度。

不允许：

• 添加造成视觉杂乱的图标
• 替换本应保留为独立图形的品牌或标识资源
• 引入会明显改变布局层级或信息密度的图标用法

5.4 图标选择指南

Lucide 图标必须遵循以下规则：

• 图标语义必须与操作或区块含义一致
• 同一区域内保持统一的描边粗细与尺寸
• 图标尺寸需要具备响应式适配能力
• 通过摆放与颜色处理来延续当前橙色玻璃质感，而不是通过额外复杂装饰去重做图标轮廓

推荐图标尺寸：

• h-4 w-4：紧凑型行内操作
• h-5 w-5：标准按钮、标签页、列表操作
• h-6 w-6：区块标题、卡片重点信息

5.5 图标样式指南

图标样式应使用 Tailwind 类名控制，例如：

• text-white/80
• text-[#FE9F00]
• shrink-0
• 在有需要时使用响应式尺寸类

图标应服务于可读性与精致度，不应喧宾夺主。

6. 布局保持规则

本项目当前处于界面打磨阶段，而不是结构重设计阶段。

因此：

• 现有模块必须保持在当前的大致位置。
• 除非为了技术整理必须调整，否则现有区块应保持当前父子层级关系。
• 现有布局模式可以做响应式适配，但不应在概念上被整体替换。
• 对于首页头部区域，在 iPad 端与 H5 移动端这类可用宽度受限的场景下，允许为保证内容完整展示而进行局部重排。

可接受的优化示例：

• 将固定宽度改为响应式宽度
• 在不同断点下优化间距
• 按屏幕尺寸调整网格列数
• 让操作栏在小屏设备上安全换行
• 优化弹窗、页脚、页头的对齐方式
• 在首页头部的平板端与移动端布局中，将次级信息卡片移动到新的一行，只要不改变模块语义与核心信息顺序

不可接受的变更示例：

• 将主要内容区块移动到其他区域
• 用无关的新布局替换现有卡片、表格或表单
• 未经批准就重排核心信息架构

7. 响应式实现标准

7.1 设备适配目标

界面必须在以下场景中保持可用且视觉协调：

• 竖屏移动端优先
• 平板竖屏与横屏
• 常规桌面宽度

7.2 响应式设计规则

• 在可行情况下优先使用流式宽度，而非固定像素宽度。
• 在有必要时，将固定横向布局改为基于断点的堆叠布局。
• 确保按钮、输入框、卡片、表格与弹窗在适配后不会发生溢出。
• 在移动端保持合理的最小点击区域尺寸。
• 除非组件语义本身确实需要，否则避免横向滚动。
• 首页头部在 iPad 端与 H5 移动端允许优先保证内容完整展示，而不是强行维持桌面端同一排布。

7.3 首页头部的响应式例外说明

首页头部区域在桌面端应尽量保持当前结构感，但在 iPad 端和 H5 移动端，允许根据可用宽度进行局部换行和重排，前提是信息语义、操作入口与阅读顺序保持清晰。

该例外的断点范围限定如下：

• base 与 md 断点允许执行上述重排。
• lg 及以上断点应默认回到桌面端原有布局逻辑，除非后续另行批准新的桌面端结构调整。

明确允许的调整方式如下：

• Claimable Points 与 Daily Claim Limit 这两个 liquid-glass-bg 信息卡片允许单独新开一行。
• 上述两个卡片允许放置在提现信息与按钮区块的上方。
• Available for Withdrawal (Cash) 与下方操作按钮区块在平板端和移动端可以下移为后一组内容。
• 该调整仅适用于首页头部区域在小屏和中屏宽度不足时的响应式适配，不视为对整体信息架构的修改。

7.4 推荐的 Tailwind 模式

• w-full md:w-auto
• flex-col md:flex-row
• grid-cols-1 md:grid-cols-2 lg:grid-cols-3
• gap-3 md:gap-4 lg:gap-5
• px-4 md:px-5 lg:px-6
• text-sm md:text-base

以上仅表示推荐方向，并非必须使用这些精确数值。

8. 样式治理

8.1 允许的样式来源

• 在 TSX 中使用 Tailwind 工具类
• 已存在的 button-play
• 已存在的 liquid-glass-bg

8.2 禁止的样式来源

• 为常规组件样式新增独立 CSS 类
• 为日常界面工作引入临时性的内联样式
• 在 Lucide 足以覆盖需求的前提下，重新引入基于 SVG 的图标样式方案

8.3 视觉一致性目标

本次界面更新应提升以下方面的一致性：

• 间距一致性
• 图标一致性
• 排版一致性
• 操作层级清晰度
• 跨页面视觉连续性

9. 审核通过后的建议执行顺序

本文档确认后，建议按以下顺序推进实现：

1. 审核当前所有 SVG 与图标使用情况，并为每一处映射到合适的 lucide-react 图标。
2. 逐页使用 Tailwind 断点调整响应式行为。
3. 在不改变布局结构的前提下，统一间距、对齐与区块节奏。
4. 对卡片、表格、表单与弹窗进行细节层面的精修。
5. 最后针对桌面端、平板端与移动端做整体一致性复查。

10. 后续基于技能的细节优化说明

用户要求后续在界面细节层面的视觉优化阶段使用 ui-ux-pro-max 技能。

当前状态：

• 该技能在当前会话中已可用。

因此，本文档将该要求视为当前可执行约束：

• 在本说明通过后，如进入进一步的界面细节增强阶段，应继续遵循本文档所定义的橙色加液态玻璃设计基线，并按照 ui-ux-pro-max 技能工作流执行。
• 即使进入后续阶段，本文档中定义的当前布局结构与风格方向仍必须保持不变。

11. 验收标准

只有当以下条件全部满足时，本次界面调整工作才可视为合格：

1. src/components/button/index.tsx 的视觉表现保持不变。
2. 现有基于 SVG 的界面图标已在适合的位置替换为 lucide-react。
3. 仅在确实提升清晰度与视觉一致性的地方补充额外的 Lucide 图标。
4. 项目在移动端、平板端与桌面端保持响应式可用。
5. 响应式行为通过 Tailwind 断点实现。
6. 除 button-play 与 liquid-glass-bg 外，新增界面样式全部仅使用 Tailwind 工具类编写，首页现有进度条样式也需同步迁移至 Tailwind CSS。
7. 橙色加液态玻璃风格继续作为核心视觉识别。
8. 当前页面结构与布局逻辑保持不变。
9. 在间距、对齐、细节质感与图标一致性方面能够看到明确提升。
10. 首页头部在 iPad 端与 H5 移动端如遇宽度不足时，允许将 Claimable Points 与 Daily Claim Limit 调整为新的一行并置于提现区块上方，只要内容展示完整且交互清晰。
11. base 与 md 断点允许首页头部执行响应式重排，lg 及以上断点默认保持桌面端原有布局逻辑。
12. 浏览器 favicon、品牌 logo 与非界面交互语义的图形资源不纳入 lucide-react 替换范围。

12. 本仓库实现备注

下一阶段实现中，较可能涉及以下区域：

• src/views/home/index.tsx
• src/views/account/index.tsx
• src/views/record/index.tsx
• src/components/modal/index.tsx
• 其余与界面展示相关的 SVG 资源使用位置

以下文件或样式必须作为核心基线保留：

• src/components/button/index.tsx
• src/index.css 中与 .button-play 相关的定义
• src/index.css 中与 .liquid-glass-bg 相关的定义

---

本文件是当前项目版本的界面调整工作说明。在完成审核并获得批准之前，不应开展超出低风险准备工作的正式实现。