DocFlow / rules

---
description: Styles architecture and CSS loading strategy
globs:
  - 'src/styles/**'
  - 'src/app/**/layout.tsx'
---

# DocFlow 样式架构规范

## 文件结构

- `src/styles/global.css` - 全局基础样式（Tailwind CSS + 主题变量）
- `src/styles/index.css` - Tiptap 编辑器样式（仅在 /docs 路由加载）
- `src/styles/partials/**` - 编辑器样式模块（blocks、collab、code 等）

## CSS 加载策略

### 全局加载（`app/layout.tsx`）

```tsx
import '@/styles/global.css';
```

包含：

- Tailwind CSS 基础层、组件层、工具层
- 主题变量（`:root` 和 `.dark`）
- 全局样式重置
- 字体配置

### 按需加载（`app/docs/layout.tsx`）

```tsx
import '@/styles/index.css';
```

包含：

- KaTeX 数学公式样式
- 代码高亮样式
- Tiptap 编辑器样式
- 协作光标样式
- 表格、列表等编辑器组件样式

## 重要规则

### ✅ 正确做法

1. `global.css` 包含 `@import 'tailwindcss'` 和主题变量
2. `index.css` **不**重复导入 Tailwind，但可以使用 `@apply` 指令
3. 编辑器相关的大型 CSS（katex、highlight.js 等）只在 `/docs` 路由加载
4. 所有 `partials/**` 文件使用 `@apply` 指令，依赖 Tailwind

### ❌ 错误做法

1. ~~在 `index.css` 中重复导入 `@import 'tailwindcss'`~~
2. ~~在全局 layout 中导入 `index.css`~~
3. ~~在 `index.css` 中重复定义主题变量~~

## 性能优化原理

- **首页加载**：只加载 ~15KB 的 `global.css`
- **编辑器页面**：额外加载 ~200KB 的 `index.css`（包括 katex 等）
- **减少首屏时间**：首页不需要的样式延迟到访问编辑器时才加载

## 文件依赖关系

```
app/layout.tsx
  └─ global.css (Tailwind + 主题)

app/docs/layout.tsx
  └─ index.css
       ├─ katex.min.css
       ├─ partials/animations.css (使用 @apply)
       ├─ partials/blocks.css (使用 @apply)
       ├─ partials/code.css (使用 @apply)
       ├─ partials/collab.css
       ├─ partials/lists.css (使用 @apply)
       ├─ partials/placeholder.css (使用 @apply)
       ├─ partials/table.css (使用 @apply)
       ├─ partials/typography.css (使用 @apply)
       ├─ partials/draggable.css (使用 @apply)
       └─ partials/frappe-gantt.css (使用 @apply)
```

## 修改样式时的注意事项

1. **修改全局样式**：编辑 `global.css`
2. **修改编辑器样式**：编辑 `index.css` 或相应的 `partials/**` 文件
3. **添加新的编辑器样式模块**：在 `partials/` 创建新文件，然后在 `index.css` 中导入
4. **使用 Tailwind 工具类**：可以在任何 CSS 文件中使用 `@apply` 指令

## 测试检查清单

修改样式后，确保：

- [ ] `pnpm build` 成功编译
- [ ] 首页样式正常显示
- [ ] 编辑器页面样式正常显示
- [ ] 没有 CSS 相关的构建警告
- [ ] 首页不加载编辑器 CSS（检查 Network 面板）

More agent context in xun082/DocFlow

6 other files this repository gives its agents.