frontend-design

前端设计

构建令人难忘且功能明确的界面，并带有清晰的观点（不要通用模板）。确定一个美学方向，定义 token，交付可访问且响应式的 UI，并保持改动范围可控。

首选目标（选择最合适的）

1. Next.js (TypeScript)：优先用于生产级应用/营销路由和设计系统工作。
2. React (TypeScript)：优先用于 Next.js 之外的 SPA/组件库。
3. Vanilla HTML/CSS/JS：非常适合静态演示、原型和独立嵌入。

快速开始（先做这一步）

1. 最多提出 4 个问题：
   • 目标用户和要完成的任务是什么（变更后什么应该让人感觉“轻松”）？
   • 它位于哪里（组件/路由），使用什么技术栈？优先 Next.js/React；vanilla 适合独立页面或原型。
   • 在 Next.js 中：默认使用 App Router（app/）。是否有服务端/客户端约束？
   • 是否有硬性约束（品牌 token、浅色/深色、动效限制、必须保留的 UI 部分、性能预算）？
2. 选择一个美学方向 + 一个标志性动作。如果不明确，从 references/aesthetic-playbook.md 中提出 2–3 个选项。
3. 定义 token（字体、调色板、间距、圆角、阴影、动效）。强调色保持在 1–2 个。
4. 先构建结构（语义化标记 + 布局），再做动效，然后打磨 + QA。

护栏（避免踩坑）

• 保持范围紧凑：只重新设计用户要求的部分。
• 如果在现有仓库中工作，复用现有 token/组件；除非被要求，否则不要引入新的全局样式系统。
• 让复杂度与愿景匹配：精致极简需要克制；极繁主义需要有意的结构（不是随机装饰）。
• 所有动画都要尊重 prefers-reduced-motion。
• 避免“AI 味”默认值。如果仓库已经使用通用字体，除非用户明确想要新字体，否则保留它。
• 强制 token 语义：错误/成功/警告颜色用于表达含义，而不是装饰；在浅色/深色下保持对比度可访问。
• 默认交付易于维护的代码：小组件、清晰层级、最小依赖。
• 不要添加新包（动画库、UI 套件、图标集），除非用户明确要求或仓库已经使用它们。
• 默认每个视图只有一个主 CTA；其余降级（次要/三级），避免操作竞争。

工作流

1) 确定一个方向

• 声明：美学方向、调色板氛围、字体搭配，以及标志性动作。
• 写一句 1–2 句的设计论点，解释层级和氛围。
• 使用 references/anti-patterns.md 避免可预测的布局和陈词滥调的调色板。

1b) 设计系统规则（严格 vs 灵活）

• 严格：语义化颜色含义、可读的字号阶梯、减少动效、可见焦点，以及 AI 操作的“人类掌控”（撤销/应用/确认）。
• 灵活：品牌强调色相、深色模式下的表面“温度”，以及密度预设（紧凑 vs 舒适）。
• 何时阅读更多：定义 token 时加载 references/tokens-and-semantics.md，添加 AI 界面时加载 references/ai-native-ui-patterns.md。

1a) React/Next.js 编码指南（实现时阅读）

• React 基础：保持组件纯粹；对于用户驱动的工作，优先使用事件处理器而不是 Effects；遵循 Hooks 规则。
• Next.js App Router：保持客户端组件小巧；默认使用服务端组件；仅在需要状态、effects 或浏览器 API 的地方标记 "use client"。
• 数据获取：优先使用服务端 fetch 和显式的缓存/重新验证控制；避免不必要的数据客户端 effects。
• 何时阅读更多：在编写复杂 React 逻辑或引入新的数据获取模式之前，加载 references/react-next-best-practices.md。

2) 规划 token 与布局（先于细节）

• 为以下内容定义 CSS 变量（或主题对象）：
  • 颜色：background/surface/ink/muted/accent（+ 可选的 accent2）
  • 字体：display/body/mono、字号比例、行高
  • 形状：圆角比例与边框规则
  • 深度：阴影与轮廓规则
  • 动效：时长 + 缓动 + 揭示错峰步长
• 规划页面/组件骨架与内容层级。
• 参考 references/implementation-patterns.md 了解模式与 QA。

3) 实现（交付代码，而非情绪板）

• 从语义化结构与无障碍交互（键盘 + 焦点状态）开始。
• 用 Grid 构建宏观布局；用 Flexbox 构建微观布局。
• 对于 Next.js/React，保持组件小巧且可组合；优先使用 CSS Modules 或仓库现有的样式方案。
• 使用“链接用于导航，按钮用于操作”，以保证语义与键盘行为正确。
• 谨慎但果断地应用标志性设计（一个令人难忘的点，而非十个）。
• 将动效作为编排（一次有力的页面加载 + 少量微交互），而非随意的装饰。

3a) Next.js 实现说明（适用时）

• 仅 App Router：假定使用 app/ 路由（而非 pages/）。
• 服务端 vs 客户端：默认使用 Server Components；仅对交互孤岛添加 "use client"。
• 数据 + 状态：尽可能在服务端进行数据获取；保持客户端状态局部且有意义。
• 性能：避免布局偏移（稳定高度、可预测的网格）；在移动端保持模糊/阴影对绘制友好。
• 平台原语：优先使用 next/link 进行导航，使用 next/image 处理真实图片（若可用）。
• 字体：若在 Next.js 中更改排版，优先使用 next/font 以避免 FOIT/FOUT 意外。
• 样式：保持一致——CSS Modules、Tailwind 或现有体系；未经询问不要引入新方案。

3b) 内容 + 状态（不要交付空壳）

• 为任何数据驱动的 UI 定义加载、空和错误状态。
• 保持文案简洁且有目的；除非被要求，避免使用占位 lorem。
• 保留现有产品术语，除非用户要求更改文案。

4) 打磨与 QA

• 响应式检查：折叠网格、保持内边距、在移动端保持 CTA 突出。
• 无障碍检查：地标、一个 h1、标签、对比度、焦点顺序、相关时提供跳转链接。
• 性能检查：避免移动端昂贵阴影、保持动画对绘制友好、避免大图。

完成定义

• 布局在移动端 + 桌面端断点下看起来有意为之（无拥挤文字、无孤立 CTA）。
• 焦点状态可见，Tab 顺序符合逻辑，动效尊重 prefers-reduced-motion。
• Token 集中管理（CSS 变量/主题），标志性设计存在但不过度使用。

交付物（如何呈现结果）

• 列出更改的文件及其作用。
• 解释美学方向 + 标志性设计（1–2 句话）。
• 提供验证命令（使用仓库的约定；常见命令包括 npm run dev、npm run lint、npm test）。

捆绑资源

• references/aesthetic-playbook.md：强有力的方向、字体+颜色线索、标志性设计。
• references/implementation-patterns.md：vanilla + React 的布局/动效/无障碍模式。
• references/anti-patterns.md：快速“不要这样做”清单，以避免泛泛输出。
• references/react-next-best-practices.md：React + Next.js 编码指南（hooks、effects、server/client、数据获取）。
• references/tokens-and-semantics.md：token 语义、字号阶梯、深色模式与密度规则（严格 vs 灵活）。
• references/ai-native-ui-patterns.md：copilot 面板、引用、披露与人机协同 UI 模式。
• assets/vanilla-starter/：可运行的 vanilla 起步项目，可复制并通过 CSS 变量重新主题化。
• assets/react-component-starter/：小型 React 组件 + CSS module 骨架，可重新主题化。
• assets/nextjs-app-router-starter/：最小 Next.js App Router 页面 + token，可复制并重新主题化。