feat: sync full workspace including web modules, docs, and configurations to Gitea
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
王冕
@@ -0,0 +1,68 @@
|
||||
# 默认动画库推荐
|
||||
|
||||
**使用时机**：仅在需要复杂动画交互 且 用户未指定动画方案 且 主题中无自定义动画系统时使用。
|
||||
|
||||
## ⚠️ 重要提醒：动画不是必须的！
|
||||
|
||||
- 少量简单动画 → 直接使用 CSS 原生动画（`transition`、`@keyframes`、`animation`）
|
||||
- Tailwind 项目 → 优先使用内置的 `transition-*`、`animate-*` 类
|
||||
- 只有在动画数量多或交互复杂时，才考虑引入动画库
|
||||
|
||||
## 🎬 推荐列表
|
||||
|
||||
| 动画库 | 推荐理由 | AI 生成友好度 | 核心劣势 | 适用场景 |
|
||||
|-------|---------|--------------|---------|---------|
|
||||
| **CSS 原生动画** | ⚡️ 零依赖首选<br>浏览器原生支持，无包体积，性能最优。 | 🌟🌟🌟🌟🌟<br>AI 对 CSS 动画极度熟悉 | 复杂时序控制困难，<br>手势交互需额外代码 | 默认首选。<br>Hover、Focus、简单过渡。 |
|
||||
| **Tailwind Animate**<br>(tailwindcss-animate) | ⚡️ Shadcn/UI 默认方案<br>纯 Class 控制，零 JS 心智负担。 | 🌟🌟🌟🌟🌟<br>AI 只需拼 class，几乎不会翻车 | 表达力有限，<br>无法处理复杂时序和状态 | 下拉、Toast、Modal、<br>Tooltip 等基础过渡。 |
|
||||
| **Framer Motion** | 👑 React 动画事实标准<br>声明式 API + Layout 动画 + 手势系统。 | 🌟🌟🌟🌟🌟<br>训练数据极多，AI 可稳定生成复杂动画 | 包体积偏大，<br>学习成本略高 | 复杂交互原型、页面转场、<br>拖拽排序、微交互系统。 |
|
||||
| **AutoAnimate**<br>(@formkit/auto-animate) | ✨ 一行代码魔法动画<br>DOM 变化即动画，极致省心。 | 🌟🌟🌟🌟<br>AI 基本不用理解动画原理 | 不可控，<br>难以产品级精调 | 列表 CRUD、表格增删、<br>卡片排序。 |
|
||||
|
||||
## 🎯 选择策略
|
||||
|
||||
**按需求复杂度匹配**：
|
||||
|
||||
1. **不需要动画** → 不引入任何动画库 ✅
|
||||
2. **需要动画但数量少（< 5 处）** → **CSS 原生动画** ✅
|
||||
3. **大量动画** → 按复杂度选择：
|
||||
- **简单过渡** → **Tailwind Animate**
|
||||
- **列表增删** → **AutoAnimate**
|
||||
- **手势/布局/复杂时序** → **Framer Motion**
|
||||
|
||||
## 💡 CSS 原生动画示例
|
||||
|
||||
```css
|
||||
/* 简单 Hover 效果 - 无需任何库 */
|
||||
.button {
|
||||
transition: all 0.2s ease;
|
||||
}
|
||||
.button:hover {
|
||||
transform: scale(1.05);
|
||||
}
|
||||
|
||||
/* 淡入动画 */
|
||||
@keyframes fadeIn {
|
||||
from { opacity: 0; transform: translateY(10px); }
|
||||
to { opacity: 1; transform: translateY(0); }
|
||||
}
|
||||
.card {
|
||||
animation: fadeIn 0.3s ease-out;
|
||||
}
|
||||
```
|
||||
|
||||
```html
|
||||
<!-- Tailwind 内置动画 - 无需额外依赖 -->
|
||||
<div class="transition-all duration-300 hover:scale-105">
|
||||
Hover 放大
|
||||
</div>
|
||||
<div class="animate-pulse">
|
||||
加载占位符
|
||||
</div>
|
||||
```
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **性能优先**：动画过多会影响性能，尤其在移动端
|
||||
2. **避免过度使用**：克制使用动画，仅在提升 UX 时添加
|
||||
3. **按需引入**：Framer Motion 较大，确认需要复杂动画再引入
|
||||
4. **一致性**：同一项目尽量使用统一的动画方案
|
||||
5. **可访问性**：尊重用户的 `prefers-reduced-motion` 设置
|
||||
@@ -0,0 +1,36 @@
|
||||
# 默认图表库推荐
|
||||
|
||||
**使用时机**：仅在用户未指定图表库 且 项目中无现有图表方案时使用。
|
||||
|
||||
## 📊 推荐列表
|
||||
|
||||
| 图表库 | 推荐理由 | 核心优劣 | 适用场景 |
|
||||
|-------|---------|---------|---------|
|
||||
| **Recharts** | 🌟 首选通用方案<br>React 原生，组件化极好，代码最干净。 | ✅ 组件化设计，代码简洁<br>✅ React 原生，易于集成<br>⚠️ 复杂交互（3D、地理）支持较弱 | 常规折线、柱状、面积图。<br>**兜底必选**。 |
|
||||
| **Tremor** | Tailwind 绝配<br>专为 Dashboard 设计，样式极美，开箱即用。 | ✅ API 极简，上手快<br>✅ 与 Tailwind 完美融合<br>⚠️ 定制性低，仅支持预设图表类型 | 现代 SaaS 风格的 KPI 面板、统计卡片。 |
|
||||
| **Ant Design Charts**<br>(@ant-design/plots) | B 端业务神器<br>基于 G2，交互强，默认样式符合国内审美。 | ✅ 图表类型丰富，交互强<br>✅ 国内 B 端审美<br>⚠️ 包体积大，非 React 原生 (Canvas)<br>⚠️ 需锁定 v2 版本避免混淆 | 后台管理系统，复杂漏斗图、桑基图。 |
|
||||
| **ECharts**<br>(echarts-for-react) | 重型全能王<br>图表类型最全（地图/3D），渲染性能最强。 | ✅ 图表类型最全，性能强<br>✅ 文档和示例丰富<br>⚠️ 难与 Tailwind 融合<br>⚠️ 配置项繁琐 | 数据大屏、复杂的地理可视化、炫酷特效。 |
|
||||
|
||||
## 🎯 选择策略
|
||||
|
||||
**按需匹配**：
|
||||
1. **没想好/通用场景** → 直接用 **Recharts**
|
||||
2. **需要漂亮的 Dashboard** → 用 **Tremor**
|
||||
3. **国内 B 端后台** → 用 **Ant Design Charts**
|
||||
4. **需要地图/3D/大屏** → 用 **ECharts**
|
||||
|
||||
## 📦 安装命令
|
||||
|
||||
```bash
|
||||
# Recharts (推荐默认安装)
|
||||
pnpm add recharts
|
||||
|
||||
# Tremor
|
||||
pnpm add @tremor/react
|
||||
|
||||
# Ant Design Charts
|
||||
pnpm add @ant-design/plots
|
||||
|
||||
# ECharts
|
||||
pnpm add echarts echarts-for-react
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
# 默认字体组合推荐
|
||||
|
||||
**使用时机**：仅在用户未指定字体方案 且 主题中无自定义字体定义时使用。
|
||||
|
||||
## 🔤 推荐列表
|
||||
|
||||
| 字体组合 | 推荐理由 | 中文环境表现 (Windows/Mac) | 适用场景 |
|
||||
|---------|---------|--------------------------|---------|
|
||||
| **Inter + System Sans**<br>(系统默认黑体) | ⚡️ 性能之王 (首选)<br>英文用 Inter (Tailwind 默认)，中文回退到系统字体 (PingFang/YaHei)。<br>无网络延迟。 | • Mac: 苹方 (完美)<br>• Win: 微软雅黑 (清晰)<br>利用系统渲染，字迹最锐利。 | **UI 界面、按钮、导航栏**。<br>绝大多数 SaaS 产品的默认选择。 |
|
||||
| **Noto Sans SC**<br>(思源黑体) | 🎨 视觉一致性<br>Google Fonts 开源。解决 Windows 下微软雅黑字重缺失（只有 Regular/Bold）的问题。 | 双端一致<br>在 Windows 上也能显示出极细(Light)或极粗(Black)的优美字重。 | **营销页面、高保真原型**。<br>当用户不想看微软雅黑那个"笨重"的样子时。 |
|
||||
| **JetBrains Mono**<br>(代码字体) | 💻 开发者最爱<br>开源等宽字体，连字特性（Ligatures）极美，阅读代码不累。 | 极佳<br>主要显示英文代码，中文备注会回退到系统黑体，互不干扰。 | **代码编辑器、JSON 预览**、<br>Markdown 里的代码块。 |
|
||||
| **Noto Serif SC**<br>(思源宋体) | 📄 文档沉浸感<br>现代风格的宋体，屏幕阅读优化极佳，比系统自带的"宋体"更清晰。 | 双端一致<br>适合长文阅读，有一种"打印刊物"的高级感。 | **PRD 文档模式、阅读模式**。<br>模拟书籍或正式公文的排版。 |
|
||||
|
||||
## 🎯 选择策略
|
||||
|
||||
**按场景匹配**：
|
||||
|
||||
1. **UI 界面（默认）** → **Inter + System Sans**
|
||||
- 按钮、表单、导航、卡片
|
||||
- 无需额外加载，性能最优
|
||||
|
||||
2. **营销页/高保真原型** → **Noto Sans SC**
|
||||
- 需要精确控制字重
|
||||
- 追求视觉一致性
|
||||
|
||||
3. **代码展示** → **JetBrains Mono**
|
||||
- 代码编辑器
|
||||
- 技术文档中的代码块
|
||||
|
||||
4. **长文阅读** → **Noto Serif SC**
|
||||
- 文章、博客、文档
|
||||
- 需要"纸质感"的阅读体验
|
||||
|
||||
## 💡 实现注意事项
|
||||
|
||||
1. **性能优先**：默认使用系统字体，避免加载延迟
|
||||
2. **字重一致性**：Windows 下微软雅黑只有 400/700，如需更多字重需用 Web Font
|
||||
3. **中英混排**：确保英文字体在 font-family 前面，中文字体在后面作为回退
|
||||
4. **字体加载优化**：
|
||||
- 使用 `font-display: swap` 避免字体加载阻塞
|
||||
- 按需加载字重，不要全部引入
|
||||
- 考虑使用 `@fontsource` npm 包而非 Google Fonts CDN（国内访问更快）
|
||||
|
||||
## ⚠️ 常见陷阱
|
||||
|
||||
- ❌ 不要同时加载多个 Web Font，会严重影响性能
|
||||
- ❌ 不要在 UI 界面使用宋体，阅读体验差
|
||||
- ❌ 不要在代码块使用非等宽字体，会导致对齐错乱
|
||||
- ✅ 优先使用系统字体 + Inter 组合，除非有明确的视觉一致性需求
|
||||
@@ -0,0 +1,27 @@
|
||||
# 默认图标库推荐
|
||||
|
||||
**使用时机**：仅在用户未指定图标库 且 主题中无自定义图标系统时使用。
|
||||
|
||||
## 🎨 推荐列表
|
||||
|
||||
| 图标库 | 推荐理由 | 风格特点 | 核心优劣 | 适用场景 |
|
||||
|-------|---------|---------|---------|---------|
|
||||
| **Lucide React** | 🌟 目前最流行 (No.1)<br>Shadcn/UI 默认图标库，极轻量，SVG 质量极高。 | 线性、圆润、现代<br>(Stroke based) | ✅ Tailwind 类名直接控制样式<br>✅ 包体积小，Tree-shaking 友好 | **Axhub Make 默认首选**。<br>适合所有现代 Web 原型。 |
|
||||
| **Ant Design Icons** | Ant Design 组件库官方配套，图标极多。 | 偏粗、商务、稳重<br>(实心/线框/双色) | ✅ 图标丰富，双色图标独特<br>⚠️ 包体积大，需配合 Antd 使用 | 必须配合 Ant Design 组件使用，<br>或需要双色图标时。 |
|
||||
| **Heroicons** | Tailwind 团队开发，无缝集成。 | 简洁、中性<br>(Outline/Solid) | ✅ Tailwind 原生支持<br>⚠️ 图标数量相对较少 | 追求 Tailwind 原生体验。 |
|
||||
| **React Icons** | 万能聚合器<br>包含 FontAwesome, Material 等几十个库。 | 风格杂乱，<br>取决于引入的子库 | ✅ 图标库最全<br>⚠️ 容易导致打包体积过大 | 需要非常冷门的图标<br>（如特定品牌 Logo）。 |
|
||||
|
||||
## 🎯 选择策略
|
||||
|
||||
**按需匹配**：
|
||||
1. **默认/不确定** → 直接用 **Lucide React**
|
||||
2. **用了 Ant Design 组件库** → 用 **Ant Design Icons**
|
||||
3. **Tailwind 纯粹主义者** → 用 **Heroicons**
|
||||
4. **需要特殊品牌图标** → 用 **React Icons**
|
||||
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **避免混用**：同一个项目只用一个图标库，保持视觉一致性
|
||||
2. **按需导入**：使用具名导入而非 `import *`，优化打包体积
|
||||
3. **优先推荐**：Lucide React（轻量、现代、Tailwind 友好）
|
||||
Reference in New Issue
Block a user