UI 开发与组件规范

🎨 核心技术栈

• 基础库: React 19 + Next.js 16 (App Router)
• UI 框架: shadcn/ui (基于 Radix UI)
• 样式: Tailwind CSS 4.0
• 图标: Lucide React
• 动画: Framer Motion
• 表单: React Hook Form + Zod

🛠️ shadcn/ui 管理规范

对于 shadcn 组件，本项目遵循以下原则：

1. 源码即真相

• 不使用技能存储组件列表: 已安装的组件列表应通过检查 frontend/src/components/ui/ 目录和 frontend/components.json 获取。
• 直接修改: 本项目鼓励直接修改 ui/ 目录下的组件源码以满足特定设计需求，而不是在其之上包裹多层。

2. 添加与更新

• 使用内置的 shadcn MCP 工具 来搜索和添加组件。
• 命令行手动操作: pnpm dlx shadcn@latest add [component-name]。

3. 组件分类

• src/components/ui/: 基础原子组件（shadcn 导出的原始组件）。
• src/components/shared/: 跨模块复用的业务组件（如 CategorySelect, PostCard）。
• src/components/{module}/: 模块私有组件（如 admin/posts/PostEditor）。

👗 样式编码标准

1. 响应式优先

• 使用 Tailwind 的响应式前缀 (sm:, md:, lg:)。
• 即使是简单的列表也应考虑移动端适配。

2. 交互状态

• 所有的交互元素（按钮、链接）必须定义 hover, focus-visible, active 状态。
• 使用 ring-offset 和 focus-visible:ring-2 确保无障碍访问。

3. 暗黑模式

• 使用 next-themes 管理状态。
• 样式中应同时考虑 light（默认）和 dark:。

✨ 交互与动画 (Framer Motion)

• 页面切换: 使用 AnimatePresence 处理进入/退出动画。
• 微交互: 用于按钮点击、弹出层出现等场景，提升质感。
• 原则: 动画应快速（通常 < 200ms）且不干扰用户操作流程。

🧩 自定义组件开发指引

1. 复合组件模式: 复杂的组件（如 Select/Combobox）应优先使用 shadcn 的组合模式。
2. 逻辑抽离: 复杂的表单逻辑或数据请求应抽离到独立的 Hook（如 use-posts.ts），组件层只负责 UI。
3. Props 规范:
   • 必须定义 TypeScript 接口。
   • 透传基础 HTML 属性（使用 React.ComponentPropsWithoutRef<"div"> 等）。
   • 使用 cn() 工具函数合并 className。

🔍 工具使用建议

• 当需要新组件时，首先调用 mcp_shadcn_search_items_in_registries。
• 查看示例时，调用 mcp_shadcn_get_item_examples_from_registries 获取最佳实践代码。