sgds-getting-started

SGDS の始め方

SGDS は初めてですか？ 続ける前に、スキルの全体像と推奨される読み進める順序について sgds-workflow をご覧ください。

SGDS ウェブコンポーネントライブラリを使ってアプリケーションを構築する場合、コンポーネントやページのコードを書く前に、次の 4 つの手順を順番に完了してください。

---

Step 1 — フォントを設定する

SGDS の基盤スタイルでは、デフォルトで Inter 書体を使用します。SGDS の CSS より前に、HTML ドキュメントの <head> に Google Fonts のインポートを追加してください。以下の URL は、SGDS のデザイントークンで定義されている 4 種類のウェイト（300、400、600、700）のみを、通常体とイタリック体の両方で読み込みます。

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link
    href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,300;0,14..32,400;0,14..32,600;0,14..32,700;1,14..32,300;1,14..32,400;1,14..32,600;1,14..32,700&display=swap"
    rel="stylesheet"
  />
</head>

---

Step 2 — Foundation CSS と Utility CSS をインポートする

プロジェクトのメイン CSS エントリーポイント（ビルドツールで処理されるファイル）に、これらのファイルをインポートしてください。

/* e.g. globals.css, index.css, main.css */

/* 1. Theme tokens — must come first */
@import "@govtechsg/sgds-web-component/themes/day.css";
/* Optional — add only if supporting dark/night mode */
@import "@govtechsg/sgds-web-component/themes/night.css";

/* 2. Foundation styles (typography, headings, body, grid) */
@import "@govtechsg/sgds-web-component/css/sgds.css";

/* 3. Utility classes (sgds: prefix) — must be processed by Tailwind */
@import "@govtechsg/sgds-web-component/css/utility.css";

utility.css には Tailwind v4 のディレクティブが含まれており、Tailwind のパイプラインで処理する必要があります。通常の JS インポートとしてインポートすることはできません。

ユーティリティクラスの設定について詳しくは、sgds-utilities をご覧ください。

---

Step 3 — SGDS ウェブコンポーネントを登録する

アプリのエントリーポイント（JS/TS）で、コンポーネントライブラリを一度だけインポートしてください。

import "@govtechsg/sgds-web-component";

これにより、すべての <sgds-*> カスタム要素がグローバルに登録されます。

React、Vue、Angular、Next.js 固有の統合方法について詳しくは、sgds-components をご覧ください。

---

Step 4 — SGDS のアプリレイアウトを使用する

すべての SGDS アプリケーションは、推奨される 2 つのレイアウトテンプレートのいずれかを使って構成してください。アプリの種類に応じて選択します。

アプリの種類	レイアウト	コンテナクラス
公開向け、汎用	Simple App	.sgds-container
内部ツール、ダッシュボード、トランザクション処理	Sidebar App	.sgds-container-sidebar

Simple App（公開向け）：

<div>
  <sgds-masthead fluid></sgds-masthead>
  <sgds-mainnav fluid>
    <strong slot="brand">My App</strong>
  </sgds-mainnav>
</div>
<div class="sgds:flex sgds:flex-col sgds:w-full">
  <div class="sgds-container sgds:py-2-xl">
    
  </div>
  <sgds-footer></sgds-footer>
</div>

Sidebar App（ダッシュボード／内部ツール）：

<div class="sgds:sticky sgds:top-0">
  <sgds-masthead fluid></sgds-masthead>
  <sgds-mainnav fluid>
    <strong slot="brand">My App</strong>
  </sgds-mainnav>
</div>
<div class="sgds:flex sgds:flex-row">
  <div class="sgds:sticky sgds:h-[calc(100vh-108px)] sgds:overflow-y-scroll sgds:top-27 sgds:w-68 sgds:border-r sgds:border-muted">
    
  </div>
  <div class="sgds:flex sgds:flex-col sgds:w-full">
    <div class="sgds-container-sidebar sgds:py-2-xl">
      
    </div>
    <sgds-footer></sgds-footer>
  </div>
</div>

レイアウトの詳細と、レスポンシブ対応のコンテナのブレークポイントについては、Application Shell をご覧ください。

---

AI エージェント向け

コンポーネント優先のルール：プレーンな HTML とユーティリティクラスで UI 要素を構築する前に、必要な機能を備えた SGDS ウェブコンポーネントがすでに存在するか、必ず確認してください。まず components-* スキルを参照してください。そのユースケースに適した SGDS コンポーネントがない場合に限り、カスタムマークアップを使用してください。

1. 新しい SGDS プロジェクトでコンポーネントやページのコードを生成する前に、必ず 4 つの手順をすべて完了してください。
2. フォントの <link> タグは CSS や JS のインポートではなく、HTML の <head> に記述してください。フォントのカスタマイズやテーマ設定については、sgds-theming を参照してください。
3. CSS のインポート順は重要です：themes/day.css → css/sgds.css → css/utility.css。基盤スタイルとユーティリティスタイルの処理時に CSS 変数トークンを利用できるよう、テーマファイルを最初に読み込む必要があります。
4. css/utility.css は Tailwind v4 で処理される CSS ファイル内にインポートする必要があります。JavaScript から直接インポートしても、sgds: ユーティリティクラスは生成されません。
5. 単一の JS インポート import "@govtechsg/sgds-web-component" で、すべてのコンポーネントが登録されます。ツリーシェイキングを明示的に行う場合を除き、個別のコンポーネントをインポートしないでください。
6. ページのコンテンツは必ず .sgds-container（Simple App）または .sgds-container-sidebar（Sidebar App）で囲んでください。コンテナの動作を再現するために、生の sgds:max-w-* ユーティリティを使用しないでください。
7. アプリの種類に迷った場合：公開向けのデジタルサービスには Simple App、内部ツール、ダッシュボード、管理ポータルには Sidebar App を使用してください。