vanilla-extract

name	vanilla-extract
description	帮助将项目样式迁移到 vanilla-extract (@vanilla-extract/css)。当需要在 Vite + React 项目中：添加 vanilla-extract、把 `.css`/`.scss`/行内样式迁移为 `*.css.ts`、建立 design tokens/sprinkles、或为样式添加测试与规范时使用。

概述

提供迁移策略、示例代码、以及可执行的辅助脚本，用于把现有 CSS（外部样式表、组件级样式、以及 React 行内样式）逐步转换为 vanilla-extract 的推荐模式（静态、零运行时、类型安全的 CSS-in-TS）。

包含内容（捆绑资源）

• references/vanilla-extract-usage.md — 快速使用与 API 摘要
• references/migration-guidelines.md — 分步迁移计划与最佳实践
• scripts/scan-styles.js — 扫描项目中需迁移的样式并生成报告
• scripts/generate-css-ts-templates.js — 从 .css 文件自动生成 *.css.ts 模板（半自动、需人工补全）

触发条件（何时使用本 Skill）

• 需要把整个仓库或某些组件从 CSS / 行内样式 迁移到 vanilla-extract。
• 需要一个可重复的迁移计划、检测/报告工具或示例转换。
• 需要在 Vite 项目中正确配置 @vanilla-extract/vite-plugin 与测试支持。

快速使用

1. 运行扫描： node .agents/skills/vanilla-extract/scripts/scan-styles.js --path apps/web/src
2. 生成模板（可选）： node .agents/skills/vanilla-extract/scripts/generate-css-ts-templates.js path/to/file.css
3. 按 references/migration-guidelines.md 的步骤逐步迁移并补全生成的 .css.ts 模板。

要我做的事情（示例）

• 全仓库扫描并输出迁移优先级报告（自动）。
• 把指定的组件或文件从 .css / 行内样式 迁移为 *.css.ts（逐文件/批量迁移）。
• 添加 tokens / sprinkles 目录并重构共享样式。

内联样式迁移指南

样式分类与迁移决策

迁移内联样式时，需要识别样式类型并决定是否迁移：

✅ 应该迁移（静态样式）

这些内联样式应该提取到 .css.ts 文件：

1. 静态样式常量

   // ❌ 迁移前
    : . = {
     : ,
     : ,
     : ,
   };
   <div style={TOOLBAR_STYLE}>
   
   // ✅ 迁移后
   // styles.css.ts
   export const toolbar = style({
     position: 'fixed',
     bottom: 72,
     zIndex: 20,
   });
   // Component.tsx
   <div className={styles.toolbar}>