token-compliance について
token-complianceは、デザインシステム向けのコード監査スキルです。ハードコード値、誤った階層のトークン参照、不統一な適用を検出し、ファイル位置や重要度、修正案を含むレポートを作成します。
主な機能
- 01ハードコード値とトークン違反の検出
- 02トークン階層と適用の一貫性確認
- 03ファイルと行番号を示すレポート
- 04修正案の提示
- 05スタイル方式と設定に応じたチェック
活用シーン
- 01トークン移行前のコードベース監査
- 02スタイルファイル内の生値の検索
- 03繰り返し発生する違反箇所の特定
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ murphytrueman/ design-system-ops --skill token-complianceインストール後、Claude Code で/token-complianceを入力して読み込まれたか確認します。
詳細
トークン準拠
コードベースや実装におけるトークン準拠違反を特定するスキルです。トークンを使用すべき箇所にハードコードされた生の値、誤った階層のトークン参照、一貫性のないトークン適用を検出します。ファイルへの参照と修正方法を含む違反レポートを作成します。
始める前に:参照を確認する
このスキルのフロントマターにある references: の各パスが、SKILL.md からの相対パスとして存在することを確認してください。存在しないパスがある場合は、処理を中断してください。通常、フラット化インストーラー(例:npx skills install)によってリポジトリルートの knowledge-notes/ ディレクトリが削除されたため、インストールが不完全です。1-INSTALL.md に記載の方法で再インストールし、インストールルートから verify-install.sh を実行するようユーザーに伝えてください。ユーザーが明示的に参照なしで進めるよう求めた場合に限り、参照を使わずに続行し、その場合は出力に、このパックの参照資料を使わずに作成したことを明記してください。
コンテキスト
トークン準拠の問題は、気づかれないまま徐々に積み重なります。ハードコードされた16進数の値が1つあっても、何かが壊れるわけではありません。しかし、2年間にわたり、数十人のコントリビューターがコードベース全体に200個の値を散在させると、ブランドの刷新やダークモードの実装は、トークンを更新するだけでは済まず、何千ものファイルを手作業で検索して置換する作業になります。
準拠チェックは、違反が蓄積する前に検出し、すでに蓄積している場合は違反のパターンを把握するためにあります。パターンは重要です。ハードコードされた値が特定の製品領域や特定のチームの貢献に集中している場合と、全体に均等に分布している場合とでは、対応が異なります。
設定
.ds-ops-config.yml が存在する場合は、設定と繰り返し実行に関するナレッジノート(../../knowledge-notes/configuration-and-recurring.md)に従い、読み込み、連携のフォールバック、繰り返し実行の方法を確認してください。このスキルでは、以下を読み込みます。
severity.*— 違反の重大度に対する上書き設定。特にhardcoded_color、wrong_tier_reference、tier_leakagesystem.theming—trueの場合、ハードコードされた色に関する違反の重大度を設定値(通常はcritical)まで引き上げますsystem.styling— 検出方法を事前に選択しますintegrations.github— チェックアウトして検索するリポジトリ(以下を参照)integrations.style_dictionary— 既存トークンと正しい階層を参照するための、解析済みトークンツリーgates.*—component-to-releaseの一環として実行する場合に、リリースをブロックする違反
自動プル統合
GitHub(integrations.github.enabled: true):
- GitHub のコード検索 API ではなく、
integrations.github.repoのローカルチェックアウトを検索します(ノートの GitHub に関する注意を参照)。コード検索では#が無視されるため、そこで色を検索しても何も見つからず、問題なしと判断されてしまいます。 - 手動チェックの前に、色を広範囲に検索します:
ripgrep がない場合:rg -n --glob '*.{css,scss,less,ts,tsx,js,jsx,vue}' --glob '!**/tokens/**' --glob '!**/{dist,node_modules}/**' \ '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\('grep -rnE --include='*.css' --include='*.scss' --include='*.tsx' [etc.] --exclude-dir=tokens --exclude-dir=node_modules --exclude-dir=dist '<same pattern>' .トークンが実際に格納されている場所に合わせて glob を調整します。誤検出(#addや#fadedなどの CSS ID セレクター)が発生する可能性があるため、手作業で取り除いてください。 - 陽性対照: トークンのソースファイルにも同じパターンを実行します。ほかの場所でゼロ件と報告する前に、そこで一致するものが見つからなければなりません。トークンのソースでも何も見つからない場合、このコードベースにパターンが適合していません。結果は未確認と伝えてください。
- スタイリングファイル内の
px値を、スペーシング準拠の指標として検索します - 詳細な監査の前に、結果を使って対象範囲を定量化します。レポートの要約では、「47 ファイルに約 340 個のハードコードされた 16 進値」のような表現(例示値)が有用です
Style Dictionary(4 または 5)(integrations.style_dictionary.enabled: true):
- トークンツリーを解析し、各ティアで利用可能なトークンの完全なマップを作成します
- 違反を指摘する際に「どのトークンを参照すべきか」を調べるための信頼できる情報源として使用します
- ハードコードされた値が、解決後の既知のトークン値と完全に一致する場合は、修正方法の案内にトークン名を自動的に含めます
Figma MCP(integrations.figma.enabled: true):
- 参照情報として Figma の変数定義を取得します。コード内でハードコードされた色が Figma の変数として定義されている場合、正しいトークンが判明しているコンプライアンス違反です。
ステップ 0:乱雑なコードベース向けプロトコル
トークンの準拠による効果が最も大きいのは、長年にわたってハードコードされた値が蓄積し、スタイル設定の方法に一貫性がなく、トークンへの移行を何度も試みてきたような、乱雑なコードベースです。こうしたコードベースでは、拡張検出プロトコルを適用します。
乱雑なコードベースを示す指標:
- 同じプロジェクト内に複数のスタイル設定方法がある(CSS カスタムプロパティ、SCSS 変数、インラインスタイルなど)
- トークンファイルはあるものの、コードベースのかなりの部分が導入前に作成されている
- スタイルファイル内に複数の命名規則が混在している(camelCase、kebab-case、BEM など)
- 古いカラーパレットと現在のトークンが共存している
- コンポーネントのテンプレートにインラインの
style=属性がある
乱雑なコードベース向けの拡張検出:
-
古い値のマッピング。 違反を指摘する前に、古い値を現在のトークンに対応付けるマップを作成します。レガシーコードにあるハードコード値の多くは、記述された当時は正しいものであり、トークンシステムの導入前のものです。
#0066CCをvar(--color-action-primary)に対応付けることで、修正案を「トークンを使う」だけでなく、具体的に示せます。 -
違反の古さの推定。
git log -S'<value>' -- <file>(値を追加したコミット)またはgit blame -w -Cを使って、違反が導入された時期を推定します。通常のgit blameやファイルの更新日時が示すのは、最後の再フォーマットやファイル移動の時点であり、元の作成者ではありません。日付を信頼する前に、一括フォーマットのコミットがないか確認してください。違反を時期ごとに分類します。- トークン導入前の時代(トークンシステムの導入前):想定される技術的負債であり、準拠違反ではありません
- 移行期(トークンの導入中):一部の値はトークンを使い、ほかの値は使っていない、部分的に移行されたファイルです
- トークン確立後の時代(トークン確立後):実際の準拠違反であり、より重大なものとして扱う必要があります
-
ホットスポットの検出。 違反が最も多い5~10個のファイルを特定します。これらは修正効果の高い対象です。修正すれば、違反数を大幅に減らせます。次の形式で提示します。
Compliance hotspots (illustrative): 1. src/legacy/checkout/styles.scss — 47 hardcoded values (pre-token era) 2. src/components/Card/Card.styles.ts — 23 hardcoded values (migration era) 3. src/pages/Dashboard/index.tsx — 19 inline styles (post-token era — PRIORITY) -
意図的なオーバーライドの検出。 ハードコードされた値がすべて違反とは限りません。
/* override */や/* intentional */のようなコメントが付いた値は、「コード内で意図的と明示」として、コメントとともに別途一覧にします。チームが確認できるようにしてください。- どのトークンにも一致しない値も、ほかの値と同様に重大度を付けて、違反ログに1回だけ記録します。「正しいトークン」列には「なし — 最も近い値:
<token>」と記入し、「メモ」ではその行にシステム外の値であることを示します。その値は個別のデザイン要件である可能性も、スケールに不足がある可能性もあります。どちらに該当するかはツールではなくチームが判断します。
ステップ 1:対象範囲とアクセスを定義する
次の項目を確認または質問します(自動取得で回答済みの質問は省略してください)。
- 何を評価しますか?(コードベース全体、特定の製品領域、特定のコンポーネント群)
- 実装へのアクセス:コードベース、Figma ファイル、Storybook、または説明されたプロパティ
- 使用中のトークンシステム:どのようなトークンが存在し、どの階層が定義され、コードでトークンがどのように使用されているか
- スタイリングの方式:CSS カスタムプロパティ(
var(--token))、SCSS 変数($token)、Tailwind ユーティリティクラス、CSS-in-JS のテーマオブジェクト、またはそれらの組み合わせ - チェックで優先すべき、既知のコンプライアンス上の重点領域
- これがベースライン監査か、以前のチェックに対するフォローアップか
- コードベースの経過年数と移行履歴: トークンが導入されたのはいつですか? 以前に移行を行っていますか? 既知のレガシー領域はありますか?(これにより、コードベースの複雑さに関するプロトコルを適用するかどうかが決まります。)
- コードからは分からないコンテキスト(以下の重大度調整にのみ使用):どのコンポーネントが重要なユーザーパス上にあり、どのコンポーネントが廃止予定ですか? 一度だけ尋ね、回答がない場合は調整を適用せず、その旨を Scope に記載します。ディレクトリ名から重要なパスを決して推測しないでください。
コードにアクセスできない場合(パスがない、ローカルのチェックアウトがない、ファイルが貼り付けられていない場合)は、作業を中断してコードの提供を求めてください。説明されたコードに基づくコンプライアンスチェックは推測にしかなりません。デザインシステム自体のコンポーネントコードも、トークンを使用するコードに該当します。対象がシステムのリポジトリである場合は、その旨を Scope に記載してください。トークンのソースファイルはチェック対象外であり、チェック対象となるのはコンポーネントだからです。
違反の検出方法はスタイリングの方式によって異なります。
- CSS カスタムプロパティ: トークン参照は
var(--color-action-primary)のようになります。ハードコード値はvar()の外にある、生の hex/rgb/px 値です。 - SCSS 変数: トークン参照は
$color-action-primaryまたはmap-get($tokens, 'action-primary')のようになります。ハードコード値は$変数を使用していない生のリテラル値です。 - Tailwind ユーティリティクラス: トークン参照は、デザインシステムの Tailwind 設定に対応するユーティリティクラスです(例:
bg-primary、text-color-content-default、gap-4)。これらはハードコード値ではなく、ユーティリティクラスで表現されたトークン参照です。Tailwind のハードコード値は任意の値を指定する角括弧です(例:h-[12px]、bg-[#ff0000]、p-[7px])。任意の値は違反として指摘し、設定済みのトークンに解決される標準ユーティリティクラスは指摘しないでください。 - CSS-in-JS(Emotion、styled-components): トークン参照は
theme.colors.action.primaryやtokens.spacing[4]のようになります。ハードコード値はスタイルオブジェクト内の生のリテラル値です。
フレームワーク固有の検出に関する注意事項:
- Vue SFC を使用している場合: トークン違反は
<style lang="scss" scoped>ブロック内に現れます。$token変数またはvar(--token)を使うべき箇所に、生のpx値がないか確認してください。Vue のスコープ付きスタイルには、動的 CSS 用にv-bind()でトークン参照が含まれることもあります。トークンを基にしたプロパティにバインドされていれば、これは有効なトークンの使用です。 - Twig/Fractal を使用している場合: トークン違反は、テンプレート内のインライン
style=""属性(例:style="background-color: {{ item.color }}")、SVG のfill/stroke属性内のハードコードされた hex 値、HTML の寸法属性内の生のピクセル値に現れます。Twig コンポーネントは通常、BEM ユーティリティクラスを介してトークンを参照します。テンプレートだけでなく、それらのクラスに対応する SCSS を監査してください。 - Emotion/styled-components を使用している場合:
theme.spacing(4)などのヘルパー呼び出しは有効なトークンの使用です。誤って指摘しないよう、まずコードベース内のヘルパーを確認してください。オブジェクト構文の検索では見つからない生の値は、テンプレートリテラル CSS(css\padding: 16px``)に隠れている可能性があります。バッククォートの中も検索してください。 - React Native を使用している場合: スタイルは
StyleSheet.createまたはインラインのstyle内で、単位のない数値(padding: 16、fontSize: 14)として記述されます。ここでの数値リテラルがハードコード形式です。トークン参照はtokens.spacing.mdやテーマフックのようになります。
ステップ 2:準拠チェックを実行する
すべてのチェックから除外するもの: トークンのソースファイル、生成された CSS(ビルド出力)、SVG アセット、ストーリー/テストフィクスチャ。Scope ブロックに、除外したパスを記載してください。
基本重大度(ステップ 3 のコンテキスト調整前。severity.* の設定キーが優先されます):
- 🔴 重大 — 複数のテーマを提供するシステムで、色がハードコードされているか、誤った階層の色を参照している場合:テーマを切り替えられません
- 🟠 高 — 単一テーマのシステムで色がハードコードされているか、誤った階層を参照している場合。トークンがあるテキストロールにタイポグラフィがハードコードされている場合
- 🟡 中 — スケールトークンが値に一致するスペーシングがハードコードされている場合。同じロールに異なるトークンを使っている兄弟コンポーネント間の不一致
- ⚪ 低 — 意図が曖昧な固定寸法(境界線の幅、タッチターゲットなど)。デザイン上の判断を待つシステム外の値
違反ごとに、Location はファイルと行番号を示します。これらが記載されていない指摘は記録しません。
すべての箇所で除外する値: transparent、currentColor、inherit、none、および CSS 全体に適用されるキーワード(initial、unset、revert)。これらは違反にはなりません。
チェック 1:色のハードコード値
トークン参照ではない色の値をすべて検出し、指摘してください:
- 16 進値(例:
#0066CC、#FFF) - RGB および RGBA 値(例:
rgb(0, 102, 204)、rgba(0,0,0,0.5)) - HSL 値
- 色名の値(例:
red、white。上記の除外キーワードは除く)
指摘ごとに、ファイル参照またはコンテキスト、検出した未加工の値、参照すべきトークンを記載してください。
コードではなくデザインファイルを対象に評価する場合は、ライブラリスタイルではなく、未加工の値として適用されている色のスタイルを探してください。
チェック 2:スペーシングのハードコード値
トークン参照ではないスペーシング値をすべて検出し、指摘してください:
- padding、margin、gap、width、height プロパティの生のピクセル値(例:
padding: 16px、gap: 8px) - スペーシングスケールの値に該当する rem 値(例:
16px/1remに対応するスペーシングトークンがある場合の1rem)
注:すべてのピクセル値が準拠違反になるわけではありません。境界線の幅、最小タッチターゲット、その他の固定寸法は、意図的にハードコードされていることがあります。意図が曖昧な場合は、⚪ 低として記録し、その理由を記載してください。
チェック 3:タイポグラフィのハードコード値
トークン参照ではないタイポグラフィの値をすべて検出し、指摘してください:
- 生のフォントサイズ値(例:
font-size: 14px) - 生のフォントウェイト値(例:
font-weight: 700) - 生の行の高さの値(例:
line-height: 1.5) - 生のフォントファミリー値(例:
font-family: 'Inter', sans-serif) - 生の文字間隔の値
チェック 4:誤った階層のトークン参照
意味トークンを経由せず、プリミティブトークンを直接参照しているコンポーネントレベルのコードを検出し、指摘してください:
違反例:ボタンの実装にある background-color: var(--color-blue-500)
あるべき形:background-color: var(--color-action-primary) → var(--color-blue-500)
これは最も見つけにくく、アーキテクチャに最も深刻な影響を与える準拠違反です。表面的には正しく見えます。適切な色が使われていますが、意味上の契約が破られるため、「アクションのプライマリ」の意味を変更するなどの意味上の変更がコンポーネントに反映されなくなります。
指摘ごとに、参照されているトークン、代わりに使用すべき意味トークン、コンテキストを記載してください。
トークンファイルでプリミティブに対して定義されているコンポーネント トークン(card.border: {color.gray.200} など)は定義上の問題であり、その対応は token-audit の階層漏れチェックが担います。ここで誤った階層の参照として記録するのは、コンポーネントのスタイルシート内の var(--color-gray-200) のように、使用側のコードに現れる場合に限ります。途中で定義上の問題に気づいた場合は、Scope の下に token-audit へ引き継ぐ問題として一度だけ記載し、TC- ID は付与しないでください。
チェック 5:トークン適用の不一致
同じ視覚的プロパティが、コンポーネントやコンテキストによって異なる方法で実装されている箇所を見つけて報告します。
- 同じセマンティックな役割が、異なるコンポーネントで異なるトークンを使って実装されている(例:同じ役割に対して、一部では
color.action.primary、別の箇所ではcolor.brand.500を使用) - 類似するコンポーネント間で、同じ間隔のコンテキストに異なるスペーシングトークンを使用している
- 共有すべきトークンが、コンポーネント間で異なるインタラクティブ状態(ホバー、フォーカス、アクティブ)に適用されている
こうした違反は、コンポーネント単位のレビューでは見つからないことが多いものの、コンポーネントを比較すると明確になります。
ステップ 3:違反レポートを作成する
トークン準拠レポート
全体の状況と、重点を置くべき箇所を伝える見出し文で始めます。
日付: [date] 対象範囲: [what was assessed] 評価方法: [codebase / design file / Storybook / described properties]
概要
準拠状況の全体像を示します。最も重大な発見事項は何ですか?違反の傾向は一部に集中していますか、それとも広範囲に及んでいますか?
違反件数
| チェック | 違反数 | 🔴 重大 | 🟠 高 | 🟡 中 | ⚪ 低 |
|---|---|---|---|---|---|
| ハードコードされた色の値 | |||||
| ハードコードされたスペーシングの値 | |||||
| ハードコードされたタイポグラフィの値 | |||||
| 誤った階層のトークン参照 | |||||
| トークン適用の不一致 | |||||
| 合計 |
違反ログ
チェックの種類ごとにまとめます。違反ごとに、次の情報を記載します。
| ID | チェック | 重大度 | 場所 | 生の値/誤った参照 | 正しいトークン | 備考 |
|---|---|---|---|---|---|---|
| TC-01 | 色 | 🔴 重大 / 🟠 高 / 🟡 中 / ⚪ 低 | [file path or context] | #0066CC | var(--color-action-primary) |
各値は一度だけ記載します。対応するトークンがないシステム外の値も、重大度を付けてこの表に記載します。「正しいトークン」列には「なし — 最も近い値:<token>」、「備考」列には「システム外」と記載します。別のリストに重複して記載しないでください。
構造上の理由で除外: 除外した値とその理由を1行で列挙します。例:max-width: 960px(レイアウトコンテナー)、border: 1px solid(区切り線)、テスト用ラッパーのパディング。これらを違反として記録しないでください。
コンテキストを考慮した違反の重大度
違反の重大度はすべて同じではありません。コンポーネントの重要度に応じて重大度を調整してください。これが、準拠チェックと単純な grep の違いです。コンテキストを考慮して重大度を調整しなければ、すべての違反が同じように見えてしまいます。
重大度を引き上げる(1段階上げる):
- 重要なユーザーパス(購入手続き、認証、主要ナビゲーション)上のコンポーネントにある違反
- 被参照数の多いコンポーネントにある違反(
codebase-indexの実行後は.ai/index/を参照してください。それ以外の場合はこの調整を省略し、その旨を記載してください) - テーマの影響を受けやすいコンポーネント(ブランドを前面に出す画面、ダークモードの対象)にある違反
- トークン導入後のコードにある違反(トークンシステムの確立後に追加されたもの。これらは過去から引き継がれた負債ではなく、現在の準拠違反です)
標準の重大度:
- 中程度の頻度で使用される汎用コンポーネントにある違反
- 移行期のコードにある違反(部分的に移行済みで、準拠に向けた改善が進行中)
重大度を引き下げる(1段階下げる):
- ユーザーに直接表示されない内部用/ユーティリティコンポーネントにある違反
- 非推奨化がすでに予定されているコンポーネントにある違反
- 既知の移行スケジュールがあるレガシーコード領域における違反
- トークンシステムの存在前に追加された、トークン導入前のコードにある違反(これらは想定される負債です)
- デザイントークンとは関係のない構造上の用途で、生のピクセル値を使用するレイアウトユーティリティ(例:コンテナーの
max-width: 1200px、区切り線のheight: 1px)。これらは違反ではありません。「構造上の理由で除外」の行に記載してください
初期の重大度を割り当てた後に調整を適用します。調整内容と理由を違反ログに記載してください。「重大度を中から高に引き上げ:コンポーネントが購入手続きの重要なパス上にある。」
パターン分析
個々の違反から一歩引いて、パターンを説明します。
- 違反は特定のファイル、コンポーネント、製品領域に集中していますか?
- 特定のトークンに明確に対応する、頻繁に現れる生の値はありますか?
- 違反件数の大半を占める特定のチェックタイプはありますか?
パターン分析によって、違反ログを実行可能なインサイトに変えられます。「ハードコードされたスペーシングの違反はレガシー製品領域に集中しています。トークンシステム導入前のものと思われます」という分析と、「ハードコードされたスペーシングの違反は均等に分布し、増加しています。トークンシステムが採用されていません」という分析では、対応が異なります。
修正の優先順位
即時対応: 階層が誤ったトークン参照と、テーマ設定やブランド変更によって問題が発生するハードコード値。これらはアーキテクチャに影響します。
計画対応: 既存のトークンに明確に対応する、一貫したハードコード値。これらは体系的な作業で解決できます。
要確認: 曖昧な値(生のパーセンテージ、状況に依存する px 値、意図的なオーバーライド)。修正前に人の判断が必要です。
修正方法
検出された違反の量とパターンに応じて、最も効率的な方法を提案します。
- 違反が大量かつ反復的な場合:手動修正よりも、移行スクリプトや codemod のほうが効率的です
- 違反が特定の領域に集中している場合:その領域に絞ったリファクタリングスプリントを実施します
- 違反が少数で分散している場合:チームの継続的なコードレビュー基準に追加し、各領域に手を加える際に対応します
- 階層が誤った参照が多い場合:修正に先立ってトークンアーキテクチャをレビューし、セマンティック階層が正しい参照に十分な状態か確認することを検討します
- トークン導入後に生じた違反には、クリーンアップと並行して件数の増加を止めるリントルールを常に適用します。CSS、SCSS、CSS-in-JS 文字列には、トークンに対応するプロパティに対して、トークンパターンを
ignoreValuesとする Stylelint のstylelint-declaration-strict-valueを使用します。Tailwind にはeslint-plugin-tailwindcssのno-arbitrary-valueを使用します。React Native には、数値のスタイルリテラルを対象にしたカスタム ESLint ルールを使用します。設定はgovernance-encoderが書き込みます
スコープ
- 調査対象: [検索したディレクトリとファイルタイプ]
- 調査対象外: [除外したパス — トークンソース、生成済み CSS、SVG アセット、ストーリー/フィクスチャ — と、調査範囲外のもの]
- 「検出なし」の確認方法: [ゼロ件と報告されたチェックについて、肯定対照として同じパターンがトークンソースで検出されたこと]
- 前提条件: [例:参照先として使用したトークンツリーが最新であること]
いずれかの値が意図的なもの(デザイン上必要な単発の値、または許容しているレガシー領域)であれば、お知らせください。今後の実行では除外します。
トークン定義はこのスキルの対象外です。DTCG 形式とエイリアスの整合性には schema-validator を、階層構造とシステム間の一貫性には token-audit を使用してください。
品質チェック
- 5 つすべてのチェックが網羅されている
- 階層が誤った参照はハードコード値とは別にチェックされている — これらは異なる種類の違反です
- パターン分析のセクションがあり、違反の合計だけでなく分布を説明している
- 修正の優先順位で、アーキテクチャ上の違反と表層的な違反が区別されている
- レポートは対応に十分な具体性がある。単に「ハードコード値が見つかった」ではなく、違反ごとにファイル参照またはコンテキストが記載されている
- ゼロ件のカウントはすべて、トークンソースに対する肯定対照で裏付けられている
- 重大度の調整には、その根拠となる事実(明示されたクリティカルパス、インデックスのファンイン数、git の時代)が記載されている。名前から推測されたものはない
- 免除キーワードと除外パスが違反として記録されていない
- レポートの末尾にスコープのブロックと、意図的な値について知らせるよう促す文がある