响应式Web应用开发计划生成器

## 执行摘要 本计划采用移动优先、渐进增强的策略，构建一个响应式Web应用，以性能为核心，以设计系统为驱动。我们将使用React + TypeScript + Vite作为技术栈，配合Tailwind CSS v4（利用其CSS-first配置）和Radix UI原语，构建一个符合WCAG 2.1 AA标准、具备流畅动画和优雅暗色模式的应用。核心方法是通过8px基准间距、流体排版和容器查询实现自适应布局，同时通过代码分割、资源优化和GPU加速动画确保Core Web Vitals达标。该计划分为四个阶段：MVP功能、设计系统完善、性能优化和跨设备质量保障。 --- ## 1. 响应式策略 ### 断点策略（移动优先） | 断点 | 宽度 | 布局策略 | 理由 | |------|------|----------|------| | `base` | 320px–639px | 单列堆叠，底部导航栏，全宽触控目标 | 覆盖小型手机，最小可用宽度 | | `sm` | 640px–767px | 单列，顶部导航栏，卡片网格2列 | 大型手机/小型平板，利用额外宽度 | | `md` | 768px–1023px | 双列布局，侧边栏可折叠，卡片网格3列 | 平板，平衡内容密度与可读性 | | `lg` | 1024px–1439px | 三列布局，固定侧边栏，卡片网格4列 | 标准桌面，最大化信息展示 | | `xl` | 1440px+ | 最大内容宽度1440px，居中，卡片网格4–6列 | 大型显示器，防止内容过度拉伸 | **方法：** 移动优先。理由：目标用户中移动端流量占60%以上，强制优先考虑核心功能和性能，并通过渐进增强实现桌面端增强。 ### 布局系统 - **CSS Grid** 用于页面级布局（`grid-template-columns: repeat(12, 1fr)`），**Flexbox** 用于组件内部排列。 - **容器查询**（`@container`）用于卡片和面板，使其能够根据父容器而非视口进行自适应。 - **流体排版：** 使用 `clamp()` 函数：`font-size: clamp(1rem, 0.9rem + 0.5vw, 1.25rem)`，确保字号在320px到1440px之间平滑缩放。 ### 设备适配 - **安全区域：** 使用 `env(safe-area-inset-*)` 处理刘海屏和底部手势条，为固定元素添加 `padding-bottom: env(safe-area-inset-bottom)`。 - **动态视口单位：** 使用 `100dvh` 用于全屏容器，`100svh` 用于粘性页脚，`100lvh` 用于需要稳定高度的滚动容器。 - **触控目标：** 所有可交互元素最小为44×44px（移动端），桌面端最小为32×32px。 - **悬停状态：** 仅在 `(hover: hover)` 和 `(pointer: fine)` 媒体查询下启用，避免触控设备出现粘滞悬停。 - **键盘导航：** 实现可见焦点指示器（2px轮廓，偏移2px），支持Tab键顺序，使用 `:focus-visible` 伪类。 ### 图片优化 - **`srcset` 和 `sizes`：** 提供320w、640w、960w、1280w、1920w的图片，配合 `sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"`。 - **艺术指导：** 使用 `<picture>` 元素为移动端提供裁剪版本（居中裁剪），为桌面端提供完整宽幅版本。 - **格式：** 使用WebP（支持率>95%），回退到JPEG；对图标使用SVG。 --- ## 2. 性能蓝图 ### 核心Web Vitals目标 | 指标 | 目标 | 达标策略 | |------|------|----------| | LCP | <2.5s（移动端3G网络） | 预加载关键资源，内联关键CSS，使用 `fetchpriority="high"` | | INP | <100ms | 最小化主线程工作，使用Web Workers处理数据解析，防抖输入处理 | | CLS | <0.1 | 为图片和嵌入内容预留尺寸，使用 `aspect-ratio` CSS属性，字体加载使用 `font-display: swap` | ### 加载策略 - **代码分割：** 使用React.lazy()按路由分割，将初始包控制在<170KB（gzip压缩后）。 - **懒加载：** 图片使用 `loading="lazy"`（首屏以上除外），IntersectionObserver用于滚动进入视口的组件。 - **资源优化：** 使用Vite的 `build.assetsInlineLimit`（默认4KB）内联小资源，使用 `vite-plugin-compression` 进行gzip/brotli预压缩。 - **预加载关键路径：** 预加载字体（`rel="preload"`）、首屏图片（`fetchpriority="high"`）和主CSS。 ### 渲染与动画 - **CSS Containment：** 在独立组件上使用 `content-visibility: auto` + `contain-intrinsic-size`，跳过视口外渲染。 - **GPU合成：** 仅对 `transform` 和 `opacity` 属性进行动画（避免 `top/left/width/height`），使用 `will-change: transform` 仅用于持续动画元素。 - **CSS Containment属性：** 在卡片、列表项和模态框上使用 `contain: layout paint`，隔离布局和绘制。 - **动画帧率：** 使用 `requestAnimationFrame` 进行JS驱动的动画，使用Web Animations API（WAAPI）实现高性能、可取消的动画。 ### 离线与降级 - **Service Worker：** 使用Workbox进行运行时缓存（图片、字体、API响应），采用Stale-While-Revalidate策略。 - **降级：** 如果WebGL不可用，回退到Canvas；如果Canvas不可用，回退到静态图片。如果JS被禁用，显示无脚本提示，并提供核心内容的静态HTML。 ### 工具 - **Lighthouse CI** 用于每次PR的预算检查（性能≥90，可访问性≥95）。 - **WebPageTest** 用于多位置、真实设备测试。 - **Bundle Analyzer**（`vite-bundle-visualizer`）用于包体积监控。 --- ## 3. 设计系统规范 ### 设计令牌架构 令牌分为三层：**原始令牌**（原始值）、**语义令牌**（用途）、**组件令牌**（组件特定）。使用CSS自定义属性（`@theme` 在Tailwind v4中）实现运行时主题切换。 ### 色彩策略 **基础调色板（原始令牌）：** - 中性色：`--color-gray-50` 至 `--color-gray-950`（10阶，冷色调） - 品牌色：`--color-primary-500`（#4F46E5，靛蓝），`--color-primary-600`（#4338CA） - 强调色：`--color-accent-500`（#F59E0B，琥珀色），用于关键操作 - 语义色：`--color-success`（#10B981），`--color-error`（#EF4444），`--color-warning`（#F59E0B），`--color-info`（#3B82F6） **语义令牌（浅色/暗色模式）：** | 令牌 | 浅色 | 暗色 | |------|------|------| | `--bg-primary` | `#FFFFFF` | `#0F172A` | | `--bg-secondary` | `#F8FAFC` | `#1E293B` | | `--text-primary` | `#0F172A` | `#F1F5F9` | | `--text-secondary` | `#475569` | `#94A3B8` | | `--border-default` | `#E2E8F0` | `#334155` | **对比度：** 所有文本/背景组合≥4.5:1（AA），大文本（≥18pt）≥3:1。暗色模式使用 `color-scheme: dark` 确保原生控件适配。 ### 字体排印 - **正文字体：** Inter（可变字体），`font-feature-settings: "cv11"` 优化屏幕显示。理由：x-height高，数字清晰，在320px宽度下可读性好。 - **标题字体：** 使用相同的Inter字体，通过字重（600–800）和字距（`-0.02em`）区分层级，避免额外的字体请求。 - **字体加载：** 使用 `font-display: swap` 预加载，使用 `size-adjust` 和 `ascent-override` 防止CLS。 **字号比例（流体）：** | 层级 | 移动端 | 桌面端 | 字重 | |------|--------|--------|------| | 标题1 | `clamp(1.5rem, 1.2rem + 1vw, 2.5rem)` | 2.5rem | 700 | | 标题2 | `clamp(1.25rem, 1rem + 0.8vw, 2rem)` | 2rem | 600 | | 标题3 | `clamp(1.125rem, 1rem + 0.5vw, 1.5rem)` | 1.5rem | 600 | | 正文 | `clamp(0.875rem, 0.85rem + 0.2vw, 1rem)` | 1rem | 400 | | 小字 | `0.875rem` | 0.875rem | 400 | ### 间距与圆角 - **间距比例：** 8px基准：`4, 8, 12, 16, 24, 32, 48, 64, 96`（对应Tailwind的 `1, 2, 3, 4, 6, 8, 12, 16, 24`）。 - **圆角：** 4px（输入框/按钮）、8px（卡片）、12px（模态框/面板）、999px（胶囊/标签）。理由：4px用于小控件保持精确，8px+用于大容器营造亲和感。 ### 阴影与层级 | 层级 | 阴影令牌 | 用途 | |------|----------|------| | 1 | `0 1px 2px rgba(0,0,0,0.05)` | 静态卡片 | | 2 | `0 4px 6px -1px rgba(0,0,0,0.1)` | 悬停状态 | | 3 | `0 10px 15px -3px rgba(0,0,0,0.1)` | 下拉菜单 | | 4 | `0 20px 25px -5px rgba(0,0,0,0.15)` | 模态框 | 暗色模式使用更高的透明度值（`rgba(0,0,0,0.3)`+）以保持深度感知。 ### 动效令牌 | 令牌 | 值 | 用途 | |------|-----|------| | `--ease-out` | `cubic-bezier(0.16, 1, 0.3, 1)` | 元素进入（模态框、下拉菜单） | | `--ease-in-out` | `cubic-bezier(0.65, 0, 0.35, 1)` | 状态切换 | | `--duration-fast` | 150ms | 悬停、按钮反馈 | | `--duration-base` | 250ms | 折叠/展开、下拉菜单 | | `--duration-slow` | 400ms | 模态框、页面过渡 | ### 图标与插画 - **图标：** 使用Lucide图标（一致笔画宽度1.5px，几何风格），通过SVG sprite内联，支持 `currentColor` 实现主题适配。 - **插画：** 使用抽象几何风格，基于品牌色（靛蓝/琥珀色），避免照片写实风格。所有插画必须包含 `role="img"` 和 `aria-label`。 ### 组件一致性 - 所有按钮：最小高度44px（移动端），圆角8px，内边距16px水平/12px垂直。 - 所有输入框：边框1px，聚焦时2px品牌色边框，标签始终可见（不使用占位符作为标签）。 - 所有卡片：圆角8px，边框1px，内边距24px，阴影层级1。 --- ## 4. UX/UI模式库计划 ### 层级与可扫描性 - **F型布局** 用于仪表盘/列表页：标题 → 筛选器 → 内容列表，关键操作在右上角。 - **Z型布局** 用于营销/落地页：Logo → 导航 → 行动号召 → 内容 → 行动号召。 - **视觉权重：** 使用字号（标题2 vs 正文）、颜色（品牌色 vs 灰色）和间距（48px vs 24px）建立层级。 - **留白策略：** 内容块之间使用32px，卡片内使用24px，元素组之间使用16px。 ### 反馈与可发现性 - **加载状态：** 骨架屏（灰色脉冲块，匹配最终布局）用于数据获取；按钮加载时使用Spinner（16px，旋转）。 - **微交互：** 按钮按下时缩放至0.98，开关切换时颜色过渡150ms，列表项悬停时背景色变化。 - **错误状态：** 内联错误信息（红色文本+图标），位于字段下方，并附有可操作的修复建议（例如“请输入有效的邮箱地址”）。 ### 导航模式 - **移动端（<768px）：** 底部导航栏（4–5个图标+标签，44px高），汉堡菜单用于二级导航。 - **平板（768–1023px）：** 顶部导航栏 + 可折叠侧边栏（通过汉堡按钮切换）。 - **桌面端（≥1024px）：** 固定左侧边栏（240px宽），顶部面包屑导航。 - **面包屑：** 用于层级页面，显示“首页 / 父级 / 当前”，并在最后一级使用 `aria-current="page"`。 ### 可访问性清单（WCAG 2.1 AA） - 所有图片使用 `alt` 文本，装饰性图片使用 `aria-hidden="true"`。 - 所有表单字段使用 `<label>` 关联，错误信息使用 `aria-describedby`。 - 模态框使用焦点陷阱（Tab循环），打开时聚焦到模态框，关闭时返回触发元素。 - 使用 `aria-live="polite"` 播报动态内容更新（例如购物车数量）。 - 所有颜色组合对比度≥4.5:1。 - 支持 `prefers-reduced-motion`：禁用非必要动画，替换为淡入淡出效果。 ### 表单与输入 - **输入类型：** 根据设备使用 `type="email"`、`type="tel"`、`type="number"`、`inputmode="numeric"` 调出正确的键盘。 - **验证：** 失焦时验证，输入时实时校验（防抖300ms），提交时全面验证。 - **自动填充：** 使用 `autocomplete="name"`、`autocomplete="email"` 等标准值，确保浏览器自动填充正确。 - **内联错误：** 字段下方显示红色文本+图标，输入框边框变红，错误信息通过 `aria-live` 播报。 ### 动效设计 - **目的：** 动效用于引导注意力（新内容高亮）、提供反馈（按钮状态）和建立空间关系（模态框从底部滑入）。 - **时长：** 微交互150ms，下拉菜单250ms，模态框400ms。 - **缓动：** 进入使用 `--ease-out`，退出使用 `--ease-in`，持续动画使用 `--ease-in-out`。 - **减少动效：** 在 `prefers-reduced-motion: reduce` 下，将所有动画时长设为0ms或仅保留透明度过渡。 ### 空状态与边缘情况 - **零数据：** 显示插画+标题+描述+行动号召按钮（例如“暂无项目，点击创建第一个”）。 - **错误：** 显示错误图标+友好信息+“重试”按钮+“联系支持”链接。 - **超时：** 显示“请求超时”+“重试”按钮，自动重试最多3次（指数退避）。 - **权限拒绝：** 显示解释+“如何启用权限”的步骤+“设置”按钮（链接到浏览器设置）。 --- ## 5. 技术架构 ### 技术栈 | 层 | 技术 | 理由 | |----|------|------| | 框架 | React 19 + TypeScript 5 | 生态成熟，类型安全，React 19的 `use()` Hook优化数据获取 | | 构建工具 | Vite 6 | 开发服务器极快（HMR<50ms），生产构建优化 | | CSS | Tailwind CSS v4 | CSS-first配置（无JS配置文件），原生CSS变量主题，内置容器查询 | | UI原语 | Radix UI | 无头组件，完全可访问（焦点管理、ARIA），样式自由 | | 状态管理 | Zustand | 轻量（<1KB），无样板代码，支持选择器避免不必要重渲染 | | 数据获取 | TanStack Query v5 | 缓存、重试、乐观更新，内置加载/错误状态 | | 路由 | React Router v7 | 声明式路由，支持代码分割和嵌套布局 | | 测试 | Vitest + Testing Library + Playwright | 单元测试、组件测试、端到端测试和视觉回归测试 | ### 组件架构（原子设计） ``` src/ ├── components/ │ ├── ui/ # 原子：Button, Input, Badge, Icon │ ├── composite/ # 分子：SearchBar, UserCard, FilterPanel │ ├── layout/ # 组织：Header, Sidebar, Footer, Container │ └── pages/ # 模板：DashboardPage, SettingsPage ├── hooks/ # 自定义Hooks：useMediaQuery, useLocalStorage ├── lib/ # 工具函数：formatters, validators ├── stores/ # Zustand stores ├── styles/ # 全局CSS，设计令牌 └── types/ # TypeScript类型定义 ``` ### 主题系统 - 使用CSS自定义属性（`@theme`）定义设计令牌。 - 通过 `data-theme="dark"` 属性在 `<html>` 元素上切换主题。 - 使用 `prefers-color-scheme` 媒体查询自动检测系统主题，并允许用户手动覆盖（存储在localStorage中）。 - 所有组件仅引用语义令牌（`var(--bg-primary)`），不引用原始令牌。 ### CSS策略 - **Tailwind CSS v4** 用于实用类（布局、间距、排版）。 - **CSS Modules** 用于复杂组件样式（伪元素、关键帧动画）。 - **全局CSS** 用于设计令牌、基础样式（重置、字体）和全局过渡。 ### 测试策略 - **单元测试（Vitest）：** 测试工具函数、Hooks、状态逻辑。 - **组件测试（Testing Library）：** 测试渲染、交互、可访问性（使用 `jest-axe`）。 - **端到端测试（Playwright）：** 在以下视口测试关键用户流程： - 移动端：iPhone SE（375×667）、iPhone 14 Pro（393×852）、Pixel 7（412×915） - 平板：iPad Mini（768×1024）、iPad Pro（1024×1366） - 桌面端：1366×768、1920×1080 - **视觉回归：** 使用Chromatic或Percy，在每次PR时对比基线截图。 --- ## 6. 分阶段推出计划 ### 第一阶段：MVP（第1–3周） **目标：** 核心功能在移动端和桌面端可用。 - 搭建Vite + React + TS + Tailwind项目。 - 实现设计令牌基础（颜色、间距、字体）。 - 构建核心布局（移动端底部导航，桌面端侧边栏）。 - 实现核心页面（仪表盘、列表页、详情页）。 - 实现基础表单验证和错误状态。 - 配置CI（Lint、类型检查、单元测试）。 **完成标准：** 核心用户流程在移动端和桌面端可用，Lighthouse性能≥70。 ### 第二阶段：设计系统完善（第4–5周） **目标：** 视觉一致性，暗色模式，动效。 - 实现完整的语义令牌（暗色模式）。 - 构建组件库（按钮、输入框、卡片、模态框、下拉菜单）。 - 实现动效令牌和过渡。 - 实现骨架屏和加载状态。 - 实现空状态和错误状态。 - 添加图标系统（SVG sprite）。 **完成标准：** 所有组件符合设计规范，暗色模式无对比度问题，动效流畅（60fps）。 ### 第三阶段：性能优化（第6–7周） **目标：** 达到Core Web Vitals目标。 - 实现代码分割（路由级懒加载）。 - 实现图片优化（srcset、懒加载、预加载关键图片）。 - 实现Service Worker（运行时缓存）。 - 优化字体加载（预加载、font-display）。 - 添加CSS containment和content-visibility。 - 使用Lighthouse CI设置性能预算。 **完成标准：** LCP<2.5s，INP<100ms，CLS<0.1，Lighthouse性能≥90。 ### 第四阶段：跨设备质量保障（第8周） **目标：** 在所有目标设备上实现无缺陷体验。 - 在真实设备上测试（BrowserStack或本地设备实验室）。 - 修复触摸目标、安全区域、动态视口问题。 - 在暗色/浅色模式下进行可访问性审计（axe-core）。 - 键盘导航测试（无鼠标操作）。 - 减少动效测试（`prefers-reduced-motion`）。 - 离线模式测试。 **完成标准：** 所有Playwright测试通过，axe审计零严重问题，手动设备测试清单全部通过。 --- ## 7. 发布前质量检查清单 ### 响应式 - [ ] 在320px、375px、768px、1024px、1440px、1920px宽度下无水平滚动。 - [ ] 所有触控目标≥44×44px（移动端）。 - [ ] 安全区域（刘海屏、底部手势条）已处理。 - [ ] 图片在所有断点下清晰且无变形。 - [ ] 字体在所有断点下可读（无截断、无重叠）。 ### 性能 - [ ] LCP < 2.5s（移动端3G网络模拟）。 - [ ] INP < 100ms（Playwright性能追踪）。 - [ ] CLS < 0.1（Lighthouse）。 - [ ] 初始包 < 170KB gzip。 - [ ] 所有图片使用WebP格式，并设置 `srcset`。 - [ ] Service Worker已注册并缓存核心资源。 ### 可访问性 - [ ] 所有图片有 `alt` 文本。 - [ ] 所有表单字段有 `<label>`。 - [ ] 模态框有焦点陷阱和正确的 `aria-labelledby`。 - [ ] 所有颜色组合对比度≥4.5:1。 - [ ] 键盘可访问所有功能（Tab顺序逻辑清晰）。 - [ ] `prefers-reduced-motion` 已支持。 ### 功能 - [ ] 所有表单验证正常工作（内联错误、提交阻止）。 - [ ] 空状态、错误状态、超时状态均已处理。 - [ ] 暗色模式切换持久化（localStorage）。 - [ ] 离线模式显示降级提示。 ### 视觉 - [ ] 所有组件符合设计令牌（颜色、间距、圆角）。 - [ ] 暗色模式下无“刺眼”对比度问题。 - [ ] 动画流畅（无卡顿、无闪烁）。 - [ ] 图标在所有尺寸下清晰（无模糊、无像素化）。