Hideki-Kobayashi/apply-digital-agency-design-system

デジタル庁デザインシステムを適用する

承認済みの公式Markdownスナップショットから、依頼に必要な根拠だけを選んで適用する。 通常作業と公式更新の確認を分け、更新候補を利用者の承認なしに有効化しない。 以降の<skill-root>は、このSKILL.mdが置かれているディレクトリの絶対パスへ置き換える。 以降の<python>はPython 3.10以上を実行できるコマンドへ置き換える。 macOSとLinuxでは通常python3、Windowsでは通常py -3を使う。

情報の境界

• references/source-manifest.jsonが示すactive_snapshot.pathを、通常作業で使う有効スナップショットとする。
• 有効スナップショットのsource-index.json、references/task-index.md、references/foundation-map.mdは派生資料である。 公式上の意味は、有効スナップショット内の該当Markdownで確認する。
• 公式MarkdownはAI参照用の再構成物であり、公式サイトの完全な代替ではない。 ローカル資料に必要な記述がない場合は、未確認事項として報告する。
• このSkillは非公式であり、デジタル庁による提供、承認、提携または推奨を示さない。
• 既存プロジェクトの現在値は、CSS変数、テーマ設定、共通スタイル、共通コンポーネントから確認する。 Skill内へ複製しない。
• 作成、変更、レビューは操作権限の分類とする。 新規作成、既存改修、個別コンポーネントは資料選択の分類とし、混同しない。

起動時の更新期限判定

最初に次のコマンドを実行する。 このコマンドはローカルファイルだけを読み、ネットワークへ接続しない。

<python> <skill-root>/scripts/manage_upstream.py status

出力のstatusをstatus_at_startとして、その依頼中は保持する。

• fresh：更新案内を出さず、通常作業を続ける。
• due、never_checked、unknown：通常作業を止めず、終了時に状態を再確認する。
• 利用者が最初から「最新版を確認して」などと明示した場合：明示依頼を外部確認への同意として扱い、保守手順へ進む。

期限はlast_successful_check_atから30日で判定する。 提案日時、失敗日時、派生した次回確認日は期限の起点にしない。

通常作業

1. 依頼を作成、変更、レビューに分類し、許可された操作範囲を確定する。
2. 対象の技術構成、既存スタイル、ブランド制約、画面構造を確認する。
3. 次の優先順で資料選択の経路を決める。
   • 対象が一つのUI部品とその状態に限られる場合は、個別コンポーネントとする。
   • 共通スタイルが既に存在する場合は、既存改修とする。
   • それ以外は、新規作成とする。
4. references/task-index.mdから対象文書を選ぶ。 該当しない場合は、次のコマンドで有効スナップショットを検索する。

<python> <skill-root>/scripts/search_guidance.py \
  --query '<検索語を空白で区切る>' \
  --manifest-file <skill-root>/references/source-manifest.json

5. 資料選択の経路に応じてreferences/foundation-map.mdを使う。
   • 新規作成：8分類を採用、対象外、保留に分け、値を決める分類の公式Markdownを読む。
   • 既存改修：既存値を先に調べ、影響する分類だけを読み、維持、移行、意図的な逸脱に分ける。
   • 個別コンポーネント：既存の共通基準、対象コンポーネント、影響する基本デザインだけを読む。 共通値を部品内で決め直さない。
6. 公式の選択肢、既定値、例、原則、要件、固定値を区別し、採用値と根拠を対応づける。
7. 既存の技術構成で実装する。 公式例を一律の固定値として適用せず、公式要件を見た目の好みとして緩めない。
8. 対象に応じて、複数画面幅、キーボード操作、フォーカス、状態変化、拡大、リフローを確認する。
9. レビュー依頼ではファイルを変更せず、根拠付きの指摘だけを返す。

通常作業の完了報告

次を簡潔に報告する。

• 参照版：source-manifest.jsonのスナップショットID、デジタル庁デザインシステム版、Markdown公開日。
• 確認範囲：読んだ公式文書と、実行した確認。
• 未確認事項：実機、支援技術、外部の現行ページなど、確認していない範囲。
• 逸脱：プロジェクト固有の理由で公式例または推奨から変えた内容。

起動時の状態がdue、never_checked、unknownだった場合だけ、報告直前にstatusを再実行する。 別の処理によってfreshになっていなければ、最終報告の末尾で一度だけ更新確認を提案する。

前回の公式更新確認から30日以上経過しています。今回の作業は承認済みの現行版で完了しました。更新確認も行いますか？

never_checkedまたはunknownでは、経過日数を断定せず理由を示す。 提案だけでは外部通信も状態更新も行わない。 利用者が断った場合も拒否日時を保存しないため、成功確認まで次回以降も提案する。

公式更新の確認

利用者が同意した場合だけ、次を実行する。 --network-approvedは利用者の同意を確認した後にだけ付ける。 30日未満でも明示的に最新版を確認する場合は--forceを追加する。

取得バックエンドは既定のautoに任せる。 autoはaxが見つかれば公式ページの取得、リンク抽出、ZIP保存をaxへ任せ、見つからなければPython標準ライブラリを使う。 axは推奨だが任意であり、導入を更新確認の前提にしない。 ax経路はリダイレクト後の最終URLを検証するが、途中の転送先を通信前に検証できない。 転送先も事前制限する必要がある場合は、--fetch-backend stdlibを使う。 一度選んだバックエンドが失敗しても、別のバックエンドへ暗黙に切り替えない。 取得後のURL・容量・ZIP形式の確認、ハッシュ計算、差分作成、状態保存はPythonで行う。 動作確認などで方式を固定する場合だけ、--fetch-backend axまたは--fetch-backend stdlibを追加する。

<python> <skill-root>/scripts/manage_upstream.py check \
  --network-approved

• unchanged：確認成功日時を更新し、取得バックエンドと変更なしを報告する。
• candidate_createdまたはcandidate_exists：取得バックエンド、候補ID、取得元、ハッシュ、追加、変更、削除の件数を報告する。
• skipped_fresh：30日未満のため外部確認を省略したと報告する。
• 失敗：last_successful_check_atと有効スナップショットを変更せず、失敗した取得先と理由を報告する。

外部確認への同意を、候補採用の承認として扱わない。 候補が見つかっても、公式ソースの確認と候補保存が完了していれば、確認成功日時は更新する。

ZIPの手動取得

自動取得が最終的に失敗し、checkが公式ZIPのURLまで特定して手動取得を案内できる場合だけ、この手順を最後の手段として提案する。 URLを特定する前に失敗した場合は、URLやファイル名から取得先を推測せず、失敗だけを報告する。

次の内容を利用者へ示す。

ZIPの自動取得に失敗しました。次の公式URLから手動で取得できます。
<公式ZIP URL>

ZIPは任意のフォルダへ保存してください。保存後、ファイル名まで含む絶対パスを教えてください。
受け取ったZIPはネットワークへ接続せずに検証し、更新候補として保存します。有効版への切り替えは別途確認します。

利用者から絶対パスを受け取ったら、次を実行する。 相対パスしか分からない場合は、絶対パスを確認してから実行する。

<python> <skill-root>/scripts/manage_upstream.py import-archive \
  --archive-file '<ZIPの絶対パス>'

import-archiveは、失敗時に記録した公式URLへローカルZIPを結び付け、ネットワークへ接続せずに通常の容量、ZIP形式、内部パス、Markdown集合、ハッシュの検証と候補化を行う。 元のZIPを変更または削除しない。 ローカル取込は外部確認の成功とは扱わず、last_successful_check_atと確認済み契約版を更新しない。 結果がcandidate_createdまたはcandidate_existsでも自動で昇格せず、「更新候補の評価と昇格」へ進む。

公式URLの特定から30日を超えた場合、または更新契約が変わった場合は、取り込みを迂回せず、新しい更新確認への同意を求める。 手動取得やローカル取込に失敗しても、last_successful_check_atと有効スナップショットを変更しない。

更新候補の評価と昇格

1. 候補内のcandidate-manifest.jsonとdiff-summary.jsonを読む。
2. verify_snapshot.pyで候補を検証する。

候補の既定保存先は、利用者別状態ディレクトリ内のcandidatesである。

<python> <skill-root>/scripts/verify_snapshot.py \
  --snapshot-dir <state-dir>/candidates/<候補ID>/snapshot \
  --index-file <state-dir>/candidates/<候補ID>/source-index.json

3. 追加、変更、削除された公式文書を読み、task-index.mdとfoundation-map.mdへの影響を確認する。
4. 代表的な作成、改修、レビュー依頼を旧版と候補版で試す。
5. 候補ID、意味の変化、派生資料の変更、確認結果を利用者へ示し、採用を明示的に確認する。
6. 利用者が候補IDを指定して承認した後だけ、次を実行する。

<python> <skill-root>/scripts/manage_upstream.py promote \
  --candidate-id '<候補ID>' \
  --human-approved

昇格後も直前スナップショットを削除しない。 昇格操作ではlast_successful_check_atを変更しない。

判断規則

• MANIFEST.mdをファイル一覧の正本にしない。 全Markdownを走査する。
• 文書IDには正規化したsource_urlを使う。 slugは本文と更新履歴で重複するため、単独のIDにしない。
• 見つからないコンポーネント、トークン、クラス名を公式仕様として作らない。
• 既存値と公式要件が衝突した場合は、黙って維持または置換せず、影響と修正範囲を示す。
• 画面確認だけを根拠に、デジタル庁デザインシステムまたはWCAGへの完全適合を宣言しない。
• 公開物へ出典を記載する場合は、有効スナップショットのintroduction/notices/index.mdを読む。
• 更新状態と候補は利用者別のローカル領域へ保存し、Skill本体の配布ファイルへ混在させない。 保存先を変える場合だけ、環境変数DADS_SKILL_STATE_DIRを使う。