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 切换到深色：

// 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:

  <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:

  <Input v-model="text" placeholder="Enter..." />
  

• 样式调整:
  • 当前项目输入框通常为白色背景，需覆盖 shadcn 默认样式：

    .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 实现 (自定义封装示例):

  <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。

  <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:

  <n-layout has-sider>
    <n-layout-sider>...</n-layout-sider>
    <n-layout-content>...</n-layout-content>
  </n-layout>
  

• Tailwind 实现:

  <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 实现:

  <Card class="w-full bg-white border-slate-200">
    <CardHeader>
      <CardTitle>Title</CardTitle>
    </CardHeader>
    <CardContent>
      Content
    </CardContent>
  </Card>
  

Collapse 折叠面板

• NaiveUI:

  <n-collapse>
    <n-collapse-item title="Group" name="1">Content</n-collapse-item>
  </n-collapse>
  

• Tailwind 实现:

  <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 实现:

  <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 样式 (浅色):

  .toast-success {
    @apply bg-white border-l-4 border-primary text-slate-900 shadow-lg;
  }
  

Loading 加载

• NaiveUI: <n-spin /> 或 v-loading
• Tailwind 实现:

  <div class="flex items-center justify-center">
    <Loader2 class="h-8 w-8 animate-spin text-primary" />
  </div>
  

---

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

为了保持项目当前的视觉风格（浅色为主），需要在全局 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 工具类进行覆盖。