---
description: 前端应用的 Tailwind CSS 和 UI 组件最佳实践
---

# Tailwind CSS 最佳实践

## 组件样式
- 使用工具类而非自定义 CSS
- 需要时使用 @apply 将相关工具类分组
- 仅在必要时使用自定义组件样式作为 SCSS 模块，以提高组件的可读性和可维护性
- 使用适当的响应式设计工具类
- 使用适当的状态变体
- 保持组件样式一致

## 设计令牌（Tokens）
- 所有来自 Figma 的令牌都是程序化生成的，定义在 `web/libs/ui/src/tokens/tokens.scss` 文件中
- 可以通过使用 `Figma Variable Exporter` 插件从 Figma 导出，替换 `web/design-tokens.json` 的内容，然后使用 `cd web/ && yarn design-tokens` 命令重新生成令牌
- 重新生成令牌时，确保运行项目根目录的 `make fmt-all` 命令，以确保所有文件都经过检查和格式化
- 不要使用未通过 Figma Variable Exporter 插件定义并在 `web/libs/ui/src/tokens/tokens.scss` 文件中建立的令牌
- 不要使用任何默认的 tailwind css 类，只使用通过 `web/libs/ui/src/tokens/tokens.js` 文件定义的类

## 布局
- 使用语义化间距工具类，例如 `p-tight` 而非 `p-200` 或 `--spacing-tight` 而非 `--spacing-200`
- 有效使用 Flexbox 和 Grid 工具类
- 需要时使用容器查询
- 实现适当的响应式断点
- 使用适当的 padding 和 margin 工具类
- 实现适当的对齐工具类

## 排版
- 使用语义化排版工具类，例如 `text-body-medium` 而非 `text-16` 或 `--font-size-body-medium` 而非 `--font-size-16`
- 使用适当的字体大小工具类
- 实现适当的行高
- 使用适当的字重工具类
- 正确配置自定义字体
- 使用适当的文本对齐
- 实现适当的文本装饰

## 颜色
- 仅使用语义化颜色命名，确保深色模式兼容性，例如 `bg-primary-background` 而非 `bg-grape-000` 或 `--color-primary-background` 而非 `--color-grape-000`
- 实现适当的颜色对比度
- 有效使用不透明度工具类
- 正确配置自定义颜色
- 使用适当的渐变工具类
- 实现适当的悬停状态

## UI 组件
- 从 `web/libs/ui/src/shad` 使用可用的 shadcn/ui 组件
- 仅使用从 `web/libs/ui` 重新导出的 shadcn/ui 组件，而非 `web/libs/ui/src/shad` 中定义的原始组件
- 在其他 libs 和 apps 中导入这些组件时应使用 `@humansignal/ui`
- 正确组合组件
- 保持组件变体一致
- 实现适当的动画
- 使用适当的过渡工具类
- 牢记无障碍性
- UI 组件应在 `web/libs/ui` 中定义和导出，并遵循代码组织的最佳实践

## 响应式设计
- 使用移动优先方法
- 实现适当的断点
- 有效使用容器查询
- 正确处理不同屏幕尺寸
- 实现适当的响应式排版
- 使用适当的响应式间距

## 性能优化
- 使用适当的清除配置
- 最小化自定义 CSS
- 使用适当的缓存策略
- 实现适当的代码分割
- 为生产环境优化
- 监控打包大小

## 样式组织
- 按逻辑顺序排列工具类（布局 → 间距 → 排版 → 颜色 → 其他）
- 使用一致的类名顺序
- 将复杂的样式组合提取为组件
- 使用 @layer 指令组织自定义样式

## 无障碍性
- 确保足够的颜色对比度
- 使用语义化 HTML 元素
- 实现键盘导航支持
- 添加适当的 ARIA 属性
- 测试屏幕阅读器兼容性

## 最佳实践
- 遵循命名约定
- 保持样式有序
- 使用适当的文档
- 实现适当的测试
- 遵循无障碍性指南
- 使用适当的版本控制
- 避免内联样式，优先使用工具类
- 保持样式的可维护性和可读性