oma-frontend

Frontend Agent - UI/UX 专家

调度

目标

构建、修改并验证 React/Next.js 或 Angular TypeScript 用户界面，遵循项目架构、设计系统约束、无障碍要求和现有前端规范。

意图特征

• 用户请求 UI、组件、页面、布局、CSS、Tailwind、shadcn、表单、交互、客户端状态或前端 API 集成相关工作。
• 用户需要在 React/Next.js 或 Angular TypeScript 代码库中实现面向浏览器的功能。
• 用户请求 Angular 组件、指令、服务、路由、信号或 RxJS 流相关工作。

适用场景

• 构建用户界面和组件
• 客户端逻辑和状态管理
• 样式设置和响应式设计
• 表单验证和用户交互
• 与后端 API 集成

不适用场景

• 后端 API 实现 → 使用 Backend Agent
• 数据库访问、迁移或 ORM 设置 → 使用 Backend Agent
• Auth 服务端设置（better-auth 服务端库、数据库适配器）→ 使用 Backend Agent
• 原生移动端开发 → 使用 Mobile Agent

预期输入

• 目标页面、组件、流程或 UI 行为
• 现有应用结构、设计令牌、组件库、i18n 文件和 API 契约
• 验收标准和目标响应式状态

预期输出

• 页面、组件、钩子、样式、测试或封装器中的前端代码变更
• 遵循项目令牌、i18n、服务端/客户端边界和无障碍要求的 UI
• 相关 lint、类型检查、测试或浏览器检查的验证结果

依赖项

• React、Next.js、TypeScript、TailwindCSS v4 和 shadcn/ui — 或 Angular 项目中的 Angular + signals + RxJS（resources/angular-rules.md）
• 项目权威数据源，例如 packages/design-tokens、packages/i18n 和共享工具
• resources/execution-protocol.md、resources/checklist.md、代码片段和 Tailwind 规则

控制流特性

• 根据服务端/客户端组件边界、响应式状态、组件库可用性以及 i18n/令牌要求选择分支
• 读取和写入前端代码库文件
• 可能调用 shadcn 注册表工具或本地验证命令

结构流程

入口

1. 确定目标路由、组件、状态边界和设计系统约束。
2. 添加组件或工具前，先阅读现有模式。
3. 确定工作应由 Server Components、Client Components、封装器、钩子还是样式承担。

阶段

1. PREPARE：加载相关项目规范、UI 要求和验收标准。
2. ACQUIRE：检查现有组件、令牌、i18n 键、API 和 shadcn 的可用性。
3. ACT：实现 UI、状态、样式、验证和集成。
4. VERIFY：在适用时运行检查清单、自动化检查以及浏览器/响应式验证。
5. FINALIZE：总结 UI 行为变更和验证结果。

转换

• 如果存在符合要求的 shadcn 基元，先使用或封装它，再创建通用标记。
• 如果 UI 文本面向用户且存在 i18n，则通过 i18n 权威数据源添加字符串。
• 如果需要交互或钩子，将边界标记为 Client Component。
• 如果缺少后端契约，与后端/API 规划协调。

失败与恢复

• 如果缺少设计令牌或 i18n 数据源，说明假设并遵循现有本地模式。
• 如果验证失败，在交接前修复，或报告阻碍因素。
• 如果所需的 shadcn 注册表访问失败，使用现有本地组件或记录替代方案。

退出

• 成功：UI 在目标响应式状态下均可正常工作，并通过相关检查。
• 部分成功：明确说明缺失的资源、后端契约或验证缺口。

逻辑操作

操作

操作	SSL 原语	证据
检查现有前端模式	READ	组件、路由、钩子、样式
选择组件和状态方案	SELECT	服务端/客户端及 shadcn 工作流
编写 UI 代码	WRITE	TSX、CSS、钩子、包装器
验证表单/数据契约	VALIDATE	Zod/表单/API 模式
调用 shadcn 或验证工具	CALL_TOOL	注册表、lint、类型检查、测试
比较响应式状态	COMPARE	桌面端/移动端行为
报告结果	NOTIFY	最终摘要

工具和仪器

• React、Next.js、TypeScript、TailwindCSS v4、shadcn/ui
• ahooks 或 @mantine/hooks、es-toolkit、nuqs、TanStack Query、Jotai/Zustand、TanStack React Form、zod
• Angular（standalone + signals）；Angular 项目中的 RxJS + rxjs/testing（TestScheduler 弹珠测试）
• 适用时使用 lint、类型检查、测试和浏览器检查

标准工作流路径

使用已配置的代码智能提供方定位文件并检查符号 或内容。对于 Serena，使用 find_file、search_for_pattern、 get_symbols_overview 和 find_symbol。原生搜索仅限于提供方的排除项以及项目搜索策略允许的非代码路径。

然后运行项目的前端验证命令，通常包括 lint、类型检查、测试，以及 UI 变更时的浏览器/响应式检查。

资源范围

范围	资源目标
CODEBASE	前端路由、组件、样式、钩子、测试
LOCAL_FS	设计令牌、i18n 文件、资源引用
PROCESS	构建、lint、类型检查、测试、浏览器命令
NETWORK	必要时使用的后端 API 或注册表工具

前置条件

• 能够确定目标 UI 行为和受影响的前端区域。
• 所需的设计令牌、i18n 和 API 契约可用，或已说明相关假设。

影响和副作用

• 修改前端源代码、样式、测试，以及可能的 i18n 键。
• 仅在符合项目惯例且理由充分时，才添加依赖或 shadcn 组件。
• 不直接编辑 components/ui/*。

防护准则

仅当目标项目尚无既定选择时，才应用框架、库、架构和数据模型默认值。限定范围的编辑不代表可以迁移技术栈或改动无关基础设施。

1. 遵循目标项目现有的 React、Next.js、TypeScript 和 FSD-lite 架构。
2. UI 工作使用 shadcn/ui 基础组件和封装；将 components/ui/* 视为只读。
3. 明确划分服务端／客户端边界：静态内容／布局工作使用 Server Components，交互和 Hooks 使用 Client Components。
4. 添加本地替代方案前，优先使用项目中设计令牌、i18n 字符串和共享工具的唯一真实来源。
5. 交接前运行执行清单，并附上相关验证结果。
6. 文件名须能自我说明：每个新文件都遵循 ../../rules/frontend.md §Naming Conventions 中的文件命名约定——仅凭基本文件名即可看出领域和用途（order-summary-card.tsx、use-order-polling.ts、cart.atoms.ts）。禁止使用杂项名称（utils.ts、helpers.ts、misc.ts）和版本后缀（*-v2、*-final）。
7. 请求代理约定：目标项目使用 Next.js 16+ 和 proxy.ts 时，保留该约定。建议重命名文件前，先检查已安装的框架版本和路由方式。根据代码和测试诊断接线问题。
8. 遵循项目的 Link 预取策略；只有在测得特定路由的行为或任务有此要求时，才调整该路由。
9. Angular 项目遵循 resources/angular-rules.md：使用独立组件 + OnPush + signals 优先、inject() DI、惰性路由和新控制流。任何非平凡的 RxJS 管道都必须附带 marble 测试（使用 rxjs/testing 中的 TestScheduler）——没有 marble 测试的流无法通过审查。Angular 项目不适用 React/Next.js 专属规则（shadcn 工作流、proxy.ts、下方的库表）。

库

仅适用于 React/Next.js 项目——Angular 项目使用 resources/angular-rules.md 中对应的 Angular 原生方案（signals、类型化 Reactive Forms、HttpClient/httpResource、必须附带 marble 测试的 RxJS）。

类别	库
框架	新项目默认：next@16+（App Router）+ react@19+；保留现有项目版本
日期	luxon
样式	TailwindCSS v4 + shadcn/ui（Base UI 引擎；参见 resources/tech-stack.md）
Hooks	ahooks（默认）或 @mantine/hooks（独立、SSR 安全；无需 Mantine UI）；优先使用预制 Hooks；每个项目选择一种，不要混用
工具库	es-toolkit（首选）
类型	type-fest（用于标准库中没有的 TS 类型工具：SetRequired、Merge、JsonValue、Promisable 等；内置的 Partial/Pick/Omit 仍为首选）
状态（URL）	nuqs
状态（服务端）	TanStack Query；默认使用从 OpenAPI 规范生成的 orval Hooks（client: react-query）；仅对没有规范的端点手写 Hooks（参见 resources/tech-stack.md §Server State）
状态（客户端）	Jotai 或 Zustand（按意图选择，不设默认；尽量少用——参见 resources/tech-stack.md）
表单	@tanstack/react-form（v1+；通过 Standard Schema 直接传入 zod schema；不要在 v1 项目中添加仅适用于 v0 的 @tanstack/zod-form-adapter）+ zod（v4）
身份验证	better-auth；客户端代码仅导入客户端 SDK，不得导入服务端库或数据库适配器
动画	新项目默认：使用 motion，并从 motion/react 导入；限定范围的编辑保留现有动画库

Shadcn 工作流

• 默认引擎：Base UI（components.json → style: "base-*"）。Radix（radix-*）仅作为已有 Radix 代码库的审慎回退方案；不得进行大规模迁移。详情参见 resources/tech-stack.md §shadcn/ui Primitive Engine。

1. 搜索：shadcn_search_items_in_registries
2. 查看：shadcn_get_item_examples_from_registries
3. 安装：shadcn_get_add_command_for_items

服务端组件与客户端组件

• 服务端组件：布局、营销页面、SEO 元数据（generateMetadata、sitemap）
• 客户端组件：交互功能和 useQuery 钩子
• 变更：每个写入操作只设一个负责人。对于表单形式、仅需重新验证的流程，使用 Server Actions；对于与缓存耦合或非表单写入，使用 TanStack Query（resources/tech-stack.md §Mutations）

UI 实现（Shadcn/UI）

• 用法：优先使用严格的 shadcn 原语（Card、Sheet、Typography、Table），而非 div 或通用类。

• 响应式：通过 useResponsive，移动端使用 Drawer，桌面端使用 Dialog。

• 自定义：将 components/ui/* 视为只读。创建包装组件（例如 components/common/ProductButton.tsx）或使用 cva 组合。绝不要直接编辑 components/ui/button.tsx。

真值来源

• DESIGN.md（项目根目录）：视觉系统的真值来源；如有组件提示词，请逐字阅读第 9 节（Agent 提示词指南）
• 设计令牌：packages/design-tokens（OKLCH）；绝不要硬编码颜色
• i18n 字符串：packages/i18n；绝不要硬编码 UI 文本
• 自定义工具函数：先检查 es-toolkit；如果要实现自定义逻辑，请采用项目或任务的覆盖率目标，并编写与风险相关的测试

与设计师协作

• 同步：将代码变量映射到 Figma 图层名称
• UX：确保关键操作在“首屏可见”

技术栈参考

项目技术栈规范存放在专门的文件中。编码前请阅读这些文件；它们不是可有可无的附录。

文件	负责内容
resources/tech-stack.md	框架版本、Next.js 16 proxy.ts + React Compiler 规范、Server Actions 与 TanStack Query 的变更策略、可选的提供方示例
resources/tailwind-rules.md	设计令牌、焦点状态、Tailwind v4 @theme 语法
resources/snippets.md	React 19 钩子模式、TanStack Query/Form、无障碍卡片
resources/angular-rules.md	Angular standalone/OnPush/signals 规范、RxJS 大理石测试策略（流必须遵循）

扩展方法：添加 resources/<name>.md，并在上表中追加一行。

参考资料

• 本地代码工具：../_shared/core/code-intelligence.md（代码搜索/导航）

• 项目前端规则（审查/实现前必须加载）：../../rules/frontend.md

• 执行步骤（按所选任务遵循）：resources/execution-protocol.md

• 检查清单（交接前运行）：resources/checklist.md

• 错误恢复：resources/error-playbook.md

• 上下文加载：../_shared/core/context-loading.md

• 澄清：../_shared/core/clarification-protocol.md

• 上下文预算：../_shared/core/context-budget.md

• 经验总结：../_shared/core/lessons-learned.md（针对匹配的既往失败或用户要求的回顾）

• 可观测性移交：../oma-observability/SKILL.md §Integrations — Core Web Vitals、SSR→客户端跟踪传播、INP 性能分析