tdesign-component-style

TDesign Component Style Development SOP

This skill provides the operation process for TDesign React component style development. For static rules, see .codebuddy/specs/css-naming-spec.md。

Trigger Conditions

Use this skill when the user needs to perform the following tasks:

• Create styles for a new component
• Modify styles of an existing component
• Configure the component style entry

Prerequisites

Before executing this SOP, you need to understand the static rules in the following spec:

• CSS Naming Conventions: .codebuddy/specs/css-naming-spec.md(BEM naming, state classes, size classes, Design Token)

SOP Process

Step 1: Create the style entry file

Create the style/ directory under the component directory:

style/index.js(reference the Less source file):

import '../../_common/style/web/components/{component-name}/index.less';

style/css.js(reference the compiled CSS):

import '../../_common/style/web/components/{component-name}/index.css';

Step 2: Ensure the component entry imports styles

In index.ts , import the styles:

import _ExampleComponent from './ExampleComponent';
import './style/index.js';  // ← 必须添加

export const ExampleComponent = _ExampleComponent;

Step 3: Develop styles in the Common sub-repository

The style files are located in packages/common/style/web/components/{component-name}/index.less

@import "../../_variables/index.less";

.@{prefix}-{component-name} {
  // 基础样式，使用 Design Token（参见 css-naming-spec.md §8）
  display: inline-flex;
  align-items: center;
  padding: @comp-paddingLR-s @comp-paddingTB-s;
  border-radius: @radius-default;
  font-size: @font-size-base;
  color: @text-color-primary;
  background-color: @bg-color-container;

  // 元素样式（BEM element）
  &__icon {
    margin-right: @comp-margin-xs;
  }

  &__content {
    flex: 1;
  }

  // 修饰类（BEM modifier）
  &--primary {
    background-color: @brand-color;
    color: @text-color-anti;
  }

  // 尺寸修饰
  &--small {
    padding: @comp-paddingLR-xs @comp-paddingTB-xs;
    font-size: @font-size-s;
  }
}

// 状态类（联合选择器，参见 css-naming-spec.md §3）
.@{prefix}-{component-name}.@{prefix}-is-disabled {
  cursor: not-allowed;
  opacity: @disabled-opacity;
}

.@{prefix}-{component-name}.@{prefix}-is-loading {
  cursor: wait;
}

Step 4: Apply class names in the React component

Use useConfig to get the prefix, and use classNames to combine class names:

import classNames from 'classnames';
import useConfig from '../hooks/useConfig';

const ExampleComponent = forwardRef((props, ref) => {
  const { classPrefix } = useConfig();
  const { size, disabled, loading, className } = props;

  const componentClass = `${classPrefix}-example-component`;

  const rootClassName = classNames(
    componentClass,
    className,
    {
      [`${componentClass}--${size}`]: size !== 'medium',
      [`${classPrefix}-is-disabled`]: disabled,
      [`${classPrefix}-is-loading`]: loading,
    }
  );

  return (
    <div ref={ref} className={rootClassName}>
      <span className={`${componentClass}__icon`}>{icon}</span>
      <span className={`${componentClass}__content`}>{content}</span>
    </div>
  );
});

Step 5: Sub-repository commit

Component styles are developed in the packages/common sub-repository; after modification, they must be committed separately:

cd packages/common
git add .
git commit -m "style({component-name}): description"
# 推送到 tdesign-common 仓库

Checklist

After completing style development, verify against the checklist in css-naming-spec.md :

• The style entry files are correctly configured (style/index.js + style/css.js)
• The component entry imports the style files
• Use the @{prefix} variable instead of hardcoding t-
• Use in React useConfig() to get the prefix
• Element class names do not reflect DOM hierarchy
• State classes use compound selectors
• Use Design Token instead of hardcoded values
• Support className passthrough
• Sub-repository changes have been committed separately