在团队开发中使用 Tailwind CSS，需要建立统一的开发规范和工作流程，以确保代码质量和开发效率。本节将详细介绍团队协作中的各项规范和最佳实践。
开发规范
命名规范
// 组件命名规范
const Button: React.FC = () => {
return (
<button className={[
// 功能性类名放在前面
'inline-flex items-center justify-center',
// 尺寸相关类名
'px-4 py-2 text-sm',
// 视觉样式类名
'bg-blue-500 text-white rounded-lg',
// 交互状态类名
'hover:bg-blue-600 focus:ring-2 focus:ring-blue-500',
// 响应式类名放在最后
'md:px-6 md:py-3 md:text-base'
].join(' ')}>
Button
</button>
);
};
类名组织规则
// utils/classNames.ts
export const classNames = {
layout: {
container: 'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8',
section: 'py-12 md:py-16 lg:py-20',
grid: 'grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3'
},
typography: {
h1: 'text-4xl font-bold tracking-tight sm:text-5xl md:text-6xl',
h2: 'text-3xl font-bold tracking-tight sm:text-4xl',
h3: 'text-2xl font-bold tracking-tight sm:text-3xl',
body: 'text-base text-gray-500 sm:text-lg'
},
components: {
button: {
base: 'inline-flex items-center justify-center rounded-md font-medium',
primary: 'bg-blue-500 text-white hover:bg-blue-600',
secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200'
}
}
};
文档规范
组件文档模板
# 组件名称
## 描述
简要描述组件的功能和用途。
## 使用示例
import { Component } from '@/components';
<Component variant="primary" size="lg">
示例内容
</Component>
## Props
| 属性名 | 类型 | 默认值 | 说明 |
|---------|---------|----------|----------|
| variant | string | 'primary'| 组件变体 |
| size | string | 'md' | 组件大小 |
## 样式定制
描述如何自定义组件样式：
// 自定义样式示例
<Component className="custom-styles">
内容
</Component>
## 注意事项
列出使用时需要注意的问题和限制。
### 样式指南
// styles/guide.ts
export const styleGuide = {
// 颜色系统
colors: {
primary: {
light: 'text-blue-400 bg-blue-50',
default: 'text-blue-500 bg-blue-100',
dark: 'text-blue-600 bg-blue-200'
}
},
// 间距系统
spacing: {
small: 'p-2 m-2',
medium: 'p-4 m-4',
large: 'p-6 m-6'
},
// 响应式断点
breakpoints: {
sm: 'sm:container sm:mx-auto',
md: 'md:container md:mx-auto',
lg: 'lg:container lg:mx-auto'
}
};
代码审查规范
审查清单
// scripts/review-checklist.ts
export const reviewChecklist = {
styling: [
{
title: '类名组织',
checks: [
'类名是否按照功能分组',
'是否遵循项目命名规范',
'是否避免重复样式'
]
},
{
title: '响应式设计',
checks: [
'是否采用移动优先策略',
'断点使用是否合理',
'是否处理了各种屏幕尺寸'
]
},
{
title: '性能优化',
checks: [
'是否避免了不必要的嵌套',
'是否合理使用了@apply',
'是否优化了选择器性能'
]
}
]
};
Git 提交规范
# .gitmessage
# 提交信息格式：
# <type>(<scope>): <subject>
#
# type 类型:
# feat: 新功能
# fix: 修复
# style: 样式调整
# refactor: 重构
# docs: 文档
# test: 测试
# chore: 构建/工具链/辅助工具的变动
#
# scope 范围:
# component: 组件相关
# style: 样式相关
# deps: 依赖相关
# config: 配置相关
#
# subject 描述:
# 简短描述，不超过50个字符
# 以动词开头，使用现在时
# 第一个字母小写
# 结尾不加句号
# 示例:
# feat(component): add new Button variants
# style(layout): update container padding
# fix(style): resolve conflicting utility classes
工作流程规范
开发流程
分支管理
# 分支命名规范
feature/component-name # 新功能分支
bugfix/issue-number # 问题修复分支
style/update-name # 样式调整分支
docs/update-name # 文档更新分支
自动化工具
ESLint 配置
// .eslintrc.js
module.exports = {
extends: [
'next',
'plugin:tailwindcss/recommended'
],
plugins: [
'tailwindcss'
],
rules: {
'tailwindcss/classnames-order': 'warn',
'tailwindcss/no-custom-classname': 'warn',
'tailwindcss/no-contradicting-classname': 'error'
}
};
Prettier 配置
// .prettierrc.js
module.exports = {
tailwindConfig: './tailwind.config.js',
plugins: [require('prettier-plugin-tailwindcss')],
tailwindFunctions: ['clsx', 'cn'],
semi: true,
singleQuote: true,
tabWidth: 2,
trailingComma: 'es5'
};
质量控制
测试规范
// components/__tests__/Button.test.tsx
import { render, screen } from '@testing-library/react';
import { Button } from '../Button';
describe('Button 组件', () => {
it('应用正确的基础样式', () => {
render(<Button>测试按钮</Button>);
const button = screen.getByRole('button');
expect(button).toHaveClass(
'inline-flex',
'items-center',
'justify-center'
);
});
it('根据变体应用正确的样式', () => {
render(<Button variant="primary">主要按钮</Button>);
const button = screen.getByRole('button');
expect(button).toHaveClass('bg-blue-500', 'text-white');
});
});
性能监控
// utils/performance.ts
export const measureStylePerformance = () => {
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (entry.entryType === 'layout-shift') {
console.log(`Layout shift: ${entry.value}`);
}
}
});
observer.observe({ entryTypes: ['layout-shift'] });
};
最佳实践
-
开发规范
- 统一的命名约定
- 清晰的文件组织
- 一致的代码风格
-
文档管理
- 详细的组件文档
- 完整的样式指南
- 规范的注释要求
-
代码审查
- 明确的审查流程
- 统一的提交规范
- 自动化工具支持
-
团队协作
- 标准的工作流程
- 有效的分支管理
- 及时的沟通反馈
-
质量保证
- 完整的测试覆盖
- 持续的性能监控
- 定期的代码重构
