frontend-agent

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.

组件复用：优先使用
```
shadcn/ui
```
组件。通过
```
cva
```
变体或组合方式扩展组件。避免自定义CSS。
设计保真度：代码必须与设计标记（Design Tokens）1:1匹配。在实现前解决所有不一致问题。
渲染策略：默认使用Server Components以提升性能。仅在需要交互性或API集成时使用Client Components。
可访问性：必须使用语义化HTML、ARIA标签、键盘导航，并确保屏幕阅读器兼容性。
工具优先：编码前先检查是否有现成的解决方案和工具。

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

指标：目标首次内容绘制（First Contentful Paint, FCP）< 1s。
优化：对重型组件使用
```
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/
): 共享逻辑（组件、lib、类型定义）。将通用代码提升到此处。
功能模块(
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%的测试覆盖率。

Note: 功能模块级别没有
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)	`jotai-location`
State (Server)	`TanStack Query`
State (Client)	`Jotai` (Minimize use)
Forms	`@tanstack/react-form` + `zod`

分类	库名称
日期处理	`luxon`
样式	`TailwindCSS v4` + `shadcn/ui`
Hooks	`ahooks` （优先使用预制Hooks）
工具函数	`es-toolkit` （首选）
URL状态管理	`jotai-location`
服务端状态管理	`TanStack Query`
客户端状态管理	`Jotai` （尽量少用）
表单	`@tanstack/react-form` + `zod`

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%的单元测试覆盖率。
设计标记（Design Tokens）：唯一可信来源是
```
packages/design-tokens
```
（基于OKLCH颜色模型）。禁止硬编码颜色值。
国际化（i18n）：唯一可信来源是
```
packages/i18n
```
。禁止硬编码字符串。

5. Component Strategy

5. 组件策略

Server vs Client Components

Server组件 vs Client组件

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

Server Components: 布局、营销页面、SEO元数据（
```
generateMetadata
```
,
```
sitemap
```
）
Client Components: 交互式功能与
```
useQuery
```
Hooks

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要求：确保关键操作位于“首屏可见区域”（Above the Fold）。

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

进行检查。

Serena Memory (CLI Mode)

Serena 记忆（CLI模式）

See

../_shared/memory-protocol.md

请查看

../_shared/memory-protocol.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.

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

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/context-loading.md
```
Reasoning templates:
```
../_shared/reasoning-templates.md
```
Clarification:
```
../_shared/clarification-protocol.md
```
Context budget:
```
../_shared/context-budget.md
```
Lessons learned:
```
../_shared/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/context-loading.md
```
推理模板:
```
../_shared/reasoning-templates.md
```
澄清流程:
```
../_shared/clarification-protocol.md
```
上下文预算:
```
../_shared/context-budget.md
```
经验总结:
```
../_shared/lessons-learned.md
```

[!IMPORTANT] 将
components/ui/*
视为只读文件。请通过创建包装组件进行自定义。