在团队开发中使用 Tailwind CSS，需要建立统一的开发规范和工作流程，以确保代码质量和开发效率。本节将详细介绍团队协作中的各项规范和最佳实践。

开发规范

命名规范

  1. // 组件命名规范
  2. const Button: React.FC = () => {
  3.   return (
  4.     <button className={[
  5.       // 功能性类名放在前面
  6.       'inline-flex items-center justify-center',
  7.       // 尺寸相关类名
  8.       'px-4 py-2 text-sm',
  9.       // 视觉样式类名
  10.       'bg-blue-500 text-white rounded-lg',
  11.       // 交互状态类名
  12.       'hover:bg-blue-600 focus:ring-2 focus:ring-blue-500',
  13.       // 响应式类名放在最后
  14.       'md:px-6 md:py-3 md:text-base'
  15.     ].join(' ')}>
  16.       Button
  17.     </button>
  18.   );
  19. };

类名组织规则

  1. // utils/classNames.ts
  2. export const classNames = {
  3.   layout: {
  4.     container: 'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8',
  5.     section: 'py-12 md:py-16 lg:py-20',
  6.     grid: 'grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3'
  7.   },
  9.   typography: {
  10.     h1: 'text-4xl font-bold tracking-tight sm:text-5xl md:text-6xl',
  11.     h2: 'text-3xl font-bold tracking-tight sm:text-4xl',
  12.     h3: 'text-2xl font-bold tracking-tight sm:text-3xl',
  13.     body: 'text-base text-gray-500 sm:text-lg'
  14.   },
  16.   components: {
  17.     button: {
  18.       base: 'inline-flex items-center justify-center rounded-md font-medium',
  19.       primary: 'bg-blue-500 text-white hover:bg-blue-600',
  20.       secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200'
  21.     }
  22.   }
  23. };

文档规范

组件文档模板

  1. # 组件名称
  3. ## 描述
  4. 简要描述组件的功能和用途。
  6. ## 使用示例
  8. import { Component } from '@/components';
  10. <Component variant="primary" size="lg">
  11.   示例内容
  12. </Component>
  14. ## Props
  15. | 属性名   | 类型    | 默认值   | 说明     |
  16. |---------|---------|----------|----------|
  17. | variant | string  | 'primary'| 组件变体  |
  18. | size    | string  | 'md'     | 组件大小  |
  20. ## 样式定制
  21. 描述如何自定义组件样式：
  23. // 自定义样式示例
  24. <Component className="custom-styles">
  25.   内容
  26. </Component>
  28. ## 注意事项
  29. 列出使用时需要注意的问题和限制。
  31. ### 样式指南
  33. // styles/guide.ts
  34. export const styleGuide = {
  35.   // 颜色系统
  36.   colors: {
  37.     primary: {
  38.       light: 'text-blue-400 bg-blue-50',
  39.       default: 'text-blue-500 bg-blue-100',
  40.       dark: 'text-blue-600 bg-blue-200'
  41.     }
  42.   },
  44.   // 间距系统
  45.   spacing: {
  46.     small: 'p-2 m-2',
  47.     medium: 'p-4 m-4',
  48.     large: 'p-6 m-6'
  49.   },
  51.   // 响应式断点
  52.   breakpoints: {
  53.     sm: 'sm:container sm:mx-auto',
  54.     md: 'md:container md:mx-auto',
  55.     lg: 'lg:container lg:mx-auto'
  56.   }
  57. };

代码审查规范

审查清单

  1. // scripts/review-checklist.ts
  2. export const reviewChecklist = {
  3.   styling: [
  4.     {
  5.       title: '类名组织',
  6.       checks: [
  7.         '类名是否按照功能分组',
  8.         '是否遵循项目命名规范',
  9.         '是否避免重复样式'
  10.       ]
  11.     },
  12.     {
  13.       title: '响应式设计',
  14.       checks: [
  15.         '是否采用移动优先策略',
  16.         '断点使用是否合理',
  17.         '是否处理了各种屏幕尺寸'
  18.       ]
  19.     },
  20.     {
  21.       title: '性能优化',
  22.       checks: [
  23.         '是否避免了不必要的嵌套',
  24.         '是否合理使用了@apply',
  25.         '是否优化了选择器性能'
  26.       ]
  27.     }
  28.   ]
  29. };

Git 提交规范

  1. # .gitmessage
  2. # 提交信息格式：
  3. # <type>(<scope>): <subject>
  4. #
  5. # type 类型:
  6. #   feat:     新功能
  7. #   fix:      修复
  8. #   style:    样式调整
  9. #   refactor: 重构
  10. #   docs:     文档
  11. #   test:     测试
  12. #   chore:    构建/工具链/辅助工具的变动
  13. #
  14. # scope 范围:
  15. #   component: 组件相关
  16. #   style:    样式相关
  17. #   deps:     依赖相关
  18. #   config:   配置相关
  19. #
  20. # subject 描述:
  21. #   简短描述，不超过50个字符
  22. #   以动词开头，使用现在时
  23. #   第一个字母小写
  24. #   结尾不加句号
  26. # 示例:
  27. # feat(component): add new Button variants
  28. # style(layout): update container padding
  29. # fix(style): resolve conflicting utility classes

工作流程规范

开发流程

  1. graph LR
  2.     A[需求分析] --> B[样式设计]
  3.     B --> C[组件开发]
  4.     C --> D[代码审查]
  5.     D --> E[测试]
  6.     E --> F[合并]
  7.     F --> G[部署]

分支管理

  1. # 分支命名规范
  2. feature/component-name    # 新功能分支
  3. bugfix/issue-number      # 问题修复分支
  4. style/update-name        # 样式调整分支
  5. docs/update-name         # 文档更新分支

自动化工具

ESLint 配置

  1. // .eslintrc.js
  2. module.exports = {
  3.   extends: [
  4.     'next',
  5.     'plugin:tailwindcss/recommended'
  6.   ],
  7.   plugins: [
  8.     'tailwindcss'
  9.   ],
  10.   rules: {
  11.     'tailwindcss/classnames-order': 'warn',
  12.     'tailwindcss/no-custom-classname': 'warn',
  13.     'tailwindcss/no-contradicting-classname': 'error'
  14.   }
  15. };

Prettier 配置

  1. // .prettierrc.js
  2. module.exports = {
  3.   tailwindConfig: './tailwind.config.js',
  4.   plugins: [require('prettier-plugin-tailwindcss')],
  5.   tailwindFunctions: ['clsx', 'cn'],
  6.   semi: true,
  7.   singleQuote: true,
  8.   tabWidth: 2,
  9.   trailingComma: 'es5'
  10. };

质量控制

测试规范

  1. // components/__tests__/Button.test.tsx
  2. import { render, screen } from '@testing-library/react';
  3. import { Button } from '../Button';
  5. describe('Button 组件', () => {
  6.   it('应用正确的基础样式', () => {
  7.     render(<Button>测试按钮</Button>);
  8.     const button = screen.getByRole('button');
  10.     expect(button).toHaveClass(
  11.       'inline-flex',
  12.       'items-center',
  13.       'justify-center'
  14.     );
  15.   });
  17.   it('根据变体应用正确的样式', () => {
  18.     render(<Button variant="primary">主要按钮</Button>);
  19.     const button = screen.getByRole('button');
  21.     expect(button).toHaveClass('bg-blue-500', 'text-white');
  22.   });
  23. });

性能监控

  1. // utils/performance.ts
  2. export const measureStylePerformance = () => {
  3.   const observer = new PerformanceObserver((list) => {
  4.     for (const entry of list.getEntries()) {
  5.       if (entry.entryType === 'layout-shift') {
  6.         console.log(`Layout shift: ${entry.value}`);
  7.       }
  8.     }
  9.   });
  11.   observer.observe({ entryTypes: ['layout-shift'] });
  12. };

最佳实践

  1. 开发规范

    • 统一的命名约定
    • 清晰的文件组织
    • 一致的代码风格

  2. 文档管理

    • 详细的组件文档
    • 完整的样式指南
    • 规范的注释要求

  3. 代码审查

    • 明确的审查流程
    • 统一的提交规范
    • 自动化工具支持

  4. 团队协作

    • 标准的工作流程
    • 有效的分支管理
    • 及时的沟通反馈

  5. 质量保证

    • 完整的测试覆盖
    • 持续的性能监控
    • 定期的代码重构