デジタル庁デザインシステムを適用する
承認済みの公式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日で判定する。
提案日時、失敗日時、派生した次回確認日は期限の起点にしない。
通常作業
- 依頼を作成、変更、レビューに分類し、許可された操作範囲を確定する。
- 対象の技術構成、既存スタイル、ブランド制約、画面構造を確認する。
- 次の優先順で資料選択の経路を決める。
- 対象が一つのUI部品とその状態に限られる場合は、個別コンポーネントとする。
- 共通スタイルが既に存在する場合は、既存改修とする。
- それ以外は、新規作成とする。
references/task-index.mdから対象文書を選ぶ。 該当しない場合は、次のコマンドで有効スナップショットを検索する。
<python> <skill-root>/scripts/search_guidance.py \
--query '<検索語を空白で区切る>' \
--manifest-file <skill-root>/references/source-manifest.json
- 資料選択の経路に応じて
references/foundation-map.mdを使う。- 新規作成：8分類を採用、対象外、保留に分け、値を決める分類の公式Markdownを読む。
- 既存改修：既存値を先に調べ、影響する分類だけを読み、維持、移行、意図的な逸脱に分ける。
- 個別コンポーネント：既存の共通基準、対象コンポーネント、影響する基本デザインだけを読む。 共通値を部品内で決め直さない。
- 公式の選択肢、既定値、例、原則、要件、固定値を区別し、採用値と根拠を対応づける。
- 既存の技術構成で実装する。 公式例を一律の固定値として適用せず、公式要件を見た目の好みとして緩めない。
- 対象に応じて、複数画面幅、キーボード操作、フォーカス、状態変化、拡大、リフローを確認する。
- レビュー依頼ではファイルを変更せず、根拠付きの指摘だけを返す。
通常作業の完了報告
次を簡潔に報告する。
- 参照版：
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と有効スナップショットを変更しない。
更新候補の評価と昇格
- 候補内の
candidate-manifest.jsonとdiff-summary.jsonを読む。 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
- 追加、変更、削除された公式文書を読み、
task-index.mdとfoundation-map.mdへの影響を確認する。 - 代表的な作成、改修、レビュー依頼を旧版と候補版で試す。
- 候補ID、意味の変化、派生資料の変更、確認結果を利用者へ示し、採用を明示的に確認する。
- 利用者が候補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を使う。