在真实项目中，前端开发者常常需要构建可复用的UI组件库。CodeBuddy的样式组件正是基于React与Tailwind CSS打造的一种轻量级封装模式，其设计理念非常直观：复用性、可配置性、易维护性。虽然团队并不强制规定目录结构或API风格，但经过大量实践，目前已经沉淀出一套被广泛认可的编写规范。接下来将详细说明一个合格样式组件的组织方式。
组件结构要清晰：逻辑、样式、导出三分离
每个样式组件推荐使用独立的文件来承载，例如 Button.tsx。内部结构建议按照以下顺序组织：
- 顶部导入（React、自定义hooks、工具函数）
- 类型定义（Props接口，包含必填字段与可选字段，默认值通过Partial或解构赋值设定）
- 主组件函数（仅负责纯渲染，不包含副作用逻辑）
- 样式类名集中管理（使用clsx或模板字符串拼接，避免内联 style）
- 默认导出组件，可选导出类型或常量（如buttonVariants）
来看一个具体的代码示例：
const Button = ({ size = 'md', variant = 'primary', className, ...props }: ButtonProps) => {const baseClasses = 'inline-flex items-center justify-center font-medium rounded focus:outline-none transition-colors';
const sizeClasses = { sm: 'px-2 py-1 text-sm', md: 'px-4 py-2', lg: 'px-6 py-3 text-lg' };
const variantClasses = { primary: 'bg-blue-600 hover:bg-blue-700 text-white', ghost: 'bg-transparent hover:bg-gray-100 text-gray-800' };
return ;
};
支持主题与定制：用props控制，避免全局CSS变量硬编码
CodeBuddy的一项核心原则是：通过属性（props）来控制样式，而不是依赖全局配置或CSS自定义属性注入。这具体意味着以下几点：
- 颜色、尺寸、圆角等视觉变量，都应该映射为组件的 props，例如 color、radius
- 如需适配深色模式，优先使用 data-theme 属性配合 Tailwind 的 dark: 前缀来实现，而不是通过 JavaScript 动态切换 className
- 不建议在组件内部读取 useTheme() —— 这样会增加耦合度，也违背了“样式组件应保持无状态”的基本设计原则
以下是一个支持暗色模式的 Badge 示例：
提供组合能力：通过子组件或render props实现灵活嵌套
对于复杂样式组件（如 Card、Dropdown、Form），需要支持结构上的扩展。具体实现通常有两种推荐方式：
- 使用命名子组件：例如 Card.Header、Card.Body，内部通过 React.Children.map 匹配并包裹对应内容
- 使用 render prop 或 slot 属性：例如 Dialog trigger={} children={
内容
}
关键原则是：子组件本身不负责样式，只做语义层面的包装；所有样式仍然由父组件统一控制，这样才能保证视觉风格的一致性。
文档与类型即契约：每个组件必须附带JSDoc与类型定义
这一点必须强调：在CodeBuddy中，样式组件被视为“接口”来使用，因此文档绝不是可有可无的选项，而是必不可少的部分。
- 每个 props 字段都需要添加 JSDoc 注释，明确说明其用途、可选值及默认值
- 对于复杂行为（例如“点击后禁用500ms”），必须写入注释中，不能仅靠代码隐含表达
- 导出的类型（如 ButtonProps）需单独声明，方便其他模块引用
值得一提的是，在CodeBuddy项目中，未编写文档的组件会被CI流水线拒绝合并。这一规则已在团队内形成硬性约束。