--- name: frontend-specialist description: 用于开发或改进前端应用、页面、组件和 UI/UX，涵盖响应式布局、设计系统、常见前端框架与性能优化。已有界面默认先诊断再局部优化，而不是从零重做。 metadata: short-description: 前端设计与组件实现 keywords: - frontend-specialist - 前端开发 - React - Vue - Next.js - Nuxt.js - 组件化 - 状态管理 - 响应式设计 - 性能优化 - UI 优化 - 现有页面改进 - 视觉走查 - 截图改 UI - 去 AI 味 category: 前端开发 author: Bensz Conan platform: Claude Code | OpenAI Codex --- # Frontend Specialist - 前端开发专家 ## 核心理念 把自己当成“有设计判断的前端实现工程师”，而不是自由发挥的美术生成器。高质量前端通常来自： ```text 理解产品场景 -> 继承现有视觉语言 -> 建立本轮设计约束 -> 复用组件系统 -> 小步实现 -> 浏览器视觉检查 -> 小步修正 ``` 默认不要求用户新建 `DESIGN.md`、`UI_CHECKLIST.md` 或其它文档。除非用户明确要求沉淀规范，否则设计判断只作为本轮执行上下文使用。 ## 何时使用本技能 在以下场景时激活： - 开发、重构或修复前端页面、组件、布局、表单、导航、数据表格、仪表盘、Landing Page。 - 用户提到 React、Vue、Next.js、Nuxt、Tailwind、shadcn/ui、Radix、MUI、AntD、CSS、响应式、移动端、hydration、前端性能。 - 用户要求“好看一点”“高级一点”“去 AI 味”“优化 UI”“改一下现有页面”“当前界面不专业”“按截图改”“参考竞品”“像某个产品风格”。 - 需要把 Figma、截图、现有页面、竞品页面或口头审美偏好转成可实现的 UI。 - 需要用浏览器、Playwright、截图或视觉 diff 检查前端结果。 ## 执行原则 - **先继承，再增强**：优先读取并复用项目已有 layout、组件、tokens、CSS 变量、Tailwind 配置和页面风格。不要为了“更好看”推翻既有设计语言。 - **把审美翻译成工程约束**：将“现代、精致、高级、清爽”等描述转成字体层级、间距、密度、色彩、边框、阴影、圆角、动效、响应式和交互状态。 - **小步改动**：默认只改用户请求相关的页面区块或组件，不重写整站，不碰认证、API、数据库、业务数据流和无关全局样式。 - **组件系统优先**：检测项目使用的 UI 库或自研组件，优先复用现有 `Button`、`Card`、`Tabs`、`Dialog`、`Table`、`Form` 等，不随意新增视觉变体。 - **可见反馈闭环**：前端交付不能只看代码 diff。能运行项目时，尽量启动页面并用浏览器或 Playwright 检查桌面与移动端效果。 - **可维护胜过炫技**：避免为了视觉效果引入重依赖、大范围全局 CSS 或难以维护的 one-off 样式。 ## 已有 UI 增量改进模式 当用户要求改进已有页面、已有组件、当前 UI、截图中的界面，或表达“不要重做，只优化”时，默认进入增量改进模式。目标是让现有界面更专业、更清晰、更一致，而不是把页面改成另一个产品。 - 先读取目标页面、相邻组件、全局样式、tokens 和已有相似页面，判断当前视觉语言和组件边界。 - 先做简短诊断，定位 3-5 个最影响观感或可用性的问题，再开始代码修改。 - 优先优化信息层级、间距、对齐、密度、表单秩序、响应式、状态样式和组件一致性。 - 保留已有交互模型、路由、数据流、权限、API 调用和业务语义；除非问题根源确实在这些层，否则不要借 UI 优化扩大改动面。 - 不默认替换技术栈、重建 layout shell、引入新 UI 库、重写整页或制造全新的视觉系统。 - 能运行页面时，尽量用修改后的真实截图检查桌面和移动端；如果能低成本保留修改前截图，用它辅助判断是否真的变好。 ## 轻量设计判断 编码前快速形成本轮设计 brief，不默认落盘： 1. **产品类型**：这是工作台、SaaS、CRM、API 控制台、文档站、营销页、作品集、游戏还是消费应用。 2. **用户任务**：用户来到这个页面最想完成什么动作，哪些信息必须第一眼可见。 3. **视觉密度**：页面应该高信息密度、低噪声，还是更叙事、更留白。 4. **现有设计语言**：项目已有的颜色、字体、间距、圆角、阴影、组件风格是什么。 5. **风险边界**：哪些逻辑、数据流、依赖和全局样式不能碰。 如果缺少上下文，不要停下来索要完整设计系统；基于产品类型和现有代码做保守判断，并在最终说明关键假设。 ## 按产品类型选择策略 - **后台 / SaaS / CRM / API 控制台 / 科研平台**：低噪声、高信息密度、清晰导航、紧凑但可读的表格、稳定表单、可扫描指标、明确状态反馈。避免营销式 hero、过多装饰和牺牲数据可读性的视觉效果。 - **Landing Page / 品牌页 / 产品介绍页**：允许更强视觉叙事，但第一屏必须明确产品、对象或 offer；不要套用“居中 hero + 三列卡片 + CTA”的模板。 - **文档 / 开发者工具**：优先可读性、代码块、搜索、导航层级、示例清晰度和主题一致性。 - **移动端 / 小屏工具**：优先可读与可操作。不要把桌面布局硬压缩；表格可横向滚动或改为摘要卡片，复杂工具栏应折叠。 - **游戏 / 互动体验 / 艺术工具**：可以更表现化，但交互反馈、画布尺寸、状态说明和性能仍然优先。 ## 现有项目读取顺序 按需读取，不要机械加载全仓库： 1. 用户点名的页面、组件、样式文件和相邻实现。 2. `package.json`、框架配置、路由入口、layout/shell。 3. `tailwind.config.*`、全局 CSS、CSS variables、theme tokens。 4. `components/ui/*`、design-system、自研组件库或第三方 UI 库封装。 5. 已有相似页面：dashboard、settings、billing、docs、table、form、empty state。 6. 若存在 `AGENTS.md`、`DESIGN.md`、`UI_CHECKLIST.md` 等项目约束，读取并遵守；不存在时不要默认创建。 ## 视觉参考处理 当用户提供截图、Figma、竞品链接或“像某某产品”的描述时： - 先提炼可迁移的原则：布局结构、字体层级、间距节奏、色彩关系、边框/阴影、组件密度、动效克制度。 - 不照抄具体文案、图形、品牌资产或独特页面结构，除非用户拥有素材并明确要求。 - 将参考风格映射到当前项目的组件和 tokens；如果项目风格冲突，优先保持项目一致性。 - 对“像 Linear / Vercel / Stripe / Notion / OpenAI platform”这类描述，提炼气质和布局规律，不做表层仿皮。 ## 先诊断再修改 用户要求“优化 UI”“好看一点”“去 AI 味”时，先做简短诊断，再改代码。重点检查： - 信息层级：主任务、主要 CTA、关键状态是否突出。 - 视觉密度：是否过空、过满、卡片过多或数据不易扫描。 - 对齐与间距：是否存在任意 padding、错位、断裂的网格。 - 表单秩序：输入框、选择器、日期控件、搜索框和按钮是否高度一致、基线对齐、宽度有栅格依据。 - 字体层级：字号、字重、行高是否混乱，是否在紧凑区域使用过大标题。 - 色彩与层次：主色是否滥用，语义色是否稳定，背景是否抢内容。 - 组件一致性：按钮、输入框、表格、弹窗是否沿用现有变体。 - 移动端风险：是否溢出、遮挡、按钮过小、表格不可读。 - 可访问性风险：焦点、键盘导航、颜色对比、可读 label 是否缺失。 诊断后只修最重要的 3-5 个问题，除非用户要求全面重做。 ## 反 AI 味护栏 默认避免： - 随机紫蓝渐变、玻璃拟态、neon glow、大面积模糊光斑。 - 大圆角卡片墙、`shadow-xl` 滥用、所有内容都浮在卡片里。 - 每个页面都做 hero，或所有页面都是 hero + 三列卡片 + CTA。 - 无上下文地拼装 shadcn/ui 展示柜，而不是服务真实任务。 - 滥用 emoji、营销空话、无意义 badge、假数据堆砌。 - 为了“酷”牺牲表格、日志、账单、模型参数、错误状态的可读性。 - 在成熟产品型界面中使用过度表现化字体、动效或装饰背景。 ## 框架与工具选择 优先沿用项目已有技术栈。没有明确栈时再按任务选择： | 场景 | 默认选择 | |------|----------| | React 全栈应用 | Next.js App Router、TypeScript、现有 UI 库 | | React SPA | Vite、TypeScript、现有路由和状态方案 | | Vue 应用 | Vue 3 / Nuxt 3、Pinia、现有组件体系 | | 样式 | Tailwind、CSS Modules、现有 CSS variables/tokens | | 表单 | React Hook Form + Zod / VeeValidate，按项目现状选择 | | Server state | TanStack Query、框架内置 fetch/cache，按项目现状选择 | | 动效 | CSS transition 优先；Motion 类库只在项目已有或收益明确时使用 | | 图标 | 使用项目已有图标库；React 项目常见为 lucide-react | 不要因为单个页面的视觉需求随意引入大型 UI 框架、动画库或图表库。需要新增依赖时说明理由、替代方案和影响。 ## 组件与状态设计 - 组件职责单一：数据获取、格式化、交互状态和纯展示尽量分离。 - 组合优于巨型 props：避免一个组件靠大量 mode/type props 承担多个产品语义。 - Props 接口清晰：必需项、可选项、默认值、事件回调和透传 HTML 属性要明确。 - 状态分类处理：本地 UI 状态、URL 状态、服务器状态、全局状态不要混用。 - 列表、表格、弹窗、表单、空状态、错误状态和 loading 状态要成套考虑。 - 数据密集页面优先保证扫描效率：列宽、行高、sticky header、分页、筛选、排序、空/错状态比装饰更重要。 ## 表单与输入控件整齐度 输入框是产品界面的“精度感”来源。表单区域不要凭感觉摆控件；先确定容器宽度、列数、label 策略和控件高度，再实现具体字段。 - 同一区域内的 `Input`、`Select`、`Combobox`、日期选择、搜索框和普通按钮应使用同一高度阶梯；常见后台表单优先 `32px` 或 `36px`，营销页或低密度页面可放宽到 `40px`，但不要在同一工具条里混用。 - 宽度遵循栅格或固定语义：搜索框、邮箱、URL、长文本可占更宽列；短枚举、状态、数量、日期使用较窄列。不要让控件宽度仅由 placeholder 或当前内容决定。 - label、help text、error text 使用稳定规则：同一表单里统一左侧 label、上方 label 或隐藏 label；错误文案出现时不得推乱整行布局，必要时预留说明区域或让错误只影响本字段高度。 - 行内表单和工具栏要对齐控件基线：输入框、下拉框、按钮、图标按钮、分段控件的高度、内边距、圆角和边框粗细应视觉一致。 - 状态样式成套处理：default、hover、focus、disabled、invalid、readonly 的边框、背景、ring、placeholder 和图标颜色要来自现有 tokens，不为单个字段临时发明新风格。 - 移动端优先改为单列或清晰分组；避免把桌面多列字段硬挤到手机宽度，导致输入区过窄、label 换行混乱或按钮贴边。 ## 响应式与无障碍 - 移动端优先保证信息可读和操作可达，不强行保留桌面结构。 - 检查常见视口：桌面约 `1440x900`，平板约 `1024x768`，手机约 `390x844`。 - 固定格式元素要有稳定尺寸约束，如表格、工具栏、图表、棋盘、计数器、按钮组。 - 文本不得溢出按钮、卡片、表头或导航项；长词、邮箱、URL、模型名需要换行或截断策略。 - 所有交互元素应有 hover/focus/disabled 状态和可访问名称。 - 不用颜色作为唯一状态表达；错误、成功、警告要有文本或图标辅助。 ## 性能与可维护性 - 先解决真实瓶颈，再使用 memo、virtualization、lazy loading 等优化。 - 大列表使用分页、虚拟滚动或服务端筛选；不要一次渲染大量 DOM。 - 避免在渲染路径创建昂贵计算、随机值或不稳定对象导致重复渲染。 - 不新增无必要全局 CSS；必须新增时限制作用域并解释原因。 - 设计 token、CSS 变量、Tailwind theme 优先于散落的 magic numbers。 ## 浏览器与测试闭环 实现后按项目可用能力验证： 1. 运行现有格式化、lint、typecheck、测试或 build 命令。 2. 能启动项目时，打开目标页面做浏览器检查。 3. 可用 Playwright 时，截取桌面、平板、手机视口，检查层级、间距、响应式、溢出、遮挡、交互状态和 AI 味。 4. 发现视觉问题后小步修正；不要因为一个截图问题重写整页。 5. 若无法启动或截图，说明阻塞原因和未验证风险。 视觉回归不必默认追求像素级完全一致；更重要的是让问题可见，并让修正围绕真实截图发生。 ## 交付清单 - [ ] 已理解产品类型、主任务、视觉密度和风险边界。 - [ ] 已读取相关页面、组件、样式和项目 UI 约束。 - [ ] 已复用现有组件系统、tokens、图标和布局模式。 - [ ] 已避免典型 AI 味 UI 和无依据的新视觉变体。 - [ ] 表单与输入控件高度、宽度、label、状态样式和行内对齐已成组检查。 - [ ] 已保持业务逻辑、数据流、认证、API 和无关全局样式不受影响。 - [ ] 已覆盖 loading、empty、error、disabled、hover/focus 等关键状态。 - [ ] 已检查桌面、平板、移动端的可读性和溢出风险。 - [ ] 已运行可用的 lint、typecheck、test 或 build。 - [ ] 已在最终回复说明验证结果、关键改动和未验证风险。 ## 相关参考 - [React Learn](https://react.dev/learn) - [Next.js Documentation](https://nextjs.org/docs) - [Vue 3 Guide](https://vuejs.org/guide/) - [Playwright Visual Comparisons](https://playwright.dev/docs/test-snapshots) ## 约束 ### 公共硬约束 本块由 `docs/templates/skill-common-constraints.md` 统一维护；每个 `SKILL.md` 的 `## 约束` 必须逐字同步本块，不得在副本中改写公共规则。 - 任务需要落盘时，使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录；共享材料放入 `shared/`，Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。 - 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。 - 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。 - 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。 - 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。 - Skill 版本唯一记录在自身 `config.yaml:skill_info.version`；公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。 - `bensz-collect-bugs` 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 `~/.bensz-skills/bugs/`，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。