---

name:react-component-creator

description:CreateReactcomponentsfollowingteamconventionswithTypeScript,hookspatterns,andproperfilestructure.Usewhentheuseraskstocreate,generate,orscaffoldanewReactcomponent.

---

# ✅ 好的写法 —— 既有能力描述，又有触发场景

description:CreateReactcomponentswithTypeScript,hooks,andproperfilestructure.Usewhentheuseraskstocreate,generate,orscaffoldanewReactcomponent.

# ❌ 差的写法 —— 太模糊，Agent 不知道什么时候该触发

description:HelpswithReactstuff.

# ✅ 好

description:GeneratesunittestsforReactcomponentsusingVitest.

# ❌ 不好

description:IcanhelpyouwritetestsforReact.

---
name: react-component-creator
description: Create React components with TypeScript and hooks. Use when the user asks to create, generate, or scaffold a React component.
---

# React Component Creator
## Instructions
1. Create component file at `src/components/[ComponentName]/index.tsx`
2. Use function component with TypeScript interface for props
3. Export as named export (not default export)

## Component Template

\```tsx

interface [Name]Props {
  // props here
}

export function [Name]({ ...props }: [Name]Props) {
  return <section>...</section>
}

\```

## Conventions
- File naming: PascalCase for components, camelCase for hooks
- One component per file
- Co-locate styles: `[ComponentName].module.css`
- Co-locate tests: `[ComponentName].test.tsx`

# ❌ 浪费：Agent 自己就知道怎么用 fetch
When making HTTP requests, you can use the fetch API. The fetch 
function takes a URL and an options object containing method, 
headers, and body...

# ✅ 有价值：这是你们团队的私有约定
All API calls MUST use the project's request wrapper:

\```ts
import { request } from '@/api/request'

// GET
const users = await request.get<User[]>('/api/users')

// POST
await request.post('/api/users', { name: 'Winty' })
\```

Do NOT use raw fetch or axios directly.

# React Component Skill
## Core Rules
1. Named exports only
2. CSS Modules for styling
3. Co-locate tests

## Need More Detail?
- Naming conventions → see [naming.md](references/naming.md)
- State management patterns → see [state.md](references/state.md)
- Accessibility checklist → see [a11y.md](references/a11y.md)

## Custom Hook 规范

\```ts
// ✅ 标准写法 — 直接照这个格式来

export function useUserList(params: UseUserListParams) {
  const [users, setUsers] = useState<User[]>([])
  const [loading, setLoading] = useState(false)
  const fetch = useCallback(async () => {
    setLoading(true)

    try {
      const data = await request.get<User[]>('/api/users', { params })

      setUsers(data)
    } finally {
      setLoading(false)
    }
  }, [params])

  useEffect(() => { fetch() }, [fetch])

  return { users, loading, refresh: fetch }

}

\```

Naming: `use` + resource name, e.g. `useOrderDetail`, `useCartItems`

Return: always return an object (not array), include a `refresh` method

## 操作边界

✅ **放手做：**
- 在 `src/components/` 下新建文件
- 在 `src/hooks/` 下新建 custom hook
- 修改当前任务相关的组件和样式

⚠️ **先问我：**
- 要改 `src/shared/` 或 `src/utils/` 里的公共代码
- 要新加一个 npm 依赖
- 要改路由配置或全局状态

🚫 **绝对不要：**
- 动任何 config 文件（webpack/vite/tsconfig/eslint）
- 删除或修改已有的测试用例
- 在代码里硬编码环境变量或密钥

## 新页面开发流程

按照以下顺序执行，不要跳步：
1. 在 `src/pages/` 下创建页面目录和 `index.tsx`
2. 在 `src/router/config.ts` 中注册路由
3. 编写页面基础结构和布局
4. 接入 API 数据，完成主要交互逻辑
5. 编写单元测试 `__tests__/index.test.tsx`
6. 运行 `npm run test` 确认通过
7. 运行 `npm run build` 确认构建无报错

## 创建新组件

不要手动创建文件。运行脚手架脚本：

\```bash
node scripts/create-component.js UserCard
\```

脚本会自动完成：
- 创建 `src/components/UserCard/` 目录
- 生成 index.tsx（含 Props interface 模板）
- 生成 UserCard.module.css（含基础类名）
- 生成 UserCard.test.tsx（含 render 基础用例）
- 在 `src/components/index.ts` 中追加 export

查看所有选项：`node scripts/create-component.js --help`

## 交付检查（每次完成任务后必须执行）

确认以下每一项都通过后，再告诉用户"已完成"：
- [ ] 运行 `npx tsc --noEmit` 无报错
- [ ] 运行 `npm run test` 全部通过
- [ ] 代码中没有 console.log / debugger / TODO 注释
- [ ] 新增的 Props 都有 JSDoc 注释
- [ ] 可交互元素有 aria-label 或 role 属性
- [ ] 组件在不传任何 props 时不会崩溃（有合理默认值）
- [ ] 新增文件已在 barrel file 中 export

## 输入参数

| 参数 | 必填 | 默认值 | 说明 |
|-----|------|-------|------|
| 组件名称 | 是 | - | PascalCase，如 UserCard |
| 样式方案 | 否 | css-modules | 可选 css-modules / tailwind |
| 是否生成测试 | 否 | 是 | 设为"否"可跳过测试文件 |
| 是否生成 Story | 否 | 否 | Storybook 文件 |

## 输出文件

根据参数生成以下文件：
-`src/components/{组件名称}/index.tsx` ← 始终生成
-`src/components/{组件名称}/{组件名称}.module.css` ← 样式方案为 css-modules 时
-`src/components/{组件名称}/{组件名称}.test.tsx` ← 开启测试时
-`src/components/{组件名称}/{组件名称}.stories.tsx` ← 开启 Story 时

## 项目工具箱

本项目提供了以下开发工具，请优先使用：

| 命令 | 用途 | 什么时候用 |
|-----|------|-----------|
| `npx plop component` | 创建组件脚手架 | 新建任何 React 组件时 |
| `npm run codegen` | 从 OpenAPI 生成 API 类型 | 后端接口有更新时 |
| `npm run analyze` | 分析打包体积 | 添加新依赖或大改动后 |
| `npm run lint:fix` | 自动修复 lint 问题 | 代码写完后 |
| `npm run test:visual` | 跑视觉回归测试 | 改了 UI 样式后 |

## 什么时候用工具 vs 手写
-**用工具**：脚手架搭建、代码生成、构建部署、格式化
-**手写**：业务逻辑、自定义 Hook、复杂交互组件

创建新组件时，**始终**优先用 `npx plop component` 而不是手动建文件。

---

name:frontend-design
description:Createdistinctive,production-gradefrontendinterfaces
withhighdesignquality.Usethisskillwhentheuseraskstobuild
webcomponents,pages,artifacts,orapplications.

---

## Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:
-**Purpose**: What problem does this interface solve? Who uses it?
-**Tone**: Pick an extreme: brutally minimal, maximalist chaos, 
  retro-futuristic, luxury/refined, playful/toy-like...
-**Constraints**: Technical requirements (framework, performance, accessibility)
-**Differentiation**: What makes this UNFORGETTABLE?

## Decision Tree: Choosing Your Approach

User task → Is it static HTML?
    ├─ Yes → Read HTML file directly to identify selectors
    │         └─ Write Playwright script using selectors
    │
    └─ No (dynamic webapp) → Is the server already running?
        ├─ No → Run: python scripts/with_server.py --help
        └─ Yes → Reconnaissance-then-action:
            1. Navigate and wait for networkidle
            2. Take screenshot or inspect DOM
            3. Identify selectors from rendered state
            4. Execute actions with discovered selectors

---
name: docs_agent
description: Expert technical writer for this project
---

You are an expert technical writer for this project.

## Your role
- You are fluent in Markdown and can read TypeScript code
- You write for a developer audience
- Your task: read code from `src/` and generate documentation in `docs/`

## Commands you can use
Build docs: `npm run docs:build`
Lint markdown: `npx markdownlint docs/`

## Boundaries
- ✅ Always do: Write new files to `docs/`, follow style examples
- ⚠️ Ask first: Before modifying existing documents in a major way
- 🚫 Never do: Modify code in `src/`, edit config files, commit secrets

---
name: react-component
description: Scaffold React components with TypeScript following team conventions. Use when the user asks to create, generate, or scaffold a React component, or mentions creating a new UI element.
---

# React Component Generator
## File Structure
For a component named `UserCard`:
\```

src/components/UserCard/
├── index.tsx          # Component implementation
├── UserCard.module.css  # Scoped styles
├── UserCard.test.tsx    # Unit tests
└── types.ts           # Type definitions (if complex)
\```

## Implementation Template

\```tsx
import styles from './UserCard.module.css'

interface UserCardProps {
  name: string
  avatar?: string
  onClick?: () => void
}

export function UserCard({ name, avatar, onClick }: UserCardProps) {
  return (
    <section className={styles.container} onClick={onClick}>
      {avatar && <img src={avatar} alt={name} className={styles.avatar} />}
      <span className={styles.name}>{name}</span>
      </section>
  )
}

\```

## Rules
1. Named exports only, no default exports
2. Props interface in same file (unless 10+ props → extract to types.ts)
3. Use CSS Modules for styling, BEM-like class naming
4. Hooks extract to `useXxx.ts` when logic exceeds 15 lines
5. Every component must have at least one test covering render + key interaction

## Test Template

\```tsx
import { render, screen } from '@testing-library/react'
import { UserCard } from '.'

describe('UserCard', () => {
  it('renders user name', () => {
    render(<UserCard name="Winty" />)
    expect(screen.getByText('Winty')).toBeInTheDocument()
  })
})

\```

## Boundaries
- ✅ Create files in `src/components/`
- ⚠️ Ask before modifying existing shared components
- 🚫 Never modify `src/utils/` or config files

## Detailed Conventions
For complete coding standards, see [conventions.md](references/conventions.md)

# ❌ Agent 完全不知道什么时候该用你
description:Helpswithfrontendstuff.

# ✅ 明确能力 + 触发场景
description:CreateandstyleReactcomponentswithTypeScriptandCSSModules.UsewhenbuildingUIcomponents,pages,orlayouts.

# ❌ Agent 会困惑到底该用哪个
You can use styled-components, or CSS Modules, or Tailwind, or Emotion...

# ✅ 给一个默认方案，必要时提供备选
Use CSS Modules for component styling.
For utility-based layouts, use Tailwind CSS classes instead.

# ❌ 毫无辨识度
name:helper
name:utils
name:tools

# ✅ 一看就知道干什么
name:react-component
name:api-test-generator
name:commit-message