• 使用方法
  • ダークモード
• デザイン・トークンの作成または更新
  • フォーマット
  • 変換
  • 名称
  • グループ
  • 値
  • エイリアス
  • 種類
  • モード
    • デフォルトのデザイン・トークン
    • ダーク・モードのデザイン・トークン

デザイントークン

デザイン・トークンは、さまざまなモード（デフォルトやダークなど）で、さまざまなツール（Figma やコードなど）に対して、値（色、間隔、長さなど）の単一のソース・オブ・トゥルースを提供します。

使用方法

デザイントークンはgitlab-ui リポジトリで管理しています。このリポジトリはnpmで公開されており、yarn で依存関係として管理されています。新しいバージョンにアップグレードするにはyarn upgrade @gitlab/uiを実行してください。

デザイントークンは、CSS（カスタムプロパティ）、JavaScript（ES6定数/JSON）、SCSS（変数）などで使用するために、さまざまなモード（デフォルト/ダーク）とファイル形式で提供されています：

例えば

import { BLUE_500 } from '@gitlab/ui/dist/tokens/js/tokens';

const color = BLUE_500; // #1f75cb

CSS

@import '@gitlab/ui/dist/tokens/css/tokens';

.elem {
  color: var(--blue-500); /* #1f75cb */
}

SCSS

@import '@gitlab/ui/dist/tokens/scss/tokens';

.elem {
  color: $blue-500; /* #1f75cb */
}

ダークモード

カラーデザイン・トークンがダークモード用に更新される場合、それらの値は、例えば.dark で付加されたファイル内で同じ名前で提供されます：

例えば

import { BLUE_500 } from '@gitlab/ui/dist/tokens/js/tokens.dark';

const color = BLUE_500; // #428fdc

CSS

@import '@gitlab/ui/dist/tokens/css/tokens.dark';

.elem {
  color: var(--blue-500); /* #428fdc */
}

SCSS

@import '@gitlab/ui/dist/tokens/scss/tokens.dark';

.elem {
  color: $blue-500; /* #428fdc */
}

デザイン・トークンの作成または更新

フォーマット

当社のデザイントークンは、さまざまなツールとインテグレーションし、必要なファイル形式に変換するデザイントークンを定義するために、デザイントークンフォーマットモジュールを使用しています。これは、Design Tokens Community Groupによって発行されたコミュニティ・グループのドラフト・レポートです。

Design Tokens Format Moduleは、デザイン・トークン・ファイルの*.token.json 拡張規格を昇格させます。名前と$value 明示的な$typeを含むフォーマットです：

// color.tokens.json
{
  "token name": {
    "$value": "#000",
    "$type": "color"
  }
}

変換

当社のデザイントークンは、style-dictionaryを使用して、デザイントークンを消費可能なファイル形式 (CSS/SCSS/JavaScript/JSON) に変換します。

パーサーは、デザイン・トークンのフォーマット・プロパティを style-dictionary のデザイン・トークン属性と互換性のあるものにします。

名称

デザイン・トークン名は、値の大文字と小文字を区別する一意の識別子です。名前は、スタイルのオーバーライドを生成するために、異なるモード間で使用できます。

グループ

グループはトークンをカテゴリにまとめる任意の方法です。デザイン・トークンのタイプや目的を推測するために使用すべきではありません。そのためには$type プロパティを使用してください。

{
  "group name": {
    "token name": {
      "$value": "#000"
    }
  }
}

グループ名は、例えば、生成された出力のデザイン・トークン名の前に付けます：

例えば

const GROUP_NAME_TOKEN_NAME = "#000";

CSS

:root {
  --group-name-token-name: #000;
}

SCSS

$group-name-token-name: #000;

値

とは、$value デザイントークンの最低限必要なプロパティで、 $value予約語です。

{
  "token name": {
    "$value": "16"
  }
}

デザイン・トークンの値には、文字列やエイリアスを使用できます：

エイリアス

例えば、エイリアス・トークンtext-color は値{color.default} を持ちます：

{
  "text-color": {
    "$value": "{color.default}"
  }
}

これにより、Output Referencesを使用して出力される生成されたCSSとSCSSは、参照を変数として使用することができます：

CSS

:root {
  --text-color: var(--color-default);
}

SCSS

$text-color: $color-default;

種類

オプションの$typeプロパティは、値の変換やトークンのグループ化などに使用します：

{
  "token name": {
    "$value": "#000",
    "$type": "color"
  }
}

ドキュメントやツール設定に使用できるtokens.grouped.json を出力します：

{
  "color": {
    "token name": "#000"
  }
}

モード

モードはデフォルト・トークンの上で処理され、他のモードと組み合わせたり、スタイルシートから個別に継承したりすることができます。モードは、.{mode}.token.json ファイル名で示されます。これは、ファイルによってトークンをフィルタリングするために使用されます。例えば、ダークモードのトークンファイルは、.dark.token.json で終わります。

デフォルトのデザイン・トークン

Input

color.tokens.json

{
  "text-color": {
    "$value": "#000",
    "$type": "color"
  }
}

出力

tokens.grouped.json

{
  "color": {
    "text-color": "#000"
  }
}

tokens.js

export const TEXT_COLOR = "#000";

tokens.scss

$text-color: #000;

tokens.css

:root {
  --text-color: #000;
}

ダーク・モードのデザイン・トークン

異なるモード用のデザイン トークンは、デフォルト トークンとは別に生成されます。トークンに同じ名前を使用することで、例えばインポート時にデフォルト値を上書きすることができます：

Input

color.dark.tokens.json

{
  "text-color": {
    "$value": "#fff",
    "$type": "color"
  }
}

出力

tokens.dark.grouped.json

{
  "color": {
    "text-color": "#fff"
  }
}

tokens.dark.js

export const TEXT_COLOR = "#fff";

tokens.dark.scss

$text-color: #fff;

tokens.dark.css

:root {
  --text: #fff;
}