Skip to content

Commit b577603

Browse files
carolin913RylanBotuyarn
authored
docs: add AI coding specs, skills and component doc-example mapping (#4171)
* docs: add AI coding specs, skills and component doc-example mapping * chore: revert common change * chore: delete release file * chore: remove release text --------- Co-authored-by: Rylan <rylanbot@qq.com> Co-authored-by: wū yāng <uyarnchen@gmail.com>
1 parent abaacda commit b577603

16 files changed

Lines changed: 3608 additions & 1 deletion

File tree

.claude/skills

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../.codebuddy/skills
Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
name: tdesign-component-style
3+
description: This skill should be used when developing or modifying styles for TDesign React components. It provides guidance on BEM naming conventions, CSS Variables usage, state classes, and the relationship between component code and common submodule styles.
4+
---
5+
6+
# TDesign 组件样式开发 SOP
7+
8+
本技能提供 TDesign React 组件样式开发的操作流程。静态规则参见 `.codebuddy/specs/css-naming-spec.md`
9+
10+
## 触发条件
11+
12+
当用户需要执行以下任务时使用此技能:
13+
- 为新组件创建样式
14+
- 修改现有组件样式
15+
- 配置组件样式入口
16+
17+
## 前置知识
18+
19+
执行本 SOP 前,需要了解以下 spec 中的静态规则:
20+
- **CSS 命名规范**: `.codebuddy/specs/css-naming-spec.md`(BEM 命名、状态类、尺寸类、Design Token)
21+
22+
## SOP 流程
23+
24+
### Step 1: 创建样式入口文件
25+
26+
在组件目录下创建 `style/` 目录:
27+
28+
**style/index.js**(引用 Less 源文件):
29+
```javascript
30+
import '../../_common/style/web/components/{component-name}/index.less';
31+
```
32+
33+
**style/css.js**(引用编译后 CSS):
34+
```javascript
35+
import '../../_common/style/web/components/{component-name}/index.css';
36+
```
37+
38+
### Step 2: 确保组件入口导入样式
39+
40+
`index.ts` 中导入样式:
41+
42+
```typescript
43+
import _ExampleComponent from './ExampleComponent';
44+
import './style/index.js'; // ← 必须添加
45+
46+
export const ExampleComponent = _ExampleComponent;
47+
```
48+
49+
### Step 3: 在 Common 子仓库开发样式
50+
51+
样式文件位于 `packages/common/style/web/components/{component-name}/index.less`
52+
53+
```less
54+
@import "../../_variables/index.less";
55+
56+
.@{prefix}-{component-name} {
57+
// 基础样式,使用 Design Token(参见 css-naming-spec.md §8)
58+
display: inline-flex;
59+
align-items: center;
60+
padding: @comp-paddingLR-s @comp-paddingTB-s;
61+
border-radius: @radius-default;
62+
font-size: @font-size-base;
63+
color: @text-color-primary;
64+
background-color: @bg-color-container;
65+
66+
// 元素样式(BEM element)
67+
&__icon {
68+
margin-right: @comp-margin-xs;
69+
}
70+
71+
&__content {
72+
flex: 1;
73+
}
74+
75+
// 修饰类(BEM modifier)
76+
&--primary {
77+
background-color: @brand-color;
78+
color: @text-color-anti;
79+
}
80+
81+
// 尺寸修饰
82+
&--small {
83+
padding: @comp-paddingLR-xs @comp-paddingTB-xs;
84+
font-size: @font-size-s;
85+
}
86+
}
87+
88+
// 状态类(联合选择器,参见 css-naming-spec.md §3)
89+
.@{prefix}-{component-name}.@{prefix}-is-disabled {
90+
cursor: not-allowed;
91+
opacity: @disabled-opacity;
92+
}
93+
94+
.@{prefix}-{component-name}.@{prefix}-is-loading {
95+
cursor: wait;
96+
}
97+
```
98+
99+
### Step 4: 在 React 组件中应用类名
100+
101+
使用 `useConfig` 获取前缀,使用 `classNames` 组合类名:
102+
103+
```typescript
104+
import classNames from 'classnames';
105+
import useConfig from '../hooks/useConfig';
106+
107+
const ExampleComponent = forwardRef((props, ref) => {
108+
const { classPrefix } = useConfig();
109+
const { size, disabled, loading, className } = props;
110+
111+
const componentClass = `${classPrefix}-example-component`;
112+
113+
const rootClassName = classNames(
114+
componentClass,
115+
className,
116+
{
117+
[`${componentClass}--${size}`]: size !== 'medium',
118+
[`${classPrefix}-is-disabled`]: disabled,
119+
[`${classPrefix}-is-loading`]: loading,
120+
}
121+
);
122+
123+
return (
124+
<div ref={ref} className={rootClassName}>
125+
<span className={`${componentClass}__icon`}>{icon}</span>
126+
<span className={`${componentClass}__content`}>{content}</span>
127+
</div>
128+
);
129+
});
130+
```
131+
132+
### Step 5: 子仓库提交
133+
134+
组件样式在 `packages/common` 子仓库开发,修改后需单独提交:
135+
136+
```bash
137+
cd packages/common
138+
git add .
139+
git commit -m "style({component-name}): description"
140+
# 推送到 tdesign-common 仓库
141+
```
142+
143+
## 检查清单
144+
145+
完成样式开发后,对照 `css-naming-spec.md` 中的检查清单验证:
146+
147+
- [ ] 样式入口文件正确配置(style/index.js + style/css.js)
148+
- [ ] 组件入口导入了样式文件
149+
- [ ] 使用 `@{prefix}` 变量而非硬编码 `t-`
150+
- [ ] React 中使用 `useConfig()` 获取前缀
151+
- [ ] 元素类名不体现 DOM 层级
152+
- [ ] 状态类使用联合选择器
153+
- [ ] 使用 Design Token 而非硬编码值
154+
- [ ] 支持 className 透传
155+
- [ ] 子仓库修改已单独提交

0 commit comments

Comments
 (0)