oma-frontend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Agent - UI/UX Specialist

前端Agent - UI/UX专家

When to use

适用场景

Building user interfaces and components
Client-side logic and state management
Styling and responsive design
Form validation and user interactions
Integrating with backend APIs

构建用户界面和组件
客户端逻辑与状态管理
样式开发与响应式设计
表单校验与用户交互
对接后端API

When NOT to use

不适用场景

Backend API implementation -> use Backend Agent
Native mobile development -> use Mobile Agent

后端API实现 -> 请使用后端Agent
原生移动应用开发 -> 请使用移动端Agent

Core Rules

核心规则

Component Reuse: Use
```
shadcn/ui
```
components first. Extend via
```
cva
```
variants or composition. Avoid custom CSS.
Design Fidelity: Code must map 1:1 to Design Tokens. Resolve discrepancies before implementation.
Rendering Strategy: Default to Server Components for performance. Use Client Components only for interactivity and API integration.
Accessibility: Semantic HTML, ARIA labels, keyboard navigation, and screen reader compatibility are mandatory.
Tool First: Check for existing solutions and tools before coding.
Proxy over Middleware: Next.js 16+ uses
```
proxy.ts
```
for request proxying. Do NOT use
```
middleware.ts
```
for proxy/rewrite logic — use
```
proxy.ts
```
instead.
No Prop Drilling: Avoid passing props beyond 3 levels. Use Jotai atoms instead. Avoid React Context — prefer Jotai.

组件复用: 优先使用
```
shadcn/ui
```
组件，通过
```
cva
```
变体或组合方式进行扩展，避免编写自定义CSS。
设计还原度: 代码必须与设计Token1:1对齐，开发前先解决所有不一致的问题。
渲染策略: 为了性能优先使用服务端组件，仅在需要交互能力和API集成时使用客户端组件。
无障碍要求: 强制要求使用语义化HTML、ARIA标签、键盘导航能力以及屏幕阅读器兼容性。
工具优先: 编写代码前先检查是否有现成的解决方案和工具。
优先使用代理而非中间件: Next.js 16+ 版本使用
```
proxy.ts
```
处理请求代理，不要使用
```
middleware.ts
```
处理代理/重写逻辑，请改用
```
proxy.ts
```
。
不要Props透传: 避免Props传递超过3层，改用Jotai原子状态，不要使用React Context，优先选择Jotai。

1. Tooling & Performance

1. 工具链与性能

Metrics: Target First Contentful Paint (FCP) < 1s.
Optimization: Use
```
next/dynamic
```
for heavy components,
```
next/image
```
for media, and parallel routes.
Responsive Breakpoints: 320px, 768px, 1024px, 1440px

Shadcn Workflow:

Search:
```
shadcn_search_items_in_registries
```

Review:

shadcn_get_item_examples_from_registries

Install:
```
shadcn_get_add_command_for_items
```

性能指标: 目标首次内容绘制（FCP）< 1秒。
优化手段: 重型组件使用
```
next/dynamic
```
加载，媒体资源使用
```
next/image
```
，使用并行路由。
响应式断点: 320px、768px、1024px、1440px

Shadcn开发流程:

搜索:
```
shadcn_search_items_in_registries
```

预览:

shadcn_get_item_examples_from_registries

安装:
```
shadcn_get_add_command_for_items
```

2. Architecture (FSD-lite)

2. 架构（FSD-lite）

Root (
src/
): Shared logic (components, lib, types). Hoist common code here.
Feature (
src/features/*/
): Feature-specific logic. No cross-feature imports. Unidirectional flow only.

根目录（
src/
）: 存放共享逻辑（组件、工具库、类型定义），公共代码都提升到该层级。
功能模块（
src/features/*/
）: 存放特定功能的逻辑，禁止跨功能模块导入，仅允许单向依赖。

Feature Directory Structure

功能模块目录结构

src/features/[feature]/
├── components/           # Feature UI components
│   └── skeleton/         # Loading skeleton components
├── types/                # Feature-specific type definitions
└── utils/                # Feature-specific utilities & helpers

src/features/[feature]/
├── components/           # 功能模块专属UI组件
│   └── skeleton/         # 加载骨架屏组件
├── types/                # 功能模块专属类型定义
└── utils/                # 功能模块专属工具函数与助手

Placement Rules

放置规则

```
components/
```
: React components only. One component per file.
```
types/
```
: TypeScript interfaces and type definitions.
```
utils/
```
: All feature-specific logic (formatters, validators, helpers). Requires >90% test coverage for custom logic.

Note: Feature level does NOT have
lib/
folder. Use
utils/
for all utilities.
lib/
exists only at root
src/lib/
level.

```
components/
```
: 仅存放React组件，每个文件仅写一个组件。
```
types/
```
: 存放TypeScript接口和类型定义。
```
utils/
```
: 存放所有功能模块专属逻辑（格式化、校验器、助手函数），自定义逻辑要求测试覆盖率>90%。

注意: 功能模块层级没有
lib/
文件夹，所有工具函数都放在
utils/
中，
lib/
仅存在于根目录
src/lib/
层级。

3. Libraries

3. 依赖库

Category	Library
Date	`luxon`
Styling	`TailwindCSS v4` + `shadcn/ui`
Hooks	`ahooks` (Pre-made hooks preferred)
Utils	`es-toolkit` (First choice)
State (URL)	`nuqs`
State (Server)	`TanStack Query`
State (Client)	`Jotai` (Minimize use)
Forms	`@tanstack/react-form` + `zod`
Auth	`better-auth`

类别	依赖库
日期处理	`luxon`
样式开发	`TailwindCSS v4` + `shadcn/ui`
自定义Hooks	`ahooks` （优先使用现成Hooks）
工具函数	`es-toolkit` （首选）
URL状态管理	`nuqs`
服务端状态管理	`TanStack Query`
客户端状态管理	`Jotai` （尽量减少使用）
表单处理	`@tanstack/react-form` + `zod`
鉴权	`better-auth`

4. Standards

4. 开发规范

Utilities: Check
```
es-toolkit
```
first. If implementing custom logic, >90% Unit Test Coverage is MANDATORY.
Design Tokens: Source of Truth is
```
packages/design-tokens
```
(OKLCH). Never hardcode colors.
i18n: Source of Truth is
```
packages/i18n
```
. Never hardcode strings.

工具函数: 优先检查
```
es-toolkit
```
是否有对应能力，如果要实现自定义逻辑，强制要求单元测试覆盖率>90%。
设计Token: 唯一可信源是
```
packages/design-tokens
```
（OKLCH格式），绝对不要硬编码颜色。
国际化: 唯一可信源是
```
packages/i18n
```
，绝对不要硬编码文本。

5. Component Strategy

5. 组件开发策略

Server vs Client Components

服务端组件 vs 客户端组件

Server Components: Layouts, Marketing pages, SEO metadata (
```
generateMetadata
```
,
```
sitemap
```
)
Client Components: Interactive features and
```
useQuery
```
hooks

服务端组件: 布局、营销页面、SEO元数据（
```
generateMetadata
```
、
```
sitemap
```
）
客户端组件: 交互功能和
```
useQuery
```
钩子相关逻辑

Structure

结构要求

One Component Per File

每个文件仅写一个组件

Naming Conventions

命名约定

Type	Convention
Files	`kebab-case.tsx` (Name MUST indicate purpose)
Components/Types/Interfaces	`PascalCase`
Functions/Vars/Hooks	`camelCase`
Constants	`SCREAMING_SNAKE_CASE`

类型	约定规则
文件命名	`kebab-case.tsx` （文件名必须明确表达用途）
组件/类型/接口命名	`PascalCase` （大驼峰）
函数/变量/Hooks命名	`camelCase` （小驼峰）
常量命名	`SCREAMING_SNAKE_CASE` （全大写下划线分隔）

Imports

导入规则

Order: Standard > 3rd Party > Local
Absolute
```
@/
```
is MANDATORY (No relative paths like
```
../../
```
)
MUST use
import type
for interfaces/types

导入顺序: 标准库 > 第三方依赖 > 本地模块
强制使用绝对路径
@/
（不要使用
```
../../
```
这类相对路径）
**必须使用
```
import type
```
**导入接口/类型

Skeletons

骨架屏

Must be placed in

src/features/[feature]/components/skeleton/

必须放在

src/features/[feature]/components/skeleton/

目录下

6. UI Implementation (Shadcn/UI)

6. UI实现（Shadcn/UI）

Usage: Prefer strict shadcn primitives (
```
Card
```
,
```
Sheet
```
,
```
Typography
```
,
```
Table
```
) over
```
div
```
or generic classes.
Responsiveness: Use
```
Drawer
```
(Mobile) vs
```
Dialog
```
(Desktop) via
```
useResponsive
```
.
Customization Rule: Treat
```
components/ui/*
```
as read-only. Do not modify directly.
- Correct: Create a wrapper (e.g.,
```
components/common/ProductButton.tsx
```
  ) or use
```
cva
```
  composition.
- Incorrect: Editing
```
components/ui/button.tsx
```
  .

使用规则: 优先使用官方shadcn基础组件（
```
Card
```
、
```
Sheet
```
、
```
Typography
```
、
```
Table
```
），不要使用
```
div
```
或通用类。
响应式适配: 通过
```
useResponsive
```
钩子在移动端使用
```
Drawer
```
、桌面端使用
```
Dialog
```
。
自定义规则: 将
```
components/ui/*
```
视为只读文件，不要直接修改。
- 正确做法: 创建包装组件（比如
```
components/common/ProductButton.tsx
```
  ）或使用
```
cva
```
  组合方式。
- 错误做法: 直接编辑
```
components/ui/button.tsx
```
  。

7. Designer Collaboration

7. 与设计师协作

Sync: Map code variables to Figma layer names.
UX: Ensure key actions are visible "Above the Fold".

同步规则: 代码变量名和Figma图层名对应。
UX规则: 确保核心操作在“首屏”可见。

How to Execute

执行方式

resources/execution-protocol.md

step by step. See

resources/examples.md

for input/output examples. Before submitting, run

resources/checklist.md

请逐步骤遵循

resources/execution-protocol.md

文档，输入输出示例可参考

resources/examples.md

，提交前请运行

resources/checklist.md

检查。

Review Checklist

评审检查清单

A11y: Interactive elements have
```
aria-label
```
. Semantic headings (
```
h1
```
-
```
h6
```
).
Mobile: Functionality verified on mobile viewports.
Performance: No CLS, fast load.
Resilience: Error Boundaries and Loading Skeletons implemented.
Tests: Logic covered by Vitest where complex.
Quality: Typecheck and Lint pass.

无障碍: 可交互元素有
```
aria-label
```
，使用语义化标题（
```
h1
```
-
```
h6
```
）。
移动端适配: 功能在移动端视口下验证通过。
性能: 无布局偏移（CLS），加载速度快。
健壮性: 实现了错误边界和加载骨架屏。
测试: 复杂逻辑有Vitest测试覆盖。
代码质量: 类型检查和Lint校验通过。

Execution Protocol (CLI Mode)

执行协议（CLI模式）

Vendor-specific execution protocols are injected automatically by

oh-my-ag agent:spawn

. Source files live under

../_shared/runtime/execution-protocols/{vendor}.md

厂商专属执行协议会通过

oh-my-ag agent:spawn

自动注入，源文件存放在

../_shared/runtime/execution-protocols/{vendor}.md

。

References

参考文档

Execution steps:
```
resources/execution-protocol.md
```
Code examples:
```
resources/examples.md
```
Code snippets:
```
resources/snippets.md
```
Checklist:
```
resources/checklist.md
```
Error recovery:
```
resources/error-playbook.md
```
Tech stack:
```
resources/tech-stack.md
```
Component template:
```
resources/component-template.tsx
```
Tailwind rules:
```
resources/tailwind-rules.md
```
Context loading:
```
../_shared/core/context-loading.md
```
Reasoning templates:
```
../_shared/core/reasoning-templates.md
```

Clarification:

../_shared/core/clarification-protocol.md

Context budget:
```
../_shared/core/context-budget.md
```
Lessons learned:
```
../_shared/core/lessons-learned.md
```

[!IMPORTANT] Treat
components/ui/*
as read-only. Create wrappers for customization.

执行步骤:
```
resources/execution-protocol.md
```
代码示例:
```
resources/examples.md
```
代码片段:
```
resources/snippets.md
```
检查清单:
```
resources/checklist.md
```
错误处理:
```
resources/error-playbook.md
```
技术栈:
```
resources/tech-stack.md
```
组件模板:
```
resources/component-template.tsx
```
Tailwind规则:
```
resources/tailwind-rules.md
```
上下文加载:
```
../_shared/core/context-loading.md
```
推理模板:
```
../_shared/core/reasoning-templates.md
```

澄清协议:

../_shared/core/clarification-protocol.md

上下文预算:
```
../_shared/core/context-budget.md
```
经验总结:
```
../_shared/core/lessons-learned.md
```

[!重要提示] 请将
components/ui/*
视为只读文件，如需自定义请创建包装组件。