Astral3D/docs/css-migration-spec.md

# Astral3D UI 样式迁移规范 (CSS & Vue Style Guide)

> **项目**: Astral3D Web 3D 编辑器  
> **迁移目标**: NaiveUI → Shadcn UI + Tailwind CSS  
> **风格**: 现代简约 / Minimalist Modern  
> **版本**: 1.0

---

## 1. 主题与色彩系统 (Theme & Colors)

### 1.1 色彩变量 (CSS Variables)
我们将在 Tailwind 的默认调色板基础上，定义与当前 NaiveUI 浅色主题兼容的 CSS 变量。

**建议配置 (`tailwind.config.ts` & `globals.css`)**:

| 用途 | Tailwind 映射 | 变量名 | 当前值 (NaiveUI Light) | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| **主色 (Primary)** | `primary` | `--color-primary` | `#63E2B7` (Mint Green) | 品牌色，用于按钮、选中态 |
| **主色悬停** | `primary-hover` | `--color-primary-hover` | `#7FE7C4` | 鼠标悬停 |
| **主色按下** | `primary-pressed` | `--color-primary-pressed` | `#5ACEA7` | 鼠标按下 |
| **背景 (Background)** | `background` | `--background` | `#ffffff` (White) | 页面主背景 |
| **侧边栏背景** | `sidebar-bg` | `--sidebar-background` | `#f8fafc` (Slate 50) | 侧边栏容器 |
| **卡片/面板背景** | `card-bg` | `--card-background` | `#ffffff` (White) | 表单、卡片背景 |
| **边框 (Border)** | `border` | `--border` | `#e2e8f0` (Slate 200) | 分割线、输入框边框 |
| **文字主色** | `foreground` | `--foreground` | `#0f172a` (Slate 900) | 标题、主要文字 |
| **文字次要** | `muted-foreground` | `--muted-foreground` | `#64748b` (Slate 500) | 标签、占位符 |

### 1.2 暗色模式适配 (Dark Mode)
我们将默认配置为浅色，支持通过 class 切换到深色：

```typescript
// tailwind.config.ts
export default {
  darkMode: 'class', // 允许通过添加 'dark' class 切换主题
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: 'var(--color-primary)',
          hover: 'var(--color-primary-hover)',
          pressed: 'var(--color-primary-pressed)',
        },
        background: 'var(--background)',
        surface: 'var(--sidebar-background)',
        border: 'var(--border)',
      }
    }
  }
}
```

---

## 2. 间距与排版 (Spacing & Typography)

### 2.1 间距系统 (Spacing)
迁移 `n-space` 和 NaiveUI 的 padding/margin 逻辑。

| NaiveUI Size | Tailwind Class | 用途 |
| :--- | :--- | :--- |
| `size="small"` | `gap-2` (8px) | 紧凑列表、工具栏 |
| `size="medium"` (默认) | `gap-3` (12px) | 通用表单、卡片 |
| `size="large"` | `gap-4` (16px) | 模块间距、大间距 |
| `n-layout-sider` padding | `p-3` (12px) | 侧边栏内容 padding |
| `n-card` padding | `p-4` (16px) | 卡片内边距 |

### 2.2 圆角系统 (Border Radius)

| NaiveUI | Tailwind Class | 说明 |
| :--- | :--- | :--- |
| `bordered` (默认) | `rounded-md` (6px) | 按钮、输入框 |
| `round` | `rounded-full` | 标签、头像 |
| - | `rounded-lg` (8px) | 模态框、卡片 |

---

## 3. 组件映射速查 (Component Mapping)

### 3.1 基础组件 (Basic Components)

#### Button 按钮
- **NaiveUI**: `<n-button type="primary">Save</n-button>`
- **Shadcn/Vue + Tailwind**:
  ```vue
  <Button variant="default">Save</Button>
  ```
- **属性映射**:
  - `type="primary"` -> `variant="default"` (Primary Color Background)
  - `type="default"` -> `variant="outline"`
  - `type="tertiary"` -> `variant="ghost"`
  - `size="small"` -> `size="sm"`
  - `ghost=true` -> `variant="ghost"`

#### Input 输入框
- **NaiveUI**: `<n-input v-model:value="text" placeholder="Enter..." />`
- **Shadcn/Vue + Tailwind**:
  ```vue
  <Input v-model="text" placeholder="Enter..." />
  ```
- **样式调整**:
  - 当前项目输入框通常为白色背景，需覆盖 `shadcn` 默认样式：
    ```css
    .Input {
      @apply bg-white border-slate-300 text-slate-900 focus:ring-primary;
    }
    ```

#### Select 选择器
- **NaiveUI**: `<n-select v-model:value="val" :options="options" />`
- **Shadcn**: 使用 `Select` 组件或自定义封装。
- **Tailwind 实现 (自定义封装示例)**:
  ```vue
  <div class="relative">
    <select v-model="val" class="appearance-none bg-white border border-slate-300 rounded-md px-3 py-2 text-sm w-full text-slate-900">
      <option v-for="opt in options" :key="opt.value" :value="opt.value">{{ opt.label }}</option>
    </select>
    <!-- 自定义箭头图标 -->
  </div>
  ```

---

### 3.2 布局组件 (Layout Components)

#### Tabs 标签页 (侧边栏)
- **NaiveUI**: `<n-tabs placement="left">` (侧边栏常规模式)
- **Shadcn 实现**: Shadcn 默认 Tabs 是水平顶部排列。
- **Tailwind 实现 (自定义侧边栏 Tabs)**:
  需要使用 Flexbox 布局模拟侧边栏 Tab。
  ```vue
  <div class="flex h-full w-full">
    <!-- 竖向 Tab 列表 -->
    <div class="flex flex-col border-r border-slate-200 w-12 items-center py-2 gap-2 bg-slate-50">
       <button 
         v-for="tab in tabs" 
         :key="tab.name"
         :class="['p-2 rounded', activeTab === tab.name ? 'bg-primary/10 text-primary' : 'text-slate-500 hover:bg-slate-100']"
         @click="activeTab = tab.name"
       >
         <component :is="tab.icon" class="w-4 h-4" />
       </button>
    </div>
    <!-- Tab 内容区 -->
    <div class="flex-1 p-4 overflow-y-auto">
       <component :is="activeComponent" />
    </div>
  </div>
  ```

#### Layout 布局容器
- **NaiveUI**:
  ```vue
  <n-layout has-sider>
    <n-layout-sider>...</n-layout-sider>
    <n-layout-content>...</n-layout-content>
  </n-layout>
  ```
- **Tailwind 实现**:
  ```vue
  <div class="flex h-screen bg-background text-foreground">
    <aside class="w-64 border-r border-border bg-sidebar p-3 overflow-y-auto">
      <!-- 侧边栏内容 -->
    </aside>
    <main class="flex-1 overflow-hidden relative">
      <!-- 主内容区 -->
    </main>
  </div>
  ```

#### Card 卡片
- **NaiveUI**: `<n-card title="Title" size="small">Content</n-card>`
- **Shadcn 实现**:
  ```vue
  <Card class="w-full bg-white border-slate-200">
    <CardHeader>
      <CardTitle>Title</CardTitle>
    </CardHeader>
    <CardContent>
      Content
    </CardContent>
  </Card>
  ```

#### Collapse 折叠面板
- **NaiveUI**:
  ```vue
  <n-collapse>
    <n-collapse-item title="Group" name="1">Content</n-collapse-item>
  </n-collapse>
  ```
- **Tailwind 实现**:
  ```vue
  <Accordion type="single" collapsible>
    <AccordionItem value="1">
      <AccordionTrigger>Group</AccordionTrigger>
      <AccordionContent>Content</AccordionContent>
    </AccordionItem>
  </Accordion>
  ```

---

### 3.3 反馈组件 (Feedback Components)

#### Modal 对话框
- **NaiveUI**: `<n-modal v-model:show="show" preset="card" title="Title" />`
- **Shadcn 实现**:
  ```vue
  <Dialog v-model:open="show">
    <DialogContent class="sm:max-w-[425px] bg-white border-slate-200">
      <DialogHeader>
        <DialogTitle>Title</DialogTitle>
      </DialogHeader>
      <DialogFooter>
        <!-- actions -->
      </DialogFooter>
    </DialogContent>
  </Dialog>
  ```

#### Message 消息提示
- **NaiveUI**: `window.$message.success('Success')`
- **迁移方案**: 使用 `sonner` 或自定义 Toast 组件。
- **Tailwind 样式 (浅色)**:
  ```css
  .toast-success {
    @apply bg-white border-l-4 border-primary text-slate-900 shadow-lg;
  }
  ```

#### Loading 加载
- **NaiveUI**: `<n-spin />` 或 `v-loading`
- **Tailwind 实现**:
  ```vue
  <div class="flex items-center justify-center">
    <Loader2 class="h-8 w-8 animate-spin text-primary" />
  </div>
  ```

---

## 4. 样式覆盖规范 (Style Overrides)

为了保持项目当前的视觉风格（浅色为主），需要在全局 CSS 中添加以下覆盖：

```css
/* src/assets/globals.css */

@layer base {
  :root {
    /* 浅色模式 (默认) */
    --background: 255 255 255; /* White */
    --foreground: 15 23 42; /* Slate 900 */
    
    --card: 255 255 255;
    --card-foreground: 15 23 42;
    
    --primary: 99 226 183; /* Mint Green #63E2B7 */
    --primary-foreground: 15 23 42;
    
    --secondary: 241 245 249; /* Slate 100 */
    --secondary-foreground: 15 23 42;
    
    --muted: 241 245 249; /* Slate 100 */
    --muted-foreground: 100 116 139; /* Slate 500 */
    
    --accent: 241 245 249;
    --accent-foreground: 15 23 42;
    
    --destructive: 239 68 68; /* Red 500 */
    --destructive-foreground: 255 255 255;
    
    --border: 226 232 240; /* Slate 200 */
    --input: 226 232 240;
    --ring: 99 226 183;
    
    --radius: 0.5rem;
  }

  /* 暗色模式 (可选) */
  .dark {
    --background: 15 23 42; /* Slate 950 */
    --foreground: 248 250 252; /* Slate 50 */
    
    --card: 30 41 59; /* Slate 800 */
    --card-foreground: 248 250 252;
    
    --secondary: 51 65 85; /* Slate 700 */
    --secondary-foreground: 248 250 252;
    
    --muted: 51 65 85;
    --muted-foreground: 148 163 184;
    
    --accent: 51 65 85;
    --accent-foreground: 248 250 252;
    
    --destructive: 239 68 68;
    --destructive-foreground: 248 250 252;
    
    --border: 51 65 85;
    --input: 51 65 85;
  }
}

/* 自定义组件样式适配当前项目 (浅色) */
.btn-primary {
  @apply bg-primary text-slate-900 hover:bg-primary/90;
}

.input-light {
  @apply bg-white border-slate-200 text-slate-900 focus:ring-primary rounded-md;
}

/* 侧边栏样式适配 */
.sidebar {
  @apply bg-slate-50 border-r border-slate-200;
}
```

---

## 5. 迁移步骤建议

1.  **安装依赖**: 运行 TODO 文档中的安装命令。
2.  **配置 Tailwind**: 创建 `tailwind.config.ts` 并配置颜色。
3.  **全局样式**: 创建 `globals.css` 并填入上方 CSS 变量。
4.  **组件替换**: 按照 "组件映射速查" 表格，逐页面替换 `naive-ui` 组件。
5.  **样式微调**: 针对特定的 NaiveUI 样式类（如 `.n-form-item`），使用 `@apply` 或 Tailwind 工具类进行覆盖。