Ant Design DESIGN.md 深度解析v6 默认浅色主题的设计令牌体系与落地实现【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-designDESIGN.md 是 Ant Design 仓库根目录下的一份面向 AI 设计工具与人类开发者的设计语言描述文件它用 YAML front-matter 声明了 v6 默认浅色主题的全部视觉令牌颜色、字体、圆角、间距与 20 余个组件原型用正文阐述自然、确定、有意义、增长四大设计价值观背后的决策逻辑。读完本文你将掌握 Ant Design 默认主题的令牌全貌、种子令牌 → 派生算法 → 组件令牌的三层主题架构以及通过ConfigProvider.theme完成种子覆盖、算法切换、组件级定制与零运行时 CSS 提取的完整实操路径。DESIGN.md 是什么AI 可读的设计语言描述文件DESIGN.md 描述的正是Ant Design v6 的默认浅色主题light theme并采用语义化版本约束自身主版本v5 → v6代表设计语言的整体翻新而次版本与补丁版本内该文档保持稳定每次发布内的令牌漂移记录在 CHANGELOG.en-US.md 中。这份文件是开源设计系统 Ant Group 长期用于交付企业级软件——中后台控制台、仪表盘与运营工具——的视觉规范沉淀。它诞生于 2015 年的产品目标给大型产品团队一个共享且有立场的基础设施让高密度的数据界面不必在每一块画布上重新决策基础视觉问题。在仓库中这份文件与配套文档 design.md 中文指南、主题核心实现 components/theme/ 共同构成规范—实现—消费的闭环仓库也提供了 tests/design-md.test.ts 对其做回归验证。AI 设计工具如 Figma Make、Stitch 类工具可以直接读取该文件按 Ant Design 的视觉语言生成界面命令行方式可通过ant-design/cli的antd design.md支持--format json、--lang zh获取同一份内容详见 CLI 文档。四大设计价值观每个决策的裁决标准系统由四个价值观统领它们不仅是口号而是冲突时的裁决规则Natural自然界面遵循既有约定不让回访用户感到意外。操作系统与上一代企业软件中已经存在的模式优先于新发明。Certain确定用户始终知道当前处于什么状态、自己的输入产生了什么效果、下一步是什么。Hover、focus、loading、error 状态必须显式且一致。Meaningful有意义视觉强调只保留给行动。不传达信息的装饰一律移除。Growing增长系统能从小表单扩展到高密度表格、多租户管理控制台而不失去一致性。Do/Donts 中的第一条 Do 即呼应此点两个方案冲突时那个让用户状态更确定、更易读的方案胜出。颜色体系种子色展开、中性文本与预置色边界种子与派生调色板由 1 个primary品牌种子色、4 个语义状态种子success、warning、error、info以及中性基础色文本与表面构成。颜色种子会自动展开为覆盖背景浅染、hover、active、描边等变体的梯度阶梯——改一个种子整套派生调色板随之移动。这一机制在源码中直接可见defaultAlgorithm 的派生函数 调用ant-design/colors的generate()为每个预置色生成 10 级梯度genColorMapToken.ts 再从中取位映射出语义令牌例如colorPrimaryBg取主色阶梯第 1 级即#E6F4FF对应菜单选中背景、hover 取第 5 级#4096FF、active 取第 7 级#0958D9——与 DESIGN.md front-matter 中button-primary-hover: #4096FF、button-primary-active: #0958D9的取值一一对应。DESIGN.md 声明的完整颜色令牌如下摘自文件 YAML front-matter令牌值角色primary/info/blue#1677FF品牌主色动作、链接、聚焦环、选中导航、激活 Tabblue-7#0958D9主色深一档用于 active 态与 Tag 文字success/green#52C41A成功状态warning/gold#FAAD14警告状态error/red#FF4D4F/#F5222D错误状态purple/cyan/magenta/orange/yellow/volcano/geekblue/lime#722ED1/#13C2C2/#EB2F96/#FA8C16/#FADB14/#FA541C/#2F54EB/#A0D911预置分类色surface#FFFFFF容器表面bg-containersurface-container#FAFAFA表头/浅染容器surface-layout#F5F5F5页面背景bg-layouton-surface#1F1F1F主文本on-surface-variant#595959次要文本on-surface-disabled#BFBFBF占位/禁用outline/outline-variant#D9D9D9/#F0F0F0描边#1677FF被选为主色是因为蓝色传达可信、聚焦既没有深海军蓝的沉闷企业感也没有高饱和青色的轻浮感。中性文本为什么是 rgba 而不是灰度 hex运行时的令牌系统中中性文本与覆盖层颜色用rgba(0, 0, 0, α)表达而非扁平灰色 hex。原因是叠加性文本落在着色卡片或高亮单元格上时不透明灰色会切断底色而透明黑能自然融合。四个标准 α 阶梯为α用途白底合成等价 hex0.88主文本#1F1F1Fon-surface0.65次要文本#595959on-surface-variant0.45三级/说明文本—0.25占位/禁用#BFBFBFon-surface-disabled文档中的 hex 是白底上的合成结果供需要 hex 的静态导出目标使用支持 α 的下游消费方应优先使用ant-design/cssinjs输出的rgba()形式。可访问性与预置色边界DESIGN.md 明确记录了可访问性事实默认视觉令牌中白字配#1677FF、主文本配浅色选中背景等组合低于 WCAG AA 对小字号文本的 4.5:1 对比度门槛。若需严格达标应通过ConfigProvider加深colorPrimary或使用组件级令牌覆盖而不是发明一次性颜色。预置色blue~lime运行时时pink是magenta的弃用别名这一点在 default/index.ts 中以presetPalettes.pink presetPalettes.magenta向后兼容保留只保留给标签、图表与分类可视化绝不用于主 UI 交互。状态用功能色success/warning/error/infoprimary保留给每屏最重要的那一个动作。字体排印14px 基准与双字重纪律基准字号是14px 而非 16px。企业控制台用可读性余量换信息密度1440px 宽的窗口要同时容纳侧边栏、顶栏、八列数据表和详情面板在 14px 下正文行宽恰好在这些布局要求的栏宽内达到约 75 字符的视觉扫读甜区。字体栈按操作系统 UI 字体优先排序Apple 的-apple-system→BlinkMacSystemFont→ Windows 的Segoe UI→ Android/ChromeOS 的Roboto→Helvetica Neue→ArialNoto Sans兜底 LinuxEmoji 回退保持精简。代码字体按同序使用SFMono-Regular、Consolas、Liberation Mono、Menlo、Courier。产品界面只出现两个字重400正文、控件、菜单项、Tab 标签与 600fontWeightStrong——标题、表头及一切 title 级文本。细体100–300、粗体700与斜体不出现在界面外壳里——它们与系统追求的平静、确定基调相冲突斜体仅在长文档正文中可接受。选中/激活态的视觉强调来自颜色与描边border、underline而非字重。front-matter 中固化的字阶令牌全部继承 14px 基准派生令牌字号/字重/行高对应种子令牌display-lg38px / 600 / 46px—headline-lg30px / 600 / 38px—headline-md24px / 600 / 32pxfontSizeLG一档headline-sm20px / 600 / 28px—title-lg16px / 600 / 24px—title-md14px / 600 / 22pxfontSizefontWeightStrongbody-lg16px / 400 / 24px—body-md14px / 400 / 22pxfontSizebody-sm12px / 400 / 20pxfontSizeSMcode13px / 400 / 20px等宽栈fontFamilyCode行高并非拍脑袋源码 genFontSizes.ts 中行高统一按(fontSize 8) / fontSize计算14px → 22px 即 1.571与上表body-md一致字阶梯度则按base * E^(i/5)生成后取偶数对齐这是 front-matter 中 12/14/16/20/24/30/38 阶梯的来源。种子侧对应 seeds.ts 的fontFamily、fontFamilyCode、fontSize默认 14。布局4px 网格与三层表面模型所有间距对齐4px 网格。六阶间距比例unit、xs、sm、md、lg、xl→ 4 / 4 / 8 / 16 / 24 / 32px覆盖系统中的全部 gap、gutter 与 inset。魔法数字如padding: 11px、gap: 13px不允许出现在令牌驱动的代码中输入框 11px 水平内边距是唯一的例外——该设计早于 4px 网格迁移 1px 会牵动数百万存量屏幕因此保留为历史债。种子令牌对应 seeds.ts 中的sizeUnit默认 4、sizeStep默认 4与controlHeight默认 32派生尺寸梯度在 genSizeMapToken.ts 中按sizeUnit × (sizeStep ± n)公式生成sizeXXL48 →sizeXXS4。表面采用三层模型bg-layout#F5F5F5——页面背景环绕并承载其余一切bg-container#FFFFFF——卡片、面板、表格、表单的承载面大多数内容的居住地bg-elevated#FFFFFF与bg-container同 hex——弹窗、下拉、气泡的表面与bg-container的区分不靠颜色而靠阴影。规则明确永远不要在产品代码里硬编码#FFF或#FAFAFA读令牌。三层模型正是暗色主题算法能够翻转表面阶梯而不破坏布局的前提。高程与动效flat-first、阴影分级与三档时长Ant Design 是flat-first的层级主要靠描边与色调对比承载阴影只出现在真正悬浮于上下文之上的表面。阴影令牌从colorShadow生成因此同名令牌在明暗主题间自动适配。核心分级令牌名可在 alias.ts 中检索到类型定义TertiaryboxShadowTertiary——浅层抬升阴影0 1px 2px 0 rgba(0,0,0,0.05), 0 1px 6px -1px rgba(0,0,0,0.03), 0 2px 4px 0 rgba(0,0,0,0.03)PopupboxShadow与boxShadowSecondary——标准浮层阴影0 6px 16px 0 rgba(0,0,0,0.08), 0 3px 6px -4px rgba(0,0,0,0.12), 0 9px 28px 8px rgba(0,0,0,0.05)CardboxShadowCard——卡片专用的窄扩散抬升阴影用于卡片需要从容器中分离的场合方向性阴影boxShadowDrawer*、boxShadowTabsOverflow*——贴边表面与滚动暗示的专用令牌气泡箭头boxShadowPopoverArrow——仅用于 Tooltip/Popover 的小三角指针。动效使用三档时长加一组命名缓动全部以令牌形式暴露令牌时长适用场景motionDurationFast0.1s状态变化hover、focus、pressmotionDurationMid0.2s组件内部过渡collapse、fademotionDurationSlow0.3s表面级变化modal 进入、drawer 滑入缓动函数预定义为motionEaseInOut、motionEaseOut、motionEaseIn、motionEaseOutBack、motionEaseOutCirc等与 seeds.ts 中的motionUnit、motionBase及motionEase*种子一一对应。规则不要随手挑transition-timing-function若需求匹配不到已有缓动用motionEaseInOut然后继续。形状圆角的组件级纪律默认圆角是6px——足够圆以显得现代友好又足够小使 32px 高的按钮仍呈现干净的近矩形轮廓适配高密度表单。按组件类别的圆角规则对应 front-matter 的rounded令牌none0 /sm2 /md4 /DEFAULT6 /lg8 /xl16 /full9999px控件button、input、select、下拉触发器—— 6pxrounded.DEFAULT表面card、modal、drawer、notification—— 8pxrounded.lg标签与小胶囊—— 4pxrounded.mdTooltip 与 Popover—— 4pxrounded.md。全圆角rounded.full9999px保留给圆形头像、徽标与圆点不用于按钮或标签直角0px保留给表格与分段控件的内边缘。相邻元素混用圆角是坏味道8px 圆角的卡片里不应装 16px 圆角的按钮。组件原型最常见的表面与状态DESIGN.md 将系统中最常见的表面与状态固化为组件原型每个条目映射到 front-matter 中的令牌引用components段并给出使用纪律原型关键令牌规则Button (primary)实心primary填充、白字、32px 高、6px 圆角hover#4096FF、active#0958D9内边距0 15px每屏唯一主导动作不要在同一个决策面叠放两个 primary 按钮Button (default)白底暗字、1px 描边hover 文字变#4096FF、描边同色次级动作其余按钮降级到 defaultInput field32px 高与按钮对齐1px 描边focus 时描边加粗为primary并加内发光占位符用on-surface-disabled内边距4px 11px11px 水平内边距是 4px 网格前的历史保留值Select与 Input 视觉一致触发器在交互前必须看起来像输入框Card白色表面、8px 圆角、可选boxShadowCard内边距 24px容器主力嵌套控件保持 16px 间距Modal与 Card 同表面同圆角二级阴影层级居中于rgba(0,0,0,0.45)遮罩正文内边距 20px上下× 24px左右Menu选中项#E6F4FF背景、primary文字导航你在这里的唯一视觉线索Tabs激活项primary文字 2pxprimary下划线未激活为on-surface-variant任何状态下 Tab 都不带背景填充Table表头行surface-container背景、title-md14px/600、内边距 16px数据行仅 hover 高亮、默认不做斑马纹——系统信任用户能读密集数据Tag4px 圆角、12px 字、预置低饱和浅染填充、内边距0 7px仅做分类标签关键状态用 Alert 或 BadgeAlertsuccess/warning/error/info浅色语义底#F6FFED/#FFFBE6/#FFF2F0/#E6F4FF 正常文本色、8px 圆角、内边距8px 12px状态由图标与底色传达而非低对比度彩色正文Badge 状态点error实心、rounded.full、6×6px紧凑状态指示可访问性关键流程中圆点不能替代文字Tooltiprgba(0,0,0,0.85)底、白字、4px 圆角、内边距6px 8px高对比反色表面位置永远由框架决定禁止手动钉死Dropdown 项 hoversurface-container填充、文字色不变hover 提示本身已经足够Dos and Donts十条裁决规则DESIGN.md 给出的可执行纪律原文完整继承Do用四大设计价值观做裁决。两方案冲突时让用户状态更确定、更易读的方案胜出。Dont在同一表面叠放两个primary色按钮。只选一个其余降级为default。Do从colors.surface、colors.surface-container、colors.surface-layout读取表面。它们反映三层模型。Dont硬编码#FFFFFF或#FAFAFA。hex 是偶然的角色才是本质。Do对找不到更具体令牌的组件级过渡使用motionDurationMid0.2s。Dont发明自定义cubic-bezier曲线。用命名缓动。Do把预置色板blue~lime保留给标签、图表与分类可视化。Dont为一次性 UI 表面在预置色板之外铸新强调色。如果某个屏幕似乎需要它多半是布局需要重做。Do通过间距比例把每个 gap、inset、gutter 对齐到 4px 网格。Dont在产品代码里用魔法数字。若比例缺了你需要的档位该重新审视的是设计而不是 1px 覆盖。源码纵深DESIGN.md 令牌在 theme 模块中的实现链路DESIGN.md front-matter 中的每个值都是由defaultAlgorithm产出的默认值。从源码结构看这套主题机制分三层全部位于 components/theme/种子层Seed Tokenseeds.ts 定义了SeedToken接口——colorPrimary、colorSuccess、colorWarning、colorError、colorInfo、colorTextBase、colorBgBase、colorLink、fontFamily、fontFamilyCode、fontSize、lineWidth、borderRadius、sizeUnit、sizeStep、controlHeight、zIndexBase、zIndexPopupBase、opacityImage、motionUnit、motionBase、motionEase*族以及风格开关wireframe默认 false、focusOutline默认 true、motion默认 true。文件顶部的注释写着 DO NOT MODIFY THIS. PLEASE CONTACT DESIGNER——种子层是设计系统最不容越权的边界。派生层Map/Alias Tokendefault/index.ts 的derivative()依次执行预置色 10 级展开generate()→genColorMapToken主色/语义色/中性色映射→genFontMapToken字阶→genSizeMapToken尺寸梯度→genControlHeight控件高度梯度→genCommonMapToken阴影、zIndex、动效等。中性色由generateNeutralColorPalettes(colorBgBase, colorTextBase)生成即正文中 rgba(0,0,0,α) 阶梯 的实现来源。darkAlgorithmcomponents/theme/themes/dark/与compactAlgorithm复用同一骨架例如 compact 的 derivative 把字号基准降到fontSizeSM12px并令controlHeight - 428px再重算尺寸与字阶梯度。消费层components/theme/index.tsx 以单个theme对象对外导出defaultSeed、useToken、defaultAlgorithm、darkAlgorithm、compactAlgorithm与getDesignTokenuseToken是 React 内的令牌消费入口getDesignToken.ts 提供 React 之外如 SSR、脚本按ThemeConfig解析令牌的纯函数路径。cssVar与zeroRuntime开关则定义在 context.ts 中前者让样式以 CSS 变量输出后者在禁用运行时样式生成时与预构建/提取的 CSS 配合使用。令牌派生的正确性由 components/theme/tests/token.test.tsx 回归守护。定制指南五层官方主题能力DESIGN.md 的 Customization 一节指出Ant Design 的主题化远不止 Design Token 替换它包含算法派生、组件作用域覆盖、动态切换、嵌套主题作用域、CSS 变量输出、静态令牌消费与零运行时 CSS 提取。主入口是ConfigProvider的theme属性完整运行时 API 见 Customize Theme 中文文档种子令牌覆盖。向ConfigProvider传theme.token即可替换任意种子。主色与语义种子colorPrimary、colorSuccess、colorWarning、colorError、colorInfo会展开为派生梯度colorBgBase与colorTextBase驱动中性表面与文本间距、圆角、字号种子同理。算法切换。theme.algorithm用于替换派生逻辑。defaultAlgorithm、darkAlgorithm、compactAlgorithm可单独使用也可以数组形式组合——不要手动反色算法负责处理非线性色板、表面、阴影与尺寸关系对应源码中三个DerivativeFunc的组合调用。组件级覆盖。theme.components.Button或任意组件的令牌命名空间可只覆盖单个组件的 Component Token 与被消费的 Alias Token 而不影响其他组件组件配置中的algorithm可让该组件在覆盖时仍遵循种子令牌关系。运行时作用域。改ConfigProvider.theme即可动态切换主题嵌套ConfigProvider创建局部主题并从父级继承未改动的令牌。注意message.xxx、Modal.xxx、notification.xxx等静态 API不会自动获得外层上下文需要主题化静态反馈时应使用 hook 形式 API、App组件或显式的上下文持有者。令牌消费与输出。React 内用theme.useToken()React 外用theme.getDesignToken()消费解析后的令牌需要 CSS 变量时用theme.cssVar必须禁用运行时样式生成时用theme.zeroRuntime配合预构建或提取的 CSS。最后一条定制纪律值得原样保留做自定义主题时先保住 Ant Design 的交互结构、密度、状态反馈与组件语义再改动最小的种子集——通常就是colorPrimary、状态色、borderRadius、fontFamily、fontSize与中性表面基础色。品牌页可以看起来不同但表单、表格、导航、浮层、聚焦态与校验反馈必须仍然像 Ant Design。避免生成绕过令牌、算法、theme.components、CSS 变量或提取静态样式的自定义 CSS 规则如果一个主题无法通过上述官方层表达应把它当作设计系统的扩展需求而不是某页的一次性样式。小结DESIGN.md 把 Ant Design v6 默认浅色主题压缩为一份机器可读、人类可执行的契约颜色上种子决定梯度、角色先于 hex字体上14px 基准 双字重纪律布局上4px 网格 三层表面高程上flat-first 命名阴影与缓动形状上圆角按组件类别分配。仓库中的 components/theme/ 实现与 tests/design-md.test.ts 回归测试则证明这份契约不是纸面规范而是被defaultSeed→defaultAlgorithm→useToken全链路执行的活代码——这正是它既能约束人类开发、又能驱动 AI 设计工具的原因。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ant Design DESIGN.md 深度解析：v6 默认浅色主题的设计令牌体系与落地实现
Ant Design DESIGN.md 深度解析v6 默认浅色主题的设计令牌体系与落地实现【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-designDESIGN.md 是 Ant Design 仓库根目录下的一份面向 AI 设计工具与人类开发者的设计语言描述文件它用 YAML front-matter 声明了 v6 默认浅色主题的全部视觉令牌颜色、字体、圆角、间距与 20 余个组件原型用正文阐述自然、确定、有意义、增长四大设计价值观背后的决策逻辑。读完本文你将掌握 Ant Design 默认主题的令牌全貌、种子令牌 → 派生算法 → 组件令牌的三层主题架构以及通过ConfigProvider.theme完成种子覆盖、算法切换、组件级定制与零运行时 CSS 提取的完整实操路径。DESIGN.md 是什么AI 可读的设计语言描述文件DESIGN.md 描述的正是Ant Design v6 的默认浅色主题light theme并采用语义化版本约束自身主版本v5 → v6代表设计语言的整体翻新而次版本与补丁版本内该文档保持稳定每次发布内的令牌漂移记录在 CHANGELOG.en-US.md 中。这份文件是开源设计系统 Ant Group 长期用于交付企业级软件——中后台控制台、仪表盘与运营工具——的视觉规范沉淀。它诞生于 2015 年的产品目标给大型产品团队一个共享且有立场的基础设施让高密度的数据界面不必在每一块画布上重新决策基础视觉问题。在仓库中这份文件与配套文档 design.md 中文指南、主题核心实现 components/theme/ 共同构成规范—实现—消费的闭环仓库也提供了 tests/design-md.test.ts 对其做回归验证。AI 设计工具如 Figma Make、Stitch 类工具可以直接读取该文件按 Ant Design 的视觉语言生成界面命令行方式可通过ant-design/cli的antd design.md支持--format json、--lang zh获取同一份内容详见 CLI 文档。四大设计价值观每个决策的裁决标准系统由四个价值观统领它们不仅是口号而是冲突时的裁决规则Natural自然界面遵循既有约定不让回访用户感到意外。操作系统与上一代企业软件中已经存在的模式优先于新发明。Certain确定用户始终知道当前处于什么状态、自己的输入产生了什么效果、下一步是什么。Hover、focus、loading、error 状态必须显式且一致。Meaningful有意义视觉强调只保留给行动。不传达信息的装饰一律移除。Growing增长系统能从小表单扩展到高密度表格、多租户管理控制台而不失去一致性。Do/Donts 中的第一条 Do 即呼应此点两个方案冲突时那个让用户状态更确定、更易读的方案胜出。颜色体系种子色展开、中性文本与预置色边界种子与派生调色板由 1 个primary品牌种子色、4 个语义状态种子success、warning、error、info以及中性基础色文本与表面构成。颜色种子会自动展开为覆盖背景浅染、hover、active、描边等变体的梯度阶梯——改一个种子整套派生调色板随之移动。这一机制在源码中直接可见defaultAlgorithm 的派生函数 调用ant-design/colors的generate()为每个预置色生成 10 级梯度genColorMapToken.ts 再从中取位映射出语义令牌例如colorPrimaryBg取主色阶梯第 1 级即#E6F4FF对应菜单选中背景、hover 取第 5 级#4096FF、active 取第 7 级#0958D9——与 DESIGN.md front-matter 中button-primary-hover: #4096FF、button-primary-active: #0958D9的取值一一对应。DESIGN.md 声明的完整颜色令牌如下摘自文件 YAML front-matter令牌值角色primary/info/blue#1677FF品牌主色动作、链接、聚焦环、选中导航、激活 Tabblue-7#0958D9主色深一档用于 active 态与 Tag 文字success/green#52C41A成功状态warning/gold#FAAD14警告状态error/red#FF4D4F/#F5222D错误状态purple/cyan/magenta/orange/yellow/volcano/geekblue/lime#722ED1/#13C2C2/#EB2F96/#FA8C16/#FADB14/#FA541C/#2F54EB/#A0D911预置分类色surface#FFFFFF容器表面bg-containersurface-container#FAFAFA表头/浅染容器surface-layout#F5F5F5页面背景bg-layouton-surface#1F1F1F主文本on-surface-variant#595959次要文本on-surface-disabled#BFBFBF占位/禁用outline/outline-variant#D9D9D9/#F0F0F0描边#1677FF被选为主色是因为蓝色传达可信、聚焦既没有深海军蓝的沉闷企业感也没有高饱和青色的轻浮感。中性文本为什么是 rgba 而不是灰度 hex运行时的令牌系统中中性文本与覆盖层颜色用rgba(0, 0, 0, α)表达而非扁平灰色 hex。原因是叠加性文本落在着色卡片或高亮单元格上时不透明灰色会切断底色而透明黑能自然融合。四个标准 α 阶梯为α用途白底合成等价 hex0.88主文本#1F1F1Fon-surface0.65次要文本#595959on-surface-variant0.45三级/说明文本—0.25占位/禁用#BFBFBFon-surface-disabled文档中的 hex 是白底上的合成结果供需要 hex 的静态导出目标使用支持 α 的下游消费方应优先使用ant-design/cssinjs输出的rgba()形式。可访问性与预置色边界DESIGN.md 明确记录了可访问性事实默认视觉令牌中白字配#1677FF、主文本配浅色选中背景等组合低于 WCAG AA 对小字号文本的 4.5:1 对比度门槛。若需严格达标应通过ConfigProvider加深colorPrimary或使用组件级令牌覆盖而不是发明一次性颜色。预置色blue~lime运行时时pink是magenta的弃用别名这一点在 default/index.ts 中以presetPalettes.pink presetPalettes.magenta向后兼容保留只保留给标签、图表与分类可视化绝不用于主 UI 交互。状态用功能色success/warning/error/infoprimary保留给每屏最重要的那一个动作。字体排印14px 基准与双字重纪律基准字号是14px 而非 16px。企业控制台用可读性余量换信息密度1440px 宽的窗口要同时容纳侧边栏、顶栏、八列数据表和详情面板在 14px 下正文行宽恰好在这些布局要求的栏宽内达到约 75 字符的视觉扫读甜区。字体栈按操作系统 UI 字体优先排序Apple 的-apple-system→BlinkMacSystemFont→ Windows 的Segoe UI→ Android/ChromeOS 的Roboto→Helvetica Neue→ArialNoto Sans兜底 LinuxEmoji 回退保持精简。代码字体按同序使用SFMono-Regular、Consolas、Liberation Mono、Menlo、Courier。产品界面只出现两个字重400正文、控件、菜单项、Tab 标签与 600fontWeightStrong——标题、表头及一切 title 级文本。细体100–300、粗体700与斜体不出现在界面外壳里——它们与系统追求的平静、确定基调相冲突斜体仅在长文档正文中可接受。选中/激活态的视觉强调来自颜色与描边border、underline而非字重。front-matter 中固化的字阶令牌全部继承 14px 基准派生令牌字号/字重/行高对应种子令牌display-lg38px / 600 / 46px—headline-lg30px / 600 / 38px—headline-md24px / 600 / 32pxfontSizeLG一档headline-sm20px / 600 / 28px—title-lg16px / 600 / 24px—title-md14px / 600 / 22pxfontSizefontWeightStrongbody-lg16px / 400 / 24px—body-md14px / 400 / 22pxfontSizebody-sm12px / 400 / 20pxfontSizeSMcode13px / 400 / 20px等宽栈fontFamilyCode行高并非拍脑袋源码 genFontSizes.ts 中行高统一按(fontSize 8) / fontSize计算14px → 22px 即 1.571与上表body-md一致字阶梯度则按base * E^(i/5)生成后取偶数对齐这是 front-matter 中 12/14/16/20/24/30/38 阶梯的来源。种子侧对应 seeds.ts 的fontFamily、fontFamilyCode、fontSize默认 14。布局4px 网格与三层表面模型所有间距对齐4px 网格。六阶间距比例unit、xs、sm、md、lg、xl→ 4 / 4 / 8 / 16 / 24 / 32px覆盖系统中的全部 gap、gutter 与 inset。魔法数字如padding: 11px、gap: 13px不允许出现在令牌驱动的代码中输入框 11px 水平内边距是唯一的例外——该设计早于 4px 网格迁移 1px 会牵动数百万存量屏幕因此保留为历史债。种子令牌对应 seeds.ts 中的sizeUnit默认 4、sizeStep默认 4与controlHeight默认 32派生尺寸梯度在 genSizeMapToken.ts 中按sizeUnit × (sizeStep ± n)公式生成sizeXXL48 →sizeXXS4。表面采用三层模型bg-layout#F5F5F5——页面背景环绕并承载其余一切bg-container#FFFFFF——卡片、面板、表格、表单的承载面大多数内容的居住地bg-elevated#FFFFFF与bg-container同 hex——弹窗、下拉、气泡的表面与bg-container的区分不靠颜色而靠阴影。规则明确永远不要在产品代码里硬编码#FFF或#FAFAFA读令牌。三层模型正是暗色主题算法能够翻转表面阶梯而不破坏布局的前提。高程与动效flat-first、阴影分级与三档时长Ant Design 是flat-first的层级主要靠描边与色调对比承载阴影只出现在真正悬浮于上下文之上的表面。阴影令牌从colorShadow生成因此同名令牌在明暗主题间自动适配。核心分级令牌名可在 alias.ts 中检索到类型定义TertiaryboxShadowTertiary——浅层抬升阴影0 1px 2px 0 rgba(0,0,0,0.05), 0 1px 6px -1px rgba(0,0,0,0.03), 0 2px 4px 0 rgba(0,0,0,0.03)PopupboxShadow与boxShadowSecondary——标准浮层阴影0 6px 16px 0 rgba(0,0,0,0.08), 0 3px 6px -4px rgba(0,0,0,0.12), 0 9px 28px 8px rgba(0,0,0,0.05)CardboxShadowCard——卡片专用的窄扩散抬升阴影用于卡片需要从容器中分离的场合方向性阴影boxShadowDrawer*、boxShadowTabsOverflow*——贴边表面与滚动暗示的专用令牌气泡箭头boxShadowPopoverArrow——仅用于 Tooltip/Popover 的小三角指针。动效使用三档时长加一组命名缓动全部以令牌形式暴露令牌时长适用场景motionDurationFast0.1s状态变化hover、focus、pressmotionDurationMid0.2s组件内部过渡collapse、fademotionDurationSlow0.3s表面级变化modal 进入、drawer 滑入缓动函数预定义为motionEaseInOut、motionEaseOut、motionEaseIn、motionEaseOutBack、motionEaseOutCirc等与 seeds.ts 中的motionUnit、motionBase及motionEase*种子一一对应。规则不要随手挑transition-timing-function若需求匹配不到已有缓动用motionEaseInOut然后继续。形状圆角的组件级纪律默认圆角是6px——足够圆以显得现代友好又足够小使 32px 高的按钮仍呈现干净的近矩形轮廓适配高密度表单。按组件类别的圆角规则对应 front-matter 的rounded令牌none0 /sm2 /md4 /DEFAULT6 /lg8 /xl16 /full9999px控件button、input、select、下拉触发器—— 6pxrounded.DEFAULT表面card、modal、drawer、notification—— 8pxrounded.lg标签与小胶囊—— 4pxrounded.mdTooltip 与 Popover—— 4pxrounded.md。全圆角rounded.full9999px保留给圆形头像、徽标与圆点不用于按钮或标签直角0px保留给表格与分段控件的内边缘。相邻元素混用圆角是坏味道8px 圆角的卡片里不应装 16px 圆角的按钮。组件原型最常见的表面与状态DESIGN.md 将系统中最常见的表面与状态固化为组件原型每个条目映射到 front-matter 中的令牌引用components段并给出使用纪律原型关键令牌规则Button (primary)实心primary填充、白字、32px 高、6px 圆角hover#4096FF、active#0958D9内边距0 15px每屏唯一主导动作不要在同一个决策面叠放两个 primary 按钮Button (default)白底暗字、1px 描边hover 文字变#4096FF、描边同色次级动作其余按钮降级到 defaultInput field32px 高与按钮对齐1px 描边focus 时描边加粗为primary并加内发光占位符用on-surface-disabled内边距4px 11px11px 水平内边距是 4px 网格前的历史保留值Select与 Input 视觉一致触发器在交互前必须看起来像输入框Card白色表面、8px 圆角、可选boxShadowCard内边距 24px容器主力嵌套控件保持 16px 间距Modal与 Card 同表面同圆角二级阴影层级居中于rgba(0,0,0,0.45)遮罩正文内边距 20px上下× 24px左右Menu选中项#E6F4FF背景、primary文字导航你在这里的唯一视觉线索Tabs激活项primary文字 2pxprimary下划线未激活为on-surface-variant任何状态下 Tab 都不带背景填充Table表头行surface-container背景、title-md14px/600、内边距 16px数据行仅 hover 高亮、默认不做斑马纹——系统信任用户能读密集数据Tag4px 圆角、12px 字、预置低饱和浅染填充、内边距0 7px仅做分类标签关键状态用 Alert 或 BadgeAlertsuccess/warning/error/info浅色语义底#F6FFED/#FFFBE6/#FFF2F0/#E6F4FF 正常文本色、8px 圆角、内边距8px 12px状态由图标与底色传达而非低对比度彩色正文Badge 状态点error实心、rounded.full、6×6px紧凑状态指示可访问性关键流程中圆点不能替代文字Tooltiprgba(0,0,0,0.85)底、白字、4px 圆角、内边距6px 8px高对比反色表面位置永远由框架决定禁止手动钉死Dropdown 项 hoversurface-container填充、文字色不变hover 提示本身已经足够Dos and Donts十条裁决规则DESIGN.md 给出的可执行纪律原文完整继承Do用四大设计价值观做裁决。两方案冲突时让用户状态更确定、更易读的方案胜出。Dont在同一表面叠放两个primary色按钮。只选一个其余降级为default。Do从colors.surface、colors.surface-container、colors.surface-layout读取表面。它们反映三层模型。Dont硬编码#FFFFFF或#FAFAFA。hex 是偶然的角色才是本质。Do对找不到更具体令牌的组件级过渡使用motionDurationMid0.2s。Dont发明自定义cubic-bezier曲线。用命名缓动。Do把预置色板blue~lime保留给标签、图表与分类可视化。Dont为一次性 UI 表面在预置色板之外铸新强调色。如果某个屏幕似乎需要它多半是布局需要重做。Do通过间距比例把每个 gap、inset、gutter 对齐到 4px 网格。Dont在产品代码里用魔法数字。若比例缺了你需要的档位该重新审视的是设计而不是 1px 覆盖。源码纵深DESIGN.md 令牌在 theme 模块中的实现链路DESIGN.md front-matter 中的每个值都是由defaultAlgorithm产出的默认值。从源码结构看这套主题机制分三层全部位于 components/theme/种子层Seed Tokenseeds.ts 定义了SeedToken接口——colorPrimary、colorSuccess、colorWarning、colorError、colorInfo、colorTextBase、colorBgBase、colorLink、fontFamily、fontFamilyCode、fontSize、lineWidth、borderRadius、sizeUnit、sizeStep、controlHeight、zIndexBase、zIndexPopupBase、opacityImage、motionUnit、motionBase、motionEase*族以及风格开关wireframe默认 false、focusOutline默认 true、motion默认 true。文件顶部的注释写着 DO NOT MODIFY THIS. PLEASE CONTACT DESIGNER——种子层是设计系统最不容越权的边界。派生层Map/Alias Tokendefault/index.ts 的derivative()依次执行预置色 10 级展开generate()→genColorMapToken主色/语义色/中性色映射→genFontMapToken字阶→genSizeMapToken尺寸梯度→genControlHeight控件高度梯度→genCommonMapToken阴影、zIndex、动效等。中性色由generateNeutralColorPalettes(colorBgBase, colorTextBase)生成即正文中 rgba(0,0,0,α) 阶梯 的实现来源。darkAlgorithmcomponents/theme/themes/dark/与compactAlgorithm复用同一骨架例如 compact 的 derivative 把字号基准降到fontSizeSM12px并令controlHeight - 428px再重算尺寸与字阶梯度。消费层components/theme/index.tsx 以单个theme对象对外导出defaultSeed、useToken、defaultAlgorithm、darkAlgorithm、compactAlgorithm与getDesignTokenuseToken是 React 内的令牌消费入口getDesignToken.ts 提供 React 之外如 SSR、脚本按ThemeConfig解析令牌的纯函数路径。cssVar与zeroRuntime开关则定义在 context.ts 中前者让样式以 CSS 变量输出后者在禁用运行时样式生成时与预构建/提取的 CSS 配合使用。令牌派生的正确性由 components/theme/tests/token.test.tsx 回归守护。定制指南五层官方主题能力DESIGN.md 的 Customization 一节指出Ant Design 的主题化远不止 Design Token 替换它包含算法派生、组件作用域覆盖、动态切换、嵌套主题作用域、CSS 变量输出、静态令牌消费与零运行时 CSS 提取。主入口是ConfigProvider的theme属性完整运行时 API 见 Customize Theme 中文文档种子令牌覆盖。向ConfigProvider传theme.token即可替换任意种子。主色与语义种子colorPrimary、colorSuccess、colorWarning、colorError、colorInfo会展开为派生梯度colorBgBase与colorTextBase驱动中性表面与文本间距、圆角、字号种子同理。算法切换。theme.algorithm用于替换派生逻辑。defaultAlgorithm、darkAlgorithm、compactAlgorithm可单独使用也可以数组形式组合——不要手动反色算法负责处理非线性色板、表面、阴影与尺寸关系对应源码中三个DerivativeFunc的组合调用。组件级覆盖。theme.components.Button或任意组件的令牌命名空间可只覆盖单个组件的 Component Token 与被消费的 Alias Token 而不影响其他组件组件配置中的algorithm可让该组件在覆盖时仍遵循种子令牌关系。运行时作用域。改ConfigProvider.theme即可动态切换主题嵌套ConfigProvider创建局部主题并从父级继承未改动的令牌。注意message.xxx、Modal.xxx、notification.xxx等静态 API不会自动获得外层上下文需要主题化静态反馈时应使用 hook 形式 API、App组件或显式的上下文持有者。令牌消费与输出。React 内用theme.useToken()React 外用theme.getDesignToken()消费解析后的令牌需要 CSS 变量时用theme.cssVar必须禁用运行时样式生成时用theme.zeroRuntime配合预构建或提取的 CSS。最后一条定制纪律值得原样保留做自定义主题时先保住 Ant Design 的交互结构、密度、状态反馈与组件语义再改动最小的种子集——通常就是colorPrimary、状态色、borderRadius、fontFamily、fontSize与中性表面基础色。品牌页可以看起来不同但表单、表格、导航、浮层、聚焦态与校验反馈必须仍然像 Ant Design。避免生成绕过令牌、算法、theme.components、CSS 变量或提取静态样式的自定义 CSS 规则如果一个主题无法通过上述官方层表达应把它当作设计系统的扩展需求而不是某页的一次性样式。小结DESIGN.md 把 Ant Design v6 默认浅色主题压缩为一份机器可读、人类可执行的契约颜色上种子决定梯度、角色先于 hex字体上14px 基准 双字重纪律布局上4px 网格 三层表面高程上flat-first 命名阴影与缓动形状上圆角按组件类别分配。仓库中的 components/theme/ 实现与 tests/design-md.test.ts 回归测试则证明这份契约不是纸面规范而是被defaultSeed→defaultAlgorithm→useToken全链路执行的活代码——这正是它既能约束人类开发、又能驱动 AI 设计工具的原因。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考