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 属性
测试屏幕阅读器兼容性

最佳实践

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