Tokens Studio for FigmaとStyle Dictionaryでデザインの共通言語をつくる

こんにちは、弁護士ドットコムデザイン部の細貝です。

担当しているプロダクトで、「Style Dictionary」と「Tokens Studio for Figma(FigmaTokens)」を使ってデザイントークンを実際のコードに反映する仕組みづくりをする機会がありました。

12月のアドベントカレンダーでも記事を書いたのですが、記事公開後に調べた内容や部分的な改善を反映しつつ、こちらのブログでも紹介させていただこうと思います。

弁護士ドットコムにデザイントークンがきた🎁
- デザイントークンとは
- デザイントークンを使ってFigmaでデザインする
仕組み化することでデザイントークンをもっと活用したい
実際に仕組みをつくってみる
今後のアイデア
まとめ

弁護士ドットコムにデザイントークンがきた🎁

弁護士ドットコムでは、2022年の1月ごろから本格的にデザイントークンの作成と導入に取り組んでいます。

qiita.com

@metsa77さんの尽力のおかげで、Figma上でデザイントークンをもとにデザイン作業ができるようになりました。

デザイントークンとは

W3Cのデザイントークンコミュニティグループのサイトを読むと、デザイントークンは下記のように定義されています。

The single source of truth to name and store a design decision, distributed so teams can use it across design tools and coding languages. （チームが設計ツールやコーディング言語全体で使用できるように、設計上の決定事項に名前を付けて保存するための信頼できる唯一の情報源） Design Tokens Glossary

プラットフォームに依存せずデザインの決定を表現する方法として、さまざまな分野やツールの間で共有できるのがメリットです。組織全体で共通の語彙を確立するときに役立つと案内されています。

デザイントークンを作成・管理するGUIツールもいくつかあり、裏側では下記のようなフォーマットのJSONファイルとして管理されているものが多いです。

{
  "token name": {
    "$type": "type name",
    "$value": "token value"
  }
}

まだ策定中の段階ですが、W3Cのデザイントークングループでも

トークンのタイプ（種類）やグループ
ファイルの形式や拡張子

など、標準化に向けた一般的な規格や周辺ツールが紹介されています。

design-tokens.github.io

デザイントークンを使ってFigmaでデザインする

普段のデザイン業務では「Tokens Studio for Figma (旧：Figma Tokens)」というプラグインを使ってデザイントークンのJSONファイルを読み込み、トークンの値を利用しています。

tokens.studio

カラーやサイズなどの設定に加えて、先日のアップデートで余白（Spacing）にショートハンドが使えるようになったりと、実際にCSSを書くときと近い感覚でデザインの作成ができます。

仕組み化することでデザイントークンをもっと活用したい

デザインを作成したあとは実際にHTML/CSSでマークアップを進めていきますが、当初はSCSSファイル上のVariablesとして、デザイントークンを手動でコード化していました。

しかし、トークンの種類が充実してくるとVariablesの追加作業が地味に大変ですし、手動での追加はどうしても小さいミスや漏れが起きるので、レビュー時の確認もそれなりに時間がかかります。

可能なところは自動化したいと思って方法を調べてみたところ、下記の3つのツールを組み合わせて実現ができそうでした。

1. Style Dictionary

Style DictionaryはAmazonが開発しているnpmのパッケージで、デザイントークンが定義されているJSONファイルをあらゆるプラットフォームや言語のフォーマットに変換してくれます。

amzn.github.io

2. Tokens Studio for Figma(Figma Tokens)

前述のTokens Studio for Figmaには、同期オプションとしてGitHubやGitLabとの連携機能があります。 Tokens Studio for FigmaとStyle Dictionaryが同じJSONファイルを参照するようにできれば、デザインと実装の連携がよりスムーズに進められそうです。

3. Storybook Design Token

あわよくば作成したデザイントークンのドキュメントも一元管理できないかな…と追加で調べてみたところ、Storybookに「storybook-design-token」というプラグインがありました。

Style Dictionaryの設定を使い、プラグインで指定しているSCSSファイルのフォーマットが出力できれば、こちらもうまく連動ができそうでした。

github.com

完成イメージ

弁護士ドットコムではコード管理にGitLabを使用しているので、連動の仕組みは下記の流れで検討しました。

デザイントークンのJSONファイルをGitLabのリポジトリに設置
Tokens Studio for FigmaのGitLab連携を使ってリポジトリ内のデザイントークンと同期する
Style Dictionaryを使って、リポジトリ内のデザイントークンをSassファイルに変換する
デザイントークンを変換したSassファイルをStorybookでドキュメント化する

図にするとこんな感じのイメージです。

実際に仕組みをつくってみる

1.GitLabのアクセストークンを発行する

まずはTokens Studio for Figmaのドキュメントを参考に、GitLabからアクセストークンを発行します。

docs.tokens.studio

https://gitlab.com/-/profile/personal_access_tokens を開く
- 自社のGitLabサーバーの場合は、 {自社のGitLabURL}/-/profile/personal_access_tokens を開く
Token name に適当な名前を入れる（添付キャプチャの場合は figma-tokensで設定）
Expiration dateの日付を設定（アクセストークンの有効期限を指しているので、無期限にしたい場合は未入力に変更しておく）
Select scopes は api にチェックを入れる
- Tokens Studio for FigmaからGitLabへ意図的にPushをさせたくない場合は read_api でもOK
Create personal access token ボタンをクリック
Your new personal access token の欄に作成されたアクセストークンが表示されるので、コピーして手元に控える

2.Tokens Studio for FigmaをGitLabに連携する

FigmaでTokens Studio for Figmaのプラグインを開き、Settings > GitLab > Add new credentials をクリックします。

下記の入力項目を埋めて「Save」ボタンをクリックします。

項目名	説明	メモ
Name	設定名	好きな名前で良い
Personal Access Token	アクセストークン	GitLabで作成したアクセストークンを貼り付ける
Repository(owner/repo)	リポジトリ名	GitLabのリポジトリ名を入力する。https://gitlab.com/developer/samples の場合は developer/samples がリポジトリ名になる。
Branch	同期するブランチ	基本的には master(main)でOK。もし作業ブランチがある場合は指定を変更できる。
File Path or Folder path	同期するファイル	1ファイルだけ同期する場合はファイル名で指定する（例: `assets/tokens/global.json` ）複数ファイルを同期する場合はフォルダで指定する（例: `assets/tokens/brand1` ）
baseUrl	リポジトリのドメイン	`https://gitlab.com/` または自社のGitLabのURLを指定する。

"File Path or Folder path"に指定したパスが連携時に存在していない場合、プラグインとの連携がエラーになるので注意します。現時点の内容で良いので、デザイントークンのJSONファイルを該当リポジトリへ事前にコミットしておくとわかりやすいと思います。

最初の連携時には「GitLabからデータをPullするか」と聞かれるのでYesまたはCancelを選びます。

Yesをクリックするとリポジトリから最新のデザイントークンデータが同期される（ローカルのデータは上書きされるので注意）
Cancelをクリックすると同期は行われない（あとから手動同期可能）

3.StyleDictionaryの設定を用意する

Tokens Studio for FigmaとGitLabの連携が無事に済んだら、次はStyleDictionaryの設定を用意します。

npm install style-dictionary を実行し、style-dictionary のパッケージをインストールする
プラットフォームや出力フォーマットを指定する設定ファイルを用意する
ビルドを実行し、変換したファイルを出力する

参考： https://amzn.github.io/style-dictionary/#/quick_start

Sassのフォーマットは、

Sassのmap形式で出力ができる Deep
variablesの一覧で出力ができる Flat

の2種類が用意されています。

フォーマットのカスタマイズや細かい出力条件は、公式ドキュメントに豊富なサンプルが載っているのでこちらを参考にしています。

amzn.github.io

今回は下記の条件でカスタマイズを入れました。

分類はFigma Tokensのカテゴリに準拠する
ブランド別にSCSSファイルを生成できるようにする
グローバルトークンには global-* の prefixをつける
Storybook Design Tokenで指定されたフォーマットにあわせてSassのコメントを出力する

CodeSandboxにサンプルコードを上げているので、ご興味があればぜひForkして動作を試してみてください。

ちなみに、

@use を含めたフォーマットの出力する
ファイル名をprefixにする

こともやりたかったのですがこちらはまだ非対応で、次のバージョン(4.0)で対応が検討されているようです。

4.Storybookと連携する

最後にStorybookのプラグインをインストールして、デザイントークンのドキュメントを生成します。

npm install storybook-design-token を実行してプラグインをインストールする
.storybook/main.js にプラグインを追加する

参考： https://github.com/UX-and-I/storybook-design-token

プラグインの設定が終わったら、Storybookのストーリーに DesignTokenDocBlock を追加すると、さきほど作成したデザイントークンがカテゴリごとに出力できます。

// colors.stories.mdx

import { DesignTokenDocBlock } from 'storybook-design-token/dist/doc-blocks';

<DesignTokenDocBlock categoryName="Color" maxHeight={600} viewType="card" />;

公式ドキュメントでは「デフォルトでは、トークンカテゴリは次のカテゴリのコメントブロックで終了します」とされていますが、Storybook上でトークンカテゴリがうまく認識されず、プレビュー表示されない現象がありました。

何度か試したところ、オプションとして用意されている終了のコメントブロックも入れておくとプレビュー表示が安定するようでした。そのため、トークングループごとに開始/終了ブロックを宣言するフォーマットにしています。

/**
  * @tokens Colors
  * @presenter Color
  */

// ここにVariablesを出力する

/**
  * @tokens-end
  */


/**
  * @tokens FontSize
  * @presenter FontSize
  */

// ここにVariablesを出力する

/**
  * @tokens-end
  */

今後のアイデア

メンバー間の意思疎通促進に加えて、ツール内外での展開や応用へのハードルが低くなるメリットもあると考えています。

アイデアとしていま試しているものや、他の記事を読んで興味深かったものをいくつか例として紹介します。

Figma上にドキュメントを自動生成

Token Studio for Figmaでは、トークンを更新するたびに更新されるリファレンスシートを作成できる「ドキュメンテーショントークン」という機能があります。トークンの値や説明を変更すると随時更新してくれるのでとても便利です。

この機能を使う際に「Automator」というプラグインを組み合わせると、定義したデザイントークンを読み取ってレイヤーを作成する作業をさらに自動化できます。

こちらは実際にいくつかのチームのデザイナーが試しているところなので、いずれ別の機会に詳細を記事にできればと思っています。

www.youtube.com

いまとは別のツールや手段に移行する

上記の紹介ではFigmaとSassを使っていますが、今後の方針によっては別のツールや方法に移行する可能性もあります。たとえば「SassのVariablesはやめてCSS変数（カスタムプロパティ）に移行しましょう」となったときも、デザイントークンがあれば変数部分の乗り換えハードルが下がります。

今回使ったToken Studio for Figmaも、今後はFigma以外のツールでも使用できるデザイントークンマネージャーを開発する意向を表明しています。

Figma、Sketch、または次のホットなものを使用しているかどうかに関係なく使用できる専用のデザイントークンマネージャーにも取り組んでいます。 Figma Tokens becomes Tokens Studio for Figma

Illustratorのスウォッチにカラーを読み込む

デザイナーの場合、Illustratorでもデザイントークンで定義したカラーを使いたいときがあるかもしれません。数が少なければ手動で登録すれば良いですが、数が多いときはスクリプトを使ってCSVからスウォッチを作成し一括登録できるアイデアが公開されています。