diff --git a/packages/vscode-ide-companion/PROGRESSIVE_TAILWIND_ADOPTION.md b/packages/vscode-ide-companion/PROGRESSIVE_TAILWIND_ADOPTION.md new file mode 100644 index 00000000..8084f7e4 --- /dev/null +++ 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 = ({ ... }) => { + return ( + // 添加Tailwind类作为补充 +
+ {/* 现有内容保持不变 */} +
+ ); +}; +``` + +#### 2.4 创建增强版本 +为现有组件创建Tailwind增强版本,供新功能使用: + +```tsx +// PermissionDrawer.tailwind.tsx +export const PermissionDrawerTailwind: React.FC = ({ ... }) => { + return ( +
+
+ {/* 使用纯Tailwind样式 */} +
+
+ ); +}; +``` + +### 第三阶段:逐步迁移现有组件 + +#### 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 = ({ + 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 ( + + ); +}; +``` + +### 4.2 混合使用现有和新组件 +```tsx +// 在页面中混合使用 +import { PermissionDrawer } from './PermissionDrawer'; // 现有组件 +import { Button } from './ui/Button'; // 新的Tailwind组件 + +export const MyPage: React.FC = () => { + return ( +
+ {/* 现有组件 */} + {/* 新组件 */} +
+ ); +}; +``` + +## 5. 注意事项 + +### 5.1 主题兼容性 +确保Tailwind的颜色、间距、圆角等与现有设计系统保持一致。 + +### 5.2 构建性能 +配置Tailwind的内容扫描路径以避免不必要的CSS生成。 + +### 5.3 团队培训 +为团队成员提供Tailwind CSS培训,确保大家理解并能正确使用。 + +## 6. 下一步计划 + +1. 在新功能开发中优先使用Tailwind组件 +2. 逐步重构现有组件 +3. 建立完整的基于Tailwind的组件库 +4. 完善文档和团队规范 \ No newline at end of file diff --git a/packages/vscode-ide-companion/TAILWIND_INTEGRATION_PLAN.md b/packages/vscode-ide-companion/TAILWIND_INTEGRATION_PLAN.md new file mode 100644 index 00000000..94b34d53 --- /dev/null +++ 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. **测试验证**:在不同主题(深色/浅色)下验证样式效果 \ No newline at end of file diff --git a/packages/vscode-ide-companion/TAILWIND_PROGRESSIVE_INTEGRATION_GUIDE.md b/packages/vscode-ide-companion/TAILWIND_PROGRESSIVE_INTEGRATION_GUIDE.md new file mode 100644 index 00000000..2d1f756d --- /dev/null +++ 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 = ({ ... }) => { + return ( +
{/* 混合使用 */} + {/* 现有内容 */} +
+ ); +}; +``` + +### 步骤2:创建Tailwind增强版本 + +为现有组件创建Tailwind增强版本,供新功能使用: + +```tsx +// PermissionDrawer.tailwind.tsx +export const PermissionDrawerTailwind: React.FC = ({ ... }) => { + return ( +
+
+ {/* 使用纯Tailwind样式 */} +
+
+ ); +}; +``` + +### 步骤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 = ({ + 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 ( + + ); +}; +``` + +## 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 ( +
+ {/* 使用现有CSS类 */} +
+ ); +}; +``` + +### 增强版本(添加Tailwind辅助类) +```tsx +// PermissionDrawer.tsx +import './PermissionDrawer.css'; // 保留现有样式 + +export const PermissionDrawer = ({ ... }) => { + return ( +
{/* 添加Tailwind类作为补充 */} + {/* 使用现有CSS类 */} +
+ ); +}; +``` + +### 完全Tailwind版本(可选的未来状态) +```tsx +// PermissionDrawer.tailwind.tsx +export const PermissionDrawerTailwind = ({ ... }) => { + return ( +
+
+ {/* 完全使用Tailwind类 */} +
+
+ ); +}; +``` + +## 5. 团队协作建议 + +1. **文档化**:维护一个Tailwind使用指南 +2. **代码审查**:在代码审查中检查Tailwind使用是否合理 +3. **组件库**:逐步建立基于Tailwind的组件库 +4. **培训**:为团队成员提供Tailwind培训 \ No newline at end of file