docs(vscode-ide-companion): add Tailwind CSS integration guides

添加 Tailwind CSS 渐进式集成文档，包括： - 渐进式采用策略文档 - 集成计划文档 - 渐进式集成指南
2025-12-19 09:33:53 +00:00 · 2025-11-23 16:41:22 +08:00
parent 9899d872a2
commit 38fd303b07
3 changed files with 473 additions and 0 deletions
--- a/packages/vscode-ide-companion/PROGRESSIVE_TAILWIND_ADOPTION.md
+++ b/packages/vscode-ide-companion/PROGRESSIVE_TAILWIND_ADOPTION.md
@@ -0,0 +1,191 @@
 # 渐进式Tailwind CSS采用指南
 ## 1. 采用策略
 我们采用渐进式的方法将Tailwind CSS集成到现有项目中，确保不影响现有功能和开发流程。
 ### 核心原则
 1. **不破坏现有功能** - 保留所有现有CSS和组件
 2. **并行开发** - 新组件使用Tailwind，现有组件保持不变
 3. **逐步迁移** - 随着时间推移逐步将现有组件迁移到Tailwind
 4. **团队协作** - 确保团队成员理解并遵循新的开发规范
 ## 2. 实施步骤
 ### 第一阶段：基础配置和新组件开发
 #### 2.1 已完成的配置
 - [x] Tailwind CSS 添加到项目依赖
 - [x] `tailwind.config.js` 配置文件创建
 - [x] `postcss.config.js` 配置文件创建
 - [x] `src/styles.css` 创建并包含Tailwind指令
 #### 2.2 创建新的Tailwind组件
 我们已经创建了以下示例组件：
 - `src/webview/components/ui/Button.tsx` - 使用Tailwind的按钮组件
 - `src/webview/components/ui/Card.tsx` - 使用Tailwind的卡片组件
 - `src/webview/components/TailwindDemo.tsx` - 展示如何使用Tailwind的演示组件
 ### 第二阶段：混合使用策略
 #### 2.3 在现有组件中添加Tailwind类
 可以在现有组件中添加Tailwind类作为补充，而不替换现有CSS：
 ```tsx
 // 示例：在现有组件中添加Tailwind类
 import './PermissionDrawer.css'; // 保留现有样式
 export const PermissionDrawer: React.FC<PermissionDrawerProps> = ({ ... }) => {
  return (
    // 添加Tailwind类作为补充
    <div className="permission-drawer flex flex-col rounded-lg">
      {/* 现有内容保持不变 */}
    </div>
  );
 };
 ```
 #### 2.4 创建增强版本
 为现有组件创建Tailwind增强版本，供新功能使用：
 ```tsx
 // PermissionDrawer.tailwind.tsx
 export const PermissionDrawerTailwind: React.FC<PermissionDrawerProps> = ({ ... }) => {
  return (
    <div className="fixed inset-0 flex items-end justify-center">
      <div className="bg-white rounded-t-xl shadow-2xl w-full max-w-md">
        {/* 使用纯Tailwind样式 */}
      </div>
    </div>
  );
 };
 ```
 ### 第三阶段：逐步迁移现有组件
 #### 3.1 选择合适的组件开始迁移
 建议从以下类型的组件开始：
 1. 独立性强、依赖较少的组件
 2. 新功能相关的组件
 3. 需要重构或改进的组件
 #### 3.2 迁移步骤
 1. 复制现有组件代码
 2. 替换CSS类名为Tailwind类
 3. 测试功能确保一致
 4. 逐步替换原有组件
 ## 3. 最佳实践
 ### 3.1 保持向后兼容性
 - 不要删除现有的CSS文件
 - 逐步替换，而不是一次性重构
 - 在团队中建立清晰的规范
 ### 3.2 性能优化
 ```js
 // tailwind.config.js - 渐进式内容扫描策略
 module.exports = {
  content: [
    // 渐进式采用策略：只扫描新创建的Tailwind组件
    "./src/webview/components/ui/**/*.{js,jsx,ts,tsx}",
    "./src/webview/components/TailwindDemo.tsx",
    // 当需要在更多组件中使用Tailwind时，可以逐步添加路径
    // "./src/webview/components/NewComponent/**/*.{js,jsx,ts,tsx}",
    // "./src/webview/pages/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {
      // 扩展主题以匹配现有设计
      colors: {
        'qwen': {
          'orange': '#615fff',
          'clay-orange': '#4f46e5',
          'ivory': '#f5f5ff',
          'slate': '#141420',
          'green': '#6bcf7f',
        }
      },
      borderRadius: {
        'small': '4px',
        'medium': '6px',
        'large': '8px',
      }
    },
  },
 };
 ```
 ### 3.3 团队协作
 1. **文档化**：维护Tailwind使用指南
 2. **代码审查**：在代码审查中检查Tailwind使用是否合理
 3. **组件库**：逐步建立基于Tailwind的组件库
 4. **培训**：为团队成员提供Tailwind培训
 ## 4. 使用示例
 ### 4.1 新组件开发
 ```tsx
 // components/ui/Button.tsx
 export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  children
 }) => {
  const baseClasses = "inline-flex items-center justify-center rounded-md font-medium transition-colors";
  const variantClasses = {
    primary: "bg-qwen-orange text-white hover:bg-qwen-clay-orange",
    secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
    ghost: "hover:bg-gray-100"
  };
  const sizeClasses = {
    sm: "h-8 px-3 text-xs",
    md: "h-10 px-4 py-2 text-sm",
    lg: "h-12 px-6 text-base"
  };
  return (
    <button
      className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]}`}
    >
      {children}
    </button>
  );
 };
 ```
 ### 4.2 混合使用现有和新组件
 ```tsx
 // 在页面中混合使用
 import { PermissionDrawer } from './PermissionDrawer'; // 现有组件
 import { Button } from './ui/Button'; // 新的Tailwind组件
 export const MyPage: React.FC = () => {
  return (
    <div>
      <PermissionDrawer /> {/* 现有组件 */}
      <Button variant="primary">New Tailwind Button</Button> {/* 新组件 */}
    </div>
  );
 };
 ```
 ## 5. 注意事项
 ### 5.1 主题兼容性
 确保Tailwind的颜色、间距、圆角等与现有设计系统保持一致。
 ### 5.2 构建性能
 配置Tailwind的内容扫描路径以避免不必要的CSS生成。
 ### 5.3 团队培训
 为团队成员提供Tailwind CSS培训，确保大家理解并能正确使用。
 ## 6. 下一步计划
 1. 在新功能开发中优先使用Tailwind组件
 2. 逐步重构现有组件
 3. 建立完整的基于Tailwind的组件库
 4. 完善文档和团队规范
--- a/packages/vscode-ide-companion/TAILWIND_INTEGRATION_PLAN.md
+++ b/packages/vscode-ide-companion/TAILWIND_INTEGRATION_PLAN.md
@@ -0,0 +1,105 @@
 # Tailwind CSS 渐进式集成计划
 ## 1. 当前状态分析
 ### 已完成的配置
 - [x] Tailwind CSS 已添加到项目依赖
 - [x] `tailwind.config.js` 配置文件已创建
 - [x] `postcss.config.js` 配置文件已创建
 - [x] `src/styles.css` 已创建并包含Tailwind指令
 ### 现有样式系统
 - SCSS/Sass 预处理器
 - CSS Modules 组件样式
 - 传统CSS文件
 - 从Claude Code提取的样式
 ## 2. 渐进式集成策略
 ### 阶段1：基础配置和工具类实现
 - 创建可复用的Tailwind工具类集合
 - 建立设计系统变量映射
 - 配置Tailwind主题以匹配现有设计
 ### 阶段2：组件样式重构
 - 选择性地重构部分组件以使用Tailwind
 - 保持向后兼容性
 - 逐步替换现有CSS类
 ### 阶段3：全面集成
 - 将Tailwind应用到所有组件
 - 移除冗余的CSS代码
 - 优化构建配置
 ## 3. 设计系统映射
 ### 颜色映射
 | 现有变量 | Tailwind 类 | 说明 |
 |---------|------------|------|
 | `--app-qwen-orange` | `text-indigo-500`, `bg-indigo-500` | 主要品牌色 |
 | `--app-primary-foreground` | `text-gray-900`, `text-white` | 主要前景色 |
 | `--app-secondary-foreground` | `text-gray-500`, `text-gray-400` | 次要前景色 |
 | `--app-primary-background` | `bg-gray-50`, `bg-gray-900` | 主要背景色 |
 | `--app-input-background` | `bg-white`, `bg-gray-800` | 输入框背景色 |
 ### 间距映射
 | 现有变量 | Tailwind 类 | 说明 |
 |---------|------------|------|
 | `--app-spacing-small` (4px) | `p-1`, `m-1` | 小间距 |
 | `--app-spacing-medium` (8px) | `p-2`, `m-2` | 中等间距 |
 | `--app-spacing-large` (12px) | `p-3`, `m-3` | 大间距 |
 | `--app-spacing-xlarge` (16px) | `p-4`, `m-4` | 超大间距 |
 ### 圆角映射
 | 现有变量 | Tailwind 类 | 说明 |
 |---------|------------|------|
 | `--corner-radius-small` (4px) | `rounded` | 小圆角 |
 | `--corner-radius-medium` (6px) | `rounded-md` | 中等圆角 |
 | `--corner-radius-large` (8px) | `rounded-lg` | 大圆角 |
 ## 4. 实施步骤
 ### 第一步：更新Tailwind配置
 ```js
 // tailwind.config.js
 module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        'qwen': {
          'orange': '#615fff',
          'clay-orange': '#4f46e5',
          'ivory': '#f5f5ff',
          'slate': '#141420',
          'green': '#6bcf7f',
        }
      },
      borderRadius: {
        'small': '4px',
        'medium': '6px',
        'large': '8px',
      }
    },
  },
  plugins: [],
 }
 ```
 ### 第二步：创建可复用组件类
 创建 `src/lib/tailwindUtils.js` 文件，导出常用的Tailwind类组合。
 ### 第三步：逐步重构组件
 选择几个关键组件开始重构，例如：
 1. `PermissionDrawer` 组件
 2. `SaveSessionDialog` 组件
 3. 输入框组件
 ## 5. 注意事项
 1. **向后兼容性**：确保现有样式在重构过程中不受影响
 2. **性能优化**：配置Tailwind的内容扫描路径以避免不必要的CSS生成
 3. **团队协作**：建立Tailwind使用规范和最佳实践
 4. **测试验证**：在不同主题（深色/浅色）下验证样式效果
--- a/packages/vscode-ide-companion/TAILWIND_PROGRESSIVE_INTEGRATION_GUIDE.md
+++ b/packages/vscode-ide-companion/TAILWIND_PROGRESSIVE_INTEGRATION_GUIDE.md
@@ -0,0 +1,177 @@
 # 渐进式Tailwind CSS集成指南
 ## 1. 集成策略
 我们采用渐进式的方式将Tailwind CSS集成到现有项目中，确保不影响现有功能：
 1. **保持现有样式**：不修改现有的CSS文件和类名
 2. **并行使用**：在新组件或组件重构时使用Tailwind
 3. **逐步替换**：随着时间推移，逐步将现有CSS替换为Tailwind类
 ## 2. 实施步骤
 ### 步骤1：创建混合样式组件
 我们可以创建同时使用传统CSS和Tailwind的组件：
 ```tsx
 // 示例：在现有组件中添加Tailwind类
 import './PermissionDrawer.css'; // 保留现有样式
 export const PermissionDrawer: React.FC<PermissionDrawerProps> = ({ ... }) => {
  return (
    <div className="permission-drawer rounded-lg shadow-lg"> {/* 混合使用 */}
      {/* 现有内容 */}
    </div>
  );
 };
 ```
 ### 步骤2：创建Tailwind增强版本
 为现有组件创建Tailwind增强版本，供新功能使用：
 ```tsx
 // PermissionDrawer.tailwind.tsx
 export const PermissionDrawerTailwind: React.FC<PermissionDrawerProps> = ({ ... }) => {
  return (
    <div className="fixed inset-0 flex items-end justify-center">
      <div className="bg-white rounded-t-xl shadow-2xl w-full max-w-md">
        {/* 使用纯Tailwind样式 */}
      </div>
    </div>
  );
 };
 ```
 ### 步骤3：创建可复用的Tailwind组件
 创建新的小组件，专门使用Tailwind样式：
 ```tsx
 // components/ui/Button.tsx
 interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
 }
 export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  children
 }) => {
  const baseClasses = "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
  const variantClasses = {
    primary: "bg-qwen-orange text-white hover:bg-qwen-clay-orange",
    secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
    ghost: "hover:bg-gray-100"
  };
  const sizeClasses = {
    sm: "h-8 px-3 text-xs",
    md: "h-10 px-4 py-2 text-sm",
    lg: "h-12 px-6 text-base"
  };
  return (
    <button
      className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]}`}
    >
      {children}
    </button>
  );
 };
 ```
 ## 3. 最佳实践
 ### 保持向后兼容性
 - 不要删除现有的CSS文件
 - 逐步替换，而不是一次性重构
 - 在团队中建立清晰的规范
 ### 性能优化
 ```js
 // tailwind.config.js - 优化内容扫描
 module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}", // 只扫描实际使用的文件
  ],
  // ...
 };
 ```
 ### 设计系统一致性
 ```js
 // tailwind.config.js - 扩展主题以匹配现有设计
 module.exports = {
  theme: {
    extend: {
      colors: {
        'qwen': {
          'orange': '#615fff',
          // ... 其他品牌色
        }
      },
      borderRadius: {
        'small': '4px',
        'medium': '6px',
        'large': '8px',
      }
    },
  },
 };
 ```
 ## 4. 示例：逐步重构PermissionDrawer
 ### 当前状态（保留现有样式）
 ```tsx
 // PermissionDrawer.tsx
 import './PermissionDrawer.css'; // 保留现有样式
 export const PermissionDrawer = ({ ... }) => {
  return (
    <div className="permission-drawer">
      {/* 使用现有CSS类 */}
    </div>
  );
 };
 ```
 ### 增强版本（添加Tailwind辅助类）
 ```tsx
 // PermissionDrawer.tsx
 import './PermissionDrawer.css'; // 保留现有样式
 export const PermissionDrawer = ({ ... }) => {
  return (
    <div className="permission-drawer flex flex-col"> {/* 添加Tailwind类作为补充 */}
      {/* 使用现有CSS类 */}
    </div>
  );
 };
 ```
 ### 完全Tailwind版本（可选的未来状态）
 ```tsx
 // PermissionDrawer.tailwind.tsx
 export const PermissionDrawerTailwind = ({ ... }) => {
  return (
    <div className="fixed inset-0 flex items-end justify-center">
      <div className="bg-white rounded-t-xl shadow-2xl w-full max-w-md flex flex-col">
        {/* 完全使用Tailwind类 */}
      </div>
    </div>
  );
 };
 ```
 ## 5. 团队协作建议
 1. **文档化**：维护一个Tailwind使用指南
 2. **代码审查**：在代码审查中检查Tailwind使用是否合理
 3. **组件库**：逐步建立基于Tailwind的组件库
 4. **培训**：为团队成员提供Tailwind培训