---
system: ant-design
category: design-md
topic: DESIGN.md
content_type: design-md
status: latest
version_label: "Ant Design 5.x"
retrieved: 2026-05-13
unofficial: true
derived_from:
  - guidance/foundations/design-values@2026-05-13.md
  - guidance/foundations/color-system@2026-05-13.md
  - guidance/foundations/typography@2026-05-13.md
  - guidance/foundations/design-tokens@2026-05-13.md
source_url: https://ant.design/docs/spec/introduce
---

> **This is a community-generated DESIGN.md derived from Ant Design's public documentation. It is not an official document published by Ant Group.**

---

colors:
  primary: "#1677ff"
  primary-hover: "#4096ff"
  primary-active: "#0958d9"
  success: "#52c41a"
  warning: "#faad14"
  error: "#ff4d4f"
  info: "#1677ff"
  text-primary: "#000000E0"
  text-secondary: "#000000A6"
  text-disabled: "#00000040"
  text-primary-dark: "#FFFFFFD9"
  text-secondary-dark: "#FFFFFFA6"
  text-disabled-dark: "#FFFFFF40"
  border: "#D9D9D9"
  border-dark: "#424242"
  bg-container: "#ffffff"
  bg-layout: "#F5F5F5"
  bg-elevated: "#ffffff"
  bg-mask: "rgba(0,0,0,0.45)"

typography:
  font-family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif"
  font-family-code: "'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace"
  font-size-base: "14px"
  line-height-base: "1.5714"
  weights:
    regular: 400
    medium: 500
    semibold: 600
  scale:
    sm: "12px"
    base: "14px"
    lg: "16px"
    heading5: "16px"
    heading4: "20px"
    heading3: "24px"
    heading2: "30px"
    heading1: "38px"

spacing:
  xs: "8px"
  sm: "12px"
  md: "16px"
  lg: "24px"
  xl: "32px"
  xxl: "48px"

radius:
  xs: "2px"
  sm: "4px"
  base: "6px"
  lg: "8px"

components:
  button-primary:
    background: "token.colorPrimary"
    color: "#ffffff"
    border-radius: "token.borderRadius"
    height: "32px"
  button-default:
    background: "token.colorBgContainer"
    color: "token.colorText"
    border: "1px solid token.colorBorder"
    border-radius: "token.borderRadius"
    height: "32px"
  input:
    background: "token.colorBgContainer"
    border: "1px solid token.colorBorder"
    border-radius: "token.borderRadius"
    height: "token.controlHeight"
    color: "token.colorText"

---

## Overview

Ant Design is an enterprise-grade design system from Ant Financial (Ant Group), used across Alibaba, Tencent, Baidu, and other major Chinese tech companies. The system is built for **task efficiency in complex, data-heavy enterprise applications**. Its visual language is restrained and functional: color is used for information delivery, not identity; typography prioritizes legibility over expression; density is managed through an algorithmic compact mode.

The system is governed by four design values: **Natural** (intuitive interaction), **Certain** (predictable patterns), **Meaningful** (purpose-driven elements), **Growing** (scalable architecture). These values explain why the system is prescriptive — ambiguity slows enterprise development teams.

## Colors

Two-level color system: system-level (120 colors across 12 named hue palettes, each with 10 steps) and product-level (brand, functional, neutral).

**Color model:** HSB — used for team communication and color adjustment clarity.

**Brand color:** `#1677ff` (Daybreak Blue, step 6 of the blue palette). Step 6 is the primary anchor across all palettes.

**Functional colors** carry fixed semantic meaning — they must stay consistent to preserve user cognitive expectations:
- Success: Polar Green
- Error/Failure: Dust Red  
- Warning: Calendula Gold
- Info/Link: Daybreak Blue (same as brand)

**Neutral text:** Alpha values that adapt to background (`#000000E0` primary text in light, `#FFFFFFD9` in dark). Using alpha rather than fixed hex ensures correct appearance on non-white surfaces.

**Color philosophy:** Restrained. Color serves information delivery first. In information-dense enterprise UIs, competing accent colors create noise — functional colors (success/error/warning) must retain their signal value.

**Dark mode:** All semantic and neutral tokens have dark-mode values. Applied via `theme.darkAlgorithm` in ConfigProvider.

## Typography

System-native font stack including `Noto Sans` for CJK glyph coverage — no custom typeface loading.

Base: **14px** / 22px line height (1.57 ratio). Scale covers 10 steps from ~12px to ~38px.

Font weight guidance: 400 (body), 500 (emphasis), 600 (bold English only — **not for Chinese characters**, which lose legibility at heavier weights).

Typography principle: limit active type sizes to 3–5 per system. Proliferating sizes creates visual noise in enterprise UIs.

## Layout

Spacing follows a named-suffix token system: `XXS`, `XS`, `SM`, `MD` (base), `LG`, `XL`, `XXL`. Tokens consumed via `theme.useToken()` → `token.paddingMD`, `token.marginLG`, etc.

Control heights: `controlHeight` (32px default), `controlHeightLG` (40px), `controlHeightSM` (24px), `controlHeightXS` (16px).

Compact mode: `theme.compactAlgorithm` recalculates all control heights and spacing proportionally — this is the correct mechanism for density reduction, not per-component overrides.

Breakpoints: XS 480 | SM 576 | MD 768 | LG 992 | XL 1200 | XXL 1600.

## Elevation & Depth

Three shadow tokens: `boxShadow` (primary elevation — popovers, dropdowns), `boxShadowSecondary`, `boxShadowTertiary` (subtle). Elevation is expressed through shadow, not tonal surface fills (unlike Material Design).

## Shapes

Four radius tokens on a XS/SM/base/LG scale: 2px / 4px / 6px (default) / 8px. Set via `borderRadius` seed token in ConfigProvider — the algorithm derives the XS/SM/LG variants automatically.

## Components

All components consume tokens from the three-layer system (Seed → Map → Alias). Component-level token overrides are available through the `components` key in ConfigProvider:

```tsx
<ConfigProvider theme={{
  components: {
    Button: { colorPrimary: '#custom', algorithm: true }
  }
}}>
```

Standard button hierarchy: `type="primary"` (filled brand color) → `type="default"` (bordered) → `type="text"` (no border) → `type="link"` (link style).

## Do's and Don'ts

**Do:**
- Use seed tokens for global customization — `colorPrimary`, `borderRadius`, `fontSize` in ConfigProvider
- Use `theme.useToken()` to access tokens in custom components — don't hardcode hex values
- Use `compactAlgorithm` for density reduction — don't manually reduce heights per component
- Use `theme.darkAlgorithm` for dark mode — don't write separate dark stylesheets
- Apply `font-variant-numeric: tabular-nums` to financial/metric displays
- Keep functional colors (success/error/warning) consistent — their semantic meaning must be predictable

**Don't:**
- Don't use bold weight (600) for Chinese characters — use medium (500) at most
- Don't customize using raw CSS overrides — use the token system so dark/compact modes continue to work
- Don't use the same `colorPrimary` value for both brand and functional colors — functional colors have independent semantic meaning
- Don't proliferate type sizes — limit to 3–5 per system
- Don't use `ThemeEditor` in production — it's a dev-time tool