feat: 添加 iOS 和 Web 项目 UI/UX 设计审查报告
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
WangDL
parent
b648353eda
commit
6c6c3cf74a
1
.gitignore
vendored
1
.gitignore
vendored
@ -1,3 +1,4 @@
|
|||||||
.claude/
|
.claude/
|
||||||
.DS_Store
|
.DS_Store
|
||||||
凭据配置/
|
凭据配置/
|
||||||
|
技术设计/awesome-design-md/
|
||||||
|
|||||||
294
技术设计/ios-projects/UI-UX审查报告.md
Normal file
294
技术设计/ios-projects/UI-UX审查报告.md
Normal file
@ -0,0 +1,294 @@
|
|||||||
|
# AIStudyApp UI/UX 设计审查报告
|
||||||
|
|
||||||
|
> 审查日期：2026-05-18 | 来源：ui-ux-pro-max 设计系统 + 代码审查 | 范围：全部 SwiftUI 视图
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一、严重问题 (CRITICAL)
|
||||||
|
|
||||||
|
### 1.1 使用 Emoji 作为图标（严重违反设计规范）
|
||||||
|
|
||||||
|
**问题描述：** App 中大量使用 Emoji 代替 SF Symbols 作为 UI 图标。ui-ux-pro-max 设计规范明确禁止此做法（"Use SVG icons, not emojis"）。
|
||||||
|
|
||||||
|
**涉及位置：**
|
||||||
|
|
||||||
|
| 文件 | 位置 | Emoji 使用 |
|
||||||
|
|------|------|-----------|
|
||||||
|
| ContentView.swift | 快速操作按钮 | 🧠 🔍 🎤 📅 |
|
||||||
|
| AIHomeView.swift | AI 互动行 | 🎤 ⚠️ 📝 |
|
||||||
|
| AIHomeView.swift | 建议区域 | 💡 |
|
||||||
|
| StudyHomeView.swift | 今日任务标记 | (通过 taskType 间接使用) |
|
||||||
|
| ProfileView.swift | 头像 | 🧑🎓 |
|
||||||
|
| ProfileView.swift | 菜单项 | 🎯 🔔 🧩 💬 |
|
||||||
|
| ProfileView.swift | 成就徽章 | 🔥 🧠 📚 ⚡ |
|
||||||
|
| SettingsView.swift | 目标选择 | 🧑🎓 💼 📚 🎯 |
|
||||||
|
| LibraryHomeView.swift | 知识库卡片 | 📚 |
|
||||||
|
|
||||||
|
**影响：** Emoji 在不同 iOS 版本/设备上渲染效果不一致，无法精确控制颜色/大小，不符合 iOS 设计规范。应采用 SF Symbols 或自定义图标。
|
||||||
|
|
||||||
|
**修复建议：** 将快捷操作按钮改为 SF Symbols（如 `brain.head.profile` 替代 🧠，`magnifyingglass` 替代 🔍），Emoji 仅保留在知识库卡片封面等表达性内容场景。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.2 不支持 Dynamic Type（动态字体）
|
||||||
|
|
||||||
|
**问题描述：** 整个 App 使用 `.font(.system(size: N))` 固定字号，未使用 Dynamic Type 语义字体。SwiftUI Skill 指南将此列为 HIGH 严重级别。
|
||||||
|
|
||||||
|
**涉及范围：全局** — DesignTokens.swift 的 ZXFont 全部为固定字号，所有视图都依赖这些固定值。
|
||||||
|
|
||||||
|
```swift
|
||||||
|
// 当前：固定字号，系统缩放无效
|
||||||
|
.font(.system(size: 22, weight: .heavy))
|
||||||
|
|
||||||
|
// 应使用：语义化 Dynamic Type 字体
|
||||||
|
.font(.title.weight(.heavy))
|
||||||
|
```
|
||||||
|
|
||||||
|
**影响：** 视障用户无法通过系统设置放大文字，严重降低可访问性。
|
||||||
|
|
||||||
|
**修复建议：** 将 DesignTokens 迁移为基于 Dynamic Type 的相对字号体系，或至少使用 `@ScaledMetric` 对关键字号做缩放。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.3 未遵循 Reduced Motion 偏好
|
||||||
|
|
||||||
|
**问题描述：** 全 App 未检查 `@Environment(\.accessibilityReduceMotion)`，所有动画无差别播放。ux-guidelines 将此列为 HIGH 严重级别。
|
||||||
|
|
||||||
|
**涉及位置：**
|
||||||
|
- ZXAnimations.swift — 所有动画（按钮缩放、加载循环、庆祝粒子、进度条）
|
||||||
|
- ZXLoadingView.swift — 持续旋转动画
|
||||||
|
- LearningSessionView.swift — 计时器环形进度动画
|
||||||
|
- ReviewCardView.swift — 卡片翻转动画
|
||||||
|
- AnalysisHomeView.swift — 图表绘制动画
|
||||||
|
|
||||||
|
**修复建议：** 在所有动画处检查 `@Environment(\.accessibilityReduceMotion) var reduceMotion`，当用户开启减弱动态效果时，禁用非功能性动画（如旋转加载改为静态指示，庆祝粒子直接显示结果卡片）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 二、高优先级问题 (HIGH)
|
||||||
|
|
||||||
|
### 2.1 触控目标尺寸不足
|
||||||
|
|
||||||
|
**问题描述：** 多个可交互元素小于 Apple HIG 要求的 44×44pt 最小触控目标。
|
||||||
|
|
||||||
|
| 元素 | 当前尺寸 | 标准 |
|
||||||
|
|------|---------|------|
|
||||||
|
| ZXIconBtn 内部图标 | 36pt（边界 OK）| 44pt |
|
||||||
|
| Checkmark circle | 20pt | 44pt |
|
||||||
|
| 评分按钮标签区 | ~40pt | 44pt |
|
||||||
|
| TabBar 文字标签 | 10pt 字号 | — |
|
||||||
|
| ZXAIInteractionRow Checkmark | 20pt | 44pt |
|
||||||
|
|
||||||
|
**修复建议：** 对小于 44pt 的触控元素，扩展其 frame、增加 padding，或将 onTapGesture 应用到更大的父容器上。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.2 Light Mode 对比度不足
|
||||||
|
|
||||||
|
**问题描述：** App 在亮色模式下，部分文字和边框对比度可能不足。DesignTokens 中亮色模式的文字色为 `#1A1A2E`，但透明度变体（如 0.3/0.35/0.4）在白底上对比度过低。
|
||||||
|
|
||||||
|
具体需要检查的色值：
|
||||||
|
- `zxF03` = `#1A1A2E` opacity 0.3 → 白底对比度约 2.8:1（需 ≥4.5:1）
|
||||||
|
- `zxF04` = `#1A1A2E` opacity 0.4 → 白底对比度约 3.7:1
|
||||||
|
- `zxF035` = `#1A1A2E` opacity 0.35 → 白底对比度约 3.2:1
|
||||||
|
- `zxBorder008` = `#000000` opacity 0.08 → 白底几乎不可见
|
||||||
|
|
||||||
|
**修复建议：** 参照设计规范 ""Glass card light mode: Use bg-white/80 or higher opacity""，将 light 模式下的低透明度文字色替换为更高对比度的实色（如 `#64748B` slate-500 替代 opacity 0.3-0.4）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.3 TextField 仅依赖 Placeholder 作为标签
|
||||||
|
|
||||||
|
**问题描述：** 多处 TextField 仅有 placeholder 而无独立 label，ux-guidelines 将此列为 HIGH 级别。
|
||||||
|
|
||||||
|
```swift
|
||||||
|
// 当前：placeholder 即标签（不符合可访问性）
|
||||||
|
TextField("问 AI 任何学习问题…", text: $text)
|
||||||
|
```
|
||||||
|
|
||||||
|
**涉及位置：**
|
||||||
|
- AIHomeView.swift — AI 输入框、搜索建议输入框
|
||||||
|
- ContentView.swift — ZXAIInputBar
|
||||||
|
- DailyThinkingPage.swift — 回答输入、RecallTest 输入
|
||||||
|
- LibraryHomeView.swift — 搜索框
|
||||||
|
- EditProfilePage.swift — 各项编辑字段（有 title 文字但非语义 label）
|
||||||
|
|
||||||
|
**修复建议：** 为输入框添加 `.accessibilityLabel()` 或在前面放置独立 Text 标签，EditProfilePage 的 ZXEditField 应将 title 链接为 label。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、中优先级问题 (MEDIUM)
|
||||||
|
|
||||||
|
### 3.1 导航已使用 Deprecated API
|
||||||
|
|
||||||
|
**问题描述：** 大量使用 `NavigationLink(destination:)` 而非 iOS 16+ 推荐的 `navigationDestination(for:)`。SwiftUI Stack 指南明确标注此问题。
|
||||||
|
|
||||||
|
```swift
|
||||||
|
// 当前写法（deprecated）
|
||||||
|
NavigationLink(destination: AIChatPage()) { ... }
|
||||||
|
|
||||||
|
// 推荐写法
|
||||||
|
NavigationLink(value: Route.aiChat) { ... }
|
||||||
|
// + .navigationDestination(for: Route.self) { route in ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
**修复建议：** 建立路由枚举，统一使用 NavigationStack + navigationDestination 模式。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.2 ZXPressModifier 手势冲突
|
||||||
|
|
||||||
|
**问题描述：** `ZXPressModifier` 使用 `DragGesture(minimumDistance: 0)` 实现按压态，这会与 ScrollView 滚动、TabView 切换等系统手势产生竞争。
|
||||||
|
|
||||||
|
```swift
|
||||||
|
// ZXAnimations.swift L32-33
|
||||||
|
.simultaneousGesture(
|
||||||
|
DragGesture(minimumDistance: 0)
|
||||||
|
```
|
||||||
|
|
||||||
|
**影响：** 在 ScrollView 中的按压元素可能导致滚动不流畅，或按压态意外触发。
|
||||||
|
|
||||||
|
**修复建议：** 改用 ButtonStyle 封装按压效果（已有 ZXButtonStyle，但 ZXPressModifier 存在重复），或使用 `LongPressGesture` + `TapGesture` 组合替代 DragGesture。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.3 按钮/交互元素缺少 loading 状态
|
||||||
|
|
||||||
|
**问题描述：** 多处异步操作的按钮未显示 loading 状态。ux-guidelines 将此列为 HIGH。
|
||||||
|
|
||||||
|
**涉及位置：**
|
||||||
|
- AIHomeView — 发送按钮无 loading 态
|
||||||
|
- SettingsView — 保存按钮无 loading 反馈
|
||||||
|
- GoalSettingDetailView / MethodPreferenceView — 保存中无 loading 指示
|
||||||
|
- FeedbackFormView — 提交中无 loading 指示
|
||||||
|
- DailyThinkingPage — 提交按钮无 loading 态
|
||||||
|
|
||||||
|
**对比：** EditProfilePage.swift 已有 `isSaving` + `ProgressView` 的完善实现，可作为模板。
|
||||||
|
|
||||||
|
**修复建议：** 为所有异步提交按钮添加 `ProgressView` + 禁用状态（参考 EditProfilePage 的实现）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.4 代码复用与组件膨大
|
||||||
|
|
||||||
|
**问题描述：** 存在重复实现和组件定义分散的问题：
|
||||||
|
- `ContentView.swift` 中的 `ZXAIInputBar` 与 `AIHomeView.swift` 底部 inputBar（L160-178）几乎相同，但后者定义了独立的内联视图
|
||||||
|
- `DailyThinkingPage.swift` 内嵌定义了 `RecallTestPage`、`WeakPointsPage`、`AIFeedbackPageView`、`AIChatPage` 等多个完整页面，文件达 196 行，违反单一职责
|
||||||
|
- `SettingsView.swift` 定义了大量子页面（GoalSetting、MethodPreference、FeedbackForm），单个文件达 312 行
|
||||||
|
|
||||||
|
**修复建议：** 将通用组件（输入框、设置行、任务行）收拢到 DesignSystem 目录；将 SettingsView 的子页面提取为独立文件。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、视觉设计细节问题 (MEDIUM)
|
||||||
|
|
||||||
|
### 4.1 状态指示圆点过小
|
||||||
|
|
||||||
|
**问题描述：** 服务器状态圆点仅 6pt（AIHomeView L35），学习计时状态圆点 6pt，在视网膜屏上几乎无法辨认。
|
||||||
|
|
||||||
|
**修复建议：** 状态指示器至少 8-10pt。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4.2 评分按钮颜色逻辑问题
|
||||||
|
|
||||||
|
**问题描述：** `ReviewCardView` 中掌握程度评分按钮选中时使用 `ZXGradient.brand`（紫→橙渐变），而按钮本身各有语义色（红/橙/黄/绿），选中反馈与语义色不匹配。
|
||||||
|
|
||||||
|
```swift
|
||||||
|
// ZXRatingBtn: 选中时统一使用 ZXGradient.brand 而非各自语义色
|
||||||
|
.background(selected ? AnyView(ZXGradient.brand) : AnyView(Color.zxFill005))
|
||||||
|
```
|
||||||
|
|
||||||
|
**修复建议：** 选中时使用各按钮对应颜色（红=`.red`，橙=`.orange`，黄=`.yellow`，绿=`.green`），增强语义关联。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4.3 骨架屏实现问题
|
||||||
|
|
||||||
|
**问题描述：** `ZXShimmer` 使用白色半透亮光，在 light mode 下几乎不可见（白色叠加在浅色背景上）。
|
||||||
|
|
||||||
|
**修复建议：** 根据 colorScheme 使用不同叠加色：light mode 用 `Color.black.opacity(0.06)`，dark mode 用 `Color.white.opacity(0.06)`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4.4 TabBar 定位指示器可优化
|
||||||
|
|
||||||
|
**问题描述：** 当前 TabBar 选中指示为紫色半透明圆（28pt, scale 1.4），视觉冲击力弱，与 Figma/Apple 标准胶囊状指示器差距明显。
|
||||||
|
|
||||||
|
**修复建议：** 改为横向胶囊形状 + SF Symbol 的 `.fill` 变体（如 `brain.head.profile.fill`），增强选中/非选中区分度。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4.5 Emoji 头像与系统设计不协调
|
||||||
|
|
||||||
|
**问题描述：** `ProfileView` 使用 🧑🎓 作为头像占位（80pt 圆内 36pt emoji），与系统联系人头像风格不统一。
|
||||||
|
|
||||||
|
**修复建议：** 使用 SF Symbol `person.crop.circle.fill` + 渐变背景，或集成系统联系人头像组件。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、动效建议 (LOW-MEDIUM)
|
||||||
|
|
||||||
|
### 5.1 庆祝动画粒子性能
|
||||||
|
|
||||||
|
**问题描述：** `ZXCelebrationView` 使用 60 个 `Circle()` 粒子同时动画，使用 `UIScreen.main.bounds` 计算位置。每帧重绘 60 个粒子在低端设备上可能掉帧。
|
||||||
|
|
||||||
|
**修复建议：** 减少粒子数量至 30-40，使用 `Canvas` 或 `timelineView` 替代逐帧动画。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5.2 进度条动画时程
|
||||||
|
|
||||||
|
**问题描述：** `ZXAIAnalysisProgress` 每步 1.2s × 4 步 = 总计 4.8s，超出微交互建议的 150-300ms，但作为分析进度展示可接受。然而当前是纯计时动画，不反映实际分析进度。
|
||||||
|
|
||||||
|
**修复建议：** 改为连接真实分析状态，或在后期迭代中实现。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5.3 动画 easing 函数使用合理
|
||||||
|
|
||||||
|
**正面评价：** 大部分动画使用了 `easeInOut`、`easeOut`、`spring` 等非线性缓动，符合设计规范建议。按钮使用 `.easeOut(duration: 0.15)` 的快响应按压反馈，设计合理。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、正面设计亮点
|
||||||
|
|
||||||
|
以下为值得保留和发扬的设计决策：
|
||||||
|
|
||||||
|
| 方面 | 实现 | 评价 |
|
||||||
|
|------|------|------|
|
||||||
|
| **设计令牌体系** | ZXColors / ZXGradient / ZXRadius / ZXSpacing / ZXSize / ZXFont | 完整统一，像素级还原度高 |
|
||||||
|
| **暗色模式** | 全量 `Color(light:dark:)` 自适应 | 双模式覆盖完整 |
|
||||||
|
| **品牌渐变** | 紫→橙 135° 渐变贯穿全应用 | 品牌一致性强 |
|
||||||
|
| **Toast 系统** | 全局单例 + 队列管理 + 类型系统 | 架构设计优秀 |
|
||||||
|
| **触觉反馈** | `.sensoryFeedback(.impact(weight: .light))` | 增强操作感知 |
|
||||||
|
| **无障碍标签** | 大部分按钮有 `.accessibilityLabel` / `.accessibilityHint` | 覆盖度较高 |
|
||||||
|
| **撤消操作** | `confirmationDialog` 二次确认 | 防止误操作 |
|
||||||
|
| **错误处理 UI** | EditProfilePage 的 saveError 状态 | 良好的错误反馈 |
|
||||||
|
| **加载骨架** | ZXShimmer + ZXDotLoader + ZXLoadingView | 多层次的 loading 方案 |
|
||||||
|
| **完成庆祝** | ZXCelebrationView 粒子+卡片组合 | 情感化设计到位 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 七、优先级整改路线
|
||||||
|
|
||||||
|
### 第一阶段：可访问性修复（本周）
|
||||||
|
1. [ ] 全 App 添加 `@Environment(\.accessibilityReduceMotion)` 检查
|
||||||
|
2. [ ] 关键字号迁移至 Dynamic Type（至少 title/body/caption）
|
||||||
|
3. [ ] Light mode 文字对比度修复（zxF03/zxF04/zxF035）
|
||||||
|
4. [ ] TextField 添加 accessibilityLabel
|
||||||
|
|
||||||
|
### 第二阶段：交互规范修复（下周）
|
||||||
|
5. [ ] 触控目标放大至 44pt
|
||||||
|
6. [ ] 异步按钮统一添加 loading 状态
|
||||||
|
7. [ ] Emoji 替换为 SF Symbols（用户可见图标）
|
||||||
|
|
||||||
|
### 第三阶段：架构优化（后续迭代）
|
||||||
|
8. [ ] NavigationStack + navigationDestination 迁移
|
||||||
|
9. [ ] ZXPressModifier 手势冲突重构
|
||||||
|
10. [ ] 大型文件拆分（DailyThinkingPage / SettingsView）
|
||||||
|
11. [ ] 组件的代码去重
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*本报告由 ui-ux-pro-max 设计系统 + 代码审查生成，共审查 32 个 Swift 文件、38 个视图组件。*
|
||||||
281
技术设计/web-projects/UI-UX审查报告.md
Normal file
281
技术设计/web-projects/UI-UX审查报告.md
Normal file
@ -0,0 +1,281 @@
|
|||||||
|
# 知习 Web 项目 UI/UX 设计审查报告
|
||||||
|
|
||||||
|
> 审查日期：2026-05-18 | 来源：ui-ux-pro-max 设计系统 + 代码审查 | 范围：web-projects (Astro + Tailwind CSS v4)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一、严重问题 (CRITICAL)
|
||||||
|
|
||||||
|
### 1.1 Z-Index 管理混乱
|
||||||
|
|
||||||
|
**问题描述：** `BaseLayout.astro` 中全局进度条使用 `z-[9999]`，而页面中其他元素使用 `z-10`、`z-20`、`z-50` 等。ux-guidelines 将 z-index 管理问题列为 HIGH 严重级别，明确指出："**Don't: Use arbitrary large z-index values**"。
|
||||||
|
|
||||||
|
```astro
|
||||||
|
<!-- BaseLayout.astro L44 — 当前写法 -->
|
||||||
|
<div id="global-progress" class="... z-[9999]">
|
||||||
|
|
||||||
|
<!-- 设计规范要求：定义 z-index 等级 -->
|
||||||
|
<!-- z-10: 基础内容, z-20: 浮动卡片, z-30: Header, z-50: Modal/Progress -->
|
||||||
|
```
|
||||||
|
|
||||||
|
**涉及位置：**
|
||||||
|
- `BaseLayout.astro` L44 — `z-[9999]` 进度条
|
||||||
|
- `index.astro` — 浮动卡片使用 `z-50`（与进度条冲突）
|
||||||
|
- `philosophy.astro` — 多处 `z-10`, `z-20`，与固定 header(`z-50`) 交错
|
||||||
|
|
||||||
|
**修复建议：** 建立全局 z-index 等级体系（`z-10` 内容 → `z-20` 浮动装饰 → `z-30` Header/Nav → `z-40` 遮罩 → `z-50` Toast/Progress），统一使用 Tailwind token 管理。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.2 未检查 prefers-reduced-motion
|
||||||
|
|
||||||
|
**问题描述：** 所有 6 个 CSS 动画（`float-slow`/`float-medium`/`float-fast`/`breathe`/`fadeInUp`/`blurIn`）和 2 个弹幕动画均未检查用户系统偏好。页面首页包含 **6 个持续动画元素**（1 个 breathe 光环 + 4 个浮动卡片 + 1 个轨道旋转），远超过 Stack 指南中 "Don't: Multiple bounce animations on page" 的建议。
|
||||||
|
|
||||||
|
**涉及文件：**
|
||||||
|
- `global.css` — 8 个 @keyframes 动画定义
|
||||||
|
- `index.astro` — 5+ 个 animate-float-* + animate-breathe 元素
|
||||||
|
- `philosophy.astro` — `animate-spin` 轨道 + `animate-float-slow` 箭头
|
||||||
|
|
||||||
|
**修复建议：**
|
||||||
|
```css
|
||||||
|
@media (prefers-reduced-motion: reduce) {
|
||||||
|
*, *::before, *::after {
|
||||||
|
animation-duration: 0.01ms !important;
|
||||||
|
animation-iteration-count: 1 !important;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.3 Light Mode 文字对比度不足
|
||||||
|
|
||||||
|
**问题描述：** 多处文字使用 `text-slate-500`（#64748B）在白色背景上对比度仅约 3.8:1，低于 WCAG AA 最低 4.5:1 要求。ux-guidelines 明确："**Don't: Gray text on gray background**"。
|
||||||
|
|
||||||
|
| 位置 | 当前颜色 | 对比度 | 标准 |
|
||||||
|
|------|---------|--------|------|
|
||||||
|
| `text-slate-500` 多处副标题 | #64748B | ~3.8:1 | ≥4.5:1 |
|
||||||
|
| `text-slate-400` 标签/小字 | #94A3B8 | ~2.6:1 | ≥4.5:1 |
|
||||||
|
| `text-slate-300` 箭头/循环标签 | #CBD5E1 | ~1.8:1 | ≥4.5:1 |
|
||||||
|
| Footer `color: #94a3b8` ICP 备案号 | #94A3B8 | ~2.6:1 | ≥4.5:1 |
|
||||||
|
|
||||||
|
**涉及文件：** `index.astro`、`product.astro`、`philosophy.astro`、`Footer.astro`、`waitlist.astro`
|
||||||
|
|
||||||
|
**修复建议：** 将正文灰色文字最低提升至 `text-slate-600`（#475569，~4.6:1），装饰性文字使用 `text-slate-500`（≥4.5:1 需验证）。ICP 备案号使用 `text-slate-500` 替代 `#94a3b8`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.4 Focus 状态缺失
|
||||||
|
|
||||||
|
**问题描述：** 多个可交互元素缺乏键盘焦点指示。WaitlistForm 中 `input:focus` 的 `outline: none` 虽有 box-shadow 替代，但页面上链接和按钮的 focus 状态不统一。
|
||||||
|
|
||||||
|
**涉及位置：**
|
||||||
|
- `Header.astro` — 导航链接无 `:focus-visible` 样式
|
||||||
|
- `index.astro` — Portal 卡片 (`<a>` 标签) 无 focus 样式
|
||||||
|
- `product.astro` — Pain point 卡片 (`<div>` + 无 `tabindex`) 键盘不可达
|
||||||
|
- `philosophy.astro` — 大量 `<div>` 卡片无键盘交互
|
||||||
|
|
||||||
|
**修复建议：** 为所有可交互元素添加 `focus-visible:ring-2 focus-visible:ring-tech-blue focus-visible:ring-offset-2`，确保 Tab 键可导航所有交互元素。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 二、高优先级问题 (HIGH)
|
||||||
|
|
||||||
|
### 2.1 表单提交按钮无 Loading 状态
|
||||||
|
|
||||||
|
**问题描述：** waitlist 表单的提交按钮点击后无 loading 过渡，直接隐藏表单显示成功。ux-guidelines 要求 "Show loading then success/error state"。
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// waitlist.astro / WaitlistForm.astro — 当前
|
||||||
|
form?.addEventListener('submit', (e) => {
|
||||||
|
e.preventDefault();
|
||||||
|
form.hidden = true;
|
||||||
|
successMessage.hidden = false;
|
||||||
|
});
|
||||||
|
// 问题：无 loading 态、无网络请求失败处理、无防重复提交
|
||||||
|
```
|
||||||
|
|
||||||
|
**修复建议：** 提交后按钮变为 loading spinner → API 调用 → 成功/失败状态。同时禁用按钮防止重复提交。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.2 滚动进度条无节流
|
||||||
|
|
||||||
|
**问题描述：** `BaseLayout.astro` 中 `scroll` 事件监听器未做节流处理，每次滚动触发 DOM 更新。
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// BaseLayout.astro L55 — 当前
|
||||||
|
window.addEventListener('scroll', updateProgress, { passive: true });
|
||||||
|
```
|
||||||
|
|
||||||
|
**修复建议：** 使用 `requestAnimationFrame` 包裹或添加 `throttle(16ms)`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.3 Footer 使用 inline onmouseover/onmouseout
|
||||||
|
|
||||||
|
**问题描述：** `Footer.astro` 中超链接使用了内联 JS 事件而非 CSS `:hover` 伪类，违反关注点分离原则。
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- Footer.astro L20 — 当前 -->
|
||||||
|
<a href="..." style="color: #64748b"
|
||||||
|
onmouseover="this.style.color='#4F7CFF'"
|
||||||
|
onmouseout="this.style.color='#64748b'">隐私政策</a>
|
||||||
|
```
|
||||||
|
|
||||||
|
**修复建议：** 使用 Tailwind `hover:text-tech-blue transition-colors` 类替代 inline JS。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.4 图片无显式宽高
|
||||||
|
|
||||||
|
**问题描述：** `product.astro` 使用 Unsplash 图片未指定 `width`/`height` 属性，导致加载时 Cumulative Layout Shift。
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- product.astro L69 — 当前 -->
|
||||||
|
<img alt="知习 产品界面展示"
|
||||||
|
class="w-full h-auto ... max-h-[600px]"
|
||||||
|
src="https://images.unsplash.com/..." />
|
||||||
|
```
|
||||||
|
|
||||||
|
**修复建议：** 添加 `width="1200" height="800"` 或使用 Astro Image 组件优化。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、中优先级问题 (MEDIUM)
|
||||||
|
|
||||||
|
### 3.1 表单样式重复定义
|
||||||
|
|
||||||
|
**问题描述：** waitlist 表单样式同时存在于两处：
|
||||||
|
- `WaitlistForm.astro` — 使用 scoped `<style>` + CSS 类
|
||||||
|
- `waitlist.astro` — 使用 `<style is:global>` 完全重新定义了 `.wl-*` 样式
|
||||||
|
|
||||||
|
两套样式互不共享，维护成本高。
|
||||||
|
|
||||||
|
**修复建议：** 统一使用 WaitlistForm 组件，waitlist.astro 仅传递配置参数。或抽离共享 CSS → `global.css` `@layer components`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.2 HTML 结构疑似错误
|
||||||
|
|
||||||
|
**问题描述：** `product.astro` L129 处有多余的 `</div>`，导致 section 结构异常嵌套。对比 L66 开始的 `<div class="relative max-w-5xl ...">` 到 L129 有 3 个 `</div>` 闭合而开启仅 2 个（滚动效果容器 + 图片容器），可能是从 index.astro 复制后遗留。
|
||||||
|
|
||||||
|
**修复建议：** 使用 HTML 校验工具检查，确保 section 内闭合标签匹配。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.3 持续循环动画过多
|
||||||
|
|
||||||
|
**问题描述：** 首页同时运行 6+ 个无限循环动画，包括 1 个 `animate-breathe`（4s）、4 个 `animate-float-*`（4-8s）、弹幕动画（15s）。html-tailwind Stack 指南指出："**Don't: Multiple bounce animations on page**"，建议仅对加载指示器使用持续动画。
|
||||||
|
|
||||||
|
**涉及元素（index.astro）：**
|
||||||
|
- L16 — `animate-breathe` 光环
|
||||||
|
- L96 — `animate-float-slow` 浮动卡片 "今日任务"
|
||||||
|
- L106 — `animate-float-medium` 浮动卡片 "主动回忆"
|
||||||
|
- L116 — `animate-float-fast` 浮动卡片 "AI 分析"
|
||||||
|
- L126 — `animate-float-slow` 浮动卡片 "复习计划"
|
||||||
|
- product.astro — 5 个 `animate-danmaku-*` 弹幕
|
||||||
|
|
||||||
|
**修复建议：** 减少活跃动画元素至 2-3 个核心区域；使用 `animation-delay` 错开启动时机，避免同时动画；或改为 scroll-triggered 一次性动画。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.4 Portal 卡片对比度与 Glass 效果
|
||||||
|
|
||||||
|
**问题描述：** `index.astro` 的 Portal 区域卡片使用 `glass-card-premium`（`rgba(255,255,255,0.6)`），内文字使用 `text-slate-500`（#64748B）。在亮色背景下，毛玻璃效果叠加灰色文字会进一步降低对比度。设计规范指出 "**Glass card light mode: Use bg-white/80 or higher opacity**"。
|
||||||
|
|
||||||
|
**涉及位置：**
|
||||||
|
- `index.astro` L146/159/172 — 三个 portal 卡片 `<a>` 标签
|
||||||
|
- `product.astro` L68 — 产品截图卡片
|
||||||
|
|
||||||
|
**修复建议：** 将 glass-card 背景提升至 `bg-white/80`，内部文字使用 `text-slate-700` 或 `text-navy` 确保对比度。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.5 移动端弹幕覆盖内容
|
||||||
|
|
||||||
|
**问题描述：** `product.astro` 弹幕容器 `absolute inset-0` 覆盖整个截图区域, `pointer-events-none` 虽有保护，但移动端小屏（375px）下弹幕文字会遮挡截图内容，影响展示效果。
|
||||||
|
|
||||||
|
**修复建议：** 移动端隐藏弹幕层（`hidden md:block`）或缩小弹幕尺寸、减少数量。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、性能与可维护性 (MEDIUM-LOW)
|
||||||
|
|
||||||
|
### 4.1 CTA 组件与页面样式"割裂"
|
||||||
|
|
||||||
|
**问题描述：** `CTA.astro` 组件使用独立的 `<style>` scoped CSS + CSS 自定义属性（`--color-accent`），但主页面的 CTA 按钮直接内联 Tailwind 类（`btn-primary-gradient`），存在两套按钮样式体系。
|
||||||
|
|
||||||
|
**CTA.astro（CSS 变量体系）：**
|
||||||
|
```css
|
||||||
|
.button.primary { background: var(--color-accent); }
|
||||||
|
```
|
||||||
|
|
||||||
|
**index.astro/product.astro（Tailwind 体系）：**
|
||||||
|
```html
|
||||||
|
<a class="btn-primary-gradient">进入产品</a>
|
||||||
|
```
|
||||||
|
|
||||||
|
**修复建议：** 统一使用 `btn-primary-gradient` 全局类或统一改为 CTA 组件渲染，消除样式双轨。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4.2 Unsplash 外链图片依赖
|
||||||
|
|
||||||
|
**问题描述：** `product.astro` 和 `philosophy.astro` 使用 `images.unsplash.com` 外链图片。Unsplash URL 参数 `?w=1200&h=800` 不一定会返回精确尺寸；外部依赖有可用性风险。
|
||||||
|
|
||||||
|
**修复建议：** 将关键展示图片本地化存放于 `/public` 目录，或使用 CDN 代理。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4.3 IntersectionObserver 选择器范围过大
|
||||||
|
|
||||||
|
**问题描述：** `BaseLayout.astro` L67 对所有 `.animate-reveal-up` 元素注册 Observer，随页面增长可能导致大量观察者。
|
||||||
|
|
||||||
|
**修复建议：** 当前规模可接受，但建议在 SPA 模式切换时清理（当前为 MPA，每页重建，影响不大）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、正面设计亮点
|
||||||
|
|
||||||
|
| 方面 | 实现 | 评价 |
|
||||||
|
|------|------|------|
|
||||||
|
| **设计令牌体系** | `global.css` 57 个 CSS 自定义属性 | 完整且命名规范（Material Design 3 风格） |
|
||||||
|
| **字体配对** | Manrope（标题）+ Inter（标签） | 现代、清晰，品牌感强 |
|
||||||
|
| **毛玻璃系统** | `.glass-card-premium` / `.glass-panel` | 层次丰富，移动端友好 |
|
||||||
|
| **动画缓动曲线** | `cubic-bezier(0.16, 1, 0.3, 1)` | 优美的缓出曲线 |
|
||||||
|
| **无障碍标签** | 表单使用 `<label for="...">` | 语义正确 |
|
||||||
|
| **图标系统** | Material Symbols（variable font） | 灵活可调节 |
|
||||||
|
| **响应式设计** | 桌面/移动端差异化布局 | 顾及全面 |
|
||||||
|
| **SEO 元标签** | og: / twitter: 全套 + canonical URL | 完整 |
|
||||||
|
| **Viewport 设置** | `content="width=device-width, initial-scale=1.0"` | 正确 |
|
||||||
|
| **品牌渐变** | 蓝→紫 135° 渐变贯穿 | 品牌一致性强 |
|
||||||
|
| **等待名单表单** | 字段类型正确（email/tel/checkbox） | 输入体验好 |
|
||||||
|
| **焦点反馈** | WaitlistForm 有 `box-shadow: 0 0 0 3px` 替代 outline | 视觉优雅 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、优先级整改路线
|
||||||
|
|
||||||
|
### 第一阶段：可访问性与规范（本周）
|
||||||
|
1. [ ] 建立 z-index 等级体系，替换 `z-[9999]`
|
||||||
|
2. [ ] 添加 `prefers-reduced-motion` 媒体查询
|
||||||
|
3. [ ] Text-slate-400/500/300 → 提升至对应高对比度色
|
||||||
|
4. [ ] 所有交互元素添加 `focus-visible` 样式
|
||||||
|
|
||||||
|
### 第二阶段：交互完善（下周）
|
||||||
|
5. [ ] Waitlist 表单添加 loading → success/error 状态机
|
||||||
|
6. [ ] 滚动进度条添加节流
|
||||||
|
7. [ ] Footer 内联 JS 替换为 CSS :hover
|
||||||
|
8. [ ] 表单样式去重（WaitlistForm.astro vs waitlist.astro）
|
||||||
|
|
||||||
|
### 第三阶段：视觉优化（后续迭代）
|
||||||
|
9. [ ] Glass-card 背景提升至 `bg-white/80`
|
||||||
|
10. [ ] 减少首页持续循环动画数量（≤3）
|
||||||
|
11. [ ] 图片显式宽高 / 本地化
|
||||||
|
12. [ ] 修复 product.astro HTML 结构对齐
|
||||||
|
13. [ ] 统一 CTA 按钮样式体系
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*本报告由 ui-ux-pro-max 设计系统 + 代码审查生成，共审查 web-projects 中 17 个源文件（Astro/CSS/JS）。webApp-projects 仓库仅有 .git 目录，无前端代码可审查。*
|
||||||
Loading…
x
Reference in New Issue
Block a user