name: css-development-create-component description: 此技能应在创建新的样式化组件或添加新的CSS类时使用。触发词包括“创建组件”、“新建按钮”、“新建卡片”、“添加样式”、“样式组件”、“构建UI元素”。指导语义化命名、Tailwind组合、深色模式支持和测试覆盖。

CSS开发：创建组件

概述

指导您按照既定模式创建新的CSS组件：

语义化类命名
通过 @apply 组合Tailwind工具类
默认支持深色模式
测试覆盖（静态CSS + 组件渲染）
组合优先于创建（重用现有类）

这是 css-development 技能的子技能 - 通常通过主技能自动调用。

适用场景

在以下情况使用：

创建新的样式化组件（按钮、卡片、表单字段等）
向components.css添加新的语义化CSS类
构建可复用的UI模式
需要确保深色模式支持和测试覆盖

模式参考

此技能遵循主 css-development 技能中记录的模式。关键模式：

语义化命名： .button-primary 而非 .btn-blue Tailwind组合： 使用 @apply 组合工具类 深色模式： 默认包含 dark: 变体 组合优先： 检查现有类是否可以组合 测试覆盖： 静态CSS测试 + 组件渲染测试

工作流程

当此技能被调用时，创建一个TodoWrite清单并按步骤执行。

宣布使用

首先，宣布您正在使用此技能：

“我正在使用 css-development:create-component 技能来指导创建这个新的CSS组件。”

创建TodoWrite清单

使用TodoWrite工具创建此清单：

创建CSS组件：
- [ ] 调研现有组件（读取components.css）
- [ ] 检查组合是否能解决问题（现有类可以组合吗？）
- [ ] 识别组件类型（如果需要新类，则确定原子/分子/有机体）
- [ ] 选择语义化名称（遵循现有命名模式）
- [ ] 编写组件类（使用@apply，包含dark:变体）
- [ ] 创建标记集成（展示React/HTML用法）
- [ ] 编写静态CSS测试（验证类是否存在）
- [ ] 编写组件渲染测试（验证className应用）
- [ ] 记录组件（添加使用注释）

分步详情

步骤1：调研现有组件

操作： 使用Read工具读取 styles/components.css

目的： 了解已存在的内容以确保一致性和识别重用机会

关注点：

可以组合的类似组件
需要遵循的现有命名模式
常见模式（按钮变体、卡片样式等）

开始前标记为进行中，完成后标记为已完成。

步骤2：检查组合是否能解决问题

操作： 分析组合现有类是否能达到目标

示例：

想要一个“带图标的按钮”？→ 组合 .button-primary + 间距工具类
想要一个“带阴影的卡片”？→ 如果存在则使用 .card，需要时添加工具类
想要一个“高亮徽章”？→ 组合 .badge + 颜色工具类

YAGNI原则： 仅当组合无效或在标记中产生过多重复时才创建新类。

决策：

如果组合有效： 记录组合并跳过剩余步骤（无需新类）
如果需要新类： 继续步骤3

决策后标记为已完成。

步骤3：识别组件类型

操作： 确定原子设计层级（如果需要创建新类）

原子 - 基本构建块：

单一用途元素
示例：.button、.input、.badge、.spinner、.link

分子 - 组合组件：

组合多个原子
示例：.card、.form-field、.empty-state、.alert

有机体 - 复杂组件：

多个分子 + 原子
示例：.page-layout、.navigation、.session-card、.conversation-timeline

重要性： 有助于界定复杂性和依赖关系

识别后标记为已完成。

步骤4：选择语义化名称

操作： 选择描述性、语义化的类名，遵循现有模式

参考代码库的命名模式：

基础 + 变体： .button-primary、.button-secondary、.button-danger
组件 + 子元素： .card-title、.card-description、.form-field
上下文 + 组件： .session-card、.marketing-hero、.dashboard-layout
状态修饰符： .session-card-active、.button-disabled

反模式（避免）：

工具类名称：.btn-blue、.card-sm、.text-big
缩写：.btn、.hdr、.desc
通用名称：.component、.item、.thing

验证： 名称应清晰指示目的并符合现有模式

选择后标记为已完成。

步骤5：编写组件类

操作： 使用Edit工具在 styles/components.css 中创建CSS类

模板：

/* [组件名称] - [简要描述]
   用法：<[元素] className="[类名]">[内容]</[元素]> */
.[类名] {
  @apply [背景工具类] [深色模式变体];
  @apply [间距工具类];
  @apply [排版工具类];
  @apply [过渡工具类];
}

必需元素：

文档注释 - 是什么，如何使用
深色模式变体 - 为颜色/背景包含 dark:
逻辑分组 - 分组相关工具类（背景、间距、排版、过渡）
交互状态 - 如果适用，包含悬停/焦点/激活状态

示例：

/* 主要按钮 - 具有悬停提升效果的主要行动号召按钮
   用法：<button className="button-primary">点击我</button> */
.button-primary {
  @apply bg-indigo-500 hover:bg-indigo-700 dark:bg-indigo-600 dark:hover:bg-indigo-800;
  @apply px-6 py-3 rounded-lg font-medium text-white;
  @apply transition-all duration-200 hover:-translate-y-0.5;
  @apply focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2;
}

使用Edit工具添加到现有文件（不要覆盖整个文件）

写入文件后标记为已完成。

步骤6：创建标记集成

操作： 记录在不同框架中如何使用该组件

展示以下用法示例：

React（如果项目使用React）
原生HTML（始终展示此项）
Vue或其他框架（如果项目使用它们）

示例文档：

## 使用 button-primary 组件

**React：**
```tsx
const Button = ({ variant = 'primary', className = '', children, ...props }) => {
  const classes = `button-${variant} ${className}`.trim();
  return <button className={classes} {...props}>{children}</button>;
};

// 用法
<Button variant="primary">点击我</Button>
<Button variant="primary" className="w-full">全宽</Button>

原生HTML：

<button class="button-primary">点击我</button>
<button class="button-primary custom-class">带自定义类</button>


**放置位置：** 项目文档、README或组件文件中的注释

**记录示例后标记为已完成。**

---

#### 步骤7：编写静态CSS测试

**操作：** 向 `styles/__tests__/components.test.ts` 添加测试（如果不存在则创建）

**目的：** 验证CSS类是否存在于components.css文件中

**测试模式：**
```typescript
import { readFileSync } from 'fs';
import { describe, it, expect } from 'vitest';

describe('components.css', () => {
  const content = readFileSync('styles/components.css', 'utf-8');

  it('应包含 button-primary 组件类', () => {
    expect(content).toContain('.button-primary');
  });

  it('应包含 button-primary 深色模式变体', () => {
    expect(content).toContain('dark:bg-indigo');
  });
});

关键检查：

类存在于文件中
存在深色模式变体（搜索 dark:）
存在文档注释（可选但推荐）

运行测试：

npm test styles/__tests__/components.test.ts
# 或
vitest styles/__tests__/components.test.ts

预期： 测试通过（绿色）

编写并通过测试后标记为已完成。

步骤8：编写组件渲染测试

操作： 添加组件渲染测试（框架特定）

目的： 验证className在实际组件中的应用是否有效

React示例：

import { render, screen } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import { Button } from '@/components/atoms/Button';

describe('Button组件', () => {
  it('应用 button-primary 类', () => {
    render(<Button variant="primary">点击</Button>);
    expect(screen.getByRole('button')).toHaveClass('button-primary');
  });

  it('接受并应用自定义className', () => {
    render(<Button variant="primary" className="custom-class">点击</Button>);
    const button = screen.getByRole('button');
    expect(button).toHaveClass('button-primary', 'custom-class');
  });
});

关键检查：

应用了语义化类
可以添加自定义className
类不冲突

运行测试：

npm test components/atoms/Button.test.tsx
# 或
vitest components/atoms/Button.test.tsx

预期： 测试通过（绿色）

编写并通过测试后标记为已完成。

步骤9：记录组件

操作： 确保组件有使用文档

文档应包含：

CSS中的注释 - 已在步骤5完成
标记示例 - 已在步骤6完成
组件API（针对框架组件）- 属性、变体等

附加文档（可选但推荐）：

如果项目有组件样式指南，则添加到其中
如果项目使用Storybook，则添加到其中
添加视觉示例或截图

最低要求： 存在CSS注释 + 标记示例

验证文档后标记为已完成。

完成

当所有清单项完成后：

运行所有测试 以确保一切通过：
```
npm test
```
显示摘要 创建的内容：
- 组件类名和文件位置
- 测试文件位置
- 文档位置
建议后续步骤：
- 提交更改
- 如果需要，创建相关变体
- 在实际UI中使用该组件

示例摘要：

已创建 button-primary 组件！

创建/修改的文件：
- styles/components.css（添加了 .button-primary）
- styles/__tests__/components.test.ts（添加了静态CSS测试）
- components/atoms/Button.test.tsx（添加了渲染测试）
- components/atoms/Button.tsx（标记集成）

后续步骤：
- 提交这些更改：git add . && git commit -m "feat: 添加 button-primary 组件"
- 在您的UI中使用：<Button variant="primary">点击我</Button>
- 如果需要，创建变体：button-secondary、button-danger等