前端UI组件设计系统【免费下载链接】blueprintA React-based UI toolkit for the web项目地址https://gitcode.com/gh_mirrors/bl/blueprint点击查看免费下载Blueprint 是 Palantir 开源的一套 React UI 工具集而设计令牌Design Tokens正是其视觉语言体系的单一事实来源。本文基于 packages/core/src/design-tokens/README.md 与 packages/core/src/design-tokens/USAGE.md结合仓库内真实的构建配置与组件消费代码系统讲解 Blueprint 设计令牌从 JSON 定义、Style Dictionary 编译到 CSS 自定义属性--bp-*落地再到 Button 等组件消费的完整链路。读完本文你将掌握令牌目录结构、DTCG 标准属性、com.blueprint.derive派生扩展、dark 主题覆盖机制、渐进增强输出策略以及如何在自有组件中正确使用 surface / intent / typography 令牌实现跨主题一致渲染。注意当前设计令牌体系在仓库中被标记为EXPERIMENTAL属于演进中的下一代BP6/BP7视觉基础设施随版本迭代 API 与生成产物可能调整使用时应关注包内 changelog。一、Design Tokens 是什么一套以 CSS 变量为载体的令牌体系Blueprint 设计令牌由 Style Dictionary 驱动生成。其核心思想是以 JSON 文件定义颜色、尺寸、阴影、字体等所有视觉原子值编译为带--bp-前缀的 CSS 自定义属性挂载在:root上组件与业务代码统一通过var(--bp-...)消费从而在 light / dark 等不同配色方案之间保持一致的主题化体验无需在每个组件里重复硬编码样式逻辑。使用方式极其简单——令牌在:root上以 CSS 自定义属性形式可用.element { color: var(--bp-typography-color-default-rest); background: var(--bp-surface-background-color-default-rest); border-radius: var(--bp-surface-border-radius); padding: calc(var(--bp-surface-spacing) * 2); }从源码结构看令牌体系由三部分组成详见 tokens 目录tokens/base/5 个基础令牌文件——palette调色板、intent语义意图色、surface表面结构、typography排版、emphasis焦点/动效tokens/themes/dark/dark 主题覆盖文件当前仅 dark 一组tokens/next/面向未来版本的占位调色板palette.bp7。二、Token 分类总览六大命名空间所有令牌通过统一前缀分类一目了然分类前缀说明Palette--bp-palette-*原始色值gray、blue、green 等Intent--bp-intent-*语义色primary、success、warning、dangerSurface--bp-surface-*背景、边框、阴影、间距、z-indexTypography--bp-typography-*字体族、字号、字重、行高、颜色Iconography--bp-iconography-*图标尺寸与颜色Emphasis--bp-emphasis-*焦点环、过渡、缓动曲线其中Iconography命名空间在 tokens/base 现有 5 个文件中的定义相对独立而 Emphasis 的完整定义可参考 emphasis.tokens.json包含transition-duration100ms、ease[0.4, 1, 0.75, 0.9]与 bounce 曲线、focus-color引用{intent.primary.rest}、focus-width2px、focus-offset2px以及motion-reduced开关0 允许动效1 减少动效。三、Token 结构与 DTCG 规范令牌遵循 DTCGDesign Tokens Community Group 规范。每个令牌使用以下标准属性属性用途$type数据类型color、dimension、shadow、fontFamily、fontWeight、number、duration、cubicBezier$value令牌值——字面量、引用如{palette.blue.3}或复杂对象如 shadow 的多层结构$description人类可读的说明文字$extensions自定义 Blueprint 元数据DTCG 的复杂类型color / shadow / dimension在仓库中均以结构化对象表达。例如 surface.tokens.json 中的border-width是{ value: 1, unit: px }的 dimension 对象而shadow.0是一个由多个 sRGB 颜色层组成的 shadow 数组每层含offsetX、offsetY、blur、spread、color。这与 sd.config.ts 中定义的DTCGColor、DTCGDimension、DTCGShadow类型一一对应构建时会由解析器逐一校验后格式化为 CSS 字符串。四、自定义扩展com.blueprint.derive 与 com.blueprint.role4.1 com.blueprint.derive基于 OKLCH 的颜色派生com.blueprint.derive用于从被引用的$value派生新颜色在 OKLCH 色彩空间上执行通道变换{ $value: {intent.default.rest}, $extensions: { com.blueprint.derive: { alpha: 0.25 } } }可用派生属性如下对应 sd.config.ts 的parseColorDerivation/parseChannelModification解析逻辑属性类型作用alphanumber 或令牌引用覆盖最终透明度可以是字面量如0.25也可以是引用如{surface.layer-opacity}构建时解析为数字lightnessScale/lightnessOffsetnumber对 L 通道做乘法缩放 / 加法偏移chromaScale/chromaOffsetnumber对 C 通道做乘法缩放 / 加法偏移hueOffsetnumber对 H 通道做加法偏移这些属性在构建期被用于产出双通道结果一个是静态 hex 回退值供不支持相对颜色语法的浏览器使用一个是相对颜色语法表达式oklch(from ...)。以 surface 边框为例base 中border-color.default派生自{intent.default.rest}且alpha: 0.12而border-color.strong使用alpha: 0.25见 surface.tokens.json对应了 README 中subtle border / more prominent border的语义分级。从 sd.config.ts 的deriveTransformConfig可以看出底层实现转换器保留原始 token 引用original.$value将其改写为var(--bp-...)基变量再按派生配置拼装oklch(from baseVar calc(l ± n) calc(c * m) calc(h n) / alpha)。同时 computeStaticFallbackForDerivedToken 会先把基令牌解析为 OKLCH借助 culori 库套用通道修改后格式化为 hex作为supports之外的静态回退。4.2 com.blueprint.role特殊构建角色com.blueprint.role为令牌指定特殊构建处理。当前只有一个角色stackable-layer—— 将编译后的颜色包装进linear-gradient(color 0 0)使其可以作为background-image图层进行叠加合成。该角色在 applyRoleForCss 中实现为linear-gradient(${value} 0 0)。动机是CSS 的background-color只能接受单一值而background-image支持多层叠加linear-gradient(color 0 0)制造一个纯色渐变从而可以在背景色之上堆叠半透明色层。五、主题覆盖dark 模式如何工作dark 主题通过tokens/themes/dark/下的文件覆盖 base 令牌覆盖方式为重新定义$value和/或$extensions。README 中的经典示例是surface.border-color.strong浅色模式基于灰色派生深色模式改为基于白色派生// base/surface.tokens.json strong: { $value: {intent.default.rest}, $extensions: { com.blueprint.derive: { alpha: 0.25 } } } // themes/dark/surface.tokens.json strong: { $value: {palette.white}, $extensions: { com.blueprint.derive: { alpha: 0.3 } } }仓库中 dark/surface.tokens.json 的实际定义与此一致border-color.default为白色 20% alpha、strong为白色 30% alphacolor-code从浅色的白色 70% 反转为黑色 30%阴影体系也整体替换为白色 inset 高亮 更深黑色投影shadow-0 至 shadow-4 每级都含inset: true的白色描边层。5.1 两个主题的构建配置主题构建计划定义在 sd.config.ts 的THEMES常量中主题输入选择器输出文件lighttokens/base/**/*.tokens.json:roottokens.cssdarkbaseincludetokens/themes/dark/**/*.tokens.json[data-bp-color-schemedark], .bp6-darktokens-dark.cssdark 配置使用include继承 base 全部令牌再以sources覆盖。生成时 dark 主题被挂载到[data-bp-color-schemedark]属性选择器同时兼容传统.bp6-dark类名因此只需在根元素上切换该属性或类名即可整体换肤组件代码无需任何改动——这正是 USAGE.md 强调的Surface tokens adapt automatically by theme。六、构建流水线从 JSON 到 CSS 变量6.1 构建命令在 packages/core/package.json 中定义pnpm run build:tokens # tsx src/design-tokens/build.ts生成 tokens该命令执行tsx src/design-tokens/build.ts构建入口调用 sd.config.ts 的buildAllThemes产物输出到src/design-tokens/build/tokens.css与tokens-dark.css。此外compile:css脚本会先跑build:tokens再执行 sass 编译确保组件 SCSS 中引用的--bp-*变量在样式编译前已生成。6.2 转换器与命名Style Dictionary 初始化时注册了一套bp/css转换组见 initializeStyleDictionary按序执行name/bp/kebab命名转换将令牌路径拼成bp-前缀的 kebab-case 变量名见 nameTransformConfig如surface.border-radius→--bp-surface-border-radiusdtcg/color/css将 DTCG color 对象格式化为oklch()/rgb()/rgba()CSS 函数sRGB 通道会round(comp * 255)dtcg/dimension/css、dtcg/duration/css格式化为16px、100ms这类带单位字符串dtcg/fontFamily/css数组拼成font-family列表含空格的字体名自动加引号dtcg/fontWeight/css、dtcg/number/css、dtcg/cubicBezier/css数值直出dtcg/shadow/css支持单层与多层数组shadow输出为box-shadow值bp/derive/css必须排在 color 转换之后用相对颜色语法覆盖已解析的颜色引用。6.3 渐进增强输出hex 回退 supports这是整套体系最有特色的部分formatProgressiveEnhancementCss生成产物包含两个区块——先输出一个所有令牌的 hex 基础块再输出一个supports增强块用相对颜色语法覆盖派生类令牌基础块全部令牌以静态 hex 值输出派生令牌由computeStaticFallbackForDerivedToken预先计算增强块supports (color: oklch(from var(--any-color) l c h))内把派生令牌重新声明为oklch(from ...)表达式。回退值采用两遍收集第一遍处理带derive扩展的令牌第二遍处理传递引用了派生令牌的令牌借助 fallback 缓存见 makeFallbackMap。supports探测条件常量定义于 SUPPORTS_RELATIVE_COLOR与组件 SCSS 中手动书写的supports (color: oklch(from var(--any-color) l c h))完全一致可对照 button/_common.scss。七、Intent 令牌语义与交互状态的映射Intent 令牌把语义含义映射到颜色上。组件不直接引用原始调色板如--bp-palette-blue-3而是引用--bp-intent-primary-rest这样每个主题或品牌都可以重映射。五种意图定义于 intent.tokens.json每种都带交互状态rest、hover、active、disabled外加foreground文字色Token 模式状态示例解析--bp-intent-default-*rest、hover、active、disabledrest→palette.gray.1--bp-intent-primary-*同上rest→palette.blue.3--bp-intent-success-*同上rest→palette.green.3--bp-intent-warning-*同上rest→palette.orange.3--bp-intent-danger-*同上rest→palette.red.3实际 JSON 中default 意图的hover/active分别指向palette.dark-gray.5/palette.dark-gray.4BP6 模式hover 比 rest 更暗primary 则沿 blue 色阶下移restblue.3→ hoverblue.2→ activeblue.1foreground 文字色除 warning 为palette.black外均为palette.white。关键特性Intent 令牌在 light / dark 主题之间不改变——两种模式下 primary 都使用同一个蓝色。主题相关的微调发生在 surface 层例如--bp-surface-background-color-primary-rest它从 intent 派生但按主题应用了不同的明度/彩度缩放。八、Surface 令牌结构、空间与背景三层体系Surface 令牌控制组件共享的结构与空间属性边框、圆角、阴影、间距、背景定义于 base/surface.tokens.jsondark 覆盖在 themes/dark/surface.tokens.json。8.1 关键结构令牌| Token | 值 | 用途 | | ----- | -- | ---- | |--bp-surface-spacing|4px| 基础间距单位组件以它做乘法如calc(var(--bp-surface-spacing) * 2) 8px 内边距 | |--bp-surface-border-width|1px| 所有带边框元素统一的边框宽度 | |--bp-surface-border-radius|4px| 共享圆角 | |--bp-surface-border-color-default|intent.default.rest12% alpha | 默认状态的细边框 | |--bp-surface-border-color-strong|intent.default.rest25% alpha | 描边类元素更明显的边框 | |--bp-surface-shadow-0~--bp-surface-shadow-4| 多层 box-shadow | 五级海拔从平铺(0)到最大深度(4) | |--bp-surface-z-index-0~--bp-surface-z-index-4|0、10、20、30、40| 层叠等级定义于 z-index 节点 |以shadow-0为例浅色模式由1px spread 的 rgba(black, 15%) 描边层 5px blur 的 rgba(black, 2%) 阴影层两层组成shadow-4则包含 50px blur、-12px spread 的 30% 黑阴影层。dark 模式每级都在首层加入inset: true的 rgba(white, 20%) 白色高亮阴影黑度最高到 85%shadow-4。组件代码零改动即可获得主题适配。8.2 背景色surface-background-color模式--bp-surface-background-color-{intent}-{state}是每个意图与交互状态完全解析、开箱即用的背景色。对 default 意图它们从 intent 颜色经明度/彩度缩放派生——default-rest在浅色模式编译为#ffffff白色尽管它派生自灰色因为令牌应用了lightnessScale: 1.909Token浅色模式深色模式--bp-surface-background-color-default-rest#ffffff以lightnessScale: 0.362派生JSON 中实际为 0.362README 表格标注 0.248 为旧值--bp-surface-background-color-default-hover#f6f7f9light-gray.5更深的灰--bp-surface-background-color-default-active#edeff2light-gray.4更深的灰--bp-surface-background-color-default-disabled#ffffff以缩放系数派生依据 dark/surface.tokens.jsondark 下default.rest使用lightnessScale: 0.362, chromaScale: 0.308, hueOffset: -1.44hover/active则组合了 scale 与 offset。README 表格中标注的 0.248 等数值应视为文档撰写时点的版本快照以仓库 JSON 为准。对于非 default意图primary、success、warning、danger背景色直接从 intent 令牌透传、无派生——同一个蓝色在两种主题下通用。dark 覆盖文件只重定义 default 背景色非 default 意图无需 dark 覆盖。8.3 图层色layer-color 与共享透明度旋钮模式--bp-surface-layer-color-{intent}是每个意图色的半透明着色由共享透明度令牌控制| Token | 值 | | ----- | -- | |--bp-surface-layer-opacity|0.055% | |--bp-surface-layer-color-default|intent.default.rest5% alpha | |--bp-surface-layer-color-primary|intent.primary.rest5% alpha | |--bp-surface-layer-color-success|intent.success.rest5% alpha | |--bp-surface-layer-color-warning|intent.warning.rest5% alpha | |--bp-surface-layer-color-danger|intent.danger.rest5% alpha |值得注意的实现细节在支持相对颜色语法的浏览器中每个 layer-color 会响应式地引用透明度令牌而非固化 5%--bp-surface-layer-color-primary: oklch(from var(--bp-intent-primary-rest) l c h / var(--bp-surface-layer-opacity));这在 JSON 中通过alpha: {surface.layer-opacity}的令牌引用达成见 surface.tokens.json。于是--bp-surface-layer-opacity成为一个共享控制旋钮——把它从0.05改成0.1所有 layer-color 的浓度同步增强。alpha 引用在 resolveAlphaValue 中被解析为数值用于计算静态 hex 回退。8.4 可叠加图层stackable layer模式--bp-surface-layer-{intent}每个图层色被包装进linear-gradient()从而可作为背景图叠加--bp-surface-layer-primary: linear-gradient(#2d72d20d 0 0);因为background-color只能接受一个值而background-image支持多层堆叠linear-gradient(color 0 0)技巧生成一个纯色渐变层可叠在背景色之上// 在默认表面之上叠加一层 primary 着色 background-color: var(--bp-surface-background-color-default-rest); background-image: var(--bp-surface-layer-primary);该包装由 JSON 中的com.blueprint.role: stackable-layer注解触发见 surface.tokens.json构建系统在 applyRoleForCss 中检测该角色并套上linear-gradient()包装。九、Typography 与 Emphasis 令牌9.1 Typographytypography.tokens.json 定义了完整排版阶梯familydefault为系统字体栈-apple-system、BlinkMacSystemFont、Segoe UI、Roboto、Oxygen、Ubuntu、Cantarell、Open Sans、Helvetica Neue、blueprint-icons-16、sans-serifmono为等宽栈sizebody 从 10pxbody-x-small到 16pxbody-largeheading 从 16pxheading-small到 46pxheading-displaycode 为 12px / 13px / 14pxweightdefault: 400、bold: 600line-heightdefault: 1.28581、large: 1.5colorcolor-default各状态从 intent 派生并做明度/彩度微调如rest对{intent.default.rest}应用lightnessOffset: -0.279, chromaOffset: -0.017, hueOffset: -4color-primary/color-success/color-warning/color-danger直接透传 intent 对应状态color-muted直引{intent.default.rest}。9.2 Emphasisemphasis.tokens.json 定义焦点与动效transition-duration100ms、easedefault[0.4, 1, 0.75, 0.9]与 bounce[0.54, 1.12, 0.38, 1.11]两条 cubicBezier、focus-color引用 primary.rest、focus-width2px、focus-offset2px以及motion-reduced数值开关。十、实战示例Button 组件如何消费令牌Button 组件src/components/button/是 surface 与 intent 令牌协同工作的最佳范例核心文件为 _common.scss共享 mixin。使用中注意该组件 dark 模式下 minimal / outline 按钮的active、hover状态目前由rest令牌派生预期随调色板更新而调整。10.1 Surface 令牌尺寸与结构// 布局——以间距令牌为乘法基数 height: calc(var(--bp-surface-spacing) * 7.5); // 默认 30px 高 padding: var(--bp-surface-spacing) calc(var(--bp-surface-spacing) * 2); // 4px 8px border-radius: var(--bp-surface-border-radius); // 4px // 盒阴影——两层inset 边框 深度投影 box-shadow: inset 0 0 0 var(--bp-surface-border-width) color-mix(in oklch, var(--bp-surface-border-color-strong) 90%, var(--bp-palette-black)), 0 1px 2px color-mix(in oklch, var(--bp-palette-black) 10%, transparent);按钮的 box-shadow 用两层以不同方式消费令牌inset 边框层用--bp-surface-border-width模拟 1px 边框代码注释说明原因CSSborder只能有一个、无法与阴影叠加、会改变元素尺寸、还需要额外 box-sizing因此改用box-shadow。浅色模式下--bp-surface-border-color-strong与--bp-palette-black按 90% 混合把灰色令牌压向黑色以取得足够对比dark 模式下则用--bp-surface-border-color-default与transparent按 50% 缩放把令牌自带的 20% alpha 减半到 10%。深度投影层使用--bp-palette-black的不同透明度rest 10%、hover/active 20%形成跨主题一致的投影。Large 变体只是放大乘法系数高度calc(var(--bp-surface-spacing) * 10)、水平内边距calc(var(--bp-surface-spacing) * 4)对照 mixinpt-button-height-default/pt-button-height-smallsmall 高度为* 6。10.2 Intent 令牌每个交互状态的颜色对非 default 意图primary、success、warning、dangerSass map 把每个意图接到其令牌上$button-intent-states: ( primary: ( var(--bp-intent-primary-rest), // background var(--bp-intent-primary-hover), // background on hover var(--bp-intent-primary-active), // background on active var(--bp-intent-primary-foreground) // text color ), // success、warning、danger 遵循同一模式 );disabled 状态引用--bp-intent-default-disabled并降低透明度minimal / outlined 变体则用--bp-surface-border-color-strong做边框如pt-button-outlined中的border: var(--bp-surface-border-width) solid var(--bp-surface-border-color-strong)。组件 SCSS 中还能看到大量color-mix()的应用例如浅色默认按钮背景为color-mix(in srgb, var(--bp-intent-default-rest) 5%, var(--bp-palette-white))深色按钮为color-mix(in srgb, var(--bp-intent-default-rest) 40%, var(--bp-palette-black))。源码注释表明对接近中性的灰色优先用 srgb 混合以避免 OKLCH 混合带来的色相偏移对非中性意图色则可用 oklch 混合。此外 warning 的 rest 色存在一个临时回退机制--bp6-button-warning-resthex 为#fbb360对应 palette.orange.5用于兼容不支持相对颜色语法的浏览器——这正是渐进增强策略在组件层的落地。十一、浏览器兼容性与回退策略部分令牌使用 CSS 相对颜色语法oklch(from ...)派生 hover、active 与 alpha 修饰色最低版本要求浏览器最低版本Chrome122Safari18Firefox128Edge122较旧浏览器会忽略这些属性值。在 Blueprint 组件内部已提供回退值生成 CSS 的基础 hex 块 组件 SCSS 中的手动回退如--bp6-button-warning-rest的:root声明在 Blueprint 之外你需要自行提供回退值。使用技巧如果目标浏览器不支持相对颜色语法直接依赖生成产物中的 hex 基础声明即可无需任何额外处理若需要自定义派生色请参考com.blueprint.derive的声明方式并自行准备supports分支。十二、开发与扩展指南重新生成令牌在 packages/core 目录执行pnpm run build:tokens产物写入src/design-tokens/build/新增基础令牌在tokens/base/相应 JSONpalette / intent / surface / typography / emphasis中按 DTCG 格式添加节点注意$type与$value结构必须能被 sd.config.ts 的解析器识别新增主题覆盖在tokens/themes/theme/下建同名 JSON只重定义需要变化的$value/$extensions并在THEMES中登记新主题选择器、源文件、输出文件名派生新颜色优先使用com.blueprint.derive的六个属性alpha、lightnessScale、chromaScale、lightnessOffset、chromaOffset、hueOffset而非手写新色值——派生能自动获得静态 hex 回退与oklch(from ...)增强双输出叠加半透明色层若需要多层背景合成声明com.blueprint.role: stackable-layer或直接消费--bp-surface-layer-{intent}。总结Blueprint 设计令牌体系把颜色/尺寸/阴影/字体从组件样式里抽离成可编程、可派生、可覆盖的 DTCG 数据源通过 Style Dictionary 编译为--bp-*CSS 变量并以静态 hex 回退 supports相对颜色增强的双输出策略兼顾现代浏览器与新老兼容。理解这套体系你既可以在业务组件中直接消费--bp-surface-*、--bp-intent-*等令牌实现跨主题一致性也可以按同样模式扩展自己的主题与派生色。相关文件索引README.md、USAGE.md、sd.config.ts、tokens/base、tokens/themes/dark、Button _common.scss、packages/core/package.json。赞分享前端UI组件设计系统【免费下载链接】blueprintA React-based UI toolkit for the web项目地址https://gitcode.com/gh_mirrors/bl/blueprint点击查看免费下载相关推荐Carbon 设计系统 DTCG 设计令牌Design Tokens格式全解析目录结构、Token 规范与 Style Dictionary 构建验证Carbon 设计系统 DTCG 设计令牌Design Tokens格式全解析目录结构、Token 规范与 Style Dictionary 构建验证 本前端UI组件设计系统Owncast 样式定义体系详解基于 Style Dictionary 的设计令牌Design Tokens与 CSS 变量生成流程Owncast 样式定义体系详解基于 Style Dictionary 的设计令牌Design Tokens与 CSS 变量生成流程 Owncast 的自音视频直播后端Eigent Theme Tokens V2: DTCG 驱动的 OKLCH 主题令牌引擎架构与实战解析Eigent Theme Tokens V2: DTCG 驱动的 OKLCH 主题令牌引擎架构与实战解析 Eigent 桌面应用的主题系统 Theme Toke人工智能AI Agent多智能体大模型本地部署MCP 服务桌面应用工作流自动化上一篇OkGo单元测试框架MockWebServer与Espresso结合下一篇如何将Mac触控板变成精准电子秤TrackWeight完整使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考