项目技能与架构文档
1. 技术栈概览
- 框架: Next.js 16 (App Router)
- 构建工具: Turbopack (开发时使用
--turbo) - 语言: TypeScript
- UI 库: React 19
- 样式: Tailwind CSS v4
- 动画: Framer Motion &
tw-animate-css - 组件基础: Radix UI (通过 Shadcn UI)
- 图标: Lucide React
- 工具库:
clcx、tailwind-merge、date-fns
2. 设计系统
色彩体系
但满足设计要求的情况下， 优先取用app/colors/page.tsx中存在的颜色
字体排版
- 无衬线: Geist Sans（简洁、现代的系统字体）
- 等宽: Geist Mono（用于代码/数据）
- 手写体: Caveat（用于活泼、个性化的点缀）— 通过
--font-handwriting配置
视觉风格
- 核心理念:
- 艺术与个性: 带有强烈的个人特征，带有艺术气息。
- 几何感: 注重几何图形与构图。
- 反套路: 避免通用设计模式（标准卡片、混浊渐变、莫名阴影）。
- 童趣感: 清新、明亮的色彩，像孩子的简笔画一样 — 干净、天真、鲜艳。
3. 项目架构
目录结构
app/
├── (home)/ # 路由分组：首页
├── json/ # 功能：JSON 编辑器与格式化工具
├── share/ # 功能：分享功能
├── layout.tsx # 根布局，包含 ThemeProvider 和全局样式
└── globals.css # Tailwind v4 配置与 CSS 变量
components/
├── ui/ # 原子设计组件（Button、Card、Input...）
├── theme-provider.tsx # Next-themes 集成
└── [feature].tsx # 功能相关组件
lib/
└── utils.ts # CN 辅助函数 (clsx + tailwind-merge)
关键架构决策
- 原子设计: UI 组件抽离到
components/ui中，最大化复用性。 - 路由分组: 使用括号文件夹（如
(home)）组织路由，不影响 URL 结构。 - 客户端/服务端分离: 交互组件（如 JSON 编辑器）显式使用
"use client"，默认保持为服务端组件以提升性能。
4. 已采纳的最佳实践
- 严格 TypeScript: 在整个应用中确保类型安全。
- Tailwind v4: 采用最新的 CSS 优先配置方式（大多数情况下不需要
tailwind.config.js）。 - 无障碍 (a11y): 基于 Radix UI 基础组件，确保键盘导航和屏幕阅读器支持。
- 性能:
- 使用
next/dynamic延迟加载重型客户端库（如react-json-view）。 - 使用 Turbopack 实现即时开发反馈。
- 使用
- 代码质量:
- 预配置 ESLint（未来可能需要 v9 兼容配置）。
- 关注点分离（Hooks、Components、Utilities）。
- 构建优化
- 充分考虑代码对首屏加载速度、页面性能的影响。 代码修改或方案设计会影响性能时需要主动让用户决策。
- 充分利用next的ssg机制， 尽量使页面不依赖js也能可读
5. 功能亮点
主题系统
- 基于
next-themes构建。 - CSS 变量定义在
globals.css的:root和.dark选择器中，实现即时、无闪烁的主题切换。