source/ant-design
1
0
Fork 0
mirror of https://github.com/ant-design/ant-design.git synced 2026-02-09 02:49:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(site): add semantic-beauty blog (#55561)

Browse Source 
* chore(site): add semantic-beauty blog

* Update docs/blog/semantic-beauty/demos.tsx

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: 遇见同学 <1875694521@qq.com>

* text auto space

* revert demo

* revert demo

* update

* update

* docs: add section on combining with Tailwind CSS for enhanced component customization

* update video source

* update

* update

* Update docs/blog/semantic-beauty.en-US.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: thinkasany <480968828@qq.com>

* docs: polish language in semantic-beauty blog posts (#55585)

Co-authored-by: thinkasany <117748716+thinkasany@users.noreply.github.com>
Co-authored-by: afc163 <507615+afc163@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

---------

Signed-off-by: 遇见同学 <1875694521@qq.com>
Signed-off-by: thinkasany <480968828@qq.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: lijianan <574980606@qq.com>
Co-authored-by: ice <1597834867@qq.com>
Co-authored-by: thinkasany <480968828@qq.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: thinkasany <117748716+thinkasany@users.noreply.github.com>
Co-authored-by: afc163 <507615+afc163@users.noreply.github.com>
This commit is contained in:
遇见同学
2025-11-04 20:59:42 +08:00
committed by GitHub
parent 4df740e22e
commit 7ed17d87bc
3 changed files with 385 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
docs/blog/semantic-beauty.en-US.md Normal file
View File

@@ -0,0 +1,143 @@
---
title: Discover the Delicate Beauty of Components with Semantic Design
date: 2025-11-22
author: meet-student,thinkasany
---
Before Ant Design v6, the experience of customizing styles based on open tokens was already great, but there were still some pain points that were difficult to solve. Ant Design v6 made many changes and improvements to address this. Today, let’s talk about how semantic design helps you discover the delicate beauty of components.
---
## Before v6
In the past, how did we typically adjust component styles?
### Method 1 (props)
- Write extensive conditional logic for combinations in `className` and `style` attributes
- Use numerous props like `wrapClassName` when modifying styles of different component regions
The code might look like this:
```tsx
<Button className={variant === 'filled' ? 'btn-filled' : 'btn-outline'}>
Submit
</Button>
<Modal wrapClassName="wrap-class" style={{ backgroundColor: '#fff' }}>
Modal
</Modal>
<Menu style={{ backgroundColor: mode === 'horizontal' ? '#fff' : '#000' }}>
<Menu.SubMenu popupClassName="popup-class">
<Menu.Item >
MenuItem
</Menu.Item>
</Menu.SubMenu>
</Menu>
```
### Method 2 (ConfigProvider)
Using the theme Design Token design introduced in Ant Design v5:
```tsx
<ConfigProvider
theme={{
components: {
Notification: {
colorTextHeading: token.blue,
colorText: token.colorTextSecondary,
},
},
}}
>
{children}
</ConfigProvider>
```
### Method 3 (CSS)
Apart from these two methods, you might also have written less recommended CSS overrides:
```css
.wrapper-class .ant-table {
border-radius: 4px;
overflow: hidden;
}
.wrapper-class .ant-table .ant-table-thead {
background-color: #f9fafc;
color: #8b97b6;
}
```
All of the above approaches have various pain points:
- Limited available `props` make it impossible to modify certain regions, and logic is not well-organized
- Limited `Design Token` configuration prevents differentiated styling based on different types/variants
- CSS overrides introduce high cognitive load and maintenance costs, with poor maintainability and semantics
## Now in v6
To avoid token proliferation and the addition of numerous API props — which would increase maintenance costs — these elements were consolidated into a more semantic structure.
- The DOM structure has been greatly simplified and refined.
- Styles and themes can now be customized more flexibly and in a more maintainable way based on different props.
- It’s possible to define styles or class names for specific semantic regions, making it easier to customize local styles or themes.
```tsx
const classNamesFn: ButtonProps['classNames'] = (info) => {
if (info.props.type === 'primary') {
return {
root: 'demo-btn-root--primary',
} satisfies ButtonProps['classNames'];
}
return {
root: 'demo-btn-root--default',
} satisfies ButtonProps['classNames'];
};
const styles: ButtonProps['styles'] = {
root: { borderWidth: 2, borderStyle: 'dashed' },
content: { fontStyle: 'italic' },
icon: { opacity: 0.85 },
};
return (
<Button styles={styles} classNames={classNamesFn}>
Button
</Button>
);
```
### Combining with Tailwind CSS
What's more exciting is that the `classNames` property integrates perfectly with atomic CSS frameworks like [Tailwind CSS](https://tailwindcss.com/). This provides developers with unprecedented freedom: you can enjoy the preset behavior and semantic structure of antd components while leveraging Tailwind's utility classes to quickly build any visual style you want. Semantic design + Tailwind CSS, makes component customization extremely flexible.
```tsx
return (
<Button
classNames={{
root: 'bg-black text-white border-none hover:bg-[#2e2e2e]',
icon: 'text-white/90',
}}
icon={<GiftOutlined />}
>
Ant Design
</Button>
);
```
<video src="https://gw.alipayobjects.com/v/huamei_iwk9zp/afts/video/Ok8fTIm1TLIAAAAAgCAAAAgAfoeUAQBr" autoplay="true" muted="true" loop="true" playsinline="true" controls="true"></video>
## Discover the Delicate Beauty of Components
Users can give components refined designs for different states based on their preferred color schemes. Let your imagination run wild and make your pages more vibrant and expressive. If you encounter any issues or have better ideas during use, feel free to share feedback — let’s make Ant Design even better together.
---
<code src="./semantic-beauty/demos.tsx" simplify="true" iframe="430"></code>
## The Relationship Between Tokens and Semantic Styling
In Ant Design’s design system, tokens are positioned as design variables — the atomic materials of the design language. Semantic styles, on the other hand, define how those materials are used. They are created by combining design tokens with component-level customizations, allowing for more flexible and expressive styling scenarios. Since semantic styles operate at the component level, they provide better control over styling scope. If you aim to design a fully customized Ant Design theme, the combination of tokens and semantic styling will be your most powerful tool — together, they enable you to craft a more refined and precisely tailored theme.

144
docs/blog/semantic-beauty.zh-CN.md Normal file
View File

@@ -0,0 +1,144 @@
---
title: 语义化发现组件精致的美
date: 2025-11-22
author: meet-student,thinkasany
---
在 Ant Design v6 之前，基于开放的 Design Token 进行样式定制已经带来了非常好的开发体验，但依然存在一些难以解决的痛点。Ant Design v6 为此做了诸多改变和优化。今天，我们来聊聊语义化是如何帮助你发现组件的精致之美。
---
## v6 之前
在过去，我们通常是怎么调整组件样式的呢？
### 方式一 (props)
- 在 `className` 和 `style` 属性上编写大量的拼接组合和逻辑判断
- 在修改组件不同区域的样式时，需要使用大量类似 `wrapClassName` 这样的 props
代码可能是这样的：
```tsx
<Button className={variant === 'filled' ? 'btn-filled' : 'btn-outline'}>
Submit
</Button>
<Modal wrapClassName="wrap-class" style={{ backgroundColor: '#fff' }}>
Modal
</Modal>
<Menu style={{ backgroundColor: mode === 'horizontal' ? '#fff' : '#000' }}>
<Menu.SubMenu popupClassName="popup-class">
<Menu.Item >
MenuItem
</Menu.Item>
</Menu.SubMenu>
</Menu>
```
### 方式二 (ConfigProvider)
采用 Ant Design v5 的主题 Design Token 设计：
```tsx
<ConfigProvider
theme={{
components: {
Notification: {
colorTextHeading: token.blue,
colorText: token.colorTextSecondary,
},
},
}}
>
{children}
</ConfigProvider>
```
### 方式三 (CSS)
除了这两种方式，你可能还写过更不推荐的 CSS 样式覆盖：
```css
.wrapper-class .ant-table {
border-radius: 4px;
overflow: hidden;
}
.wrapper-class .ant-table .ant-table-thead {
background-color: #f9fafc;
color: #8b97b6;
}
```
以上方式都存在诸多痛点：
- 可用的 `props` 参数有限，导致部分区域的样式无法更改，逻辑也不够聚合
- `Design Token` 的配置能力有限，无法根据不同的类型/变体做差异化的样式修改
- 样式覆盖的方式存在较高的心智负担和维护成本，可维护性和语义化都很差
## v6 现在
为了避免 `Design Token` 泛滥和添加大量的 `API props`（这会导致维护成本升高），我们将这些能力聚合成了语义化设计。
- DOM 结构得到了显著地简化和优化
- 可以根据不同的 `props` 更灵活、更易维护地定制样式和主题
- 可以为特定的语义区域定义样式和类名，更友好地实现局部样式和主题的定制
```tsx
const classNamesFn: ButtonProps['classNames'] = (info) => {
if (info.props.type === 'primary') {
return {
root: 'demo-btn-root--primary',
} satisfies ButtonProps['classNames'];
}
return {
root: 'demo-btn-root--default',
} satisfies ButtonProps['classNames'];
};
const styles: ButtonProps['styles'] = {
root: { borderWidth: 2, borderStyle: 'dashed' },
content: { fontStyle: 'italic' },
icon: { opacity: 0.85 },
};
return (
<Button styles={styles} classNames={classNamesFn}>
Button
</Button>
);
```
### 与 Tailwind CSS 结合
更令人兴奋的是，`classNames` 属性可以与 [Tailwind CSS](https://tailwindcss.com/) 这类原子化 CSS 框架完美结合。这为开发者带来了前所未有的自由度：你可以在享受 antd 组件预设行为和语义化结构的同时，利用 Tailwind 的功能类快速构建出任何想要的视觉风格。语义化 + Tailwind CSS，让组件定制变得极其自由。
```tsx
return (
<Button
classNames={{
root: 'bg-black text-white border-none hover:bg-[#2e2e2e]',
icon: 'text-white/90',
}}
icon={<GiftOutlined />}
>
Ant Design
</Button>
);
```
<video src="https://gw.alipayobjects.com/v/huamei_iwk9zp/afts/video/Ok8fTIm1TLIAAAAAgCAAAAgAfoeUAQBr" autoplay="true" muted="true" loop="true" playsinline="true" controls="true"></video>
## 发现组件精致的美
用户可以根据自己喜爱的配色为组件的不同状态赋予精致的设计，发挥你的想象力，让页面更加丰富多彩吧！如果你在使用过程中遇到任何问题或有更好的想法，欢迎提交反馈，让我们一起让 Ant Design 变得更好。
---
<code src="./semantic-beauty/demos.tsx" simplify="true" iframe="430"></code>
## Design Token 和语义化的关系
在 Ant Design 的设计体系中，Design Token 定位为设计变量（Design Tokens），可以理解为设计能力中的原子原料。而语义化样式定义了样式的使用方式，它通过组合 Design Token 和组件级的私有定制，实现更自由的定制场景。由于语义化是在组件维度上进行的，因此可以更好地控制样式的作用范围。如果你想设计一套覆盖场景全面的 Ant Design 主题，Design Token 和语义化能力将是你的利器，两者搭配使用，能够自由定制更精致的主题。

98
docs/blog/semantic-beauty/demos.tsx Normal file
View File

@@ -0,0 +1,98 @@
import React from 'react';
import { Button, Drawer, Flex, Modal, Switch } from 'antd';
import BreadcrumbPreview from '../../../components/breadcrumb/demo/style-class';
import InputPreview from '../../../components/input/demo/style-class';
const { _InternalPanelDoNotUseOrYouWillBeFired: InternalPanel } = Modal;
const { _InternalPanelDoNotUseOrYouWillBeFired: InternalDrawer } = Drawer;
const SwitchNode = (
<Flex orientation="horizontal" gap="middle">
<Switch styles={{ root: { width: 40, backgroundColor: '#F5D2D2' } }} />
<Switch styles={{ root: { width: 40, backgroundColor: '#BDE3C3' } }} />
</Flex>
);
const ModalNode = (
<InternalPanel
footer={
<>
<Button
styles={{ root: { borderColor: '#ccc', color: '#171717', backgroundColor: '#fff' } }}
>
Cancel
</Button>
<Button type="primary" styles={{ root: { backgroundColor: '#171717' } }}>
Submit
</Button>
</>
}
title="Custom Function Modal"
styles={{
container: { borderRadius: 14, border: '1px solid #ccc', padding: 0, overflow: 'hidden' },
header: { padding: 16, margin: 0 },
body: { padding: '0 16px' },
footer: { padding: 10, backgroundColor: '#fafafa' },
}}
>
<div>🌈 Following the Ant Design specification.</div>
</InternalPanel>
);
const DrawerNode = (
<InternalDrawer
title="Drawer"
style={{ height: '100%', borderRadius: '10px 0 0 10px', overflow: 'hidden' }}
styles={{
header: { padding: 16 },
body: { padding: 16 },
footer: { padding: '16px 10px', backgroundColor: '#fafafa' },
}}
footer={
<Flex gap="middle" justify="flex-end">
<Button
styles={{ root: { borderColor: '#ccc', color: '#171717', backgroundColor: '#fff' } }}
>
Cancel
</Button>
<Button type="primary" styles={{ root: { backgroundColor: '#171717' } }}>
Submit
</Button>
</Flex>
}
>
<div>
🌈 Following the Ant Design specification, we developed a React UI library antd, interactive
user interfaces.
</div>
</InternalDrawer>
);
const h1Style: React.CSSProperties = {
fontSize: 20,
lineHeight: 2,
fontWeight: 'bold',
};
const Demo: React.FC = () => {
return (
<Flex orientation="horizontal" gap="middle" style={{ padding: 10 }}>
<div style={{ width: '35%' }}>
<h1 style={h1Style}>Input</h1>
<InputPreview />
</div>
<div style={{ width: '35%' }}>
<h1 style={h1Style}>Switch</h1>
{SwitchNode}
<h1 style={h1Style}>Breadcrumb</h1>
<BreadcrumbPreview />
<h1 style={h1Style}>Modal</h1>
{ModalNode}
</div>
<div style={{ width: '30%' }}>{DrawerNode}</div>
</Flex>
);
};
export default Demo;