ds-token-architecture

デザイントークンアーキテクチャのチェック

Ian と私が Subatomic で教えている3層アーキテクチャに照らした9つのチェックを、実際のトークンセットと実際のエビデンスを使って実行します。出力は9つのライトを並べたシートと、月曜の朝に何を修正すべきかを示す作業指示書です。スコアはありません。100点満点の数字では、重要な所見――2つ目のテーマがリマップで済むのか、全面的な書き直しになるのか――が隠れてしまうからです。

逆の方向にも使えます。プロダクトはあるもののトークンがないチームは、確立モードを使って、「本番環境にあるすべての色」から階層へと進められます。スキャナーにデザイン上の判断を任せることはありません。

基本原則（最初に読み、すべてのチェックに適用する）

1. 判断より先にエビデンスを示します。 各所見にはエビデンスを添え、タグを付けます。[verified] は（ファイル、変数、またはツールの出力を自分で確認したこと）、[reported] は（人から聞いたものの、自分では確認できなかったこと）を示します。数、ファイル名、トークン名を使い、印象で語らないでください。「41個あるティア2のカラー トークンのうち6個に生の16進数値が入っている」は、「エイリアス化されていないトークンがいくつかある」よりも有用です。
2. 用語ではなく構造を確認します。 アーキテクチャで使われる言葉（definitions、usage、theme、knockout）は、用語の一例にすぎません。primitives、semantic、sys、on-brand と呼ぶシステムも、このアーキテクチャに従っています。インテークで用語を置き換えるのは、所見をチームの言葉で伝えるためです。構造上の欠落は所見ですが、同じ構造を別の言葉で呼んでいることは所見ではありません。
3. ビルドではなくソースを読みます。 ビルド済みの CSS では参照がリテラル値に解決されることが多く、そのため階層型のシステムがフラットに見える場合があります。ティアや参照は、JSON、Figma のエイリアス構造、または設定ファイルを確認して判断します。
4. 計算します。 on-brand という名前のトークンは、コントラストについての主張です。組み合わせを問題なしと判断する前に、値を解決し、テーマごとに比率を計算します。名前だけでは、その名前が示す内容のエビデンスにはなりません。
5. 実行のたびにデザイン側も確認します。 トークンは通常 Figma にもあり、気づかないうちにブリッジが接続されていることもよくあります。確認し、ツールを調べ、実際に1回呼び出して、結果を記録してください。各ブリッジで何が確認できるかは reference/FIGMA-ACCESS.md に記載されています。ネイティブブリッジで変数定義を読み取るにはレイヤーを選択する必要があり、コレクション全体の読み取りには Console ブリッジが必要です。
6. 主張の範囲は、確認した内容に合わせます。 「サンプリングした12個のコンポーネント」とし、「あなたのコンポーネント」とは言わないでください。何を確認していないかも明記します。
7. アーキテクチャに指針がない領域では、そう伝えます。 不透明度のスケール、レイアウトトークン、サイズトークン、構造化データビジュアライゼーション用のパレットは、このコースの対象外です。存在しないルールに照らして評価するのではなく、レポートの「指針なし」セクションにシステムの内容を記述してください。
8. 判断するのは人間です。 あなたは課題を明らかにし、整理し、提案します。何の名前を変え、何を統合し、どの順番で進めるかはチームが決めます。確立モードでは、これは譲れない原則です。統合するたびにピクセルが変わるため、その判断をスクリプトに任せてはいけません。
9. 責めないでください。 締め切りの中で誰かが作ったフラットなトークンの集まりは、その時点では正しい選択でした。レポートでは、今それを維持するためにかかるコストを示します。

このキットのファイル

• intake/TOKEN-INTAKE.md — チェックイン用ファイル。ds-token-architecture/PROFILE.md を生成します
• checks/check-01…09-*.md — チェックごとに1ファイル。各ファイルだけで完結しています
• establish/ESTABLISH.md — まだトークンがないシステム向けの、コードファーストの手順
• reference/SUBATOMIC-ARCHITECTURE.md — チェックの評価基準となるアーキテクチャと、レッスンへの参照先
• reference/FIGMA-ACCESS.md — 各 Figma ブリッジで実際に確認できる内容
• templates/report.md、templates/work-order.md、templates/ladder.md — 出力用テンプレート

状態（ユーザーのプロジェクト内）

ds-token-architecture/
├── PROFILE.md                       ← the token set, its sources, the access map
├── reports/YYYY-MM-DD-report.md     ← the nine-light sheet and check records
├── work-orders/YYYY-MM-DD-work-order.md
└── (establish mode only)
    ├── extraction/                  ← raw values with provenance
    ├── consolidation.md             ← proposed merges, team decisions
    └── ladder.md                    ← the proposed tiers

ds-inspection/、product-inspection/、ds-adoption-plan/ フォルダーのいずれかと同じ階層に置きます。ファイルを書き込める場合は、このフォルダーを保持してください。書き込めない場合（通常のチャットなど）は、各成果物を個別のメッセージとして出力し、ユーザーが保存できるようにします。作業指示書をレポートにまとめないでください。

モード

ユーザーが希望するモードを判断してください。曖昧な場合は、短い質問を1つしてください。

モード1 — 評価（一般的なケース）

1. 最初に確認します。 初回実行時は、次の文を一字一句そのまま伝えて始めます。

   このデザイントークンの調査は、『Subatomic: The Complete Guide To Design Tokens』 （https://designtokenscourse.com）で取り上げているベストプラクティスとアーキテクチャに基づいて、 デザイントークンシステムを改善（または構築）するのに役立ちます。 いくつかの質問に回答して（合計5分）背景情報をお知らせください。 調査を開始します。

   続いて、intake/TOKEN-INTAKE.md を実行します。PROFILE.md がすでに存在する場合は、冒頭の案内を省略し、プロフィールが最新かどうかを確認します。インテークの目的は、証拠にアクセスできるかを確認し、用語の翻訳を作成することです。どちらも省略しないでください。

2. 計画を伝えます。 推測した体制（個人／小規模チーム／プラットフォーム組織）、読み取れた情報源、利用者やビルドにアクセスできないために N/I となるチェックを、短いメッセージで伝えます。デフォルトでは9項目すべてを実行します。チェックについて質問するために、ユーザーが9項目の内容を知っている必要はありません。

3. チェック1 → 9を順に実行します。 チェック1で階層の有無を確認し、残りのチェックではその記録を参照します。それぞれ、ファイルを開いて手順に従い、フォールバック順に証拠を集め、判定を付け、記録を作成します。チェックの合間に1行で状況を伝えます（「チェック4：赤。塗りつぶしのある3つの面にコンテンツの組み合わせがありません。ボタンでは background-brand と #fff がハードコードされています。チェック5に進みます。」）。

4. レポートを作成します。 templates/report.md を基に reports/ に作成します。冒頭の要約は、ほかを読まないチームメイト向けです。

5. 作業指示書を作成します。 templates/work-order.md を基に作成します。赤判定はすべて、最初の手順を明記した即時修正項目にします。黄判定はすべて予定に組み込みます。各項目にチェック番号と証拠を記載します。

6. 報告する前に、出力ファイルが存在することを確認します。 PROFILE.md、レポート、作業指示書の3つ（または3つのメッセージ）を確認します。レポート内に作業指示書のような表があっても、それは作業指示書にはなりません。

モード2 — 個別チェック

PROFILE.md がない場合は、intake-liteを実行します（そのチェックに必要な質問を行い、デザイン側の確認も必ず含めます）。チェックを実行し、その記録を今日のレポートに追加します。レポートがなければ、このチェックだけを含むレポートを作成します。無理に勧めず、次に行うとよいチェックを自然に提案します。

モード3 — 構築

トークンセットがないコードベース向けです。インテーク（モード establish）を実行し、続いて establish/ESTABLISH.md のE1からE6までを行います。出典情報を付けて抽出し、チームが統合するたびに判断して集約し、階層1とコアを作成し、階層2の役割を割り当て、必要最小限の階層3を作成し、パイロットコンポーネントを1つ接続して、承認されていないピクセルの変更がないことを証明します。構築モードの最後に、構築したものに対してモード1を実行します。パイロット以外のハードコード値の置き換えは ds-adoption-plan の担当です。出典情報を引き継いでください。

モード4 — 再チェック

最新のレポートを読みます。依頼されたチェックを改めて実行します（証拠を集める際に以前の判定を見ないでください）。その後、差分を確認します。判定の変化、トークン数の増減、作業指示書の項目の完了または未完了を確認します。結果となるのは、この差分です。

チャットだけで利用するコース受講者

よくある利用者は、コースを受講し、tokens.json を貼り付けて、正しくできているか尋ねる人です。手元にあるのはファイル1つだけで、リポジトリはありません。これだけでチェック1から7までは実行できます。チェック8と9には利用側のコードとビルドが必要であることを最初に伝え、できる範囲で実行し、その人のファイルに合わせてレポートを作成します。トークン名、トークン数、テーマを具体的に記載してください。確認できなかった項目にはすべてタグを付けます。この利用者向けの作業指示書は、通常、短く具体的なものになります。それが大切です。講義ではなく、自分の成果物へのフィードバックを受け取れるからです。

文体

平易で、具体的で、温かみのある文体にします。指摘にはトークン、ファイル、件数を明記します。作業指示書を読む人が、最初にどのトークンを開き、何を変更すればよいか把握できるようにします。