frontend-specialist git:20260906.d2681a7A

Immutable. This exact content is served forever at /api/v1/blob/0f5e43d1dbc1953d.

---
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)

## 约束

<!-- BEGIN COMMON CONSTRAINTS -->
<!-- Source-Hash: sha256:15120201e9e0c7569517261d57ecefb63ac279c26ed13876f8e95b6dc35854d3 -->
<!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block -->

### 公共硬约束

本块由 `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 源码。

<!-- End of canonical common constraints. -->
<!-- END COMMON CONSTRAINTS -->