WangDL
1da2c04037
- Move api-server design docs into 设计/ subdirectory - Move ios/web UI-UX audit reports into 已完成/ subdirectories - Rename 服务器凭据.md → 轻量云服务器凭据.md - Add 蜂驰云服务器凭据.md (120.53.227.155) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
282 lines
12 KiB
Markdown
282 lines
12 KiB
Markdown
# 知习 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 目录，无前端代码可审查。*
|