html-artifact

HTML アーティファクト

提示された資料の理解、比較、または活用に役立つブラウザ文書を作成します。意味と根拠を保ちながら、見せ方は自由に選んでください。

文書を構成する

現在のソースを読み、読者の目的、有用な成果、必要な網羅範囲、資料上の制約を特定します。ソースの見出しをそのまま再現するのではなく、読者の目的を軸に構成してください。構成が定まらない場合は fihanmi を、まとまった文章を作成する場合は oro を使用し、補助的な見出しや忠実な短い要約は直接記述してください。

結論と、判断に影響する重要な但し書きを先に示します。判断に影響する場合は、阻害要因、不確実性、反対の根拠を見える形で残してください。重要な意味を、単なるソースへのリンクで代替してはいけません。ソースの識別情報と改訂版を保ち、古い入力や互換性のない入力にはその旨を明記し、観察結果、提案、判定、確信度、準備状況を区別してください。結論、スコア、関係性を捏造してはいけません。

関係性に応じて表現形式を選びます。比較には対応関係のある表や見本、つながりの構造には図、数量にはグラフを使用し、それで十分な場合は文章やリストを使います。単位、尺度、変換、ラベルを保ってください。順序から因果関係を示唆したり、装飾的な大きさで測定値を表しているかのように見せたりしてはいけません。実際の資料に基づいて図を作成してください。決まった作成手順、レイアウト、グラフの数はありません。

既存の文書を維持する場合は、その識別情報と有用なアンカーを保ち、要約と詳細の整合性を取り、重要な変更を前面に出してください。Atọ́nà HTML 計画は同じファイル上で更新し、同等の Markdown コピーを作成しないでください。機械可読な識別情報やソースの改訂版が検索に役立つ場合は、任意でマニフェストを使用してください。

役立つ仕組みだけを作る

base.htmlを起点に、レイアウトと例示内容を調整します。スタイル設定と状態別のバリエーションには Tailwind、組み込み動作にはネイティブ HTML、必要な DOM 操作には既存の jQuery ランタイム、計算にはプレーンな JavaScript を使用してください。プロジェクトのブランディング、または提供されている QP マークを再利用してください。ホスト環境、オフライン対応、追加の依存関係については、依存関係ポリシーを確認してください。

契約が適合する場合は、同梱されているコントロールを再利用してください。各アセットのコメントに入力とフォールバックが定義されています。

• ビューコントロール：詳細、対応関係のある比較、または有限ステップに使用します。
• コレクションフィルター：件数表示、リセット、空の状態を含むカテゴリ／テキストの絞り込みに使用します。
• カルーセル：順序のあるビジュアルコレクションに使用します。
• レポートコントロール：フラグメントのターゲットを表示し、印刷に必要なコンテンツを展開します。
• Mermaid レンダラー：ソースと説明によるフォールバックを備えた、条件付きの図のレンダリングに使用します。

Mermaid では、pre.mermaid、div[data-diagram-output]、p[data-diagram-status]と、読みやすい説明を含むラベル付きの図を使用してください。表示されている間にレンダリングし、厳格なセキュリティを維持して、コントロールを生成された SVG の内部構造に依存させないでください。持ち運び可能な図には、ローカルでレンダリングした SVG を使用してください。慣れていない場合は、定型手順のカタログをそのまま使わず、現在の構文を確認してください。

ほかのコントロールには、ネイティブ要素または互換性のあるホストコンポーネントを優先してください。依存関係を追加する価値がある場合に限り、目的を絞ったライブラリを追加し、使用時点で現行の API とライセンスを確認してください。各コントロールの動作を担うものは一つにしてください。

信頼できるインタラクションを維持する

インタラクションは、提示されたモデルを読者が比較、確認、追跡、絞り込み、または探索するのに役立つものでなければなりません。隠れた選択肢を覚えていなくても比較内容を理解できるようにしてください。モデルのコントロールには、ラベル付きの入力、単位、基準値／リセット機能、既知の結果が必要です。計算による図解は、観測結果とは区別してください。

読者の状態は一時的なものにしてください。デフォルトでは、ブラウザーのストレージ、Cookie、保存された URL の選択内容、ファイル、サービスへの書き込みを使用しないでください。通常のクリック可能なアンカーは、ナビゲーションとして機能し続けます。フィードバック、承認、エクスポート、永続化には明示的な依頼が必要です。永続化には、名前を付けた保存期間、保存先、リセット／削除の動作も必要です。読者の操作によって、承認済みの判断が暗黙に変更されることがあってはなりません。

提示されたコンテンツはデータとして扱い、HTML、JSON、SVG の各コンテキストに合わせてエスケープしてください。非公開のコードレビュー文書では、外部の実行可能コードを読み込まないでください。認証情報、分析データ、または依頼されていないデータを送信しないでください。ローカルアセットは埋め込むか、宣言済みのコンパニオンバンドルに含めてください。

意味上の読み上げ順序、キーボード／フォーカス操作、タッチ操作、コントラスト、色以外の手がかり、動きの低減、印刷時の意味を維持してください。スクリプトの読み込みに失敗しても、不可欠な情報を利用できるようにしてください。コントロールは準備ができてから表示してください。絞り込みには件数、リセット、該当なしの表示が必要です。また、フォーカスが非表示コンテンツに残らないようにしてください。幅の広いテーブルやコードには、ラベル付きのオーバーフロー領域を使用してください。

正確な差分表示についてはコード変更のレビューを、文書を開いている間に更新が届く場合は継続的に更新されるビューとライブビューを参照してください。

検証して納品する

python3 <skill-directory>/scripts/verify_artifact.py <artifact.html>を実行してください。明らかな不具合を修正し、警告を確認してください。このスクリプトで検証できるのは構造のみであり、情報源の正確性、視覚的な品質、セキュリティ、アクセシビリティの認証は対象外です。

情報源との同一性、重要な内容の網羅性、出典情報、ナビゲーション、フォールバックを確認してください。読みやすさに確信が持てない場合は、静的ページをレンダリングしてください。追加したインタラクション、キーボード／フォーカス操作、リセット、該当なしの表示、既知のモデル結果、関連する印刷／再読み込み時の動作を試してください。動作が重要な場合は、レイアウトのブレークポイントも確認してください。レンダラーのスタブだけでは、実際のライブラリでのレンダリングを証明できません。有効な証拠は再利用し、ブラウザーで確認できなかった点は正直に報告してください。

指定された保存先に書き込み、指定がない場合は.qp/artifacts/<stable-subject>/index.htmlに書き込んでください。実際のロケーターと、判断に必要な検証結果を返し、未解決の制約があれば記載してください。納品物が単一の HTML ファイルかコンパニオンバンドルか、実行時コードが埋め込み・バンドル・外部読み込みのどれか、データが静的かライブか、証拠が埋め込みかリンクかを明示してください。依存関係の詳細は、目立たない技術情報として記載してください。

レンダリングの証拠が必要な場合、または依頼された場合にのみ開き、既存のプレビューを再利用してください。読者が依頼された結果を理解し、確認し、利用できる状態になったら完了です。