Skip to content

使用 Style Dictionary 管理 Design Token

Posted on:2022-07-15 12:34

在之前的文章中,我介绍了Design Token 相关的基本概念。本文将介绍如何使用现有的工具来管理 Design Token。

什么是Style Dictionary

社区上处理和解析Design Token的工具很多,这有一个可参考的目录。比较受欢迎的有 Style DictionaryTheo 等。我选择 Style Dictionary,因为社区受关注度更高,更新也比较及时,最近正在计划做4.0版本

Style Dictionary 是一个构建系统。使用它可以让你一次性定义风格,供任何平台或语言使用。在一个地方可以创建和编辑你的样式,通过一个命令就可以把这些规则导出到你需要的所有地方,iOS、Android、CSS、JS、HTML、Sketch 文件、样式文档,或者任何你能想得到的地方。它可以通过npm作为CLI使用,也可以像普通的Node.js模块一样使用。

简单案例,快速上手

为了帮助开发者快速上手,官方很贴心地提供了一些实例。让我们来看一下简单的实例,从中了解Style Dictionary 到底做了什么事情。随便找个目录,执行以下命令。

$ mkdir MyStyleD
$ cd MyStyleD
$ style-dictionary init basic

这个命令先将仓库中的实例文件复制到本地目录,然后执行 style-dictionary build ,生成构建的产出物。不出意外的话,你会在你的控制台中看到这些输出:

Copying starter files...

Source style dictionary starter files created!

Running `style-dictionary build` for the first time to generate build artifacts.


scss
✔︎ build/scss/_variables.scss

android
✔︎ build/android/font_dimens.xml
✔︎ build/android/colors.xml

compose
✔︎ build/compose/StyleDictionaryColor.kt
✔︎ build/compose/StyleDictionarySize.kt

ios
✔︎ build/ios/StyleDictionaryColor.h
✔︎ build/ios/StyleDictionaryColor.m
✔︎ build/ios/StyleDictionarySize.h
✔︎ build/ios/StyleDictionarySize.m

ios-swift
✔︎ build/ios-swift/StyleDictionary+Class.swift
✔︎ build/ios-swift/StyleDictionary+Enum.swift
✔︎ build/ios-swift/StyleDictionary+Struct.swift

这意味着你已经成功运行了这个实际的例子。回头看看当前你操作的文件目录,它应该长这样:

├── README.md
├── config.json
├── tokens/
│   ├── color/
│       ├── base.json
│       ├── font.json
│   ├── size/
│       ├── font.json
├── build/
│   ├── android/
│      ├── font_dimens.xml
│      ├── colors.xml
│   ├── compose/
│      ├── StyleDictionaryColor.kt
│      ├── StyleDictionarySize.kt
│   ├── scss/
│      ├── _variables.scss
│   ├── ios/
│      ├── StyleDictionaryColor.h
│      ├── StyleDictionaryColor.m
│      ├── StyleDictionarySize.h
│      ├── StyleDictionarySize.m
│   ├── ios-swift/
│      ├── StyleDictionary.swift
│      ├── StyleDictionaryColor.swift
│      ├── StyleDictionarySize.swift

Style Dictionary 由配置驱动,必须包含一份config.json和配置中引用的design token对应的文件。

Style Dictionary 的架构

为了更好地理解style dictionary的能力和工作原理,让我们来看看它的架构设计。下面是官方给到的架构图。

一图胜千言,这张图已经很直观地展示其工作原理。

当上述四个步骤都成功执行并结束后,你就能得到你想要的输出产物了。

与设计师协作

浅谈Design Token中我曾经提到过,设计师可以通过 Figma 等设计工具,以文件的形式将 design token 提供给开发人员。现在,身为开发人员的我们,可以使用 Style Dictionary 对token进行处理,输出我们想要的文件。

我们将所有的tokens文件托管到内部的gitlab仓库中。设计师定义好token之后,将文件上传到仓库,然后告知到对应的工程师。工程师使用基于Node.js开发的脚本,实现token的下载和转换输出。

使用 Node API 增强定制能力

style dictionary 提供了比较强大的 Node API,你可以使用这些API实现一些更复杂的能力,满足更多的需求场景,这里是API的文档,感兴趣的朋友可以仔细阅读。接下来我会结合实际案例,向大家演示如何使用Node API。

先从一个简单的例子开始,新建一个JavaScript文件。引入依赖之后,调用extend 传入配置。然后调用返回实例的buildAllPlatforms 方法。

// build.js
const StyleDictionary = require('style-dictionary').extend('config.json');

StyleDictionary.buildAllPlatforms();

extend方法的参数可以是一个文件路径,也可以是个对象。

// build.js
const StyleDictionary = require('style-dictionary').extend({
  source: ['properties/**/*.json'],
  platforms: {
    scss: {
      transformGroup: 'scss',
      buildPath: 'build/',
      files: [{
        destination: 'variables.scss',
        format: 'scss/variables'
      }]
    }
    // ...
  }
});

StyleDictionary.buildAllPlatforms();

你可以多次调用extend和buildAllPlatforms方法,可以用在输出嵌套主题或者多品牌主题等类似的场景。

// build.js
const StyleDictionary = require('style-dictionary');

const brands = [`brand-1`, `brand-2`, `brand-3`];
brands.forEach(brand => {
  StyleDictionary.extend({
    include: [`tokens/default/**/*.json`],
    source: [`tokens/${brand}/**/*.json`],
    // ...
  }).buildAllPlatforms();
});

假设下面是我们的 token.json。

// token.json
{
  "sizing": {
    "10": {
      "value": "10",
      "type": "sizing"
    },
    "12": {
      "value": "12",
      "type": "sizing"
    },
    "14": {
      "value": "14",
      "type": "sizing"
    },
    "16": {
      "value": "16",
      "type": "sizing"
    },
    "18": {
      "value": "18",
      "type": "sizing"
    },
    "20": {
      "value": "20",
      "type": "sizing"
    },
    "22": {
      "value": "22",
      "type": "sizing"
    },
    "24": {
      "value": "24",
      "type": "sizing"
    },
    "28": {
      "value": "28",
      "type": "sizing"
    },
    "32": {
      "value": "32",
      "type": "sizing"
    },
    "36": {
      "value": "36",
      "type": "sizing"
    },
    "40": {
      "value": "40",
      "type": "sizing"
    },
    "48": {
      "value": "48",
      "type": "sizing"
    }
  }
}

先创建Style Dictionary 需要的 config.json。

// config.json
{
  "source": ["./token.json"],
  "platforms": {
    "scss": {
      "transformGroup": "scss",
      "buildPath": "build/scss/",
      "files": [
        {
        "destination": "sizing.scss",
        "format": "scss/variables"
        }
      ]
    }
  }
}

然后试着执行 node build.js 。不出意外的话,执行结束之后,会在当前目录中创建 build/sizing.scss

// Do not edit directly
// Generated on Thu, 04 Aug 2022 07:08:59 GMT

$sizing-10: 10;
$sizing-12: 12;
$sizing-14: 14;
$sizing-16: 16;
$sizing-18: 18;
$sizing-20: 20;
$sizing-22: 22;
$sizing-24: 24;
$sizing-28: 28;
$sizing-32: 32;
$sizing-36: 36;
$sizing-40: 40;
$sizing-48: 48;

虽然输出了我们想要的文件,但是文件的内容好像和预期不符,每一个 Scss 变量应该带上单位。要想定制这个输出结果,我们需要使用自定义的Transform。

Transform 和 TransformGroup

Style Dictionary 中的Transform是用来修改token的函数。使用 Transform可以对token的name、value 或者 attribute 进行转换,从而实现适配输出不同平台的能力。比如,将pixel转换成point。可以使用内置的Transforms,也可以使用registerTransform方法注册自定义Transform。

StyleDictionary.registerTransform({
  name: 'time/seconds',
  type: 'value',
  matcher: function(token) {
    return token.attributes.category === 'time';
  },
  transformer: function(token) {
    // Note the use of prop.original.value,
    // before any transforms are performed, the build system
    // clones the original token to the 'original' attribute.
    return (parseInt(token.original.value) / 1000).toString() + 's';
  }
});

TransformGroup就是一组Transform。有开箱即用的内置的TransformGroup,也可以通过registerTransformGroup方法注册自定义TransformGroup。

StyleDictionary.registerTransformGroup({
  name: 'Swift',
  transforms: [
    'attribute/cti',
    'size/pt',
    'name/cti'
  ]
});

为了给sizing加上单位pixel,我们先注册一个自定义 Transform 和 TransformGroup。

StyleDictionary.registerTransform({
  name: 'size/px', //定义transform的名称,作为引用标记
  type: 'value', // transform 转换的对象,我们需要转换token对应的值
  matcher: token => { // token 匹配函数,返回boolean。
    return token.type === 'sizing' && token.value !== 0
  },
  transformer: token => { // transform函数,接受token,返回想要的内容
    return `${token.value}px`
  }
})

StyleDictionary.registerTransformGroup({
  name: 'custom/scss', 
  transforms: StyleDictionary.transformGroup['scss'].concat([
    'size/px',
    'size/percent'
  ])
})

接着在config.json中使用叫做custom/scss 的 TransformGroup。

{
  "source": ["./token.json"],
  "platforms": {
    "scss": {
      "transformGroup": "custom/scss",
      "buildPath": "build/scss/",
      "files": [
        {
        "destination": "sizing.scss",
        "format": "scss/variables"
        }
      ]
    }
  }
}

最后检查输出内容。

// Do not edit directly
// Generated on Thu, 04 Aug 2022 07:08:59 GMT

$sizing-10: 10px;
$sizing-12: 12px;
$sizing-14: 14px;
$sizing-16: 16px;
$sizing-18: 18px;
$sizing-20: 20px;
$sizing-22: 22px;
$sizing-24: 24px;
$sizing-28: 28px;
$sizing-32: 32px;
$sizing-36: 36px;
$sizing-40: 40px;
$sizing-48: 48px;

掌握工具的使用,配合自动化脚本,可以让token2css的过程变得非常丝滑流畅。

结束语

style dictionary 是一个功能丰富,易于定制和拓展的优秀开源工具。多平台输出的能力,能够帮助我们实现样式的一次定义,多处使用。通过自定义的Transform,你还可以将Design Token导出为ESM,你可以在JavaScript代码中使用。如果你的项目使用了 CSS-in-JavaScript 的技术方案时,这非常有用。团队当前正在和设计团队一起验证基于 Design Token 的协作流程,style dictionary 是必不可少的一环。