component-family-consistency

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Component Family Consistency

组件家族一致性

Every interactive component in a product — buttons, inputs, selects, checkboxes, radio buttons, pills, badges, tags, calendars, date pickers, sliders, toggles — belongs to the same visual family. They share a common design DNA. A user should be able to look at any component and feel that it belongs to the same product as every other component.

When components are designed in isolation without shared tokens, the product feels assembled from parts rather than built as a whole.

产品中的每个交互组件——按钮、输入框、选择器、复选框、单选按钮、胶囊控件、徽章、标签、日历、日期选择器、滑块、开关——都属于同一个视觉家族。它们拥有共同的设计DNA。用户看到任意组件时，都能感受到它与其他组件同属一个产品。

如果组件在设计时孤立存在，不共享设计令牌（tokens），产品会给人一种拼凑感，而非浑然一体的整体。

The Shared DNA

共享的设计DNA

Define these tokens once. Every component inherits from them.

只需定义一次这些令牌，所有组件都从中继承。

Border-Radius

All interactive components use the same base radius token. Variations are derived, not invented.

css

--radius-base:    8px;   /* buttons, inputs, selects */
--radius-sm:      4px;   /* checkboxes, small badges */
--radius-lg:      12px;  /* cards, modals, large panels */
--radius-full:    9999px; /* pills, tags, avatar chips */

A button and an input on the same form must have the same radius. A pill is always

--radius-full

. A badge is

--radius-sm

--radius-full

depending on brand tone — but consistent across all badges.

所有交互组件使用相同的基础圆角令牌。变体是派生而来，而非凭空创造。

css

--radius-base:    8px;   /* buttons, inputs, selects */
--radius-sm:      4px;   /* checkboxes, small badges */
--radius-lg:      12px;  /* cards, modals, large panels */
--radius-full:    9999px; /* pills, tags, avatar chips */

同一表单中的按钮和输入框必须具有相同的圆角。胶囊控件始终使用

--radius-full

。徽章根据品牌风格选择

--radius-sm

或

--radius-full

——但所有徽章的样式必须保持一致。

Border Style

边框样式

Borders across all form components and containers should use a highly restricted set of tokens.

The 2-Step Rule: Limit border widths to at most two options (e.g.,

1px

and

4px

, or

1px

and

8px

). Do not use an incremental scale like

1px, 2px, 3px, 4px...

. A limited choice makes the hierarchy clear and the product feel intentional.

css

--border-width-thin:   1px;   /* Default for inputs, cards, dividers */
--border-width-thick:  4px;   /* Featured items, bold accents, active indicators */

--border-color:        var(--color-border);
--border-color-focus:  var(--color-primary);
--border-color-error:  var(--color-error);

An input border and a select border are identical at rest. Focus state uses

--border-color-focus

everywhere. Error state uses

--border-color-error

everywhere.

所有表单组件和容器的边框应使用一套高度受限的令牌。

两步规则： 将边框宽度限制为最多两种选项（例如

1px

和

4px

，或

1px

和

8px

）。不要使用

1px、2px、3px、4px……

这样的增量层级。有限的选择能让层级关系清晰，产品给人一种精心设计的感觉。

css

--border-width-thin:   1px;   /* 输入框、卡片、分隔线的默认值 */
--border-width-thick:  4px;   /* 特色项、醒目强调、激活状态指示器 */

--border-color:        var(--color-border);
--border-color-focus:  var(--color-primary);
--border-color-error:  var(--color-error);

输入框和选择器在默认状态下的边框完全相同。所有组件的聚焦状态都使用

--border-color-focus

。所有组件的错误状态都使用

--border-color-error

。

Spacing and Height

间距与高度

Components at the same visual scale share height and internal padding.

css

/* Default (md) size */
--component-height-md:    40px;
--component-padding-x-md: 12px;
--component-padding-y-md: 8px;

/* Small */
--component-height-sm:    32px;
--component-padding-x-sm: 8px;
--component-padding-y-sm: 6px;

/* Large */
--component-height-lg:    48px;
--component-padding-x-lg: 16px;
--component-padding-y-lg: 10px;

A button and an input placed next to each other must be the same height. This is not cosmetic — mismatched heights break form layouts and signal disorder.

同一视觉层级的组件共享高度和内部边距。

css

/* 默认（中等）尺寸 */
--component-height-md:    40px;
--component-padding-x-md: 12px;
--component-padding-y-md: 8px;

/* 小尺寸 */
--component-height-sm:    32px;
--component-padding-x-sm: 8px;
--component-padding-y-sm: 6px;

/* 大尺寸 */
--component-height-lg:    48px;
--component-padding-x-lg: 16px;
--component-padding-y-lg: 10px;

相邻放置的按钮和输入框必须高度相同。这不仅仅是美观问题——高度不匹配会破坏表单布局，给人一种杂乱无章的感觉。

Shadow

阴影

Interactive components use a consistent shadow logic:

At rest: no shadow, or
```
--shadow-xs
```
for floating components (select dropdown trigger)
On focus: focus ring via
```
outline
```
, not
```
box-shadow
```
(unless using
```
box-shadow
```
as the focus ring consistently)
Elevated (dropdowns, popovers opening from components):
```
--shadow-md
```

交互组件使用一致的阴影逻辑：

默认状态：无阴影，或浮动组件（如选择器下拉触发器）使用
```
--shadow-xs
```
聚焦状态：通过
```
outline
```
实现聚焦环，而非
```
box-shadow
```
（除非统一使用
```
box-shadow
```
作为聚焦环）
悬浮层（下拉菜单、从组件弹出的气泡框）：使用
```
--shadow-md
```

Colour Logic

色彩逻辑

The same colour roles apply uniformly across all components:

State	Colour token
Rest border	`--color-border`
Focus border / ring	`--color-primary`
Error border	`--color-error`
Disabled	`--color-text-secondary` at reduced opacity
Selected / active fill	`--color-primary`
Hover background	`--color-primary` at 8–12% opacity

相同的色彩角色统一应用于所有组件：

状态	色彩令牌
默认边框	`--color-border`
聚焦边框/聚焦环	`--color-primary`
错误边框	`--color-error`
禁用状态	`--color-text-secondary` 降低透明度
选中/激活填充	`--color-primary`
悬停背景	`--color-primary` 设置8–12%的透明度

Component Family Members

组件家族成员

Component	Shares radius	Shares height	Shares border	Shares colour logic
Button	✓	✓	— (filled)	✓
Input / textarea	✓	✓	✓	✓
Select	✓	✓	✓	✓
Checkbox	`--radius-sm`	—	✓	✓
Radio	`--radius-full`	—	✓	✓
Toggle / switch	`--radius-full`	✓	—	✓
Pill / tag	`--radius-full`	✓	✓ optional	✓
Badge	`--radius-sm` or `--radius-full`	—	—	✓
Date picker / calendar	`--radius-base`	✓	✓	✓
Slider	`--radius-full` (track + thumb)	—	—	✓
Search input	✓	✓	✓	✓
Combobox	✓	✓	✓	✓

组件	共享圆角	共享高度	共享边框	共享色彩逻辑
按钮	✓	✓	—（填充样式）	✓
输入框/文本域	✓	✓	✓	✓
选择器	✓	✓	✓	✓
复选框	`--radius-sm`	—	✓	✓
单选按钮	`--radius-full`	—	✓	✓
开关	`--radius-full`	✓	—	✓
胶囊控件/标签	`--radius-full`	✓	✓（可选）	✓
徽章	`--radius-sm` 或 `--radius-full`	—	—	✓
日期选择器/日历	`--radius-base`	✓	✓	✓
滑块	`--radius-full` （轨道+滑块）	—	—	✓
搜索输入框	✓	✓	✓	✓
组合框	✓	✓	✓	✓

Gradients in Components

组件中的渐变

If the brand uses gradients, apply them consistently:

A gradient on a primary button should use the same gradient angle and stops as gradient usage elsewhere in the product
Hover state: slightly shift the gradient lightness, not the hue
Do not use gradients on some button variants and flat colour on others — pick one approach per variant and apply it universally

如果品牌使用渐变，需保持应用一致：

主按钮上的渐变应与产品其他地方使用的渐变角度和色标一致
悬停状态：略微调整渐变的亮度，而非色相
不要在某些按钮变体上使用渐变，而在其他变体上使用纯色——为每个变体选择一种风格并统一应用

Review Checklist

评审检查清单

Do buttons and inputs on the same form share the same height?
Do all bordered components use at most two border-width options (e.g., 1px and 4px)?
Does focus state look identical across all focusable components?
Does error state look identical across all components that can have errors?
Are all radius values derived from the same base token — not set independently per component?
Do pills and tags use
```
--radius-full
```
consistently?
Is gradient usage (if any) consistent across all button variants?
Could a new component be added to the library using only existing tokens?

同一表单中的按钮和输入框是否高度相同？
所有带边框的组件是否最多使用两种边框宽度选项（例如1px和4px）？
所有可聚焦组件的聚焦状态样式是否一致？
所有可能出现错误的组件的错误状态样式是否一致？
所有圆角值是否都源自同一个基础令牌——而非为每个组件单独设置？
胶囊控件和标签是否一致使用
```
--radius-full
```
？
渐变的使用（如果有）在所有按钮变体中是否一致？
是否可以仅使用现有令牌向组件库中添加新组件？