ub-tailwind

UB Tailwind

概述

使用此技能，可在不同环境中保持 Tailwind 用法的时效性和正确性，并避免过时模式。此技能针对最新稳定版 Tailwind CSS：采用 CSS 优先设置，应用官方框架方案，并替换生成的指导内容中的旧版默认做法。

根据检测到的项目和工具实际情况实施，但在设置和迁移指导中，优先采用现代 CSS 优先的 Tailwind，而不是默认保留旧版配置习惯或兼容层。

按需加载参考资料

• 调整路由指导或跨技能编写规范时，阅读 ../ub-authoring/references/authoring-conventions.md。
• 阅读 references/tailwind-guardrails.md，了解严格的操作规则、弃用语法陷阱和审查清单。
• 阅读 references/framework-recipes.md，了解特定环境的设置路径（独立 HTML/CDN、Vue + Vite、Nuxt）。
• 阅读 references/tailwind-legacy-to-modern-migration.md，了解迁移对照表、升级替换方案和兼容性注意事项。

不适用场景

• 如果任务涉及纯 CSS 架构、选择器策略或不以 Tailwind 为主要样式层的令牌驱动样式，请勿使用此技能；当 Tailwind 与 CSS 架构有交集时，应同时加载或改用 ub-css。
• 如果主要问题是框架运行时行为，而非 Tailwind 集成或实用类编写，请勿使用此技能。

核心工作流

1. 编写任何 Tailwind 设置前，先识别目标环境。
2. 执行必要的检测：nuxt.config.*、vite.config.*、package.json 依赖、CSS 入口文件，以及 Nuxt 应用的样式表位置（对于现代 Nuxt，应为 app/assets/css/main.css）。
3. 从 references/framework-recipes.md 中选择匹配的方案。
4. 对于非简单或与版本相关的建议，比较官方指导、仓库实际情况和观察到的代码现状。
5. 如果权威来源、仓库实际情况或现有代码在重要的非简单建议上存在实质分歧，应标记 OFFICIAL_CONFLICT。
6. 如果针对某项重要主张进行了定向调研后，仍无法在官方来源中确认，应标记 UNVERIFIED。
7. 应用 references/tailwind-guardrails.md 中的现代 Tailwind CSS 优先规则。
8. 应用 references/tailwind-legacy-to-modern-migration.md 中适用于安全升级的替换方案。
9. 执行特定环境的验证清单。
10. 拒绝并替换已弃用或旧版语法。

环境选择

• 对于没有构建工具的纯 HTML 页面，使用 独立 HTML/CDN 方案。
• 对于使用 Vite 打包的 Vue 项目，使用 Vue + Vite 方案。
• 对于集成细节与纯 Vite 不同的 Nuxt 应用，使用 Nuxt 方案。
• 对于 Nuxt，默认采用官方设置路径（在 nuxt.config.* 中接入 @tailwindcss/vite），而非旧版模块默认配置。

如果环境不明确，先检查项目标记（package.json、框架配置、构建插件），不要猜测。

不可妥协的规则

Tailwind 版本和语法

• 使用现代 Tailwind CSS 优先模式和当前文档语义。
• 优先使用 CSS 入口语句 @import "tailwindcss"。
• 根据需要，优先使用 @theme、@utility、@variant、@custom-variant、@source 和 @reference 等 CSS 指令。
• 除非明确出于兼容性需要，否则将 @config 和 @plugin 视为旧版路径。
• 仅将兼容性作为有明确边界的层，并记录迁移回 CSS 优先默认设置的方案。

构建策略

• 不要假设现代 Tailwind 必须使用 PostCSS。
• 在适用时，对于 Vue + Vite 工作流使用 Vite 插件集成（@tailwindcss/vite）。
• 对于 Nuxt，遵循官方 Nuxt 框架指南流程，并在 Nuxt 配置中设置 Vite 插件；不要创建仅适用于 Vue 的 vite.config.* 指南。
• 保持设置精简，并符合环境惯例。

Vue/Nuxt 样式上下文

• 对于使用 @apply 或 @variant 的 Vue/Nuxt 组件作用域样式，请通过 @reference 引用主样式表或应用样式上下文。
• 避免仅为在组件本地样式中使用主题值而重复导入 CSS。

设计令牌

• 将 Tailwind 令牌集中在 @theme 中。
• 复用现有令牌基元，避免随意硬编码导致偏差。

不要生成

• 不要将 @tailwind base;、@tailwind components;、@tailwind utilities; 生成为默认的现代入口。
• 不要假设现代 Tailwind 必须配置 PostCSS。
• 对全新的 Nuxt 配置指南，不要默认将 @nuxtjs/tailwindcss 作为首选方案。

输出要求

生成或修改代码时，始终提供：

1. 简短的环境检测说明。
2. 来源依据说明：检测到的项目版本、环境标记，以及与最新稳定版指南之间的任何实质性差距。
3. 选定的配置路径（CDN、Vue + Vite 或 Nuxt）。
4. 已应用的确切弃用语法到现代写法替换（语法/工具链/实用工具变更）。
5. 用于确认 Tailwind 现代配置的快速验证清单。
6. 保留旧版指令（@config/@plugin）时的兼容性说明。
7. 相关时提供冲突说明：使用 OFFICIAL_CONFLICT 或 UNVERIFIED，并附上简要解释和实施影响。

版本与调研政策

• 以 Tailwind CSS 的最新稳定版为目标。
• 从 package.json 和锁文件中检测项目实际使用的 Tailwind 版本。
• 使用网络搜索对照 Tailwind CSS 官方文档，核实当前最佳实践、指令可用性和迁移指南。
• 决定当前项目实际可以安全采用的方案时，将仓库实际情况视为最佳实现标准。
• 对面向未来的设计和便于迁移的模式，将 Tailwind 官方文档作为首选指南基准。
• 如果官方指南与仓库实际情况在非琐碎建议上存在实质差异，请标明 OFFICIAL_CONFLICT，采用适合仓库的安全方案，并说明迁移路径。
• 如果官方来源对非琐碎建议存在分歧，也请标明 OFFICIAL_CONFLICT，不要默默消解分歧。
• 如果经过针对性调研后仍无法从官方来源确认某项非琐碎说法，请标记为 UNVERIFIED，或避免将其作为确定的指南呈现。
• 冲突和不确定性说明应仅针对非琐碎、与版本相关或存在争议的指南，而非琐碎修改。
• 如果项目安装的版本低于最新稳定版，请说明版本差距并建议升级路径。
• 如果存在 AGENTS.md 或同等说明，请检查宿主仓库中的相关文件，了解项目特定的版本政策和工具要求；不要假设其中包含此目录的默认设置。
• 生成的指南中不要硬编码版本号，让建议保持长期适用。

时效性审查

• 变化频率：高
• 审查建议：内容修改时审查，并在定期维护期间复核；条件允许时以每季度一次为目标。
• 触发信号：官方迁移指南变更、指令弃用、Tailwind 重大版本发布，或影响配置方案的仓库工具链变更。
• 执行方式：仅供参考；Tailwind 指南过时只是审查信号，本身不应成为阻断条件。
• 稳定核心：环境检测、官方方案选择和避免使用已弃用语法应保持实用，即使具体配置细节随时间演进也不例外。

完成检查清单

• 在开始设置前明确标识环境。
• Tailwind 入口文件和指令符合现代指南。
• 不保留已弃用或旧版语法，除非明确说明兼容性原因。
• 妥善处理框架特定差异（CDN 与 Vite、Nuxt）。
• Nuxt 指南使用官方框架路径，不偏离到仅适用于 Vue 的 vite.config.* 步骤。
• 统一并一致地使用 Token。
• 生成的指令简洁、确定，并面向当前版本。
• 相关时，明确披露与官方来源的重大冲突或未经验证的重要指南。