html-generator

HTML Generator Skill

デザインシステムに基づいて、個性とブランドらしさのある HTML ページやスタンドアロンコンポーネントを作成します。

最も重要な理解

HTML ページの作成は、テンプレートへの入力ではなく、デザインシステム主導の構成です。各コンポーネントは、単独でも、組み合わせたページの一部としても機能する、独立したデザイン成果物です。すべてのセクションが、熟練したシニアデザイナーによって意図的に作り込まれた、個性的で忘れがたいものに感じられる必要があります。

• 受け取るもの：デザイントークン、コンポーネントカタログ、ブランドアイデンティティを含むデザインシステム（canvas-philosophy.md + design-system.md）。
• 作成するもの：スタンドアロンの HTML コンポーネント + 単一ファイルの HTML ページ。
• 基準：見る人がスクロールを止めるような作品。大胆で、個性的で、ありきたりではないもの。

呼び出されるとき

/html-page および /html-page-quick から呼び出されます。受け取るもの：デザインシステムのファイル（canvas-philosophy.md + design-system.md）、ブランドフィロソフィー（brand-philosophy.md またはサブアイデンティティの上書き設定）、コンポーネントの選択、components/ 内の再利用可能なコンポーネント、コンテンツ、references/web-style-constraints.md のスタイル制約。

2 つの出力モード

• コンポーネント生成 — 個別のスタンドアロンコンポーネント：<style> を埋め込んだ完全な HTML フラグメント、CSS カスタムプロパティによるデザイントークン、プロパティ／スロットのメタデータコメントを含み、トークンのフォールバックを使って単独で表示できます。
• ページ構成 — コンポーネントを 1 つの .html ファイルに組み立てます。共通の :root トークン、ビューポートメタタグを含むレスポンシブラッパー、一貫した間隔で並べたコンポーネント、上部のナビゲーション + 下部のフッター、重複を排除した単一の <style> ブロック、スタイル上必要な場合に限った最小限の <script> を含みます。

ファイル形式、ボイラープレート、コンポーネント／ページ全体の構造については、references/html-technical.md を参照してください。

Part 1: デザイン思考のプロセス

HTML を書き始める前に、デザインシステムをしっかり理解してください。

0. ブランドの存在を確認する — プロジェクトに design-system.md がない場合は、作業を中止して、まず /design-html を提案してください。brand-philosophy.md がない場合は、まず /brand-extract を提案してください。デフォルト値や例の値を使って作業を進めてはいけません。
1. キャンバスのフィロソフィーを読む — ルールだけでなく、その美的ムーブメントを吸収してください。
2. デザイントークンを読み込む — 色、フォント、間隔を CSS カスタムプロパティにします。
3. スタイルを理解する — references/web-style-constraints.md の強制要件を読みます。
4. コンテンツを検討する — ページの目的は何ですか？ 誰が見るのでしょうか？ どのような感情を抱いてほしいのでしょうか？
5. 差別化を計画する — このページをありきたりなものと視覚的に区別し、記憶に残るものにする要素は何でしょうか？

差別化のテスト

生成前に、こう問いかけてください。「このページはどのブランドにも属しうるだろうか？」もしそうなら、さらに個性を強めてください。続けて、**「このページについて、見る人が覚えていることは何だろうか？」**と問いかけます。たとえば、大胆な文字サイズのスケール、意外性のある色使い、予想外のレイアウトの崩し方などです。答えが見つからないなら、そのデザインにはまだ十分な個性がありません。

キャンバスのフィロソフィーならではのムーブメントや精神、予想外のレイアウトの選択（非対称、重なり、グリッドを崩す構成）、アートとしてのタイポグラフィ、雰囲気（グラデーションメッシュ、ノイズ、パターン、奥行きのあるシャドウ）、マイクロインタラクションによるブランドの個性を取り入れてください。

強度より意図

実装の複雑さを、美的ビジョンに合わせてください。 マキシマリストなデザインには、豊富なアニメーションや重層的な効果を伴う複雑なコードが必要です。一方、ミニマルで洗練されたデザインには、抑制、精度、慎重な余白とタイポグラフィが必要です。重要なのは強度ではなく意図です。数学的な精度で仕上げたスイスデザインは、奔放なエネルギーで仕上げたメンフィスデザインと同じほど力強いものです。「大胆さ」を一律に当てはめず、スタイルに合わせて調整してください。

Part 2: ブランドの統合

デザイントークン → CSS カスタムプロパティ

プロジェクトの design-system.md を読み、すべてのトークンセクションを :root のカスタムプロパティに割り当てます。色（--color-primary、--color-accent、--color-bg、--color-text、…）、タイポグラフィ（--font-heading、--font-body、--font-size-*）、スペーシング（--space-xs…--space-2xl）、レイアウト（--max-width、--border-radius、--min-tap-target）、インタラクションのタイミング／イージング、フォームがあるページではフォーム用トークンも対象です。デザインの唯一の信頼できる情報源は design-system.md です。値をハードコードしないでください。

ブランドバイアスの防止（HTMLを生成する前に確認）

□ All colors use CSS custom properties from design-system.md (--color-primary, etc.)
□ No hardcoded hex values except #FFFFFF/#000000 for universal black/white
□ font-family from design-system.md, never "Inter", "Roboto", or "Arial" as defaults
□ If no design-system.md exists: STOP, suggest /design-html first
□ Background, accent, and text colors all traced to design tokens

参照ファイルの例にある16進カラーコードやフォント名を、生成するHTMLに決してコピーしないでください。 すべてのビジュアル値は、design-system.md → CSS カスタムプロパティ → コンポーネントのスタイルの順に適用します。

色の優勢の原則

控えめで均等に配分されたパレットよりも、優勢な色と際立つアクセントのほうが効果的です。--color-primary を主役として（見出し、CTA、アクティブなナビゲーションに）、--color-accent を鋭いアクセントとして（リンク、ホバー、ハイライトに）使い、--color-bg／--color-text は構造を支える控えめな役割にします。パレットが「均等」に感じられる場合は、プライマリをより強くするか、セカンダリを抑えます。

フォントの読み込み

システムフォールバックスタックを指定した <link> で、個性的な Google Fonts を読み込みます。Inter、Roboto、Arial をデフォルトとして使わないでください。正確な <link> マークアップとフォールバックスタックは、references/html-technical.md § Font Loading Strategy に記載されています。

パート 3：コンポーネントの生成

すべてのコンポーネントに適用されるルール

1. 単体での有効性 — 各コンポーネントが単独のHTMLファイルとして機能すること。
2. 共有トークン — すべてのコンポーネントが同じ CSS カスタムプロパティ名を参照すること。
3. 一貫した命名 — {type}-{variant}.html（例：hero-centered.html）。
4. プロパティ／スロットのメタデータ — コンテンツの挿入箇所を示すHTMLコメント。
5. レスポンシブ対応 — モバイルファーストで、3つすべてのブレークポイントで機能すること。
6. アクセシブル — セマンティックHTMLを使い、必要に応じてARIAラベルとフォーカス管理を追加すること。
7. インタラクティブ状態 — クリック可能なすべての要素に、インタラクショントークンを使ったホバー、フォーカス、アクティブのスタイルを定義すること。
8. タッチ対応 — インタラクティブ要素が適切な間隔を確保し、--min-tap-target 以上のサイズであること。

メタデータコメント（必須）

すべてのコンポーネントには、変換に対応したメタデータコメントを必ず付けてください。これらがないと、design-system-converter はコンポーネント、プロパティ、スロットを識別できません。

• … でコンポーネント全体を囲む
• `` を、注釈対象の要素の直前に置く
• … で繰り返し／挿入可能なコンテンツを囲む
• `` を SVG の前に置く

サポートされているプロパティ型：string、boolean。これらのコメントは、単独コンポーネントと合成ページの両方に必ず含めてください。例を含む完全な形式については、references/html-technical.md § Convertibility Metadata Format を参照してください。

コンポーネントの CSS

BEM風の命名（.hero、.hero__title、.hero__title--large）でスタイルの適用範囲を限定し、値をハードコードせず、デザイントークンを参照してください。15種類すべてのコンポーネントタイプに対応するHTMLの骨組みとCSSパターンは、references/html-components.md に記載されています。

パート 3.5：アイコンの統合

Lucide アイコン（1,500種類以上）は、node "$BRAND_CONTENT_DESIGN_DIR/scripts/html-icons.js" get|search|category|categories を使ってインラインSVGとして利用できます。アイコンのストロークには currentColor を使い、サイズはコンテナーから継承します。明確な視覚的メタファーがある場合に限ってアイコンを使い、テキストラベルと組み合わせてください。装飾的なアイコンには aria-hidden="true" を、意味のあるアイコンには role="img" aria-label="…" を指定します。取得コマンド、埋め込みパターン、コンテナーの CSS については、references/html-technical.md § Icon Integration を参照してください。

パート 4：スタイルの適用

選択したスタイルについて references/web-style-constraints.md を読み、セクションごとの上限（単語数／要素数）、スペーシング値、タイポグラフィのルール、配色方針、レイアウト指示、JavaScript の使用許可、アンチパターンを適用してください。適用ルールをすべてのコンポーネントと合成ページに反映してください。

パート 5：レスポンシブデザイン

モバイルファーストで、ブレークポイントは3つです。基本は375px、タブレットは@media (min-width: 768px)、デスクトップは@media (min-width: 1200px)です。一般的な調整として、ハンバーガーメニューから横並びのナビゲーションへ、縦積みのヒーローから横並びへ、グリッドの列数を1から2、さらに3～4列へ変更します。モバイルでは文字サイズを15～20％縮小し、セクションのパディングを30～40％減らします。ブレークポイントのコードとタイポグラフィのスケーリングについては、references/html-technical.md § Responsive Breakpointsを参照してください。

パート 6：CSS優先のインタラクティブ性

CSSを優先し、CSSで実現できない効果に限りJSを使用してください。

モーションの優先順位 — ページごとに、モーションの予算を最もインパクトの大きい瞬間ひとつに集中させます。段階的な表示を取り入れた、きちんと演出されたページ読み込みは、散在する細かなインタラクションに勝ります。ヒーローの登場、統計値のカウントアップ、カードグリッドのカスケード表示からひとつ選び、磨き上げて、残りは控えめにしてください。

CSSのみで実現できるパターン：ホバー遷移（transform、box-shadow、opacity）、<details>／<summary>アコーディオン、scroll-snap、@keyframes、scroll-behavior: smooth、:focus-visible。スタイル（Kinetic、3D／Immersive、パララックス）の実現にJSが必要な場合は、バニラJSのみを使い、プログレッシブエンハンスメントを取り入れ、prefers-reduced-motionを尊重し、コードを約50行以内に収めてください。JSパターンのコード（Intersection Observer、モバイルナビゲーションの切り替え、軽量なパララックス）については、references/html-technical.md § Vanilla JS Patternsを参照してください。

パート 7：アートとしてのタイポグラフィ

HTMLページにおいて、タイポグラフィは主要なデザインツールです。大胆な選択をしてください。

• 見出しと本文の組み合わせ — 対照的でありながら調和する組み合わせ（セリフ体の見出し＋サンセリフ体の本文、またはその逆）。
• ウェイトのコントラスト — 300～900の幅を活用して階層を表現します。
• サイズのコントラスト — 見出しを本文より圧倒的に大きくします（3～6倍）。
• 字間 — 大文字の見出しでは広く、大きなディスプレイテキストでは狭くします。
• 行の高さ — 本文はゆったり（1.6～1.8）、見出しは詰めて（1.0～1.2）設定します。

絶対に使用しないでください：Inter／Roboto／Arial／Helvetica（ブランドまたはスタイルのVisual DNAで指定されている場合を除く）、システムフォントのみのスタック、全体を通して単一のウェイトを使うこと、均一なサイズ設定。

収束の回避 — 生成を重ねても、フォントの選択が同じにならないようにしてください。生成した10ページを並べたとき、10人の異なるデザイナーの作品に見えるべきです。プロジェクトごとに、ディスプレイフォント、本文フォント、ウェイトの分布、サイズのスケールを変えてください。

パート 8：空間構成

• 対称性より非対称性 — 完全な対称性は単調です。制御された非対称性が躍動感を生みます。
• 重なりとレイヤー — 要素を重ねてもかまいません（テキストの背後に画像を配置する、装飾的な図形を重ねるなど）。
• グリッドを崩す — まずグリッドを定め、重要な場面では意図的にそこから外します。
• 十分な余白 — var(--space-xl)～var(--space-2xl)のパディングを使い、セクションにゆとりを持たせます。
• 全幅で見せる場面 — 一部のセクションは最大幅のコンテナからはみ出させます。
• 雰囲気づくり — グラデーションメッシュ、控えめなSVGノイズ／粒状感、CSSで生成する幾何学模様、レイヤー化したbox-shadowによる奥行き、リズムを生むセクション背景の切り替え。

パート 9：アクセシビリティ（必須）

生成するすべてのページは、次の要件を満たす必要があります。セマンティックなHTML5ランドマーク、レベルを飛ばさないh1→h2→h3の階層、スキップナビゲーションリンク、WCAG AAのコントラスト（通常のテキストは4.5:1、大きなテキストは3:1）、視認可能な:focus-visibleインジケーター、説明的なaltテキスト（またはプレースホルダーコメント）、ナビゲーション／ランドマーク／インタラクティブ要素へのARIAラベル、アニメーションを無効にする@media (prefers-reduced-motion: reduce)、<html lang="en">、ビューポートのメタタグ。

ニューモーフィズムに関する注意 — 似た背景色にソフトシャドウを重ねると、WCAG AAの要件を満たせないおそれがあります。コントラストを再確認し、必要に応じて明示的な境界線を追加するか、シャドウのコントラストを高めてください。チェックリストの全項目については、references/html-technical.md § Accessibility Checklistを参照してください。

Part 10: ページの構成

コンポーネントを組み合わせてページ全体を構成する際は、すべてのコンポーネントセクションでメタデータコメントを必ず保持してください。これは、フレームワークへの変換を可能にするための最も重要な要件です。

• 最外側の要素の前に を置き、閉じタグの後に を置きます。
• 注釈を付ける要素の直前に を置きます。スロット領域は … `` で囲みます。
• メタデータを削除、要約、簡略化したり、セクション区切りコメント（, ）に置き換えたりしないでください。

構成したページの CSS の順序は、リセット → :root トークン → ベースのタイポグラフィ → ユーティリティ（.container、.sr-only、.skip-link）→ コンポーネントのスタイル（重複排除済み）です。セクションのパディングは一貫させ（デスクトップでは var(--space-xl) 0、モバイルでは var(--space-lg) 0）、背景を交互に切り替えてリズムを付け、セクション間に目に見える境界線を設けないでください。構成済みページの完全な例と HTML のボイラープレートについては、references/html-technical.md § Page Composition Format を参照してください。

Part 11: 画像の処理

Claude は画像を生成できません。スマートなプレースホルダーを使用してください。ブランドパレットに合わせた CSS グラデーション、比率を保つ aspect-ratio、画像の差し替え手順を記した HTML コメント、変化を付ける装飾的な CSS パターン、チーム写真用のイニシャルやアイコンのプレースホルダーなどです。プレースホルダー用 CSS については、references/html-technical.md § Image Placeholder Approach を参照してください。

Part 12: 変換可能な構造

コンポーネントは、将来的に Drupal SDC、React、Canvas、その他のフレームワークへ変換できるように設計してください。変換を可能にするのは、Part 3 と Part 10 のメタデータコメントです。セマンティックなコンポーネント名（hero、feature-grid、cta）、BEM CSS クラス、すべてのブランド値に対する CSS カスタムプロパティ、動作フック用のデータ属性（data-reveal、data-parallax）を使用してください。HTML メタデータから SDC／React／Twig への完全なマッピング表は、references/html-technical.md § Convertibility Metadata Format にあります。

アンチパターン（絶対に避ける）

• CSS フレームワークを出力に含めないでください。Bootstrap、Tailwind、Foundation は使用しないでください。
• 外部 JS を出力に含めないでください。jQuery、React、Alpine、HTMX は使用しないでください。
• 壊れた画像を使用しないでください。CSS のプレースホルダーを使用し、<img src="missing.jpg"> は決して使わないでください。
• AI 生成物のような低品質な表現を避けてください。ありきたりなストックフォト風の見た目、使い古されたグラデーション、陳腐なレイアウトは避けてください。
• テキストの壁を作らないでください。スタイル制約で指定されたセクションごとの単語数制限を守ってください。
• インラインスタイルを使わないでください。CSS はすべて <style> ブロックに記述してください（CSS カスタムプロパティの上書きを除く）。
• タイポグラフィにピクセル単位を使わないでください。アクセシビリティのため、rem／em を使用してください。
• フレームワークのフォント読み込みを使わないでください。Google Fonts の <link> のみ使用してください。

参考資料

同梱資料（プラグイン固有）

• references/html-design-guide.md — デザインシステムの考え方とコンテンツタイプのガイド
• references/web-style-constraints.md — Web 向けのスタイル制約ブロック 21 種
• references/html-components.md — HTML／CSS パターンを含む 15 種のコンポーネントタイプ
• references/html-technical.md — ボイラープレート、メタデータ形式、レスポンシブ対応、フォント、アイコン、JS、アクセシビリティ、ページ構成、変換可能性

オンライン開発ガイド（デザインシステム）

このプラグインのビジュアルスタイルの範囲を超えるデザインシステムの基本事項については、「design system recognition」「Bootstrap mapping」「Radix SDC」「component classification」などのキーワードを指定して /dev-guides-navigator を呼び出してください。ナビゲーターがキャッシュと曖昧さの解消を処理します。dev-guides の URL を直接取得しないでください。