Carbon Design System 排版基石carbon/type 的 Sass 使用指南与源码级原理解析【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文基于 IBM Carbon Design System当前仓库 carbo/carbon中carbon/type包的 Sass 官方文档 编写。carbon/type是 Carbon Design System 的排版基础包封装了 IBM Design Language 的字阶Type Scale、字体IBM Plex 系列与整套排版设计令牌Type Tokens并内置了h1、h2、p等常见元素的有主见默认样式。读完本文你将掌握carbon/type的全部 Sass 用法快速接入、四个核心 Mixin、类型令牌与工具类的选用、$prefix配置以及其字阶公式、流式排版Fluid Type与 CSS 自定义属性等底层实现原理可直接上手把它接入自己的项目。一、carbon/type 是什么carbon/type是 Carbon Design System 的排版包当前仓库版本为11.67.0见 packages/type/package.json它提供三样核心能力字阶Type Scale一套从 12px 到 92px、共 23 个步进的字号系统字体FontsIBM Plex 系列字体族及其回退栈fallback stack排版设计令牌Type Tokens如productive-heading-01、body-02等每个令牌包含font-size、font-weight、line-height、letter-spacing的完整声明组合。除此之外它还带来开箱即用的默认样式通过default-typeMixin 可以直接为h1~h6、p、a、em等 HTML 元素应用设计系统认可的排版无需逐个手动书写。从构建层面看该包同时提供 JavaScript APIsrc/index.ts构建产物为lib/index.js、es/index.js与 Sass 入口index.scss并在package.json中通过sass: index.scss声明本文聚焦其 Sass 侧能力。二、快速开始接入 carbon/type2.1 安装carbon/type是独立发布的 npm 包与carbon/layout提供间距、字号 rem 换算和carbon/grid提供断点系统配合工作这两者也是它的直接依赖见 packages/type/package.json 的dependencies字段。安装命令npm install carbon/type # 或 yarn add carbon/type2.2 最小使用示例在 Sass 中使用现代模块系统use引入并调用四个常用 Mixinuse carbon/type; // 包含排版 resethtml 字号、body 字体与抗锯齿、code 等基线样式 include type.reset(); // 包含默认排版样式作用于 h1, h2, h3 等元素 include type.default-type(); // 包含排版相关的工具类utility classes include type.type-classes(); .selector { // 在任意选择器中套用某个类型令牌 include type.type-style(productive-heading-01); }其中use carbon/type会加载包的 Sass 入口 packages/type/index.scss该入口通过forward依次暴露了 7 个子模块scss/prefix、scss/font-family、scss/scale、scss/reset、scss/styles、scss/classes、scss/default-type。因此上述四个 Mixin 均可用type.前缀直接调用。2.3 仓库内真实使用参考仓库自带的示例工程 packages/type/examples/preview/src/styles.scss 展示了完整实践先通过use carbon/styles/scss/config with (...)配置字体路径与需要加载的字体含阿拉伯、梵文、希伯来、泰文等多语言 IBM Plex 字体再use carbon/type as *;随后直接include reset();、include type-classes();并基于$type-scale循环生成.type-scale-1~.type-scale-23演示类。三、核心 API 详解3.1 四个核心 MixinExport导出说明mixin type-classes生成排版工具类的 CSS字体族、字重、斜体、各令牌mixin reset生成 Carbon Design System 的基础排版基线样式mixin default-type为h1~h6、p、a等元素生成默认排版样式mixin type-style在任意选择器内输出某个类型令牌的全部声明reset的源码细节见 packages/type/scss/_reset.scss。它接收两个可选参数mixin reset( $body-font-family: font-family(sans), $mono-font-family: font-family(mono) )输出内容为html { font-size: 100%; }—— 保证 rem 换算基准body使用sans字体族、regular400字重并开启-moz-osx-font-smoothing: grayscale、-webkit-font-smoothing: antialiased、text-rendering: optimizeLegibility以优化渲染code使用等宽字体monostrong提升为semibold600字重。default-type的映射关系见 packages/type/scss/_default-type.scss。它把语义元素映射到设计令牌无需记忆字号即可获得规范排版元素令牌h1heading-06h2heading-05h3heading-04h4heading-03h5heading-02h6heading-01pbody-02同时它还为a设置链接色var(--cds-link-primary, #0062fe)优先读取 CSS 自定义属性缺失时回退到 IBM 蓝#0062fe为em设置斜体。注意a与em使用--#{$prefix}-link-primary动态拼接因此会跟随$prefix配置变化。type-classes的生成逻辑见 packages/type/scss/_classes.scss。它通过三个each循环遍历$font-families、$font-weights与$tokens三张映射表分别生成字体族、字重、以及每个令牌对应的工具类见下节。3.2 类型工具类Type classestype-classesMixin 会输出一批工具类可直接用于 HTML 元素类名说明.cds--type-{font-family}设置font-family。可选值mono、sans、sans-condensed、sans-arabic、sans-devanagari、sans-hebrew、sans-jp、sans-kr、sans-thai-looped、sans-thai、serif.cds--type-{font-weight}设置font-weight。可选值light300、regular400、semibold600.cds--type-italic设置font-style: italic.cds--type-{token}将元素样式设置为对应类型令牌如.cds--type-productive-heading-01这些字体族与字重的完整定义位于 packages/type/scss/_font-family.scss$font-families映射中每个字体族都带完整的回退栈例如sans展开为IBM Plex Sans, system-ui, -apple-system, BlinkMacSystemFont, .SFNSText-Regular, sans-serif$font-weights则定义了light: 300、regular: 400、semibold: 600三档推荐字重。3.3 完整令牌清单Token API下表列出了carbon/type导出的全部类型令牌变量均以!default声明即允许你在use ... with (...)之外通过 Sass Modules 覆写或在使用前重新赋值覆盖。它们以 Map 形式存在每个值包含font-size、font-weight、line-height、letter-spacing含breakpoints的为流式令牌见 4.3 节。令牌变量!default$label-01、$legal-02、$helper-text-01、$helper-text-02✅$body-short-01、$body-compact-01、$body-long-01、$body-01✅$body-short-02、$body-compact-02、$body-long-02、$body-02✅$code-01、$code-02✅$heading-01、$productive-heading-01、$heading-compact-01✅$heading-02、$productive-heading-02、$heading-compact-02✅$productive-heading-03、$heading-03✅$productive-heading-04、$heading-04✅$productive-heading-05、$heading-05✅$productive-heading-06、$heading-06✅$productive-heading-07、$heading-07✅$expressive-heading-01、$expressive-heading-02、$expressive-heading-03、$fluid-heading-03✅$expressive-heading-04、$fluid-heading-04、$expressive-heading-05、$fluid-heading-05、$expressive-heading-06、$fluid-heading-06✅$expressive-paragraph-01、$fluid-paragraph-01✅$quotation-01、$fluid-quotation-01、$quotation-02、$fluid-quotation-02✅$display-01、$fluid-display-01、$display-02、$fluid-display-02、$display-03、$fluid-display-03、$display-04、$fluid-display-04✅所有令牌被统一聚合进$tokens映射表见 packages/type/scss/_styles.scss该表同时是type-styleMixin 与type-classes工具类生成器的数据来源。命名上有两条规律值得注意productive / expressive / fluid 三大家族productive-*面向紧凑型产品界面行高更小expressive-*面向营销与叙事场景行高更大且带响应式断点fluid-*是expressive-*的别名强调随视口连续缩放新旧令牌并存如body-short-01/body-long-01V10 遗留与body-compact-01/body-01V11 令牌在$tokens中同时存在部分旧令牌如$caption-01、$caption-02、$helper-text-01在源码中被标记为deprecated新项目应优先选用 V11 令牌。四、配置项$prefix 与 CSS 自定义属性前缀carbon/type支持通过 Sass Modules 的with语法进行配置use carbon/type with ( $prefix: custom-prefix );配置项完整列表如下选项说明默认值$prefix用于选择器、CSS 自定义属性等的前缀cds$prefix会影响三处输出见 packages/type/scss/_prefix.scss工具类名.cds--type-sans变为.custom-prefix--type-sansCSS 自定义属性名type-style输出形如font-size: var(--cds-productive-heading-01-font-size, ...)的声明前缀同样随之变化default-type中的链接色var(--cds-link-primary, #0062fe)。此外_prefix.scss还声明了第二个配置变量$custom-property-prefix: cds !default它专门控制 CSS 自定义属性前缀可由内部的configure($values)Mixin 单独设置便于在工具类前缀与自定义属性前缀需要分离的场景如与carbon/themes协同下使用。五、源码级原理剖析5.1 字阶公式从 12px 到 92pxcarbon/type的字阶不是拍脑袋定死的数值而是由一条递推公式生成见 packages/type/scss/_scale.scssYn Yn-1 {INT[(n-2)/4] 1} * 2其中Y1 12px。该公式的含义是每跨过一个步进字号在前一步基础上增加 2px、4px、6px…… 的阶梯增量增量每 4 步提升 2px使得字号在大尺寸段拉开间距、小尺寸段保持细腻从 12px 一路递增到 92px共 23 个步进。每个步进再通过carbon/layout的to-rem转换为 rem 单位存入$type-scale列表。相关函数与 Mixin// 取第 $step 步的字号rem $fs: type-scale(8); // 或直接在选择器中设置 .selector { include type-scale(8); // 等价于 include font-size(8); }5.2 type-style令牌是如何输出的type-styleMixin 的核心逻辑位于 packages/type/scss/_styles.scssmixin type-style($name, $fluid: false, $breakpoints: gridconfig.$grid-breakpoints) { if not map.has-key($tokens, $name) { error Unable to find a token with the name: #{$name}; } $token: map.get($tokens, $name); // 开启流体且令牌定义了 breakpoints 时走流体排版 if $fluid true and map.has-key($token, breakpoints) { include fluid-type($token, $breakpoints); } else { // 否则输出 CSS 自定义属性 回退值 include custom-properties($name, $token); } }要点一令牌名错误会直接编译报错error避免静默失败。要点二默认输出的是CSS 自定义属性而非裸属性值例如.selector { font-size: var(--cds-productive-heading-01-font-size, 0.875rem); font-weight: var(--cds-productive-heading-01-font-weight, 600); line-height: var(--cds-productive-heading-01-line-height, 1.28572); letter-spacing: var(--cds-productive-heading-01-letter-spacing, 0.16px); }这一设计让主题系统可以在运行时通过覆盖自定义属性实现换肤而编译期回退值保证了不依赖运行时变量时的可用性。仓库测试 packages/type/tests/scss-test.js 专门验证了这一行为断言每个属性值都包含var(--且回退值与 JS 侧令牌productiveHeading01对应键一致。5.3 流式排版Fluid Type对于定义有breakpoints键的令牌如$expressive-heading-03、$display-04等type-style($name, true)会启用流体排版font-size不再由断点阶梯切换而是通过calc()依据视口宽度连续计算.selector { include type-style(expressive-heading-03, true); }其原理实现见_styles.scss的fluid-type与fluid-type-size参考了 CSS-Tricks 的 fluid typography 方案以当前断点宽度为min-vw、下一个含流体定义的断点宽度为max-vw以两个断点的字号为min-font-size/max-font-size输出形如font-size: calc(min (max - min) * ((100vw - min-vw) / (max-vw - min-vw)))的插值公式。行高则使用百分比相对值以适配动态字号。源码注释特别提醒流体排版应谨慎用于固定宽度容器因为字号完全取决于视口。同时无breakpoints的令牌即使传true也会回退为普通静态输出。5.4 与其它包的协作carbon/type处于 Carbon 设计令牌生态的中层依赖carbon/layout负责to-rem换算等基础工具依赖carbon/grid提供断点系统$grid-breakpoints、breakpoint()、breakpoint-next()供流体排版与令牌断点使用与carbon/themes约定共享 CSS 自定义属性前缀机制源码中留有 TODO计划将custom-propertiesMixin 抽取为两包共用模块。六、最佳实践小结三段式引入reset()default-type()建立全局排版基线type-classes()按需输出工具类体积敏感时可改为只引入自己用到的type-style优先用令牌而非手写数值所有字号、行高、字重都通过令牌表达保证与设计系统一致且可被主题覆盖区分静态与流体正文、表格等密集内容用productive-*/body-*静态令牌营销头图、大标题用expressive-*并开启$fluid: true注意前缀一致性自定义$prefix时需同步确保 HTML 中使用的工具类名如.cds--type-sans与新前缀匹配多语言场景阿拉伯、梵文、希伯来、泰文、日文、韩文等字体族已内置回退栈仅需按示例工程方式在carbon/styles的$fonts配置中开启对应字体加载。相关文档与源码入口Sass 文档、包入口、令牌与流体实现、字阶实现、字体族与字重、Sass 测试。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考