SuperAPI AI 工具集

code-architecture-tailwind-v4-best-practices

前端与建站

查看项目

更新于 10-16 04:40

技能介绍

用途

该技能面向使用 Tailwind CSS v4 构建组件的开发者,核心目标是帮助选择组件样式模式,使样式保持局部、显式、可访问且易于修改。其基本原则是:优先使用 Tailwind 工具类,只有当变体数量足以证明抽象必要时才进行抽象。

主要能力

技能提供了一套决策规则与流程,用于在以下方案之间选择:

  • 纯工具类:适用于 1-2 个变体、结构简单、无需共享 API 的组件。
  • CVA(class-variance-authority):适用于 3 个及以上变体、需要类型安全 props 的按钮类组件。
  • tailwind-variants:适用于插槽(slots)、复合部件、响应式变体或复杂设计系统。
  • 自定义 @utility:仅用于罕见的项目专属工具类。
  • @apply:除非项目约定要求,否则避免用于组件样式。

同时给出组件层面的规则:保持基础布局类清晰;当状态影响样式时使用 data-* 属性表达状态;正确使用 disabled、aria-disabled、aria-busy;仅在确实需要扩展时接受 className;使用项目已有的辅助函数(通常是 cn)合并类名;不要用含义不清的辅助函数隐藏重要设计决策;同一组件族只保留一种样式方案;在交互元素上保持可访问性。

使用方式

技能建议按以下流程操作:

  1. 检查现有组件的样式模式。
  2. 统计变体与插槽数量。
  3. 选择工具类、CVA 或 tailwind-variants。
  4. 需要时通过 @theme 添加设计令牌。
  5. 用属性建模组件状态。
  6. 验证响应式行为与可访问性。

Tailwind v4 设置示例:

@import "tailwindcss";

@theme {
  --color-brand-primary: oklch(0.65 0.24 354.31);
  --font-sans: "Inter", sans-serif;
  --radius-button: 0.5rem;
}

输出格式建议为:

## Tailwind v4 Decision
- Approach: [utilities/CVA/tailwind-variants]
- Reason: [variant count, slots, or project pattern]
- Tokens: [added or none]
- Accessibility: [states and labels checked]
- Migration notes: [v3 changes or none]

适用场景

适用于构建 Tailwind 组件、按钮、卡片、变体、插槽、状态样式或设计令牌时;也适用于从 Tailwind v3 迁移到 v4 的项目,需要了解相关类名变更的情况。

限制与迁移说明

技能列出了 v3 到 v4 的部分变更:shadow-sm 变为 shadow-xs;rounded-sm 变为 rounded-xs;bg-opacity-50 变为 bg-black/50;bg-gradient-to-r 变为 bg-linear-to-r;border 现在使用 currentColor;ring 现在使用 currentColor,需显式指定 ring 宽度与颜色。

参考资料包括 Tailwind CSS v4 文档、CVA(class-variance-authority)、Tailwind Variants 与 shadcn/ui。关于该技能的具体安装命令、收费方式、支持平台等信息,资料中暂未提供。