148 lines
6.0 KiB
Plaintext
148 lines
6.0 KiB
Plaintext
# Cursor Rules for Outfit Web Project
|
||
|
||
## 项目概述
|
||
这是一个基于 React 19 + TypeScript + Vite + Tailwind CSS 的前端项目，使用 shadcn/ui 组件库，包含自动生成的 API 客户端。
|
||
|
||
## 技术栈
|
||
- **前端框架**: React 19
|
||
- **语言**: TypeScript
|
||
- **构建工具**: Vite
|
||
- **样式**: Tailwind CSS 4.x
|
||
- **UI 组件库**: shadcn/ui (基于 Radix UI)
|
||
- **图标库**: Lucide React
|
||
- **工具库**: class-variance-authority, clsx, tailwind-merge
|
||
- **HTTP 客户端**: Axios
|
||
- **API 生成**: openapi-typescript-codegen
|
||
|
||
## 代码规范
|
||
|
||
### TypeScript 规范
|
||
- 使用严格的 TypeScript 配置
|
||
- 优先使用类型推断，但为公共 API 和复杂对象显式定义类型
|
||
- 使用 `interface` 定义对象类型，使用 `type` 定义联合类型和工具类型
|
||
- 避免使用 `any`，优先使用 `unknown` 或具体类型
|
||
- 使用泛型提高代码复用性
|
||
|
||
### React 组件规范
|
||
- 使用函数组件和 React Hooks
|
||
- 组件名使用 PascalCase
|
||
- 文件名与组件名保持一致
|
||
- 使用 TypeScript 为 props 定义接口
|
||
- 优先使用 `useState` 和 `useEffect` 等内置 Hooks
|
||
- 自定义 Hooks 以 `use` 开头
|
||
|
||
### shadcn/ui 组件库规范
|
||
- 使用 shadcn/ui 作为主要 UI 组件库
|
||
- 组件配置使用 "new-york" 风格
|
||
- 组件放在 `src/components/ui/` 目录
|
||
- 使用 `@/components/ui` 别名导入 UI 组件
|
||
- 使用 `@/lib/utils` 导入工具函数
|
||
- 图标使用 Lucide React 库
|
||
- 遵循 shadcn/ui 的设计原则和可访问性标准
|
||
- 组件引入、升级、修复请统一使用 `npx shadcn@latest add [component]`，确保与 Tailwind v4、React 19 兼容
|
||
- 组件样式、主题、变量配置统一在 `components.json` 和 `tailwind.config.ts`/`tailwind.config.js` 中管理，Tailwind v4 下 `config` 字段应留空，主题色用 `baseColor`，如 `neutral`、`zinc` 等
|
||
- 推荐开启 `cssVariables: true`，用 CSS 变量做主题定制，支持暗色模式
|
||
- 组件样式冲突时可用 `prefix` 字段（如 `tw-`）隔离 Tailwind 工具类
|
||
- 组件样式入口通过 `tailwind.css`/`globals.css` 引入
|
||
- 组件变体、条件样式统一用 `class-variance-authority`、`clsx`、`tailwind-merge` 组合
|
||
- 推荐使用 `cn()` 工具函数（`clsx`+`tailwind-merge`）合并类名，避免冲突
|
||
- 组件开发/迁移时优先用函数组件，类型用 `React.ComponentProps<typeof X>` 推断，避免 `forwardRef`，如需 `ref` 用 `data-slot` 辅助样式
|
||
- 组件升级/迁移时注意 Tailwind v4 新特性（如 `size-*` 替换 `w-* h-*`）
|
||
- 组件主题色、动画、变量扩展统一用 `cssVars` 和 `theme.extend`，如需自定义色彩/动画，参考官方 registry item 配置
|
||
- 组件可访问性（a11y）严格遵循 shadcn/ui 官方标准，确保键盘可用、aria 属性齐全、对比度达标
|
||
- 组件 peerDependencies 必须支持 React 19，升级依赖时如遇 npm ERESOLVE，优先用 `--force` 或 `--legacy-peer-deps` 解决
|
||
- 组件升级后如有 breaking change，需同步更新相关用法和文档
|
||
|
||
### 样式规范
|
||
- 使用 Tailwind CSS 类名
|
||
- 使用 `clsx` 和 `tailwind-merge` 进行条件样式组合
|
||
- 使用 `class-variance-authority` 创建变体组件
|
||
- 避免内联样式，优先使用 Tailwind 类名
|
||
- 响应式设计使用 Tailwind 的断点前缀
|
||
- 使用 CSS 变量进行主题定制（baseColor: neutral）
|
||
|
||
### 文件组织
|
||
- 组件放在 `src/components/` 目录
|
||
- UI 组件放在 `src/components/ui/` 目录
|
||
- 页面组件放在 `src/pages/` 目录
|
||
- 工具函数放在 `src/lib/` 目录
|
||
- 自定义 Hooks 放在 `src/hooks/` 目录
|
||
- API 相关代码在 `src/api/` 目录（自动生成）
|
||
- 类型定义放在 `src/types/` 目录
|
||
|
||
### 导入规范
|
||
- 使用绝对路径导入（`@/` 别名）
|
||
- 按以下顺序组织导入：
|
||
1. React 相关
|
||
2. 第三方库
|
||
3. shadcn/ui 组件
|
||
4. 内部组件/工具
|
||
5. 类型定义
|
||
6. 样式文件
|
||
|
||
### API 使用规范
|
||
- 使用自动生成的 API 客户端
|
||
- 在组件中使用 `useApi` Hook 进行 API 调用
|
||
- 处理加载状态和错误状态
|
||
- 使用 TypeScript 类型确保类型安全
|
||
|
||
### 命名规范
|
||
- 变量和函数使用 camelCase
|
||
- 常量使用 UPPER_SNAKE_CASE
|
||
- 组件使用 PascalCase
|
||
- 文件使用 kebab-case 或 PascalCase（组件文件）
|
||
- 类型和接口使用 PascalCase
|
||
|
||
### 代码质量
|
||
- 使用 ESLint 进行代码检查
|
||
- 遵循 React Hooks 规则
|
||
- 避免不必要的重新渲染
|
||
- 使用 React.memo 优化性能
|
||
- 正确处理副作用和清理
|
||
|
||
### 开发工作流
|
||
- 使用 `npm run dev` 启动开发服务器
|
||
- 使用 `npm run build` 构建生产版本
|
||
- 使用 `npm run generate-api` 重新生成 API 客户端
|
||
- 使用 `npm run lint` 检查代码质量
|
||
- 使用 `npx shadcn@latest add [component]` 添加新组件
|
||
|
||
## 最佳实践
|
||
|
||
### shadcn/ui 使用最佳实践
|
||
- 优先使用 shadcn/ui 提供的组件，避免重复造轮子
|
||
- 使用 `cn()` 工具函数组合类名
|
||
- 遵循 shadcn/ui 的可访问性标准
|
||
- 使用 `class-variance-authority` 创建组件变体
|
||
- 保持组件的可组合性和可扩展性
|
||
|
||
### 状态管理
|
||
- 对于简单状态，使用 `useState`
|
||
- 对于复杂状态，考虑使用 `useReducer`
|
||
- 避免过度使用全局状态
|
||
|
||
### 性能优化
|
||
- 使用 React.memo 包装纯组件
|
||
- 使用 useCallback 和 useMemo 优化回调函数和计算值
|
||
- 懒加载路由和组件
|
||
- 优化图片和资源加载
|
||
|
||
### 错误处理
|
||
- 使用 Error Boundaries 捕获组件错误
|
||
- 为 API 调用添加适当的错误处理
|
||
- 提供用户友好的错误信息
|
||
|
||
### 可访问性
|
||
- 使用语义化的 HTML 标签
|
||
- 添加适当的 ARIA 属性
|
||
- 确保键盘导航支持
|
||
- 提供足够的颜色对比度
|
||
- 遵循 shadcn/ui 的可访问性指南
|
||
|
||
## 注意事项
|
||
- API 客户端是自动生成的，不要手动修改
|
||
- 使用 Tailwind CSS 4.x 的新特性
|
||
- 遵循 React 19 的最佳实践
|
||
- 保持代码简洁和可维护性
|
||
- shadcn/ui 组件是可定制的，可以根据需要修改
|
||
- 使用 CSS 变量进行主题定制，支持暗色模式 |