From 6c6c3cf74a6dd405ac05729dfc5e2ff87006096e Mon Sep 17 00:00:00 2001 From: WangDL Date: Mon, 18 May 2026 21:03:41 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=20iOS=20=E5=92=8C=20?= =?UTF-8?q?Web=20=E9=A1=B9=E7=9B=AE=20UI/UX=20=E8=AE=BE=E8=AE=A1=E5=AE=A1?= =?UTF-8?q?=E6=9F=A5=E6=8A=A5=E5=91=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.7 --- .gitignore | 1 + 技术设计/ios-projects/UI-UX审查报告.md | 294 +++++++++++++++++++++++++ 技术设计/web-projects/UI-UX审查报告.md | 281 +++++++++++++++++++++++ 3 files changed, 576 insertions(+) create mode 100644 技术设计/ios-projects/UI-UX审查报告.md create mode 100644 技术设计/web-projects/UI-UX审查报告.md diff --git a/.gitignore b/.gitignore index 90a64fa..8547175 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .claude/ .DS_Store 凭据配置/ +技术设计/awesome-design-md/ diff --git a/技术设计/ios-projects/UI-UX审查报告.md b/技术设计/ios-projects/UI-UX审查报告.md new file mode 100644 index 0000000..7f951a7 --- /dev/null +++ b/技术设计/ios-projects/UI-UX审查报告.md @@ -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 个视图组件。* diff --git a/技术设计/web-projects/UI-UX审查报告.md b/技术设计/web-projects/UI-UX审查报告.md new file mode 100644 index 0000000..f0d351b --- /dev/null +++ b/技术设计/web-projects/UI-UX审查报告.md @@ -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 — `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 卡片 (`` 标签) 无 focus 样式 +- `product.astro` — Pain point 卡片 (`
` + 无 `tabindex`) 键盘不可达 +- `philosophy.astro` — 大量 `
` 卡片无键盘交互 + +**修复建议：** 为所有可交互元素添加 `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 + +隐私政策 +``` + +**修复建议：** 使用 Tailwind `hover:text-tech-blue transition-colors` 类替代 inline JS。 + +--- + +### 2.4 图片无显式宽高 + +**问题描述：** `product.astro` 使用 Unsplash 图片未指定 `width`/`height` 属性，导致加载时 Cumulative Layout Shift。 + +```html + +知习 产品界面展示 +``` + +**修复建议：** 添加 `width="1200" height="800"` 或使用 Astro Image 组件优化。 + +--- + +## 三、中优先级问题 (MEDIUM) + +### 3.1 表单样式重复定义 + +**问题描述：** waitlist 表单样式同时存在于两处： +- `WaitlistForm.astro` — 使用 scoped `