chore: remove outdated DESIGN_SYSTEM.md and update migration documentation

- Deleted the obsolete DESIGN_SYSTEM.md file to streamline documentation. - Updated MIGRATION_STATUS.md to reflect the new design token namespace (`--cs-*`) and improved clarity on migration phases and principles. - Revised README.md to correct the number of import methods and enhance usage instructions for the updated design system.
2025-12-26 11:44:28 +08:00 · 2025-10-31 15:54:29 +08:00 · 2025-10-31 15:54:29 +08:00 · 6042ee8ca8
commit 6042ee8ca8
parent d164d7c8bf
3 changed files with 81 additions and 413 deletions
--- a/packages/ui/DESIGN_SYSTEM.md
+++ b/packages/ui/DESIGN_SYSTEM.md
@ -1,368 +0,0 @@
-# Cherry Studio Design System 集成方案
-
-本文档聚焦三个核心问题：
-
-1. **如何将 todocss.css 集成到 Tailwind CSS v4**
-2. **如何在项目中使用集成后的设计系统**
-3. **如何平衡 UI 库和主包的需求**
-
---
-
-## 一、集成策略
-
-### 1.1 文件架构
-
-```
-todocss.css (设计师提供)
-    ↓ 转换 & 优化
-design-tokens.css (--ds-* 变量)
-    ↓ @theme inline 映射
-globals.css (cs-* 工具类)
-    ↓ 开发者使用
-React Components
-```
-
-### 1.2 核心转换规则
-
-#### 变量简化
-
-```css
-/* todocss.css */
--Brand--Base_Colors--Primary: hsla(84, 81%, 44%, 1);
-
-/* ↓ 转换为 design-tokens.css */
--ds-primary: hsla(84, 81%, 44%, 1);
-
-/* ↓ 映射到 globals.css */
-@theme inline {
-  --color-cs-primary: var(--ds-primary);
-}
-
-/* ↓ 生成工具类 */
-bg-cs-primary, text-cs-primary, border-cs-primary
-```
-
-#### 去除冗余
-
- **间距/尺寸合并**: `--Spacing--md` 和 `--Sizing--md` 值相同 → 统一为 `--ds-size-md`
- **透明度废弃**: `--Opacity--Red--Red-80` → 使用 `bg-cs-destructive/80`
- **错误修正**: `--Font_weight--Regular: 400px` → `--ds-font-weight-regular: 400`
-
-### 1.3 命名规范
-
-| 层级 | 前缀 | 示例 | 用途 |
-|------|------|------|------|
-| 设计令牌 | `--ds-*` | `--ds-primary` | 定义值 |
-| Tailwind 映射 | `--color-cs-*` | `--color-cs-primary` | 生成工具类 |
-| 工具类 | `cs-*` | `bg-cs-primary` | 开发者使用 |
-
-#### Tailwind v4 映射规则
-
-| 变量前缀 | 生成的工具类 |
-|----------|-------------|
-| `--color-cs-*` | `bg-*`, `text-*`, `border-*`, `fill-*` |
-| `--spacing-cs-*` | `p-*`, `m-*`, `gap-*` |
-| `--size-cs-*` | `w-*`, `h-*`, `size-*` |
-| `--radius-cs-*` | `rounded-*` |
-| `--font-size-cs-*` | `text-*` |
-
-### 1.4 为什么使用 @theme inline
-
-```css
-/* ❌ @theme - 静态编译，不支持运行时主题切换 */
-@theme {
-  --color-primary: var(--ds-primary);
-}
-
-/* ✅ @theme inline - 保留变量引用，支持运行时切换 */
-@theme inline {
-  --color-cs-primary: var(--ds-primary);
-}
-```
-
-**关键差异**：`@theme inline` 使 CSS 变量在运行时动态解析，实现明暗主题切换。
-
---
-
-## 二、项目使用指南
-
-### 2.1 在 UI 库中使用
-
-#### 文件结构
-
-```
-packages/ui/
-├── src/styles/
-│   ├── design-tokens.css    # 核心变量定义
-│   └── globals.css          # Tailwind 集成
-└── package.json             # 导出配置
-```
-
-#### globals.css 示例
-
-```css
-@import 'tailwindcss';
-@import './design-tokens.css';
-
-@theme inline {
-  /* 颜色 */
-  --color-cs-primary: var(--ds-primary);
-  --color-cs-bg: var(--ds-background);
-  --color-cs-fg: var(--ds-foreground);
-
-  /* 间距 */
-  --spacing-cs-xs: var(--ds-size-xs);
-  --spacing-cs-sm: var(--ds-size-sm);
-  --spacing-cs-md: var(--ds-size-md);
-
-  /* 尺寸 */
-  --size-cs-xs: var(--ds-size-xs);
-  --size-cs-sm: var(--ds-size-sm);
-
-  /* 圆角 */
-  --radius-cs-sm: var(--ds-radius-sm);
-  --radius-cs-md: var(--ds-radius-md);
-}
-
-@custom-variant dark (&:is(.dark *));
-```
-
-#### 组件中使用
-
-```tsx
-// packages/ui/src/components/Button.tsx
-export const Button = ({ children }) => (
-  <button className="
-    bg-cs-primary
-    text-white
-    px-cs-sm
-    py-cs-xs
-    rounded-cs-md
-    hover:bg-cs-primary/90
-    transition-colors
-  ">
-    {children}
-  </button>
-)
-```
-
-### 2.2 在主项目中使用
-
-#### 导入 UI 库样式
-
-```css
-/* src/renderer/src/assets/styles/tailwind.css */
-@import 'tailwindcss' source('../../../../renderer');
-@import '@cherrystudio/ui/styles/globals.css';
-
-@custom-variant dark (&:is(.dark *));
-```
-
-#### 覆盖或扩展变量
-
-```css
-/* src/renderer/src/assets/styles/tailwind.css */
-@import '@cherrystudio/ui/styles/globals.css';
-
-/* 主项目特定覆盖 */
-:root {
-  --ds-primary: #custom-color;  /* 覆盖 UI 库的主题色 */
-}
-```
-
-#### 在主项目组件中使用
-
-```tsx
-// src/renderer/src/pages/Home.tsx
-export const Home = () => (
-  <div className="
-    bg-cs-bg
-    p-cs-md
-    rounded-cs-lg
-  ">
-    <Button>主项目按钮</Button>
-  </div>
-)
-```
-
-### 2.3 主题切换实现
-
-```tsx
-// App.tsx
-import { useState } from 'react'
-
-export function App() {
-  const [theme, setTheme] = useState<'light' | 'dark'>('light')
-
-  return (
-    <div className={theme}>
-      <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
-        切换主题
-      </button>
-      {/* 所有子组件自动响应主题 */}
-    </div>
-  )
-}
-```
-
-### 2.4 透明度修饰符
-
-```tsx
-<div className="
-  bg-cs-primary/10      /* 10% 透明度 */
-  bg-cs-primary/50      /* 50% 透明度 */
-  bg-cs-primary/[0.15]  /* 自定义透明度 */
-">
-```
-
---
-
-## 三、UI 库与主包平衡策略
-
-### 3.1 UI 库职责
-
-**目标**：提供可复用、可定制的基础设计系统
-
-```json
-// packages/ui/package.json
-{
-  "exports": {
-    "./styles/design-tokens.css": "./src/styles/design-tokens.css",
-    "./styles/globals.css": "./src/styles/globals.css"
-  }
-}
-```
-
-**原则**：
-
- ✅ 定义通用的设计令牌（`--ds-*`）
- ✅ 提供默认的 Tailwind 映射（`--color-cs-*`）
- ✅ 保持变量语义化，不包含业务逻辑
- ❌ 不包含主项目特定的颜色或尺寸
-
-### 3.2 主包职责
-
-**目标**：导入 UI 库，根据业务需求扩展或覆盖
-
-```css
-/* src/renderer/src/assets/styles/tailwind.css */
-@import '@cherrystudio/ui/styles/globals.css';
-
-/* 主项目扩展 */
-@theme inline {
-  --color-cs-brand-accent: #ff6b6b;  /* 新增颜色 */
-}
-
-/* 主项目覆盖 */
-:root {
-  --ds-primary: #custom-primary;     /* 覆盖 UI 库的主题色 */
-}
-```
-
-**原则**：
-
- ✅ 导入 UI 库的 `globals.css`
- ✅ 通过覆盖 `--ds-*` 变量定制主题
- ✅ 添加项目特定的 `--color-cs-*` 映射
- ✅ 保留向后兼容的旧变量（如 `color.css`）
-
-### 3.3 向后兼容方案
-
-#### 保留旧变量
-
-```css
-/* src/renderer/src/assets/styles/color.css */
-:root {
-  --color-primary: #00b96b;         /* 旧变量 */
-  --color-background: #181818;      /* 旧变量 */
-}
-
-/* 映射到新系统 */
-:root {
-  --ds-primary: var(--color-primary);
-  --ds-background: var(--color-background);
-}
-```
-
-#### 渐进式迁移
-
-```tsx
-// 阶段 1：旧代码继续工作
-<div style={{ color: 'var(--color-primary)' }}>旧代码</div>
-
-// 阶段 2：新代码使用工具类
-<div className="text-cs-primary">新代码</div>
-
-// 阶段 3：逐步替换旧代码
-```
-
-### 3.4 冲突处理
-
-| 场景 | 策略 |
-|------|------|
-| UI 库与 Tailwind 默认类冲突 | 使用 `cs-` 前缀隔离 |
-| 主包需要覆盖 UI 库颜色 | 覆盖 `--ds-*` 变量 |
-| 主包需要新增颜色 | 添加新的 `--color-cs-*` 映射 |
-| 旧变量与新系统共存 | 通过 `var()` 映射到 `--ds-*` |
-
-### 3.5 独立发布 UI 库
-
-```json
-// packages/ui/package.json
-{
-  "name": "@cherrystudio/ui",
-  "exports": {
-    "./styles/design-tokens.css": "./src/styles/design-tokens.css",
-    "./styles/globals.css": "./src/styles/globals.css"
-  },
-  "peerDependencies": {
-    "tailwindcss": "^4.1.13"
-  }
-}
-```
-
-**外部项目使用**：
-```css
-/* 其他项目的 tailwind.css */
-@import 'tailwindcss';
-@import '@cherrystudio/ui/styles/globals.css';
-
-/* 覆盖主题色 */
-:root {
-  --ds-primary: #your-brand-color;
-}
-```
-
---
-
-## 四、完整映射示例
-
-### todocss.css → design-tokens.css
-
-| todocss.css | design-tokens.css | 说明 |
-|-------------|-------------------|------|
-| `--Brand--Base_Colors--Primary` | `--ds-primary` | 简化命名 |
-| `--Spacing--md` + `--Sizing--md` | `--ds-size-md` | 合并重复 |
-| `--Opacity--Red--Red-80` | *(删除)* | 使用 `/80` 修饰符 |
-| `--Font_weight--Regular: 400px` | `--ds-font-weight-regular: 400` | 修正错误 |
-| `--Brand--UI_Element_Colors--Primary_Button--Background` | `--ds-btn-primary` | 简化语义 |
-
-### design-tokens.css → globals.css → 工具类
-
-| design-tokens.css | globals.css | 工具类 |
-|-------------------|-------------|--------|
-| `--ds-primary` | `--color-cs-primary` | `bg-cs-primary` |
-| `--ds-size-md` | `--spacing-cs-md` | `p-cs-md` |
-| `--ds-size-md` | `--size-cs-md` | `w-cs-md` |
-| `--ds-radius-lg` | `--radius-cs-lg` | `rounded-cs-lg` |
-
---
-
-## 五、关键决策记录
-
-1. **使用 `@theme inline`** - 支持运行时主题切换
-2. **`cs-` 前缀** - 命名空间隔离，避免冲突
-3. **合并 Spacing/Sizing** - 消除冗余
-4. **废弃 Opacity 变量** - 使用 Tailwind 的 `/modifier` 语法
-5. **双层变量系统** - `--ds-*` (定义) → `--color-cs-*` (映射)
-6. **共存策略** - Tailwind 默认类 + `cs-` 品牌类
--- a/packages/ui/MIGRATION_STATUS.md
+++ b/packages/ui/MIGRATION_STATUS.md
@ -9,16 +9,16 @@ This document outlines the detailed plan for migrating Cherry Studio from antd +
 ### Target Tech Stack

 - **UI Component Library**: shadcn/ui (replacing antd and previously migrated HeroUI)
- **Styling Solution**: Tailwind CSS (replacing styled-components)
- **Design System**: Custom CSS variable system (see [DESIGN_SYSTEM.md](./DESIGN_SYSTEM.md))
- **Theme System**: CSS variables + shadcn/ui theme
+- **Styling Solution**: Tailwind CSS v4 (replacing styled-components)
+- **Design System**: Custom CSS variable system (`--cs-*` namespace)
+- **Theme System**: CSS variables + Tailwind CSS theme

 ### Migration Principles

 1. **Backward Compatibility**: Old components continue working until new components are fully available
 2. **Progressive Migration**: Migrate components one by one to avoid large-scale rewrites
 3. **Feature Parity**: Ensure new components have all the functionality of old components
-4. **Design Consistency**: Follow new design system specifications (see DESIGN_SYSTEM.md)
+4. **Design Consistency**: Follow new design system specifications (see [README.md](./README.md))
 5. **Performance Priority**: Optimize bundle size and rendering performance
 6. **Designer Collaboration**: Work with UI designers for gradual component encapsulation and UI optimization

@ -105,7 +105,7 @@ When submitting PRs, please place components in the correct directory based on t

 | Phase | Status | Main Tasks | Description |
 | --- | --- | --- | --- |
-| **Phase 1** | 🚧 **In Progress** | **Design System Integration** | • Integrate design system CSS variables (todocss.css → design-tokens.css → globals.css)<br>• Configure Tailwind CSS to use custom design tokens<br>• Establish basic style guidelines and theme system |
+| **Phase 1** | ✅ **Completed** | **Design System Integration** | • Converted design tokens from todocss.css to tokens.css with `--cs-*` namespace<br>• Created theme.css mapping all design tokens to standard Tailwind classes<br>• Extended Tailwind with semantic spacing (5xs~8xl) and radius (4xs~3xl) systems<br>• Established two usage modes: full override and selective override<br>• Cleaned up main package's conflicting Shadcn theme definitions |
 | **Phase 2** | ⏳ **To Start** | **Component Migration and Optimization** | • Filter components for migration based on extraction criteria<br>• Remove antd dependencies, replace with shadcn/ui<br>• Remove HeroUI dependencies, replace with shadcn/ui<br>• Remove styled-components, replace with Tailwind CSS + design system variables<br>• Optimize component APIs and type definitions |
 | **Phase 3** | ⏳ **To Start** | **UI Refactoring and Optimization** | • Gradually implement UI refactoring with UI designers<br>• Ensure visual consistency and user experience<br>• Performance optimization and code quality improvement |

@ -129,16 +129,22 @@ When submitting PRs, please place components in the correct directory based on t
 ## Design System Integration

 ### CSS Variable System
- Refer to [DESIGN_SYSTEM.md](./DESIGN_SYSTEM.md) for complete design system planning
- Design variables will be managed through CSS variable system, naming conventions TBD
- Support theme switching and responsive design
+
+- All design tokens use `--cs-*` namespace (e.g., `--cs-primary`, `--cs-red-500`)
+- Complete color palette: 17 colors × 11 shades each
+- Semantic spacing system: `5xs` through `8xl` (16 levels)
+- Semantic radius system: `4xs` through `3xl` plus `round` (11 levels)
+- Full light/dark mode support
+- See [README.md](./README.md) for usage documentation

 ### Migration Priority Adjustment
+
 1. **High Priority**: Basic components (buttons, inputs, tags, etc.)
 2. **Medium Priority**: Display components (cards, lists, tables, etc.)
 3. **Low Priority**: Composite components and business-coupled components

 ### UI Designer Collaboration
+
 - All component designs need confirmation from UI designers
 - Gradually implement UI refactoring to maintain visual consistency
- New components must comply with design system specifications
+- New components must comply with design system specifications
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@ -7,7 +7,7 @@ Cherry Studio UI 组件库 - 为 Cherry Studio 设计的 React 组件集合
 - 🎨 **设计系统**: 完整的 CherryStudio 设计令牌（17种颜色 × 11个色阶 + 语义化主题）
 - 🌓 **Dark Mode**: 开箱即用的深色模式支持
 - 🚀 **Tailwind v4**: 基于最新 Tailwind CSS v4 构建
- 📦 **灵活导入**: 3种样式导入方式，满足不同使用场景
+- 📦 **灵活导入**: 2种样式导入方式，满足不同使用场景
 - 🔷 **TypeScript**: 完整的类型定义和智能提示
 - 🎯 **零冲突**: CSS 变量隔离，不覆盖用户主题

@ -23,52 +23,54 @@ npm install @cherrystudio/ui
 npm install @heroui/react framer-motion react react-dom tailwindcss
 ```

-### 三种使用方式
+### 两种使用方式

-根据你的需求选择一种：
+#### 方式 1：完整覆盖 ✨

-#### 方式 1：完整主题（推荐给主包）
+使用完整的 CherryStudio 设计系统，所有 Tailwind 类名映射到设计系统。

 ```css
 /* app.css */
@import '@cherrystudio/ui/styles/theme.css';
 ```

- ✅ 使用标准 Tailwind 类名（`bg-primary`、`bg-red-500`）
+**特点**：
+
+- ✅ 直接使用标准 Tailwind 类名（`bg-primary`、`bg-red-500`、`p-md`、`rounded-lg`）
 - ✅ 所有颜色使用设计师定义的值
- ⚠️ 会覆盖 Tailwind 默认颜色
+- ✅ 扩展的 Spacing 系统（`p-5xs` ~ `p-8xl`，共 16 个语义化尺寸）
+- ✅ 扩展的 Radius 系统（`rounded-4xs` ~ `rounded-3xl`，共 11 个圆角）
+- ⚠️ 会完全覆盖 Tailwind 默认主题
+
+**示例**：

 ```tsx
-<Button className="bg-primary text-red-500 p-md">
-  {/* bg-primary → CherryStudio 品牌色（lime-500） */}
+<Button className="bg-primary text-red-500 p-md rounded-lg">
+  {/* bg-primary → 品牌色（lime-500） */}
  {/* text-red-500 → 设计师定义的红色 */}
-  {/* p-md → 2.5rem（设计师定义） */}
+  {/* p-md → 2.5rem（spacing-md） */}
+  {/* rounded-lg → 2.5rem（radius-lg） */}
 </Button>
+
+{/* 扩展的工具类 */}
+<div className="p-5xs">最小间距 (0.5rem)</div>
+<div className="p-xs">超小间距 (1rem)</div>
+<div className="p-sm">小间距 (1.5rem)</div>
+<div className="p-md">中等间距 (2.5rem)</div>
+<div className="p-lg">大间距 (3.5rem)</div>
+<div className="p-xl">超大间距 (5rem)</div>
+<div className="p-8xl">最大间距 (15rem)</div>
+
+<div className="rounded-4xs">最小圆角 (0.25rem)</div>
+<div className="rounded-xs">小圆角 (1rem)</div>
+<div className="rounded-md">中等圆角 (2rem)</div>
+<div className="rounded-xl">大圆角 (3rem)</div>
+<div className="rounded-round">完全圆角 (999px)</div>
 ```

-#### 方式 2：仅变量（推荐给 npm 用户）
+#### 方式 2：选择性覆盖 🎯

-```css
-/* app.css */
-@import 'tailwindcss';
-@import '@cherrystudio/ui/styles/index.css';
-```
-
- ✅ 不覆盖你的 Tailwind 主题
- ✅ 通过 CSS 变量使用（`var(--cs-primary)`）
- ✅ 你的 `bg-red-500` 不受影响
-
-```tsx
-<button style={{ backgroundColor: 'var(--cs-primary)' }}>
-  {/* 使用 CherryStudio 品牌色 */}
-</button>
-
-<div className="bg-red-500">
-  {/* 使用你自己的红色，不受影响 */}
-</div>
-```
-
-#### 方式 3：选择性覆盖
+只导入设计令牌（CSS 变量），手动选择要覆盖的部分。

 ```css
 /* app.css */
@ -77,11 +79,42 @@ npm install @heroui/react framer-motion react react-dom tailwindcss

 /* 只使用部分设计系统 */
@theme {
-  --color-primary: var(--cs-primary);  /* 用 CS 的主色 */
-  --color-red-500: oklch(...);         /* 用自己的红色 */
+  --color-primary: var(--cs-primary);     /* 使用 CS 的主色 */
+  --color-red-500: oklch(...);            /* 使用自己的红色 */
+  --spacing-md: var(--cs-size-md);        /* 使用 CS 的间距 */
+  --radius-lg: 1rem;                      /* 使用自己的圆角 */
 }
 ```

+**特点**：
+
+- ✅ 不覆盖任何 Tailwind 默认主题
+- ✅ 通过 CSS 变量访问所有设计令牌（`var(--cs-primary)`、`var(--cs-red-500)`）
+- ✅ 精细控制哪些使用 CS、哪些保持原样
+- ✅ 适合有自己设计系统但想借用部分 CS 设计令牌的场景
+
+**示例**：
+
+```tsx
+{/* 通过 CSS 变量使用 CS 设计令牌 */}
+<button style={{ backgroundColor: 'var(--cs-primary)' }}>
+  使用 CherryStudio 品牌色
+</button>
+
+{/* 保持原有的 Tailwind 类名不受影响 */}
+<div className="bg-red-500">
+  使用 Tailwind 默认的红色
+</div>
+
+{/* 可用的 CSS 变量 */}
+<div style={{
+  color: 'var(--cs-primary)',           // 品牌色
+  backgroundColor: 'var(--cs-red-500)', // 红色-500
+  padding: 'var(--cs-size-md)',         // 间距
+  borderRadius: 'var(--cs-radius-lg)'   // 圆角
+}} />
+```
+
 ### Provider 配置

 在你的 App 根组件中添加 HeroUI Provider：
@ -127,9 +160,6 @@ function App() {
 // 只导入组件
 import { Button } from '@cherrystudio/ui/components'

-// 只导入 hooks
-import { useDebounce, useLocalStorage } from '@cherrystudio/ui/hooks'
-
 // 只导入工具函数
 import { cn, formatFileSize } from '@cherrystudio/ui/utils'
 ```