RoninForge/roninforge-tailwind-v4
GitHub: RoninForge/roninforge-tailwind-v4
Cursor 插件，解决 Tailwind CSS v4 迁移中的 AI 幻觉与版本混淆问题。
Stars: 0 | Forks: 0
# roninforge-tailwind-v4
[](https://github.com/RoninForge/roninforge-tailwind-v4/actions/workflows/validate.yml)
[](https://opensource.org/licenses/MIT)
[](https://github.com/RoninForge/roninforge-tailwind-v4/releases)
Cursor 插件用于 Tailwind CSS v4。防止 v3 幻觉，提供经过验证的 v4 模式、迁移技能和反模式检测。
## 问题
Tailwind CSS v4 带来了与 v3 的破坏性变更。LLM 默认生成 v3 语法，因为它们的训练数据早于 v4。导致结果是：已弃用的代码无法正常工作。
本插件防止以下常见的 AI 错误：
- 在 v4 项目中创建 `tailwind.config.js`（现在 CSS 优先）
- 使用 `@tailwind base; @tailwind components; @tailwind utilities;`（已被 `@import "tailwindcss"` 取代）
- 生成 `bg-opacity-50`（已移除，使用 `bg-red-500/50`）
- 使用 `shadow-sm`（在 v4 中重命名为 `shadow-xs`）
- 在类名前添加 `!`（在 v4 中移动到类名末尾）
- 向 PostCSS 配置添加 `autoprefixer`（v4 中已内置）
## 安装
克隆仓库并将规则/技能文件复制到项目中：
```
git clone https://github.com/RoninForge/roninforge-tailwind-v4.git
cp -r roninforge-tailwind-v4/rules/* your-project/.cursor/rules/
cp -r roninforge-tailwind-v4/skills/* your-project/.cursor/skills/
cp -r roninforge-tailwind-v4/agents/* your-project/.cursor/agents/
```
或者作为本地插件安装（Cursor 会自动从此目录加载插件）：
```
git clone https://github.com/RoninForge/roninforge-tailwind-v4.git ~/.cursor/plugins/local/roninforge-tailwind-v4
```
当在 Cursor 市场可用时，可直接从市场 UI 在 Cursor 中安装。
## 包含内容
### 规则（5 个文件，自动附加）
| 规则 | 作用域 | 功能 |
|------|-------|------|
| `tailwind-v4-core` | 始终激活 | 核心 v4 语法：导入、配置、工具类重命名、不透明度修饰符 |
| `tailwind-v4-anti-patterns` | 始终激活 | 12 种常见 AI 错误及避免方法 |
| `tailwind-v4-config` | CSS/配置文件 | `@theme`、`@source`、构建工具配置、深色模式配置 |
| `tailwind-v4-utilities` | 模板文件 | 重命名的类、容器查询、渐变、新变体 |
| `tailwind-v4-migration` | 按需激活 | v3 到 v4 的逐步迁移流程 |
### 技能（3 个命令）
| 技能 | 命令 | 功能 |
|------|-------|------|
| 迁移 | `/tw-migrate` | 扫描 v3 项目，生成完整的迁移计划及精确的查找替换命令 |
| 组件 | `/tw-component` | 生成符合 v4 规范、可访问且支持深色模式的 UI 组件 |
| 验证 | `/tw-validate` | 审计项目是否存在 v3/v4 版本混用和已弃用模式 |
### 子代理（1 个）
| 代理 | 功能 |
|------|------|
| `tailwind-reviewer` | 审查代码变更中的 v3 模式、缺失的可访问性以及主题不一致问题 |
### 参考文档
捆绑的 v4 参考文档来源于官方 Tailwind CSS 升级指南和 v4 发布说明。提供真实数据，使 LLM 不依赖过时的训练数据。
## 与其他方案的区别
**与 `.cursorrules` 片段（danhollick, cursor.directory）相比：**
- 明确教授 LLM 不要做什么的反模式规则
- 面向实际工作流的技能（迁移、验证），而不仅是被动规则
- 捆绑参考文档供 LLM 验证
- 通过通配符自动附加（CSS 规则作用于 CSS 文件，工具类规则作用于模板文件）
- 用于自动代码审查的子代理
**与无插件相比：**
- 防止 12 种最严重的 Tailwind v4 AI 错误
- 迁移技能自动化 v3 到 v4 的升级流程
- 验证技能在发布前捕获版本混用
- 组件技能生成可访问且支持深色模式的 v4 组件
## 测试用例
`tests/` 目录包含用于测试的 v3 和 v4 示例项目：
- `tests/fixtures/v3-sample/` - 包含 v3 模式（配置、CSS、组件）的项目
- `tests/fixtures/v4-sample/` - 同一项目迁移到 v4 的版本
使用这些来验证迁移技能是否正常工作：
1. 在安装插件的 Cursor 中打开 `tests/fixtures/v3-sample/`
2. 运行 `/tw-migrate` 并将输出与 `tests/fixtures/v4-sample/` 进行比较
## 验证
运行插件验证脚本以检查结构和内容：
```
chmod +x tests/validation/validate-plugin.sh
./tests/validation/validate-plugin.sh
```
## 项目结构
```
roninforge-tailwind-v4/
.cursor-plugin/
plugin.json Plugin manifest
rules/
tailwind-v4-core.mdc Core v4 rules (always active)
tailwind-v4-anti-patterns.mdc Anti-pattern detection (always active)
tailwind-v4-config.mdc Config rules (CSS/config files)
tailwind-v4-utilities.mdc Utility rules (template files)
tailwind-v4-migration.mdc Migration rules (agent-requested)
skills/
tw-migrate/
SKILL.md v3-to-v4 migration assistant
references/
migration-checklist.md
tw-component/
SKILL.md v4 component generator
references/
component-patterns.md
tw-validate/
SKILL.md v3/v4 version mixing detector
agents/
tailwind-reviewer.md Code review subagent
docs/
tailwind-v4-reference.md Complete v4 reference
tests/
fixtures/
v3-sample/ Sample v3 project for testing
v4-sample/ Sample v4 project (migration target)
validation/
validate-plugin.sh Plugin structure validator
```
## 贡献
1. 叉取仓库
2. 创建变更分支
3. 提交前运行 `./tests/validation/validate-plugin.sh`
4. 提交拉取请求
所有规则内容必须对照官方 [Tailwind v4 升级指南](https://tailwindcss.com/docs/upgrade-guide) 进行验证。不要在未验证的情况下添加基于假设或 LLM 生成内容的模式。
## 准确性策略
本插件的每条规则和模式均来源于官方 Tailwind CSS 文档。如果发现不准确之处，请提交问题并提供指向官方文档的链接以说明正确行为。
## 许可证
MIT - 参见 [LICENSE](LICENSE)
## 链接
- [Tailwind CSS v4 升级指南](https://tailwindcss.com/docs/upgrade-guide)
- [Tailwind CSS v4 发布说明](https://tailwindcss.com/blog/tailwindcss-v4)
- [Cursor 插件文档](https://docs.cursor.com/plugins)
- [RoninForge](https://roninforge.org)
标签：AI 辅助, CSS, Cursor 插件, SEO, Tailwind CSS, v3 弃用, v4 迁移, 代码规范, 反模式检测, 数据可视化, 自动化安全运营, 迁移技能, 验证规则