【完全ガイド】Auto Design Tokens Optimizer 導入・実装・運用まで全部解説

はじめに

Auto Design Tokens Optimizer（以下 ADTO）とは何か

実際の導入手順（npm / CLI / PostCSS）

・デザイントークンの書き方と注意点

・実運用でのおすすめ構成

・CI への組み込み方法

・よくあるハマりポイント

この記事はgakuseibotアドベントカレンダー21日目の記事となります。
ぜひ最後までお読みください。

1. Auto Design Tokens Optimizer とは？

ADTO は デザイントークン（特に色）を自動で最適化するツールです。

• 背景色と文字色のコントラストを自動補正

• 色相・明度・彩度の微調整

• JSON / CSS トークンに対応

• CLI / PostCSS どちらでも利用可能

目的はただ一つ。

「人がミスしやすい色調整を、機械に任せる」

2. 対応環境・前提条件

必要な環境

• Node.js 18 以上（推奨）

• npm / pnpm / yarn のいずれか

想定プロジェクト構成

project/
├─ tokens/
│  └─ design-tokens.json
├─ src/
│  └─ styles.css
├─ package.json
└─ postcss.config.js

3. インストール方法（npm）

① パッケージの追加

npm install @akiy2009/auto-design-tokens-optimizer

または開発用として入れる場合：

npm install -D auto-design-tokens-optimizer

② package.json の確認

{
  "devDependencies": {
    "auto-design-tokens-optimizer": "^x.x.x"
  }
}

※ バージョンは実際の最新版に合わせてください。
2025年12月16日時点では1.01が最新バージョンです。

4. CLI を使った基本的な使い方

4-1. デザイントークンを用意する

{
  "color": {
    "background": "#ffffff",
    "primary": "#3a86ff",
    "text": "#bbbbbb",
    "danger": "#ff006e"
  }
}

4-2. 最適化コマンドを実行

npx adt-optimize \
  --input tokens/design-tokens.json \
  --output tokens/optimized-tokens.json

実行内容

• 背景色に対して文字色が薄い場合 → 自動補正

• 色同士の差が小さい場合 → 視認性を考慮して調整

• 元データは一切変更されない（安全）←これがこのADTOの魅力の一つ

4-3. 出力結果の例

{
  "color": {
    "background": "#ffffff",
    "primary": "#2f6fe0",
    "text": "#333333",
    "danger": "#e6005c"
  }
}

※ 実際の数値は入力によって異なります。

5. CSS / PostCSS と連携する方法

5-1. PostCSS プラグインとして使う

npm install -D postcss

5-2. postcss.config.js

module.exports = {
  plugins: [
    require('auto-design-tokens-optimizer/postcss')({
      input: './tokens/design-tokens.json',
      output: './tokens/optimized-tokens.json'
    })
  ]
};

5-3. CSS 側でトークンを使う

:root {
  --color-bg: var(--background);
  --color-text: var(--text);
  --color-primary: var(--primary);
}

6. Tailwind CSS と一緒に使う場合

6-1. 最適化済みトークンを読み込む

// tailwind.config.js
const tokens = require('./tokens/optimized-tokens.json');

module.exports = {
  theme: {
    extend: {
      colors: tokens.color
    }
  }
};

6-2. メリット

• Tailwind 側は「安全な色」しか使わない

• デザイントークンの更新が即反映

• 手動調整がほぼ不要

7. CI（GitHub Actions）への組み込み

7-1. ワークフロー

name: Optimize Design Tokens

on:
  push:
    paths:
      - 'tokens/**'

jobs:
  optimize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - run: npm ci

      - run: npx adt-optimize \
          --input tokens/design-tokens.json \
          --output tokens/optimized-tokens.json

7-2. こうすると何が良い？

• 誰が色を変更しても自動で最適化

• 人為的ミスが入りにくい

• レビュー時に「色大丈夫？」議論が減る

8. 実運用でのおすすめルール

✅ 元トークンと最適化後は分ける

tokens/
├─ raw-tokens.json
└─ optimized-tokens.json

👉 人が触るのは raw のみ

✅ 最適化後は編集禁止

• optimized は自動生成物

• Git 管理するかはチーム方針次第

✅ デザインツールとの役割分担

• Figma → raw-tokens

• ADTO → optimized-tokens

• フロント → optimized-tokens

9. よくあるハマりポイント

❌ 色が変わりすぎる

→ コントラストが極端に低い可能性あり
→ 元トークンの色を見直す

❌ 最適化結果が毎回違う

→ 入力値がランダム要素を含んでいないか確認
（通常は再現性あり）

10. まとめ

Auto Design Tokens Optimizer は、

• デザイントークン管理

• アクセシビリティ対策

• CI 自動化

を 一気に楽にする実務向けツール です。

色は感覚から
色はルールと自動化へ移行したい人には、かなり相性がいいです。

この記事をここまで読んだ人は、色のデザインに自信がないのでしょう。
これを機にADTOを導入してみませんか？

参考リンク

• GitHubリンク

• GitHubリリースノート

• npmパッケージリンク

ぜひコントリビュートお願いします！！！
間違いやおすすめの改良方法があればコメントをお願いします。
それではまた、、、