design-audit

バージョンに依存します。 以下に記載するすべての API 名、SDK の条件、ブラウザーのサポートに関する説明は、 2026-09-08 時点で一次資料に基づいて検証済みです。何をいつ照合したかは、 _jutsu/VERSIONS.md をご覧ください。その日付が古い場合は、バージョン番号に基づいて作業する前に再検証してください。

デザイン監査

最終チェックポイントです。パイプラインの最後に /genjutsu:paint によって読み込まれます。 コードベースをスキャンして、モーションの不足、アクセシビリティ違反、パフォーマンス上の問題、不整合を検出します。

---

静的チェック

スクリプトを実行してください。grep を手書きしないでください。

python3 "$SKILL_BASE/design-audit/scripts/audit.py" .

後処理する場合は --json を追加してください。--only <check-id> で単一のチェックを実行し、--group tells または --group hygiene で単一のグループを実行します。

このスクリプトは3種類の結果を報告します。特に後ろの2つを区別することが、このスクリプトの存在理由です。

• findings - チェックが実行され、何かが見つかりました。各結果には file:line と 一致したテキストが含まれるため、判定ではなく根拠を報告できます。
• clean - 実際のファイルに対してチェックが実行され、何も見つかりませんでした。
• not applicable - 該当する種類のファイルがなかったため、チェックは実行されませんでした。未チェックとして 報告してください。合格として報告してはいけません。

以前は、これらの grep が src/ を起点としてこのファイル内に記載されていました。デフォルトの Next.js の app-router プロジェクトや Nuxt 3 プロジェクトには src/ がないため、何も一致しませんでした。その結果、パイプラインは空の出力を問題なしと解釈し、 納品の直前にユーザーへそのように伝えていました。このスクリプトはルートを検出し、node_modules とビルド出力を除外します。 JSX や CSS に加えて .vue、.svelte、.astro も対象とし、各チェックが機能することを確認するテストも用意しています。

Tells は別に報告されます。 スクリプトは tells グループも実行します。番号付きのアイブロウ、天気情報の帯、 同じ大きさのカード3枚、コピー内の U+2014（em ダッシュ）など、何も求められていないときにモデルが選びがちな既定パターンを 18項目チェックします。ほとんどのチェックでは、クラス名やスタイルオブジェクトではなく、マークアップに表示されるテキスト （タグ間のテキスト、alt、title、aria-label、placeholder）だけを読み取るため、width: "100%" を完璧さの主張と見なすことはありません。 5項目は、その特徴がクラスや CSS ルールにあるため、ソースを読み取ります。対象はグラデーションテキスト、グラス、 グロー、ブロブ、絶え間ないモーションです。JavaScript のデータ（機能の配列やコンテンツファイルなど）にあるコピーは、 スクリプトにとって表示テキストではありません。手動で確認してください。

検出結果は専用セクション「Tells - それぞれを数える前に、設計意図と照合する」に表示され、 常に nice-to-have とされます。スクリプトは設計意図を読み取れないため、問題として数えることはありません。 各項目を自分で照合してください。

• 検証済みの設計意図にそのパターンが明記されている場合（たとえば、スタジオがパリと東京で活動しており、 ヘッダーに両方の時計を表示すると書かれている場合）、その文章を引用して 設計意図で許可済み として列挙します。
• 明記されていない場合、その tell は問題であり、ほかの問題と合わせて数えます。

雰囲気を表す言葉だけでは何も指定していません。「エディトリアル」や「エージェンシー」という言葉は、番号付きアイブロウを許可しません。 ほとんどの tell は、まさにそうした言葉から連想される決まりきった表現です。tells モジュールが読み込まれた場合は、そのルールに従ってください。

一覧には、期間やイージングに加えて色、角丸、フォントファミリーも表示され、各値には最大5つの file:line の場所が示されます。 ここで判定は行いません。トークンと設計意図に照らして確認してください。

コントラストはスクリプトの対象外です。 出力したトークン値を使って自分で計算し、比率とともに色の組み合わせを報告してください。 #831843 on #FDF2F8 = 9.4:1 のように記載します。本文テキストは 4.5:1、大きなテキストと UI の境界は 3:1 が基準です。 見た目で確認した色見本は測定値ではありません。

python3 が利用できない場合は、その旨を1行で伝え、次の順序で手を加えたコンポーネントを読み取って確認してください。 reduced-motion ガード、終了アニメーション、レイアウトプロパティのアニメーション、フォーカスの可視性、非インタラクティブ要素のクリックハンドラー。 監査が部分的であることと、実行できなかったチェックを報告してください。

---

スタック別監査

プロジェクトのスタックに該当するサブセクションを選んでください。

Compose（Android／Multiplatform）

• Layout Inspector（Android Studio）を実行します。再コンポーズを調査し、状態が変わるたびに再コンポーズされるコンポーネントを特定します。
• Macrobenchmark（androidx.benchmark.macro）を実行します。実際のデバイスで、代表的なスクロール／アニメーション負荷をかけた際のフレーム時間を測定します。目標：60fpsで1フレームあたり16.67ms未満、120fpsで8.33ms未満。
• 再コンポーズ回数を調査します。Layout Inspector > Component Tree > View Options > Show Recomposition Counts（API 29+、Compose 1.2+）。各操作の前にカウンターをリセットし、数値が意味のあるものになるようにします。androidxにはModifier.recomposeHighlighterはありません。これはデバッグ用のソースセットに取り込むサンプルです。
• 本番ビルド用のBaseline Profiles（BaselineProfileGenerator）を生成します。
• カスタムコンポーネントにModifier.semanticsが設定されていることを確認します（TalkBackのサポート）。

SwiftUI（iOS／macOS）

• Instruments Time Profilerを実行し、アニメーション中のホットパスを特定します（目標：16.67msを超えるフレームをゼロにする）。
• Instruments Hitches Instrumentを実行します（iOS 14+）。フレーム落ちや停止を検出します。
• Metalシェーダー用にInstruments GPU Frame Captureを実行し、シェーダーのコンパイル時間と、GPU／CPUのどちらがボトルネックかを確認します。
• すべてのインタラクティブなビューに.accessibilityLabel／.accessibilityHintが設定されていることを確認します。
• サイズを200%にしたDynamic Typeでテストします（XcodeのEnvironment Overrides）。
• Reduce Motionをオンにしてテストします。

Web

• 上記の既存チェックリスト（Lighthouse、Chrome DevTools Performanceなど）。

---

出力形式

重要度別に調査結果を整理します。

Critical（リリース前に必ず修正）

• prefers-reduced-motionへの対応がない
• キーボード操作に対応していないクリック可能なdiv
• :focus-visibleによる代替がないoutline: none
• レイアウトプロパティ（width／height／top／left）のアニメーション

Important（現在のスプリントで修正）

• AnimatePresenceを使わない条件付きレンダリング
• トランジションのないホバー状態
• 装飾的なアニメーションにaria-hiddenがない
• アニメーションループにsetTimeoutを使用
• durationが不統一（値が8種類を超える）

Nice-to-have（バックログ）

• スタガーアニメーションのないリスト
• トランジションのないインラインスタイル
• will-changeの過剰な使用
• 対称でない入退場（方向が誤っている）
• 実際の使用状況に対して大きすぎるアニメーションライブラリ