メニュー
帮助将项目样式迁移到 vanilla-extract (@vanilla-extract/css)。当需要在 Vite + React 项目中：添加 vanilla-extract、把 `.css`/`.scss`/行内样式迁移为 `*.css.ts`、建立 design tokens/sprinkles、或为样式添加测试与规范时使用。
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/ymsjl/page-scaffold-builder --skill vanilla-extractコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
SOC 職業分類に基づく
| 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）。
.css 文件自动生成 *.css.ts 模板（半自动、需人工补全）vanilla-extract。@vanilla-extract/vite-plugin 与测试支持。node .agents/skills/vanilla-extract/scripts/scan-styles.js --path apps/web/srcnode .agents/skills/vanilla-extract/scripts/generate-css-ts-templates.js path/to/file.cssreferences/migration-guidelines.md 的步骤逐步迁移并补全生成的 .css.ts 模板。.css / 行内样式 迁移为 *.css.ts（逐文件/批量迁移）。迁移内联样式时，需要识别样式类型并决定是否迁移：
这些内联样式应该提取到 .css.ts 文件：
静态样式常量
// ❌ 迁移前
: . = {
: ,
: ,
: ,
};
<div style={TOOLBAR_STYLE}>
// ✅ 迁移后
// styles.css.ts
export const toolbar = style({
position: 'fixed',
bottom: 72,
zIndex: 20,
});
// Component.tsx
<div className={styles.toolbar}>
重复的通用样式
// ❌ 迁移前
<Space direction="vertical" style={{ width: "100%" }}>
<AutoComplete style={{ width: "100%" }}>
<Flex style={{ width: "100%" }}>
// ✅ 迁移后 - 提取为共享类
export const fullWidth = style({ width: '100%' });
<Space className={styles.fullWidth}>
<AutoComplete className={styles.fullWidth}>
静态布局样式
// ❌ 迁移前
<div style={{ cursor: "grab", display: "flex", alignItems: "center" }}>
// ✅ 迁移后
export const dragHandle = style({
cursor: 'grab',
display: 'flex',
alignItems: 'center',
});
静态定位样式
// ❌ 迁移前
<Handle style={{ left: "30%" }} />
// ✅ 迁移后
export const handleTopLeft = style({ left: '30%' });
<Handle className={styles.handleTopLeft} />
这些内联样式应该保留，因为需要运行时计算：
基于 props/state 的动态值
// ✅ 保留 - 依赖运行时变量
<div style={{ paddingLeft: `${level * 8}px` }}>
<div style={{ borderColor: color }}>
<div style={{ background: enabled ? undefined : "#fafafa" }}>
第三方组件的 style props
// ✅ 保留 - 组件 API 要求
<ProCard bodyStyle={{ padding: '16px' }} />
<Modal overlayInnerStyle={{ borderRadius: 8 }} />
<ProFormText fieldProps={{ style: { width: "100%" } }} />
拖拽库的 transform 样式
// ✅ 保留 - 由库动态计算
const style = {
transform: CSS.Transform.toString(transform),
transition,
opacity: isDragging ? 0.5 : 1,
};
<div style={style}>
当多个相关组件共享样式时，创建统一的 .css.ts 文件：
// RuleBuilder.css.ts - 服务整个 RuleBuilder 生态
export const fullWidth = style({ width: '100%' });
export const deleteButton = style({
background: 'none',
border: 'none',
cursor: 'pointer',
});
export const canvasCard = style({ minHeight: 260 });
// 在 RuleBuilder.tsx、RuleCanvas.tsx、RuleItem.tsx 中共享使用
import * as styles from './RuleBuilder.css';
优先扩展现有 .css.ts 而不是创建新文件：
// EntityModelDesigner/styles.css.ts 已存在
export const setAsPkButton = style({ /* ... */ });
// 添加新样式到同一文件
export const actionsRow = style({ marginBottom: 12 });
export const fullWidth = style({ width: '100%' });
使用选择器实现悬停显示效果：
// ✅ 正确模式 - 在子元素中引用父元素
export const wrapper = style({ /* ... */ });
export const actions = style({
visibility: 'hidden',
selectors: {
[`${wrapper}:hover &`]: {
visibility: 'visible',
},
},
});
第三方组件或库的类名需要全局样式：
import { globalStyle } from '@vanilla-extract/css';
export const setAsPkButton = style({ visibility: 'hidden' });
// Ant Design 表格单元格悬停
globalStyle(`.ant-table-cell:hover .${setAsPkButton}`, {
visibility: 'visible',
});
扫描与分析
node .agents/skills/vanilla-extract/scripts/scan-styles.js
# 查看 .vanilla-extract-scan.json 了解剩余内联样式
读取并分类
style={ 使用创建或扩展 .css.ts
.css.ts 文件批量更新组件
// 使用 multi_replace_string_in_file 同时更新多个文件
// 1. 添加 import 语句
// 2. 替换 style= 为 className=
// 3. 移除样式常量定义
验证与测试
pnpm --filter ./apps/web test -- --run
| 原始内联样式 | 推荐类名 | vanilla-extract 定义 |
|---|---|---|
style={{ width: "100%" }} | className={styles.fullWidth} | width: '100%' |
style={{ marginBottom: 12 }} | className={styles.actionsRow} | marginBottom: 12 |
style={{ cursor: "pointer" }} | className={styles.clickable} | cursor: 'pointer' |
style={{ minHeight: 260 }} | className={styles.canvasCard} | minHeight: 260 |
style={{ borderRadius: 8, padding: 4 }} | className={styles.container} | { borderRadius: 8, padding: 4 } |
style={{ fontSize: 12, display: "block" }} | className={styles.message} | { fontSize: 12, display: 'block' } |
ComponentPreview.tsxTOOLBAR_STYLE、TOOLBAR_CONTAINER_STYLE 常量previewStyles.css.tsRuleBuilder.tsx、RuleCanvas.tsx、RuleItem.tsxRuleBuilder.css.ts 统一管理SchemaList.tsx完成迁移后，记录关键指标：
# 迁移前
cssFiles: 9, inlineStyleFiles: 25, cssImports: 9
# 迁移后
cssFiles: 0, inlineStyleFiles: 13, cssImports: 2
# 成果
- 所有外部 CSS 文件已迁移 ✅
- 静态内联样式减少 48% (25 → 13)
- 剩余主要为动态样式和第三方组件 props
优先扩展而非新建
.css.ts 时，扩展它而不是创建新文件语义化命名
toolbar、dragHandle、actionsRowmarginBottom12、width100共享通用样式
fullWidth、clickable渐进式迁移
使用批量操作
multi_replace_string_in_file 提高效率不要迁移动态样式
// ❌ 错误 - 这是动态样式，应保留内联
<div style={{ paddingLeft: `${level * 8}px` }}>
不要移除第三方组件的 style props
// ❌ 错误 - ProComponents 的 fieldProps 需要 style 对象
<ProFormText fieldProps={{ style: { width: "100%" } }} />
不要在 .css.ts 中使用运行时值
// ❌ 错误 - vanilla-extract 是构建时生成，无法访问运行时变量
export const dynamic = style({
color: props.color, // ❌ 不可用
});
不要过度拆分样式
// ❌ 过度拆分
export const mb2 = style({ marginBottom: 2 });
export const mb4 = style({ marginBottom: 4 });
export const mb8 = style({ marginBottom: 8 });
// ✅ 使用语义化名称或保留内联
export const cardGap = style({ marginBottom: 8 });
父悬停显示子元素：
export const wrapper = style({ position: 'relative' });
export const actions = style({
visibility: 'hidden',
selectors: {
[`${wrapper}:hover &`]: { visibility: 'visible' },
},
});
// 使用
<div className={wrapper}>
<div className={actions}>...</div>
</div>
全局第三方类名：
import { globalStyle } from '@vanilla-extract/css';
export const button = style({ visibility: 'hidden' });
globalStyle(`.ant-table-cell:hover .${button}`, {
visibility: 'visible',
});
问题：样式没有生效
vite.config.ts 是否正确配置 @vanilla-extract/vite-plugin.css.ts 文件在 Vite 处理范围内问题：选择器语法错误
// ❌ 错误
selectors: {
'&:hover ${other}': { ... } // vanilla-extract 不支持
}
// ✅ 正确
selectors: {
[`${parent}:hover &`]: { ... } // 在子元素中引用父元素
}
问题：类型错误
.css.ts 导出用作 React.CSSPropertiesclassName 使用避免过多的全局样式
globalStyle 会增加 CSS 体积复用 token
@/styles/tokens.css 导入设计 token按需导入
// ✅ 推荐 - 命名空间导入，tree-shaking 友好
import * as styles from './Component.css';
// ⚠️ 可用但不推荐 - 导入所有内容
import { style1, style2, style3 } from './Component.css';
发现内联样式 style={...}
↓
是否为静态值？
├─ 是 → 是否重复使用？
│ ├─ 是 → 提取为共享类 (fullWidth, clickable)
│ └─ 否 → 提取为组件专用类 (toolbar, header)
│
└─ 否 → 是否依赖运行时变量？
├─ 是 (props/state) → 保留内联 ✅
├─ 第三方组件 props → 保留内联 ✅
└─ 拖拽库 transform → 保留内联 ✅
# 扫描项目中的样式使用情况
node .agents/skills/vanilla-extract/scripts/scan-styles.js
# 查看扫描结果
cat .vanilla-extract-scan.json
# 运行测试验证迁移
pnpm --filter ./apps/web test -- --run
# 开发模式验证样式
pnpm --filter ./apps/web dev
创建新的组件样式文件：
// Component.css.ts
import { style } from '@vanilla-extract/css';
export const container = style({
// 样式定义
});
export const fullWidth = style({
width: '100%',
});
组件中使用：
// Component.tsx
import * as styles from './Component.css';
export const Component = () => (
<div className={styles.container}>
<div className={styles.fullWidth}>...</div>
</div>
);
扩展现有样式文件：
// 在已有的 styles.css.ts 末尾添加
export const newStyle = style({
// 新样式
});
每次迁移后检查：
project-root/
├── .vanilla-extract-scan.json # 扫描结果报告
├── .agents/skills/vanilla-extract/ # Skill 目录
│ ├── SKILL.md # 本文档
│ ├── references/ # 参考文档
│ └── scripts/ # 辅助脚本
└── apps/web/src/
├── styles/
│ └── tokens.css.ts # 设计 token
└── components/
└── YourComponent/
├── YourComponent.tsx # 组件文件
└── YourComponent.css.ts # 样式文件