sgds-blocks

SGDS ブロックテンプレート

あらゆるページレイアウトに組み込める、再利用可能な UI ブロックです。各ブロックは独立したセクションです。sgds-templates のページテンプレートに配置すれば、レイアウトコードを一から書かずにページ全体を組み立てられます。

ブロックとは？

ブロックとは、次のような UI のまとまりです。

• 単一の明確な役割を担います（コンテンツの絞り込み、統計情報の表示、フォームセクションの表示、ヒーローバナーの作成など）。
• 任意のコンテナ内で単独で機能します。
• 1 つのページに複数回配置したり、ほかのブロックと組み合わせたりできます。

Application Shell は特別な必須ブロックです。これは、すべての SGDS ページに含める必要があるページの枠組み（<sgds-masthead>、<sgds-mainnav>、<sgds-footer>）です。ほかのブロックはすべて、シェル内に配置するコンテンツブロックです。

ブロックは材料で、ページテンプレートはレシピです。

前提条件

import "@govtechsg/sgds-web-component/themes/day.css";
import "@govtechsg/sgds-web-component/css/sgds.css";
import "@govtechsg/sgds-web-component/css/utility.css";

インストールの詳細については、sgds-components をご覧ください。

---

クイック選択ガイド

必要なもの	使用するブロック
SGDS ページに必須のページ枠組み（masthead、mainnav、footer、container）	Application Shell
見出し、説明、CTA ボタン、任意の画像を含む全幅のヒーローセクション	Hero
画像やコンポーネントの配置、グリッド比率を設定できる機能紹介セクション	Feature
コールトゥアクションセクション（primary、raised、alternate、centered、または full-bleed）	CTA
統計・指標の表示（3、4、5、または6列）	Stats
カードグリッドレイアウト（3列または4列）	Cards
パンくずリスト、アイコン＋タイトル、説明、メイン CTA を含むページレベルのヘッダー	Page Header
主要なキーと値のフィールド、編集アクションを含む読み取り専用のエンティティ概要カード	Basic Details Card
フィルターインターフェースと検索結果のレイアウト	Filter
適切なコンポーネントサイズ、グループ化、レイアウトルールを備えた複数フィールドのフォーム	Form

---

→ reference/application-shell.md を読む

すべてのページで必須です。 アプリケーションシェルは、必須のシンガポール政府のページ枠組みである <sgds-masthead>、<sgds-mainnav>、<sgds-footer> で、すべてのページコンテンツを囲みます。2 種類のレイアウトバリエーション（Simple App（.sgds-container、一般公開向け）と Sidebar App（.sgds-container-sidebar、ダッシュボードや内部ツール向け））を提供し、ブレークポイントの全表と固定ヘッダーのパターンを含みます。

---

→ reference/hero.md を読む

複数のレイアウトや背景オプションを備えたヒーローセクションです。ランディングページ、キャンペーンページ、セクションの導入など、ファーストビューのコンテンツに使用します。

---

→ reference/feature.md を読む

画像やコンポーネントの配置、グリッド比率を設定できる機能紹介セクションです。主要な製品のメリット、機能、特長を強調する際に使用します。

---

→ reference/cta.md を読む

複数のスタイルと配置オプション（primary、raised、alternate、centered、contained、または full-bleed）を備えたコールトゥアクションセクションです。ページ全体を通して、ユーザーのアクションを促す際に使用します。

---

→ reference/stats.md を読む

複数の列数（3、4、5、または6列。右寄せのバリエーションも選択可能）に対応する統計・指標の表示です。主要な指標、成果、影響を示す数値の紹介に使用します。

---

→ reference/cards.md を読む

カードコンポーネント向けのグリッドレイアウト（3列または4列）です。項目の一覧を構造化されたカードグリッドで表示する際に使用します。

---

→ reference/page-header.md を読む

パンくずリスト＋アイコンで色付けされたコンテナ＋h1 見出し＋説明＋メイン CTA ボタンです。ユーザーにページの内容を伝え、メインアクションを提示するため、コンテンツページの先頭に使用します。

---

→ reference/basic-details.md を読む

サブタイトル見出し、縦に並ぶキーと値のペア、任意の編集ボタンを備えた枠線付きカードです。詳細ページやプロフィールページで、エンティティのメタデータ（ID、名前、説明、連絡先情報）を読み取り専用で表示するために使用します。

---

→ reference/filter.md を読む

フィルターインターフェースと検索結果のレイアウトです。高度なフィルタリングや検索結果の表示に使用します。

---

→ reference/form.md を読む

フォームのレイアウト規則：グリッド計算、コンポーネントの組み合わせ、バリデーションフィードバック、標準パターン。 すべてのフォームで、12列の .sgds-grid を使用します。フォームコンテナは8列幅（左揃えまたは中央揃え）です。ペアにするフィールドはそれぞれ6列幅（1行につき最大2つ）です。全幅フィールド（textarea、checkbox-group、radio-group、file-upload）は常に12列にします。再利用可能な5つのパターン（全幅のみ、ペアフィールド、混合レイアウト、複数セクション、サイドバーナビゲーション）を含みます。

---

ページテンプレートでブロックを組み合わせる

ブロックはページテンプレートのコンテンツ領域内に配置します。一般的なパターンは次のとおりです。

<sgds-masthead></sgds-masthead>
<sgds-mainnav>...</sgds-mainnav>

<div class="sgds:bg-surface-default sgds:min-h-screen">
  <div class="sgds:w-container sgds:mx-auto sgds:py-layout-md">

    
    <div class="sgds:flex sgds:gap-layout-md sgds:items-start">

      
      <aside class="sgds:shrink-0 sgds:w-64">
        
      </aside>

      
      <div class="sgds:flex-1">
        
      </div>

    </div>
  </div>
</div>

<sgds-footer></sgds-footer>

---

フォームのコードを書く前に

SGDS コンポーネントには固有の制約があるため、フォームは複雑です。まず reference/form.md を読んでください。グリッド計算、コンポーネントの組み合わせルール、5つの標準パターン、配置のバリエーションがすべて記載されています。

コンポーネント API の確認

使用する <sgds-*> 要素ごとに、コンポーネントのリファレンスを読んでください。

• 子要素の命名：各コンポーネントには固有の子要素名があります。<sgds-select> は <sgds-select-option>（<sgds-option> ではありません）を使用します。<sgds-combo-box> は <sgds-combobox-option> を使用します。sgds-components skill のリファレンスで必ず確認してください。
• スロットの要件：<sgds-file-upload> のスロットにはテキストラベルが必要です（アイコンだけでは不可）。コンポーネントが子要素、スロットコンテンツ、JS プロパティのどれを想定しているかを確認してください。
• 任意のプロパティ：<sgds-stepper> は、<sgds-stepper-item> のような HTML 子要素ではなく、JS プロパティ（steps 配列）を使用します。属性と JS プロパティのどちらを受け付けるか、コンポーネントごとに確認してください。

フォーム固有の制約

reference/form.md より：

• フォームの幅は .sgds-container 内で正確に8列です
• ペアにできるフィールド（Input、Select、Datepicker、Combo-box の単一選択）：lg 以上ではそれぞれ6列（sm では4列）です
• 全幅フィールド（Textarea、Checkbox-group、Radio-group、Combo-box の複数選択、File-upload）：常に12列です
• グリッド計算：sidebar_cols + form_cols + toc_cols ≤ 12
• 複数選択の Combo-box：⚠️ 重大な注意 — 全幅にする必要があります。他のコンポーネントと組み合わせないでください

コーディングの前に、必ず reference/form.md と照合してください。

---

カスタムブロックの作成

ユーザーは、レイアウト、構成、視覚的な階層など、創造性を存分に発揮して独自のブロックを自由に設計できます。唯一の制約は、すべてのブロックが SGDS システムのルールに従うことです。

要件	方法
UI コンポーネント	<sgds-*> Web コンポーネントを使用してください。SGDS コンポーネントがある場合は、通常の HTML に置き換えないでください（例：独自に作成した <span> チップではなく、<sgds-badge> を使用します）。
スタイル設定	色、余白、タイポグラフィ、レイアウトには sgds: Tailwind ユーティリティのみを使用してください。デザイントークンで表現できる値を重複して定義する CSS の任意値は記述しないでください。
タイポグラフィ	セマンティックなロールトークン（sgds:text-heading-md、sgds:text-body-md、sgds:text-overline-md など）を、対応するウェイト、行の高さ、トラッキングのトークンと組み合わせて使用してください。公開 API に含まれないスケールトークン（sgds:text-base、sgds:text-sm）は使用しないでください。
アイコン	<sgds-icon name="..."> のみを使用してください。生の SVG やサードパーティ製アイコンライブラリを埋め込まないでください。
外部の参考例	レイアウトのアイデアを得るために、shadcnblocks.com、Tailwind UI、その他のデザインギャラリーを参考にしても構いません。ただし、参照元サイトの CSS やコンポーネントライブラリではなく、必ず SGDS コンポーネントとトークンを使って再実装してください。

→ トークンの全リファレンス、アンチパターン、注釈付きの例については、reference/custom-block-rules.md をお読みください。

---

AI エージェント向け

⚠️ 重大なルール — 必ず最初に以下のスキルを読み込んでください

ブロックのコードを書く前に、必ず次の手順を実行してください。

1. sgds-utilities スキルを読み込む — ユーティリティクラスの完全なリファレンスが必要です
2. sgds-components スキルを読み込む — コンポーネント API と子要素の名前が必要です
3. その後、このスキル内の reference/custom-block-rules.md を読む

スタイル設定のルール（すべてのブロックに適用）：

• 余白、色、タイポグラフィ、レイアウトには sgds: Tailwind ユーティリティのみを使用してください
• UI 要素には <sgds-*> コンポーネントのみを使用してください
• デザイントークンを再現するために、インラインの <style> ブロックを使用しないでください（例：margin: 24px、var(--sgds-*)）
• デザイントークンで表現できる内容と重複する CSS を任意に記述しないでください

ユーティリティとコンポーネントを最初に読み込まないと、インラインスタイルを使ってしまい、デザインシステムに違反することになります。これはエージェントがブロックで犯す最大の間違いです。

---

エージェントのワークフロー（順番どおり）

1. sgds-utilities スキルを読み込む
2. sgds-components スキルを読み込む
3. このスキルを読み込む
4. reference/custom-block-rules.md を読む
5. その後、ユーティリティとコンポーネントを使用してブロックのコードを書く

ガイドライン

1. すべてのページに Application Shell が必要です — <sgds-masthead>、<sgds-mainnav>、<sgds-footer> は、すべての SGDS ページで必須です。レイアウトのパターンとコンテナクラスについては、reference/application-shell.md をお読みください。
2. ユーザーがフィルター付きリストページを求めた場合は、Filter Sidebar ブロックと、sgds-templates の List Page テンプレートを組み合わせてください。
3. カテゴリーラベル、値、件数はユーザーの実際のデータ領域に合わせて変更してください。カンファレンスの例をそのままコピーしないでください。
4. ユーザーが「カスタムブロックを作成したい」と言った場合、または外部デザイン（shadcnblocks、Figma、スクリーンショット）を参照した場合は、出力を生成する前に reference/custom-block-rules.md をお読みください。