token-audit

トークン監査

現在使用している各階層（通常はプリミティブとセマンティック、システムで使用している場合はコンポーネントトークンも対象）にわたって、デザイントークンのアーキテクチャを監査するスキルです。重大度を付けた指摘事項と、優先順位付きの改善リストを含む構造化レポートを作成します。

始める前に：参照を確認する

このスキルのフロントマターにある references: の各パスが、SKILL.md を基準に存在することを確認してください。存在しないものがある場合は、そこで中断してください。インストールが不完全であり、通常はフラット化するインストーラー（たとえば npx skills install）がリポジトリのルートにある knowledge-notes/ ディレクトリを取り込めなかったことが原因です。1-INSTALL.md に記載された方法で再インストールし、インストールルートから verify-install.sh を実行するようユーザーに伝えてください。ユーザーが明示的に続行を指示した場合に限り、参照なしで作業を進め、その場合は出力に、このパックの参照資料なしで作成したことを明記してください。

コンテキスト

このスキルでは、階層化されたトークンアーキテクチャのモデルを使用します。プリミティブは生の値を表し、セマンティックトークンは意図を表します。また、コンポーネントトークンがある場合は、その意図を特定の UI コンテキストに対応付けます。すべてのシステムがコンポーネントトークンを使用するわけではなく、コンポーネント階層がないこと自体は指摘事項ではありません。トークンに関する技術的負債の多くは、階層の境界が曖昧になることで蓄積します。たとえば、コンポーネントのコンテキストがプリミティブを直接参照している場合、セマンティック名が目的ではなく見た目を表している場合、またはプリミティブ階層だけが唯一の階層として扱われている場合です。

この監査は、特定の命名規則を強制するものではありません。トークン構造が、それを利用するチームの作業を妨げている箇所を特定することを目的としています。

---

設定

.ds-ops-config.yml が存在する場合は、設定と継続的な知識に関するノート（../../knowledge-notes/configuration-and-recurring.md）に従って、読み込み、統合の代替手段、定期実行に対応してください。このスキルでは、以下を読み込みます。

• severity.* — 指摘事項の重大度評価を上書きします（例：デフォルトの high ではなく、hardcoded_color: critical を指定）
• system.theming — true の場合、設定で指定された重大度までハードコードされた色に関する指摘の重大度を引き上げます
• system.styling — 適用する形式別ガイダンスをあらかじめ選択します
• integrations.style_dictionary — Style Dictionary 4 または 5 を使用してトークンを解析します（以下を参照）
• integrations.figma — 追加のトークンソースとして Figma 変数を使用します
• recurring.* — 傾向を比較するための前回のレポート（以下の定期実行ワークフローを参照）

統合からの自動取得

Style Dictionary 4 または 5、あるいは Terrazzo（integrations.style_dictionary.enabled: true、またはリポジトリ内の設定）：

• integrations.style_dictionary.config_path にある設定を解析します
• 解決済みの参照と階層構造を含む、トークンツリー全体を抽出します
• これを主要なトークンソースとして使用し、「トークンファイルを指定してください」という手動での質問は省略します
• npx style-dictionary build --config [path] をスクラッチ出力ディレクトリに対して実行します（または npx terrazzo build を実行します）。ツールにすべてのエイリアスを解決させてからツリーを分析してください。エラーは、そのツール名を情報源として指摘事項にします

Figma 変数（integrations.figma.enabled: true）：

• Figma MCP サーバーを使用して、integrations.figma.file_key にあるファイルから変数を読み取ります
• 変数コレクション、モード、解決済みの値を抽出します
• Figma の変数とコードのトークンファイルを照合し、不一致を検出します（Figma で --color-primary が #0066CC なのに、コードでは #0064CC とされている場合は指摘事項です）

GitHub（integrations.github.enabled: true）：

• ローカルファイルが提供されていない場合は、デフォルトブランチからトークンファイルを直接取得します

ステップ 0：トークンの検出

ユーザーにファイルを求める前に、コードベースを検索してトークンらしいパターンを探します。このステップにより、トークンは存在するものの一元管理されていないチームでも、調査を始めやすくなります。ユーザーがトークンの保存場所をすべて把握している必要はありません。

検索対象：

1. CSS カスタムプロパティ — すべての .css ファイルを対象に、:root ブロックまたは -- で始まるプロパティを検索します。.dark、[data-theme="..."]、.theme-* などのスコープ付きバリエーションも含めます。
2. SCSS/Sass 変数 — すべての .scss および .sass ファイルを対象に、$ で始まる名前を検索します。@import と @use の参照をたどり、パーシャルファイル（_colors.scss、_variables.scss、_tokens.scss）を見つけます。
3. JSON/YAML トークンファイル — よく使われるトークンの命名パターンに一致するファイルを検索します：tokens.json、tokens.yaml、*.tokens.json、design-tokens/**、src/tokens/**、tokens/**。また、$type または $value キーを含む DTCG 形式のファイルも探します。
4. Style Dictionary の設定 — style-dictionary.config.json、style-dictionary/ ディレクトリ内の config.json、または .style-dictionary.json を検索します。
5. TypeScript/JavaScript のトークンオブジェクト — .ts および .js ファイルを対象に、一般的なパターンに一致するエクスポートを検索します：export const tokens、export const theme、export default { color、トークンらしいキー階層を持つ as const 型付きオブジェクト。
6. Tailwind の設定 — tailwind.config.js、tailwind.config.ts、または tailwind.config.mjs を検索し、theme と extend ブロックを抽出します。
7. Figma Tokens / Tokens Studio — .tokens または tokens ディレクトリ内の tokens.json や、Tokens Studio からエクスポートされたファイルを検索します。

検索方法：

ファイルシステムへのアクセス（glob パターン、ファイルの読み取り）を使ってプロジェクトをスキャンします。GitHub 連携が設定されていてローカルクローンがない場合は、候補ファイルの特定にのみ gh api search/code を使用し、その後ファイルを読み取ります。Figma 連携が設定されている場合は、追加のトークンソースとして Figma の変数を取得します。

具体性の高いものを優先します。専用の tokens/ ディレクトリは、分散した CSS ファイルより信頼性が高くなります。Style Dictionary の設定は、未加工の JSON より信頼性が高くなります。ただし、すべて収集してください。トークンソースの分散そのものが調査結果となります。

検出結果：

続行する前に、簡潔な一覧を作成します。

Token sources found:
- src/tokens/colors.json (94 tokens, JSON, likely primitives)
- src/tokens/semantic.json (67 tokens, JSON, likely semantic tier)
- src/styles/variables.scss (43 variables, SCSS)
- tailwind.config.ts (theme block with 28 custom values)
Total: ~232 token-like declarations across 4 sources

検出結果がない場合は、ステップ 1 に進み、ユーザーに手動での入力を求めます。複数の形式にまたがって分散したソースが見つかった場合は、調査結果として次のように指摘します：「[N] 個のファイルに、[M] 種類の異なる形式でトークンが存在します。この分散は構造的負債です。単一の信頼できる情報源に一元化することを検討してください。」

検出したソースをユーザーに提示し、次のように尋ねます：「これらのトークンソースが見つかりました。すべてを監査しますか、それとも特定のファイルに絞りますか？」これにより、ユーザーが自分で一覧を作成しなくても、対象を選べるようになります。

---

ステップ 0b：孤立トークン検出のチェックポイント

本格的な監査を実施する前に、トークンの使用状況を一度確認します。孤立トークンの確認はここでのみ行い、ステップ 3c ではその結果を再利用します。

1. 宣言済みトークン — ステップ 0 で見つかった（またはステップ 1 で手動で提供された）すべてのトークンを数えます。
2. 参照されているトークン — 宣言済みの各トークンが参照されているか、他のトークンおよびこのリポジトリのコンポーネントから検索します。CSS カスタムプロパティの場合は var(--token-name) を検索します。SCSS 変数の場合は、宣言ファイル以外で $variable-name を検索します。JSON/DTCG トークンの場合は、エイリアス参照（{token.path}）を検索します。TypeScript オブジェクトの場合は、インポートおよびアクセスのパターン（tokens.color.primary、theme.spacing.md）を検索します。
3. 陽性対照 — 結果を信頼する前に、使用されていることがわかっているトークンを1つ選び、各検索パターンで見つかることを確認します。使用中のトークンが見つからないパターンは、このコードベースに適合していません。そのパターンを修正するか、その形式の孤立トークンは未確認として報告してください。
4. 孤立候補 — 他のトークンまたはスキャン対象のリポジトリ内のコンポーネントから参照されていないトークンです。

デザインシステムのリポジトリでは、スキャンされていないプロダクトリポジトリで大半のトークンが利用されています。ここでの孤立とは「リポジトリ内に利用箇所がない」という意味であり、「使われていない」という意味ではありません。利用するリポジトリまたは使用状況データへのアクセスをユーザーから提供されていない限り、孤立トークンは外部利用者について未確認として報告してください。

チェックポイントの要約を作成します（数値は説明用です）。

Orphan detection:
- 232 tokens declared
- 189 tokens referenced in-repo (at least once)
- 43 orphan candidates (no reference from another token or an in-repo component)
  Top candidates: --color-legacy-teal, --spacing-xl-deprecated, $font-heading-alt (3 more)
  Positive control: --color-action-primary found in 14 files by the same patterns
  Not checked: consuming product repos

これにより、本格的な監査を始める前に、ユーザーは問題の規模を把握できます。確認済みの孤立トークンは価値を生まない一方で、メンテナンスの負担になります。自動補完を煩雑にし、新しいチームメンバーを混乱させ、トークン数を増加させます。孤立候補は、主な監査結果にも含めてください（カテゴリ：カバレッジ、深刻度：低。ただし、総数の20％を超える場合は中）。また、どの利用者を確認したかも明記してください。

孤立トークンの割合が高い（総数の30％超）場合は、目立つように次のように警告してください。「宣言済みトークンの3分の1超が参照されていません。トークンの品質を監査する前に、クリーンアップを行うことでアーキテクチャを簡素化できるか検討してください。」

---

ステップ 1：トークンのソースを収集する

ステップ 0 でトークンのソースが見つかった場合は、それを主な入力として使用します。ユーザーが変更を希望しない限り、手動で質問する必要はありません。ステップ 0 で何も見つからなかった場合（またはコードベースにアクセスできずスキップされた場合）は、トークンのソースを尋ねます。受け付け可能な入力：

• JSON、YAML、または DTCG 形式のトークンファイル
• Figma ファイルまたは Tokens Studio のエクスポート
• トークン名と値の一覧を貼り付けたもの
• Style Dictionary の設定
• カスタムプロパティを含む CSS ファイル（例：:root { --color-primary: #5e4890; }、または .dark { }、[data-theme="dark"] などのセレクターにスコープされたテーマバリエーション）
• 変数を含む SCSS/Sass ファイル（例：$color-primary: #5e4890;）
• TypeScript または JavaScript のトークンオブジェクト（例：export const tokens = { color: { ... } }）
• カスタムトークンを定義する theme または extend ブロックを含む Tailwind CSS 設定ファイル（tailwind.config.js または tailwind.config.ts）

形式ごとのガイダンス：

CSS カスタムプロパティの場合：-- が付いたプロパティをそれぞれトークンとして扱います。命名パターンから階層を推測します。--color-blue-500 のようなプロパティはプリミティブ、--color-action-primary はセマンティック、--button-background-default はコンポーネント階層である可能性が高いです。プロパティがセレクター（:root、.dark、[data-theme="dark"]）にスコープされている場合は、各スコープをテーマバリエーションとして扱います。var(--other-token) を使用した CSS カスタムプロパティ間の参照は階層の関係を示します。JSON トークン参照と同じ方法で対応付けます。

SCSS 変数の場合：$ が付いた変数をそれぞれトークンとして扱います。他の変数を参照する SCSS 変数（例：$color-primary: $blue-500）は、階層の関係を示します。変数がパーシャル（_colors.scss、_spacing.scss）に分割されている場合、ファイルの構成が階層構造を示している可能性があります。

TypeScript/JavaScript オブジェクトの場合：エクスポートされたオブジェクトのキー階層をトークン構造として扱います。ネストされたオブジェクトは、JSON トークンと同じ方法で各階層に対応付けます。Emotion または styled-components のテーマでは、テーマオブジェクトがトークンのソースです。一般的なパターンには、フラットなエクスポート（export const backgroundColor = { scene: '#FFF', primary: '#206EF6' }）、as const 型付きオブジェクト（const tokens = { ... } as const）、集約されたバレルエクスポート（export const tokens = { breakpoint, fontSize, spacing }）、テーマを CSS 変数にマッピングする関数（mapThemeToVars()）などがあります。トークン値に解決される theme.spacing(4) や theme.colors.primary などのヘルパー関数は、有効なトークン参照です。

Tailwind 設定の場合：theme ブロックはプリミティブを定義し、extend はセマンティックなオーバーライドを追加します。カスタムトークンを参照する Tailwind ユーティリティクラス（例：bg-primary、text-color-content-default）は、ハードコードされた値ではなくトークン参照です。角括弧内の任意の値（例：h-[12px]、bg-[#ff0000]）は、実際のハードコード違反です。

値なしでトークン名だけが貼り付けられた場合は、命名と構造の監査のみを行います。出力では、値の分析ができなかったことを記載してください。

ステップ 2：階層構造を対応付ける

存在する階層を特定します。

プリミティブ階層 — セマンティックな意味を持たない生の値。例：color.blue.500、spacing.4、font-size.base

セマンティック階層 — 意図に基づく参照。例：color.action.primary、spacing.component.gap、text.body.size

コンポーネント階層 — 特定のコンポーネントコンテキストにスコープされたもの。例：button.background.default、card.padding.inner

プリミティブ階層またはセマンティック階層が欠けている場合は、その点を指摘します。プリミティブだけのシステムにはセマンティックな契約がありません。セマンティックトークンだけのシステムには、生の値の単一の信頼できる情報源がありません。どちらも明示すべき構造上の問題です。コンポーネント階層の欠如は指摘事項ではありません。token-architecture の注記を参照してください。

ステップ 3：監査チェックを実行する

各チェックについて、具体例を挙げて PASS、WARN、FAIL の評価を付けます。すべての検出事項には、トークンのパスと定義箇所のファイルおよび行番号による根拠を示します（tokens/component.tokens.json:9、src/styles/tokens.css:17）。

重大度の基準（severity.* 設定キーで以下の既定値を上書きできます）：

• 🔴 Critical — 主張する正式な情報源ではないトークンファイル（生成された出力がそこから乖離している）；複数のテーマを提供するシステムにおける、階層の漏出、またはセマンティック層やコンポーネント層での生の値。テーマの切り替え時に、その値がひそかに反映されなくなるためです
• 🟠 High — 単一テーマのシステムにおける、階層の漏出、またはセマンティック層やコンポーネント層での生の値；上位層への参照（セマンティック → コンポーネント）；外観を名前に含むセマンティックトークン（color.semantic.blue）
• 🟡 Medium — 同じ層内での命名規則の不統一；コンポーネントですでに使われている役割に対するインタラクション状態の欠落；区別が文書化されていない生の値の重複；しきい値の 20% を超える孤立候補
• ⚪ Low — 曖昧さのフラグ、プラットフォーム接尾辞、しきい値未満の孤立候補、DTCG 移行の兆候

命名チェック

説明的な命名と、外観を指示する命名 セマンティックトークンでは、外観ではなく用途を表します。

• FAIL の例：color.semantic.blue — 意図ではなく色を表しています
• PASS の例：color.action.primary — 役割を表しています

階層の漏出 コンポーネントトークンは、プリミティブではなくセマンティックトークンを参照する必要があります。

• FAIL の例：button.background.default: {color.blue.500} — セマンティック層を飛ばしています
• PASS の例：button.background.default: {color.action.primary} — 正しい参照チェーンです

曖昧さのフラグ 複数の意味に解釈できる、または文脈がないと解釈できないトークン名（詳細なルールと例外については、トークンアーキテクチャの注記を参照してください）：

• フラグ対象の例：normal、alt、variant、misc、other、および役割全体が default または base であるもの（color.default）
• フラグ対象外：役割に付随する状態またはレベルのセグメントとしての default／base（color.action.default、color.surface.base）、および T シャツサイズや数値のスケール段階（spacing.sm、radius.lg）
• フラグが付いた各トークンには、名前の変更案を含めてください

命名規則の一貫性（このスキルではトークンの命名を扱い、naming-audit ではコンポーネントとパターンを扱います） 各層で優勢な大文字・小文字の使い方、区切り文字、セグメントの順序を特定し、それに従わないトークンにフラグを付けます：color.blue.500 と並ぶ color.blue-500、hover/pressed と並ぶ hover/active、button.background.hover と並ぶ button.background-hover。チームが意図した規則か確認できるよう、検出結果に優勢な規則を報告してください。

プラットフォーム接尾辞の乱用 変換レイヤーではなく、プラットフォーム固有の情報を名前に含めているトークン：

• 例：color.primary.ios、spacing.mobile.gap — これらは名前ではなく、変換に含めるべきです

値のチェック（値を取得できる場合）

セマンティック層またはコンポーネント層でのハードコード値 参照ではなく生の値を持つセマンティックトークンまたはコンポーネントトークンは、構造上の負債です。

• 見つかった値ごとに、トークン名、生の値、参照先の候補を示します

エイリアスのない重複した生の値 異なる名前でプリミティブ層に現れる、説明のない同一の生の値：

• 重複の可能性がある値にフラグを付け、意図的な区別かどうかを確認します

層を越えた参照 より具体性の高い層のトークンを参照しているトークン：

• 例：コンポーネントトークンを参照するセマンティックトークン — 依存関係の方向が逆になっています

カバレッジのチェック

インタラクション状態の不足 標準的なすべての状態（デフォルト、ホバー、アクティブ、無効、フォーカス、エラー、成功、警告）に対して、セマンティックトークンが存在するか確認します。

ダークモード／テーマエイリアスの不足 システムがテーマ設定をサポートする予定であれば、テーマに対応したエイリアスとしてセマンティックトークンが存在するか、または生の値が直接使用されているかを確認します。

コンポーネント階層の不整合（システムがコンポーネントトークンを使用している場合のみ） システムがコンポーネントトークンを採用しており、同じカテゴリ内で一部のコンポーネントには存在する一方、ほかには存在しない場合、その不整合を指摘します。システムがコンポーネントトークンをまったく使用していない場合、これは指摘事項ではありません。プリミティブとセマンティクスの2階層アーキテクチャは、妥当で一般的な選択肢です。

ステップ 3b：DTCG 2025.10 への準拠状況の評価（条件付き — 該当する場合のみ含める）

トークンソースが DTCG 形式ではなく、チームが DTCG への移行にも言及していない場合は、このセクション全体を省略してください。ほとんどのチームには不要です。トークンソースが DTCG 形式を使用している場合、チームが DTCG への準拠について尋ねている場合、または監査の目的が移行計画である場合に含めてください。

トークンソースが DTCG 形式を使用している場合、またはチームが DTCG への移行を検討している場合：

構造検証は schema-validator の役割です。 型の解決、13 種類以外の $type 値、2025.10 の値の形式、複合値のサブ値の整合性、無効なエイリアスや循環するエイリアス、リゾルバー文書の妥当性は、すべて schema-validator で扱います。schema-validator のレポートがある場合は、このセクションで該当する指摘 ID を引用してください。ない場合は、手作業で再確認するのではなく、実行してください（迅速で機械的に処理できます）。このセクションでは、それらの結果がアーキテクチャ上何を意味するかを報告し、階層マップが必要な以下の2つのチェックを追加します。

複合トークンにおけるエイリアスの階層。 サブ値に参照と生の値が混在する複合トークン（typography.body で fontFamily: {font.family.body} を参照している一方、fontSize: "16px" となっているもの）は、セマンティック階層における生の値の複合形式です。テーマを切り替えられません。形式については schema-validator が報告し、この監査ではその評価を行います。重要度：🟡 中。テーマ対応のコンポーネントで複合トークンが使用されている場合は 🟠 高。

リゾルバーのコンテキストとテーマ設定。 .resolver.json ファイルがある場合は、各モディファイアの contexts と resolutionOrder を確認します（ノートには構造が記載されています。仕様で使われる用語は「モード」ではなく「コンテキスト」です）。コンテキストで再定義されていないトークンが前の値を引き継ぐのは設計であり、欠落ではありません。この監査で報告するのは、テーマに依存するセマンティックトークン（色、シャドウ、ボーダー色）のうち、デフォルト以外のコンテキストで再定義されていないもの（そのため、テーマで値がデフォルトのまま暗黙に維持されるもの）と、どのセットにも含まれていないトークンファイルです。重要度：リリース済みテーマにおける継承された色トークンは 🟠 高（コントラストのリスク）、すべてのセットの対象外にあるトークンファイルは ⚪ 低。チームが複数のテーマを使用している場合は、theme-audit がこれをさらに詳しく調べるため、重複して報告せず、そちらを引用してください。

移行の目安（参考情報）。 まだ DTCG 2025.10 に移行していないチームには、型の解決後に $type が必要になるトークン数、オブジェクト値への再構成が必要な複合トークン数、文字列値をオブジェクト形式に変換する必要があるかどうか、テーマ設定にリゾルバーファイルが必要かどうかを、1段落で示します。最もリスクが低い最初のステップ（通常は、解決後の値を変えずにプリミティブに $type を注釈として追加すること）を明記してください。希望された場合は、工数の目安を含む段階的な移行計画を提示してください。求められていない場合は作成しないでください。

Step 3c: トークン依存関係マップ（条件付き — コードベースにアクセスできる場合に含める）

コードベースにアクセスできない場合、または監査の対象がトークンの命名／構造のみの場合は、このセクションをスキップしてください。ユーザーがコードベースを接続しており、変更を加える前に影響範囲を把握したい場合は、このセクションを含めてください。

依存関係グラフの生成元は codebase-index のみです。これはトークンとコンポーネントのエッジを .ai/index/ に書き込みます。そのディレクトリが存在する場合は、そこからトークンのエッジを読み取り、Step 0b で特定した孤立候補をそれらにマークし、ファンアウトの大きいトークン（このリポジトリ内の多数のコンポーネントに紐づいているもの。数を示し、リポジトリ外の利用側はカウントされないことに留意してください）を一覧にしてください。存在しない場合は、影響範囲のビューが作成されていないことを伝え、まず codebase-index を実行するよう提案してください。ここで2つ目のグラフを作成しないでください。トークンとFigmaの整合性確認は figma-variable-audit のStep 6で行います。

Step 4: 監査レポートを作成する

全体の状態と注目すべき点を伝える、見出しとなる一文から始めてください。例：「トークンアーキテクチャには構造上の問題が3つあります。セマンティック階層に2つ、階層をまたぐ衝突が1つです。詳細は以下のとおりです。」

レポートは次のように構成してください。

---

トークン監査レポート

概要 1段落で記述します。トークンアーキテクチャ全体の状態はどうなっていますか。最も緊急性の高い問題は何ですか。コンプライアンス報告書ではなく、同僚によるレビューのように書いてください。

階層構造

• プリミティブ階層：🟢 強固 / 🟡 機能的 / 🟠 弱い / 🔴 なし
• セマンティック階層：🟢 強固 / 🟡 機能的 / 🟠 弱い / 🔴 なし
• コンポーネント階層：🟢 強固 / 🟡 機能的 / 🟠 弱い、または「未使用」（問題点ではありません）
• 階層の漏出箇所：［件数］

指摘事項

各指摘事項に次の内容を含めてください。

• 指摘 ID（例：TA-01）
• 重大度：🔴 重大 / 🟠 高 / 🟡 中 / ⚪ 低
• チェックカテゴリ：命名 / 値 / カバレッジ
• 説明：1文
• 根拠：各トークンが定義されているトークンパス、ファイル、行
• 推奨対応：置き換え先を明記した、具体的で実行可能な対応

修正の優先順位 指摘事項を次の3段階に分類してください。

1. 最初に修正 — 下流の利用側に影響する構造上の問題
2. 次に修正 — 時間とともに積み重なる命名上の負債
3. 将来的に対応 — カバレッジの不足と、あると望ましい改善点

作業量の見積もり 各修正段階について、前提条件と注意事項を明示した、現実的な作業量の見積もりを提示してください。

指摘事項	推定作業量	前提条件	確度
[指摘 ID]	[範囲。例：4–8時間]	[見積もりの前提条件]	[高／中／低]

必ず範囲で示し（「6時間」ではなく「4–8時間」）、前提条件を明記してください。確度は高／中／低で評価し、低の場合は、何について調査・範囲設定が必要かを記載してください。「最初に修正」する項目については、見積もりの対象はトークン側の変更のみで、利用側の移行は別途必要であることを明記してください。トークンが200個を超える場合、または利用するアプリが3つを超える場合は、スプリント計画を確定する前に、期間を区切った調査を提案してください。

目標は、プロジェクトマネージャーがスプリント計画で根拠を示せる見積もりです。超過して信頼を損なうような楽観的な目標ではありません。

対象範囲

• 調査済み：［実際に読み込んだトークンファイル、設定、ディレクトリ］
• 未調査：［アクセスできなかった対象。例：利用側の製品リポジトリ、Figma］
• 「該当なし」の確認方法：［例：孤立項目の検索におけるポジティブコントロール。該当項目がないとの主張を含まないレポートでは省略］
• 前提条件：［検証せずに事実として扱った内容］

末尾に、以下の締めくくりの注記を記載してください。

---

定期的なワークフロー

設定と定期実行に関する注記の定期実行手順に従います。このスキル固有の内容は次のとおりです。

• 違反の総数を比較します。増加、横ばい、減少のいずれかを示してください。
• 2サイクル以上にわたって未対応のまま残っている指摘事項にフラグを付けてください。
• 違反数の増減（+/- n）と、新たに発生した違反の一覧を含む「前回監査からの傾向」セクションを、レポートのヘッダーに追加してください（新たな違反は最近の負債であるため、優先して対応します）。

ステップ 5：Figma の変数

コードトークンと Figma の変数を比較し、Figma で変数を作成または名前変更するのは、figma-variable-audit の役割です（相互参照はステップ 6、書き込みはステップ 10 で行います）。Figma ファイルが設定されている場合、またはユーザーが Figma に言及した場合は、コード側の監査が完了したことを伝え、同じトークンソースに対して figma-variable-audit を実行し、2 つのレポートで名前を一致させることを提案してください。ここでは Figma との比較や Figma への書き込みは行わないでください。

締めくくりの注記（すべてのレポートに記載）

レポートの最後に、次の内容を記載してください。

コンテキストに関する注記： この監査で確認できるのはトークンファイルであり、その背後にある判断までは確認できません。チームが意図的に選んだパターンが、一部の指摘に含まれる場合があります。意図的な判断についての指摘があればお知らせください。今後の実行では除外し、システムの規約を学習します。すでに行った選択を批判するのではなく、まだ気づいていない問題を明らかにすることが目的です。

品質チェック

• すべての指摘に、一般的な説明ではなく、ファイルと行を示した具体例と、評価基準に基づく重大度が含まれている
• 要約段落では、婉曲的な表現を避け、重大度を率直に示している
• 修正案は具体的である。「命名を改善する」ではなく、「color.semantic.blue を color.action.primary に名前変更する」とする
• 階層構造の評価では、プリミティブ階層とセマンティック階層に加え、システムでコンポーネント階層を使用している場合はそれも扱っている
• 値を確認できなかった場合、どのチェックを、なぜ省略したのかをレポートに記載している
• DTCG の構造チェック、依存関係グラフ、Figma との比較については、ここでやり直さず、schema-validator、codebase-index、figma-variable-audit による結果を引用している
• 孤立しているという指摘では、その根拠となるポジティブコントロールを示し、どの利用側を確認していないかを明記している
• Scope ブロックと、意図的な逸脱に関する締めくくりの注記が含まれている