design-system-compliance について
プロジェクトが宣言したデザイントークンに、実行中のUIが準拠しているかを調べるReticle向けスキルです。ブラウザーで解決されたスタイルと要素の位置を示し、デザインの良し悪しは評価しません。
主な機能
- 01計算済みカラーをデザイントークンと比較
- 02トークン数と有効なテーマ範囲を報告
- 03遮蔽、サイズ、不透明度、カーソルを検査
- 04実行中および完了したアニメーションを一覧表示
- 05要素のソース位置を提示
活用シーン
- 01宣言済みトークンに合わない色の発見
- 02検査時にテーマが適用されているか確認
- 03コントロールの表示状態と使用可否の確認
- 04アニメーションが想定時間で動くか検証
MCP 対応
Reticleは、このスキルが使うライブページ検査とアニメーション機能をMCPツールとして提供します。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/design-system-complianceを入力して読み込まれたか確認します。
詳細
描画された UI は実際にデザインシステムを使っているか？
ソースを読めば、コンポーネントが何を 要求している かはわかります。しかし、ブラウザーで実際に解決された内容はわかりません。3 層上書きされたトークン、たまたま近い色に見えるハードコードされた #3b82f6、適用されなかったダークテーマのスコープなどです。その答えがわかるのは、実行中のページだけです。
Reticle は実行中のアプリで計算済みスタイルを読み取り、プロジェクトのトークンと比較します。まだ設定していませんか？reticle スキルに従ってください。Reticle をインストールし、init によるアプリのファイル変更の前にユーザーへ確認し、1 つのフローで動作を実証します。
チェック
reticle_look({ action: "page", sessionId, mode: "interactive" })
reticle_look({ action: "element", sessionId, ref })
inspect は各要素について theme レポートを返します。
| フィールド | 説明 |
|---|---|
offTheme | 最も重要な項目です。 設定済みの不透明色がパレット内のどのトークンにも一致しない場合は true です。修正すべき違反を示します |
colorTokens / backgroundTokens | この色と解決後の値が一致するすべてのトークンです。空の場合、パレットにない色です |
colorToken / backgroundToken | 一意に 一致するトークン。複数のトークンが同じ色を共有している場合は null です。ここでの null は違反ではなく、一致を断定しないことを意味します。複数形のフィールドを確認してください |
tokenCount | アクティブなテーマで解決されたトークンの数です。0 はアプリにパレットが定義されていないことを意味し、offTheme は決して true になりません。問題なしと判断せず、その旨を報告してください |
themeScope | キャプチャ時にアクティブだったテーマ（例：.dark）です。これにより、数分間隔で実行した 2 つの inspect も比較できます |
まず tokenCount を確認してください。トークンが 0 個なら準拠すべきものがなく、それより下にあるすべての「合格」は意味をなしません。
色以外：コントロールは実際に使えるか？
同じ呼び出しで、スクリーンショットからはわからない点も確認できます。
occluded：オーバーレイに覆われています。描画されていますが、ユーザーはクリックできません。box：0×0は存在しているのに見えない状態です。「DOM にあるのに見える」という、最もよくあるバグです。styles.opacity/styles.cursor：無効に見える状態と、実際に無効な状態の違いです。source: { file, line }：修正箇所です。
色だけを比較するデザインレビューでは、誰も押せないボタンが合格してしまいます。
アニメーション
reticle_run({ tool: "reticle_animations", args: { sessionId } })
実行中および最近完了したアニメーションを、対象とタイミングとともに返します。モーションに関する作業の後に確認すべき点が 2 つあります。追加したアニメーションがここに表示されない場合、実行されていません。また、アニメーションの長さがトークンと一致しない場合は仕様違反です。どちらもスクリーンショットでは同じように見えます。
違反は意見ではなく場所として報告する
失敗した要素ごとに、inspect が示す file:line と具体的な事実を伝えてください。「背景色 #3b82f6 はどのトークンにも一致しません。パレットでは --color-primary が #2563eb です」。場所を示さないデザインレビューのコメントは、ほかの誰かがやり直さなければならない作業です。
これは何ではないか
これは、プロジェクトが宣言するトークンへの準拠をチェックするものです。デザインの良し悪しに対する評価でも、アクセシビリティ監査でもありません。コントラスト比、フォーカス順序、スクリーンリーダー向けのセマンティクスは別の作業です。ここでそれらを確認したと主張するのは、このリポジトリが防ごうとしているものそのもの、つまり誤った「問題なし」の判定です。
そのほかの内容は、1 ページずつ確認してください：curl https://docs.reticle.sh/llms.txt。デザイントークンのチェックに必要なものが足りませんか？reticle_session { action: "feedback" } に kind: "gap" を指定してください。