html-design-examples

HTML デザインの例

単体で完結する .html ファイルのライブラリです。静的な HTML アーティファクトは、同じ内容を Markdown で作成するよりも多くの情報を伝えられることを示しています。同様のタスクで HTML の成果物を作成する際に、視覚面と構成面の参考として活用してください。

Markdown ではなく HTML を使う理由

ボトルネックはエージェントが作成できるものではなく、人間の注意力です。500 行の Markdown 計画は読まれませんが、同じ内容でも図、表、インライン操作を備えた HTML ページなら関心を持ってもらえます。HTML なら、表、SVG、CSS レイアウト、スクリプト、空間的な構成を 1 つのファイルにまとめられ、どのブラウザーでも開けます。また、添付ファイルではなく URL で共有できます。トークンと遅延のコストは確かにかかりますが、人間が読む必要のあるアーティファクトなら、その価値があります。

人間向けの一時的なアーティファクト（仕様書、計画書、レポート、文書、プロトタイプ、一時的なエディター）には HTML を優先してください。リポジトリで長期にわたって行単位でレビューする必要があるもの（RFC、ADR、運用手順書）は Markdown またはソースのままにしてください。HTML の差分は見づらくなります。

このスキルの使い方

1. ユーザーの意図に最も近い例を選びます（下のカタログを参照）。
2. 自分で作成する前に、そのファイルを最後まで読みます。参考資料のスタイル、情報密度、構成が重要です。
3. 共通の規約（「規約」を参照）に合わせます。
4. ユーザーの実際の内容に合わせて調整します。例では架空の「Birchline」ブランドとフィクスチャデータを使用していますが、それらを引き継がないでください。
5. アーティファクトがエディターまたはインタラクティブな画面の場合は、ユーザーの作業をエージェントのループに戻せるよう、「copy as JSON」または「copy as prompt」ボタンを最後に追加します。

リソースカタログ

ファイルは resources/ にあります。サムネイル付きのギャラリーを表示するには、resources/index.html を開いてください。

探索と計画

• 01-exploration-code-approaches.html - 3 つの実装方法をトレードオフとともにインラインで比較します。
• 02-exploration-visual-designs.html - レイアウトとカラーパレットの選択肢をリアルタイムで表示し、視覚的に比較できます。
• 16-implementation-plan.html - タイムライン上のマイルストーン、データフロー図、インラインのモックアップ、リスクの高いコード、リスク表を掲載します。

コードレビューと理解

• 03-code-review-pr.html - 余白の注釈、重大度タグ、ジャンプリンクを備えた注釈付き差分です。
• 17-pr-writeup.html - 作成者向けの PR 説明です。動機、変更前と変更後、ファイルごとの解説を含みます。
• 04-code-understanding.html - なじみのないパッケージをボックスと矢印で図示し、重要な処理経路を強調します。

デザイン

• 05-design-system.html - 色、文字サイズのスケール、余白のトークンをコピー可能なスウォッチで表示します。
• 06-component-variants.html - 1 つのコンポーネントのすべてのサイズ、状態、用途を 1 枚の一覧にまとめます。

プロトタイピング

• 07-prototype-animation.html - 時間とイージングを調整するスライダーを備え、トランジションを単独で表示します。
• 08-prototype-interaction.html - 操作感を確かめるのに十分な再現度を備えた、相互にリンクされた 4 つの画面です。

イラストと図

• 10-svg-illustrations.html - ブログ記事に適した、インライン SVG の図版シートです。
• 13-flowchart-diagram.html - クリックすると手順の詳細を表示する、注釈付きフローチャートです。

スライドデッキ

• 09-slide-deck.html - ビルド手順なしで、矢印キーを使って操作できる 1 ファイル構成のスライドです。

調査と学習

• 14-research-feature-explainer.html - 要約、折りたたみ可能なリクエスト経路の手順、タブ付きの設定スニペット、FAQ を備えています。
• 15-research-concept-explainer.html - インタラクティブなデモ、比較表、ホバーで連動する用語集を備えています。

レポート

• 11-status-report.html - リリースした内容、遅れた内容、小さなグラフをまとめた週次ステータスです。
• 12-incident-report.html - 分単位のタイムライン、ログ抜粋、フォローアップのチェックリストを含む事後分析です。

カスタム編集インターフェース

• 18-editor-triage-board.html - チケットを「Now」「Next」「Later」「Cut」の間でドラッグし、並び順を Markdown としてエクスポートします。
• 19-editor-feature-flags.html - 依存関係の警告と、変更されたキーの差分コピーボタンを備えた、グループ化されたトグルです。
• 20-editor-prompt-tuner.html - 変数スロットを強調表示した編集可能なテンプレートです。3 つの入力例は、入力に応じてリアルタイムで再描画されます。

すべての例に共通する規則

• .html ファイルは1つだけで、ブラウザーで直接開けます。ビルド、npm、CDNスクリプト、外部スタイルシートは不要です。
• カラーパレットとフォントスタックには、:root の CSS カスタムプロパティを使用します。
• セリフ体のディスプレイ見出しとサンセリフ体の本文を組み合わせるのが、繰り返し使われるタイポグラフィのパターンです。
• インタラクティブな機能は、1つの <script> タグ内のバニラ JavaScript で実装します。
• 落ち着いたエディトリアルな美しさを目指します。紙のような色合い、控えめなアクセントカラー、ゆとりのある余白を使います（ただし、情報を狭い列に詰め込まないでください。画面領域を有効に活用してください）。
• インタラクティブな画面では状態をエクスポートできるようにします。仕上げとして「JSON としてコピー」または「プロンプトとしてコピー」ボタンを設けます。

美的な一貫性

ユーザーが独自のデザイン言語を持つ既存プロジェクトを使用している場合は、デザインシステムをまとめた HTML ファイルを1つ生成または参照し（形式は 05-design-system.html を参照）、以降の成果物ではそれをスタイルの基準として使います。ギャラリーのエディトリアルなカラーパレットをそのままコピーするのではなく、プロジェクト独自のブランドとトークンを優先してください。

注意点

• HTML の差分は見づらくなります。成果物をリポジトリに格納し、今後行単位でレビューする予定がある場合は、代わりに Markdown を作成してください。
• エクスポートボタンのないエディターは、ツールとしては不完全です。インタラクティブな成果物は、結果をテキストに戻せる方法を必ず用意して仕上げてください。
• 矢印キーで操作するスライドデッキを求めている場合は、html-slides スキルが専用に用意されています。コピー用プロンプトボタンを備えた設定可能なエクスプローラーを求めている場合は、playground スキルが専用に用意されています。このスキルは、それ以外の単一ファイルの HTML 成果物全般に対応します。