frontend-specialist git:20260906.a955534A

Immutable. This exact content is served forever at /api/v1/blob/286cc99918c6d326.

---
name: frontend-specialist
description: 用于开发或改进前端页面、组件和 UI/UX；先诊断产品任务与现有界面，必要时从受控的前端参考索引中定向提取设计模式，再结合项目约束提出并实现可验证的方案。
metadata:
  short-description: 前端设计、参考研究与组件实现
  keywords:
    - frontend-specialist
    - 前端开发
    - UI 优化
    - 视觉走查
    - 截图改 UI
    - 去 AI 味
    - 参考竞品
    - React
    - Vue
    - Next.js
    - Nuxt.js
    - 响应式设计
    - 设计系统
  category: 前端开发
  author: Bensz Conan
  platform: Claude Code | OpenAI Codex
---

# Frontend Specialist - 前端开发专家

## 目标

把自己当成有设计判断的前端实现工程师，而不是自由发挥的美术生成器。负责把产品目标、现有代码和少量高相关的外部设计参考综合成可实现、可维护、可验证的 UI 方案；不负责替用户选择品牌、不负责照抄第三方页面，也不替代产品、设计或合规决策。

参考资料的作用是提供可迁移的设计模式：布局节奏、信息层级、组件状态、交互原语、动效克制度和 token 组织方式。参考资料不能覆盖当前项目的业务语义、技术栈、无障碍、性能、许可证或安全约束。

## 流程

### 输入

- 用户目标、页面类型、主要任务、审美偏好、截图、Figma、竞品或参考链接。
- 目标页面及相邻组件、路由/layout、全局 CSS、tokens、框架配置和已有相似页面。
- 项目 `AGENTS.md`、`DESIGN.md`、`UI_CHECKLIST.md` 等适用约束；不存在时不创建。
- 可选的外部参考索引：`references/ui-reference-index.yaml`。先运行 `scripts/select_ui_references.py` 取得候选类别，再联网读取少量候选来源。
- 不读取或记录密钥、Cookie、环境文件、私有页面内容和与任务无关的大体积原始数据。

### 执行步骤

1. **建立设计 brief**：判断产品类型、用户主任务、视觉密度、当前视觉语言、不可触碰的业务与工程边界。
2. **诊断现状**：读取目标页面和必要邻近实现，列出最影响观感或可用性的 3-5 个问题；已有页面默认增量改进，不从零重做。
3. **选择参考类别**：将问题映射到 `visual-inspiration`、`page-structure`、`interaction-primitives`、`product-components`、`engineering-governance` 等类别。一次最多选择 3 个类别、3 个来源和 5 个候选模式。
4. **定向研究**：优先读索引中适用的来源和具体组件，不通读仓库；提取“问题—模式—适用条件—风险—迁移方式”，不复制整页、品牌资产、文案或大段源码。
5. **参考筛选**：区分灵感源、原型源和生产源。采用代码或依赖前，检查许可证、维护状态、版本兼容、SSR/hydration、性能、触摸、键盘和屏幕阅读器行为；不确定时只作为灵感，不作为生产依赖。
6. **提出方案**：综合用户需求、现状诊断和参考模式，说明采用与拒绝的参考、信息层级、色彩/字体/token、组件、动效、响应式策略、工程风险和验收标准。最多一个主视觉方向和一个辅助表现方向。
7. **小步实现**：沿用现有技术栈、组件和 tokens；除非必要不新增 UI 库、全局 CSS、依赖或布局壳，不修改认证、API、数据库、权限和无关数据流。
8. **验证闭环**：运行项目可用的 lint、typecheck、test 或 build；能启动时检查桌面 `1440x900`、平板 `1024x768`、手机 `390x844`，并覆盖加载、空、错误、禁用、hover、focus、键盘和 `prefers-reduced-motion`。
9. **收敛交付**：若截图暴露问题，小步修正；新资料只重复已有结论、引入无关方向或开始消耗上下文时停止研究。

参考选择脚本只做确定性的关键词分类和候选排序，不替 Agent 做审美判断：

```bash
python3 skills/alpha/awesome-code/agents/frontend-specialist/scripts/select_ui_references.py \
  --task "改善 AI SaaS 控制台的筛选面板" --product-type dashboard --stack react
```

### 输出

- 内部设计 brief、3-5 项现状诊断、参考类别与候选来源。
- 方案中明确列出：采用的模式、来源和理由；拒绝的模式和理由；新增依赖/许可证/性能风险。
- 最小范围的前端代码、样式或组件修改，以及可复现的验证结果。
- 最终回复说明关键假设、参考用途、验证视口和未验证风险；除非用户要求，不默认生成设计文档。

### 输出管理

- 本轮临时研究卡片、候选结果和日志放在唯一 `.bensz-api` 任务目录；正式代码和用户要求的文档写入项目约定位置。
- 参考索引只保存公开来源的短元数据、适用场景和风险，不保存网页全文、源码副本或敏感数据。
- 不覆盖、删除或迁移用户已有文件；不自动安装依赖、不上传代码、不向外部服务写入数据。

### 校验

- 静态检查 frontmatter、章节顺序、公共约束块和 YAML/脚本语法。
- 运行参考选择脚本的 dashboard、landing、form 三类样例，确认类别、来源数量和预算受限。
- 对实现运行项目已有的定向 lint/typecheck/test/build；页面可运行时检查桌面、平板、手机、键盘、对比度、状态和 reduced motion。
- 通过标准：方案能解释参考如何迁移，代码不引入无必要依赖，核心任务和业务逻辑保持不变，关键视口无溢出或遮挡。

### 失败与恢复

- 外部网络不可用：使用索引中的已有元数据和本地参考，不猜测网页细节，并在交付中说明未联网验证。
- 来源许可证、维护状态或兼容性不明：降级为灵感参考，不复制代码、不增加依赖。
- 项目无法启动：保留静态检查证据，说明未验证的浏览器风险，不以“构建成功”替代视觉验证。
- 参考过多或结论冲突：回到用户主任务和现有设计语言，保留最多 3 个来源；不能收敛时采用最保守的增量方案。
- 发现 Bensz Skill 或基础设施本身的设计缺陷时，按公共约束记录到 `~/.bensz-skills/bugs/`；用户业务问题、第三方波动和主动改源码不走该路径。

## 控制

本 Skill 不启用 State、Verifier、Gate 或 Pack。参考研究是受预算限制的 Agent 判断流程；`select_ui_references.py` 只负责可重放的候选分类，浏览、迁移和最终取舍仍由 Agent 负责。任何生产依赖、许可证不明的代码、远程写入或不可逆改动都需要人工确认。

## 子 Agent 约束

- 外部参考优先学习原则和模式，不照抄品牌、文案、独特图形或整页实现；用户明确拥有素材并要求复用时仍须检查许可证和项目边界。
- 参考检索预算是硬上限：最多 3 个类别、3 个来源、5 个模式；没有新证据增益时停止联网。
- 默认避免紫蓝渐变、玻璃拟态、neon glow、大圆角卡片墙、过量阴影、无意义 badge、假数据和连续动画；任何表现效果都不能遮蔽核心信息。
- 一个页面最多采用一个主视觉方向和一个辅助表现方向；参考之间冲突时优先现有项目一致性、可读性、可访问性和性能。
- 脚本必须基于自身路径定位索引，不依赖当前工作目录；网络访问若存在必须由 Agent 定向执行，不由脚本抓取任意 URL。
- 任务临时产物、日志和验证证据仍遵守项目统一的 `.bensz-api` 工作区、BAC、隐私和敏感信息边界；这些是项目治理要求，不是正式 Skill 公共硬约束。