visual-design-system-extractor

ビジュアルデザインシステム抽出ツール

ビジュアルリファレンスを、パーサーで検証可能な単一の YAML デザインシステムに変換します。すべての主張は目に見えるものに基づき、選択する書体はすべて、実行時点でライブカタログに使用頻度が低いとランク付けされている Google Fonts ファミリーです。

ゲートの実行には、ターミナル、ライブフォントカタログへのネットワークアクセス、Mise が提供するランタイムが必要です。このスキルのディレクトリからコマンドを実行してください。パッケージを受け入れる前に、mise run ci が終了コード 0 で完了する必要があります。

このスキルで受け付けるコマンドは何ですか？

リファレンスまたは URL が添付された通常のリクエストは、extract として解釈します。

コマンド	結果
help	この表と現在のスキーマバージョンを表示します。
extract <refs>	提供されたリファレンスから、完全な YAML デザインシステムを生成します。
fonts <brief>	抽出をすべて行わずに、使用頻度の低い Google Fonts の候補をランク順に返します。
preview <file>	再抽出せずに、ドキュメントをレンダリング、スクリーンショット撮影、評価します。
validate <file>	既存の抽出結果に対して、スキーマとフォントのゲートを実行します。
maintain <change>	以下のテストファーストルールに従って、このパッケージを編集します。

リファレンスが添付されておらず、アクセスもできない場合は、そこで作業を止め、画像、スクリーンショット、ムードボード、スタイルフレーム、または URL を求めてください。説明だけをもとにシステムを作り上げてはいけません。

各コマンドは何を返しますか？

• help：コマンド表とスキーマバージョンを文章で返します。
• extract：検証済みの YAML ドキュメントのみを返します。コードフェンス、前後の文章、リファレンスの要約、いずれかのゲートに不合格だったドキュメントは含めません。ドキュメントには meta.viability レコードが含まれるため、ビジュアル判定も一緒に提示されます。
• 3 回の反復を経ても実現可能性ゲートを通過できない extract：失敗した各基準と、観察されたビジュアル上の理由、最後にレンダリングしたファイルとスクリーンショットのパスを示す文章を返し、その後に meta.viability.verdict: fail と記されたドキュメントを返します。成功したと主張してはいけません。
• preview：レンダリングとスクリーンショットの出力、および各終了コードを返した後、基準ごとに判定と観察された理由を記した表の行を返します。
• 名前付きセクションに絞り込んだ extract：要求されたセクションのみを YAML で返します。「トークンをください」のような何気ない表現は絞り込みと見なしません。ユーザーがセクションを指定するか、「のみ」と指示した場合に限り絞り込んでください。
• fonts：検出結果またはセットの JSON に加え、適合スコア、同点時の希少性による順位付け、次点候補より優れている理由、寸法ごとのペアリング却下があればその内容を示す短い段落を返します。
• validate：バリデーターの JSON に加え、終了コードと失敗した各パスを示す平易な言葉での判定を返します。
• すでに返したドキュメントへの追加編集：変更内容とその代償を簡潔にまとめた文章に続けて、再検証済みの YAML を返します。
• maintain：自由形式の文章を返します。

決定性とは、同じエビデンスから同じセクション、キー順、信頼度ラベル、該当なしオブジェクトが得られることを意味します。判断はフィールド値の中だけに記述し、各値が目に見えるエビデンスを指し示すようにしてください。

抽出はどのように実行しますか？

以下の完全な計画に従ってください。任意のディレクトリを 1 つ選び、すべてのファイルをそこに保存します。ドキュメントには extraction.yaml、ログには extraction-log.md を使い、ログは手順ごとに 1 行記録します。ファイルに書き込めない場合も、同じ記録を返信に含めてください。各手順の後に指定されたチェックを実行し、失敗があれば先に修正してから次に進んでください。

1. 少なくとも1つの参照が利用可能で、読み取り可能であることを確認します。確認事項：参照がログに記録されています。
2. スケルトンを読み込みます：mise run schema-tools skeleton --output extraction.yaml。フィールドの意味が不明な場合は、ファイル全体を読むのではなく、mise run schema-tools field <dotted.path> または mise run schema-tools group <name> でスキーマコントラクトを確認します。確認事項：ファイルが存在し、meta: から始まっています。
3. スケルトンのキー順をそのまま引き継ぎます。トップレベルのセクションの名前を変更したり、順序を入れ替えたり、削除したりしないでください。また、ユーザーがより限定的な成果物を求めている場合を除き、セクションを追加しないでください。セクション内では、該当しない階層を該当なしオブジェクトにまとめることも、適用可否を示すキーの横にそのキーを残すこともできます。どちらの形式でも問題ありません。確認事項：セクションの一覧がスケルトンと一致しています。
4. まず meta、source_analysis、confidence_scores を記入し、観察された事実、推論したロジック、推測に基づく外挿を別々の区分に保ちます。適用した下限値を meta.rarity_floor に、実行日を meta.extracted_at に記録し、参照ごとに1つの source_types エントリーを記録します。確認事項：観察された事実の区分に推測が含まれていません。
5. 視覚的な基礎要素を記入します。色、余白、レイアウト、グリッド、サイズ、境界線、角丸、シャドウ、グラデーション、マテリアル、テクスチャ、ライティングが対象です。各トークンには value、usage、visual_grounding、confidence、inference_basis を含めます。また、色には hex、rgb、hsl を、動きには duration、easing、trigger を含めます。確認事項：assets/minimal-extraction.yaml に各種類の記入済みトークンが1つずつ示されており、記入内容が同じ形式に沿っています。
6. フォント選定ルールを読み、視覚的なタイポグラフィの証拠に基づいて assets/font-brief.json を記入します。その後、すべてのロールを1セットとして記入します：mise run font-set -- --brief <brief.json>。適合性と可読性を優先し、同等の場合は希少性で選びます。ペアリングチェックで候補が却下される場合もあります。確認事項：コマンドが終了コード 0 で終了し、unfilled が空で、pairing.passes が true です。
7. typography を記入し、catalog_snapshot、正確な rarity ブロック、および選択した各ファミリーの fit_score、legibility_score、evidence を含む fit ブロックを記録します。確認事項：すべての rarity ブロックで retrieved_at の日付が統一されており、各ファミリーについて mise run font-verify -- --family "<name>" が終了コード 0 で終了します。
8. 体験に関わる階層を記入します。動き、アニメーション、カメラ、構図、環境、設定、衣装、小道具、アイコン、画像スタイル、レンダリングスタイルが対象です。確認事項：対応しない階層には推測ではなく、該当なしオブジェクトを使用しています。
9. スキーマの順序どおりにプロダクトの各階層を記入します：accessibility、interaction_design、ui_patterns、sound_design、narrative_tone、emotional_palette、worldbuilding、styling_rules、dos_and_donts、token_dependencies、dynamic_tokens、responsive_rules、state_variants、platform_adaptations、ai_generation_prompts、implementation_notes。確認事項：mise run schema-tools sections が出力するキーの順序と一致しています。
10. システム全体をページにレンダリングします：mise run render-preview extraction.yaml --output preview.html。確認事項：終了コードが 0 で problems が空です。これは、必須のトークングループがすべてページに反映されたことを意味します。
11. スクリーンショットを撮影します：mise run screenshot-preview preview.html --output preview.png。確認事項：PNG が存在します。
12. PNG を見て、以下の8つの基準をそれぞれ1つの判定と1つの観察理由で評価します。確認事項：判定理由では、画像に何が表示されているかを説明し、トークンの値を繰り返していません。
13. 基準を満たさない場合は、該当するトークンを修正してから、手順10〜12を繰り返します。確認事項：繰り返しは最大3回です。3回目でも基準を満たさない場合は、成功とせず、満たせなかった基準を報告して終了します。
14. 合格した判定を meta.viability に記録します。rendered_file、screenshot_file、iterations、verdict、criteria リストを含めます。確認事項：以下の一覧にある基準名がそれぞれ1回ずつ含まれています。
15. ゲートを実行します：mise run validate-design-system-yaml extraction.yaml。終了コード 0 が必須です。終了コードが 1 の場合は、表示された問題をすべて修正して再実行します。確認事項：再実行時に "valid": true が出力されます。
16. 検証済みの YAML のみを返し、検証レポートは含めません。

バリデーターは何を報告しますか？

レポートは stdout に出力される 1 つの JSON オブジェクトです。ドキュメントが合格するのは、終了コードが 0 で、以下のすべてのフィールドが正しく読み取れる場合に限ります。

• valid：errors が空の場合に限り true になります。
• errors：問題ごとに 1 文で示します。順序の問題では、位置と、その位置にあるキーを示します。
• rarity_floor：今回の実行で適用される下限です。初期値は 70.0 で、ドキュメントにそれより高い meta.rarity_floor が記録されている場合はその値まで引き上げられ、フラグでより高い --min-rarity-percentile が指定されている場合はその値まで引き上げられます。
• live_fonts_checked：記録されたランクがライブカタログと照合された場合は true です。false の場合、照合はスキップされているため、結果は未検証であり、回答でもその旨を伝える必要があります。
• confidence_markers：ドキュメントに含まれる confidence キーの数です。デフォルトで 5 の --min-confidence-markers 以上である必要があります。
• font_entries：確認したフォントファミリーの数です。プライマリ、サポート用、およびすべての希少候補を数えます。
• viability_recorded：meta.viability にレンダリング済みファイル、スクリーンショットファイル、反復回数、および各基準に対する判定が 1 つずつ記録されている場合に限り true になります。false の場合、システムはまだ確認されていないため、実行は未完了です。

フォントのルールは何ですか？

書体を選ぶ前に、mise run validate を使ってフォントの選定ルールを読み込んでください。このルールでは、ライブカタログの権威性、希少度の下限、適合性と可読性の基準、タイブレーカーとしての希少度、一般的な書体の例外、書体の組み合わせ、フォールバックルール、必須の記録、およびフィード障害時の契約を定めています。各選択済みフォントファミリーの記録は引き続きステップ 7 で扱い、フィードが利用できない場合は、検証済みのタイポグラフィは認められません。

システムが機能することはどのように証明されますか？

スキーマ検証で証明できるのは構造であり、システムが機能することではありません。残りを証明するのがレンダリングゲートです。mise run render-preview は、ドキュメント自体からスタンドアロンのページを書き出すため、手書きではなく再現可能です。また、ドキュメントでライトとダークの両方が宣言されている場合は、両方のモードで、ヘッダー、ナビゲーション、ヒーロー、読める長さの本文、すべての見出しレベル、各状態のボタン、フォームフィールド、テーブル、カードグリッド、コードブロック、フッター、トークン一覧に、すべてのトークンを適用します。mise run screenshot-preview はページ全体をキャプチャします。

スクリーンショットを見て 8 つの基準を評価し、出典のない数値ではなく、画像に何が写っているかを記録してください。基準は legibility、contrast、hierarchy、font_pairing、spacing_rhythm、color_harmony、state_distinction、reference_fidelity です。基準に不合格があれば、判定の文言ではなくトークンに戻って修正してください。このループは最大 3 回までです。それでも不合格の基準が残る実行では、その基準を報告し、成果物をリリースしません。

いつ何を読み込むか？

スキーマの契約は、セクションの順序、フィールドのルール、フォントのルール、構文のルール、セルフチェックリストを記載した機械可読な YAML です。全体を読むのではなく、mise run schema-tools を使って照会してください。フォント関連のフィールドに触れる前に、フォント調達ルールを読み込んでください。このパッケージを編集する場合に限り、生成の契約を読み込んでください。

スケルトンコマンドで assets/schema-skeleton.yaml を読み込み、フォントの調査前に assets/font-brief.json を読み込み、最小限の合格ドキュメントとして assets/minimal-extraction.yaml を読み込んでください。実行可能なゲートは、名前が付いた Mise タスクを通じて実行してください。スクリプトの動作を変更するときに限り mise run test を実行し、動作やタイミングに関する作業では mise run evals を使って evals/ を読み込んでください。

対応するコマンドを実行する前に、examples/ からファイルを1つ読み込んでください。各ファイルには、実際の終了コードを含む実際のトランスクリプトが記載されています。

• help に回答する前に examples/help.md を読み込んでください。
• 初回の抽出を行う前に examples/extract.md を読み込み、検証可能な完全なドキュメントについては examples/extract-output.yaml を参照してください。
• 入力済みのブリーフからコマンドラインを作成するため、調査を実行する前に examples/fonts-brief.md を読み込んでください。
• 他の人が作成したファイルを検証する前に examples/validate.md を読み込んでください。
• このパッケージを編集する前に examples/maintain.md を読み込んでください。
• ドキュメントがすでに存在する状態で、ユーザーからより珍しい書体を求められた場合は examples/make-it-rarer.md を読み込んでください。
• 現在のキャプチャ、8項目の基準による判定、再試行ルールを確認するため、レンダリングの前に examples/viability-loop.md を読み込んでください。
• バリデーターがセクションの順序に関する問題を報告した場合は examples/failure-section-order.md を読み込んでください。このスキルで最もよく発生する失敗です。

このパッケージはどのように保守しますか？

リソースゲート：ここに記載されたパッケージファイルを使用する前に、mise run validate を実行してください。

maintain では、YAML のみを返す応答契約は適用されません。まず失敗状態を確認してください。有効な入力を拒否するゲート、欠けている動作、またはユーザーが指定した正確な不足箇所のいずれかです。対象を絞ったテストを追加して失敗することを確認し、それを通過させる最小限の変更を加えてから、このファイルの先頭に記載された5つのチェックを実行してください。報告する前に、すべてのチェックが終了コード 0 で完了している必要があります。詳細な情報は references/ に、実行可能なチェックは名前が付いた Mise タスクの背後に、テンプレートは assets/ に、実行例は examples/ に置いてください。ルールの変更によって例が古くなる場合は、同じ編集でその例も更新してください。

注意点

• フィードは、ファミリー数を超えるランクを報告します。分母はランクの上限、つまり実行内の最高ランクであり、希少な末尾の項目も順序を保てます。ランクと上限は、返された値をそのまま記録してください。
• 2つのファミリーが同じパーセンタイルを報告する場合、popularity_rank が高いほうがより希少です。検出結果はすでにその順序で並べ替えられているため、最初の行が最も希少な候補です。
• --subset と --variable-only を指定すると、希少な末尾の項目が大幅に絞り込まれ、最も希少なファミリーが隠れることがあります。参照情報で求められている場合にのみ適用し、条件を緩和する場合は、その代償を明記してください。
• meta.rarity_floor は必須条件です。バリデーターはその値を読み取り、独自の下限値を一致するように引き上げるため、90.0 を記録すると、それ以降のすべての再検証で 90.0 が適用されます。
• 先月は希少だったファミリーが、今日も希少とは限りません。デフォルトの検証では、記録されたランクを最新のカタログと比較し、変動があれば失敗します。これはゲートが機能している証拠です。
• 一般的なインターフェースのデフォルト値は、周囲の説明文で推奨されていても、common_face_reason に目視できる根拠を記載しない限り、名前を理由に却下されます。
• 分母はランクの上限に 1 を加えた値であるため、パーセンタイルは 100.0 未満にとどまります。これにより、最も希少なファミリーの値が飽和せず、同じ 100.0 によって同率の項目が見えなくなることもありません。
• より希少なフェイスが可読性の下限を満たさない場合、それは却下であり、代償について議論する余地はありません。却下として報告し、下限値を明記してください。
• インラインリンクは、すべてのモードでアクセントの役割を担います。そのため、ダークキャンバスのシステムでは、アクセントトークンを変更することで contrast の不合格を解消できます。リンクがブラウザーのデフォルトのままなら、それはハーネスの不具合であり、トークンの選択の問題ではありません。
• どのトークン値でも修正できない基準がある場合は、その旨を伝え、ハーネスの制約を明記してください。問題を隠すためにページを編集しても合格にはなりません。
• 「珍しい」や「見落とされている」などの言葉だけでは、何の根拠にもなりません。rarity_reason は測定値の理由を説明するものであり、測定値そのものの代わりにはなりません。
• フォールバックスタックには、実在するファミリーを指定し、末尾は必ず総称ファミリーにしてください。
• セクションごとに個別の検証を実行しないでください。統合されたバリデーターが唯一の機械的なゲートです。
• スキーマ契約を最初から最後まで読まないでください。一度に1つのフィールドまたはグループだけを照会してください。
• セクションの順序、信頼度ラベル、フォントの下限値は、すべてスキーマ契約に定められています。そこでルールを変更すれば、すべてのゲートに反映されます。スクリプトに値をハードコーディングすると、その連携が壊れます。

抽出が完了したと判断できるのはいつですか？

抽出が完了したと言えるのは、最新の実行でバリデーターが終了コード 0 を返し、live_fonts_checked が true であるか、その失敗が平易な言葉で報告されていること、選択した各ファミリーに適用される下限以上の希少性レコードと、役割ごとの下限を満たす fit ブロックがあること、フォントセットがペアリングチェックに合格すること、対応していないすべてのレイヤーが「該当なし」オブジェクトを使用していること、レンダリングされたページのスクリーンショットが撮影され、meta.viability.verdict: pass を伴って8つすべての基準に合格すること、そして返信に検証済みの YAML のみが含まれていることがすべて満たされた場合に限られます。画像が合格するまでは実行は完了しておらず、完了したと報告してはいけません。

ファクトリー実行契約

受け入れ条件は、視覚的な根拠からソース固有のデザイントークンシステムを抽出し、現在のレンダリング結果に照らして検証することです。現在の視覚的なトークン抽出の動作を維持しながら、その最小の所有者を変更します。

1. mise run ci で現在のパッケージを凍結し、そのダイジェストを記録します。
2. mise run domain-research-policy を実行し、現在の視覚的なトークン抽出のソースと反証を評価します。
3. 指定された視覚的なトークン抽出操作に対して mise run agentic-request を実行します。意味上の判断はモデルに委ねます。
4. mise run decision-policy、mise run ci、動作評価を実行します。失敗した場合は、最も低い階層の所有者に戻ります。
5. mise run invocation-policy -- <receipt> を実行し、すべてのタスクを実施するか、ドメイン固有の理由で実施しないことを説明します。
6. 任意で mise run improvement-policy を実行します。保護対象の次元に後退がない場合に限り、変更する次元は1つだけにします。

契約の確認が必要な場合にのみ、mise run use-case-policy で assets/use-case-contract.json を読み込み、mise run evals で evals/evals.json を読み込みます。

Mise は、繰り返し可能な仕組み、順序、記録、チェックを担います。モデルは、コードでは補えない解釈、因果関係の判断、創造的な作業、直接的な知覚を担います。権限の不足、古くなった証拠、またはゲートの失敗があれば停止します。