How Ant Design 6 Leverages CSS Variables to Cut Size and Simplify Styling

Ant Design v6 is released without the need to support Internet Explorer, allowing the library to refactor several components using CSS variables. This reduces CSS bundle size and improves performance.

Variant Property in v5

In v5, components used the variant prop to achieve different styles, exemplified by the Button component:

.ant-btn-solid.ant-btn-red { color: #fff; background: red; }
.ant-btn-solid.ant-btn-blue { color: #fff; background: blue; }
.ant-btn-outlined.ant-btn-red { color: #fff; border: 1px solid red; }
.ant-btn-outlined.ant-btn-blue { color: #fff; border: 1px solid blue; }
/* ... */

After switching to CSS variables, the styling logic moves from explicit variants to a palette controlled by variables, enabling rapid style generation after defining a base color palette.

Using CSS Variables

.ant-btn { color: var(--ant-btn-color); background: var(--ant-btn-background); border-color: var(--ant-btn-border-color); border-width: 1px; border-style: solid; }
.ant-btn-solid { --ant-btn-color: #fff; --ant-btn-background: var(--ant-color-solid); }
.ant-btn-outlined { --ant-btn-color: #fff; --ant-btn-border-color: var(--ant-color-solid); }
/* CSS Variables. The more colors you have, the more size you save. */
.ant-btn-red { --ant-color-solid: red; }
.ant-btn-blue { --ant-color-solid: blue; }
/* ... */

Style Overrides with CSS Variables

Previously, overriding a component required handling multiple states and specificity:

.ant-btn-solid.my-btn:not(:disabled) { background: #f00; }
.ant-btn-solid.my-btn:not(:disabled):hover { background: #e00; }
.ant-btn-solid.my-btn:not(:disabled):active { background: #d00; }
.ant-btn-outlined.my-btn:not(:disabled) { color: #f00; border-color: #f00; }
.ant-btn-outlined.my-btn:not(:disabled):hover { color: #e00; border-color: #e00; }
.ant-btn-outlined.my-btn:not(:disabled):active { color: #d00; border-color: #d00; }

With CSS variables, overriding becomes much simpler:

.ant-btn-outlined.my-btn { --ant-color-solid: #f00; --ant-color-solid-hover: #e00; --ant-color-solid-active: #d00; }

Conditional Compatibility Using @container

Conditional styling can be expressed with @container queries, though Firefox currently lacks support, so Ant Design treats it as a fallback mechanism rather than a core feature.

@container style(--custom-var) { /* ... */ }

Scoped Styling with @scope

The @scope rule offers powerful namespacing, replacing the previous :where approach used in v5 for theme isolation:

:where(.css-BamBoo) { .ant-btn { color: red; } }
:where(.css-LIghT) { .ant-btn { color: blue; } }

However, @scope also lacks Firefox support, meaning it will likely appear in a future major version after compatibility concerns are addressed.

Component Tokens and Conditional Logic

When a token exists, developers may add a class name based on its presence. The token is generated asynchronously during the component's render effect, so direct checks in CSS are preferred. Example using useToken:

const Sample = () => {
  const { token } = useToken();
  // if (token.components.sample.customVar) { /* ... */ }
};

Since the token is not available synchronously, CSS container queries provide a better solution.