sgds-theming

SGDS テーマ設定スキル

SGDS CSS トークンのオーバーライドを使って、製品テーマ（ブランドカラー、昼／夜モード、フォント、角丸、スペーシングの密度）をカスタマイズする方法です。

---

前提条件

カスタム CSS より前に themes/day.css をインポートしてください。インポート順の詳細については、sgds-getting-started を参照してください。

---

選択ガイド

変更したい内容	トークン／方法	リファレンス
製品ブランドカラー（カスタム）	--sgds-product-primary-{100–900} をオーバーライド	brand-colour.md
製品ブランドカラー（GovTech）	themes/gt/<colour>.css のいずれか1つをインポートし、--sgds-product-primary-* にマッピング	brand-colour.md
ダーク／夜間モードを有効化	themes/night.css をインポートし、.sgds-night-theme を <html> に追加	以下を参照
フォント書体（すべての役割）	--sgds-font-family-brand をオーバーライド	typography.md
フォント書体（役割ごと）	個別の --sgds-font-family-{display,heading,subtitle,body,label,code} をオーバーライド	typography.md
角丸	セマンティックな --sgds-{purpose}-border-radius トークンをオーバーライド	border-radius.md
スペーシングの密度（コンパクト／ゆったり）	themes/density/compact.css または spacious.css をインポート	density.md

---

製品ブランドカラーの変更

デフォルトの製品カラーは紫（--sgds-product-primary-*）です。ブランドカラーを使って100～900のスケール全体をオーバーライドすると、すべての主要なUI要素のテーマを一度に変更できます。

カスタム CSS ファイルを作成し、:root のプリミティブトークンをオーバーライドします。

/* yourCustomCss.css */
:root {
  --sgds-product-primary-100: #F5B6DA;
  --sgds-product-primary-200: #F186C0;
  --sgds-product-primary-300: #EE4FA6;
  --sgds-product-primary-400: #EE0290;
  --sgds-product-primary-500: #EF0078;
  --sgds-product-primary-600: #DD0074;
  --sgds-product-primary-700: #C6006E;
  --sgds-product-primary-800: #B0006A;
  --sgds-product-primary-900: #880061;
}

オーバーライドを適用するには、SGDS テーマファイルの後にカスタム CSS をインポートします。

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

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

セマンティックトークン（--sgds-primary-*）はプリミティブスケールを参照するため、プリミティブ値を変更すると、主要なカラーを使用するすべてのコンポーネントに自動的に反映されます。

---

GovTech ブランドカラー

GovTech 製品では、カスタムの16進数値を定義するのではなく、themes/gt/ にある事前承認済みのカラーパレットを使用してください。各製品で選択できるカラーは必ず1色だけです。複数の GT パレットを混在させることはできません。

利用可能なカラー

ファイル	カラー
themes/gt/blue.css	青
themes/gt/cyan.css	シアン
themes/gt/magenta.css	マゼンタ
themes/gt/pink.css	ピンク
themes/gt/purple.css	紫
themes/gt/red.css	赤

適用方法

各 GT ファイルは、:root で --gt-color-100 から --gt-color-900 を定義します。カスタム CSS ファイルで、これらを SGDS の製品プライマリスケールにマッピングします。

/* yourCustomCss.css */
:root {
  --sgds-product-primary-100: var(--gt-color-100);
  --sgds-product-primary-200: var(--gt-color-200);
  --sgds-product-primary-300: var(--gt-color-300);
  --sgds-product-primary-400: var(--gt-color-400);
  --sgds-product-primary-500: var(--gt-color-500);
  --sgds-product-primary-600: var(--gt-color-600);
  --sgds-product-primary-700: var(--gt-color-700);
  --sgds-product-primary-800: var(--gt-color-800);
  --sgds-product-primary-900: var(--gt-color-900);
}

インポート順 — マッピングの実行時に --gt-color-* 変数が定義されているよう、GT ファイルをカスタム CSS より前に読み込む必要があります。

import "@govtechsg/sgds-web-component/themes/day.css";
import "@govtechsg/sgds-web-component/themes/gt/blue.css"; // pick one colour only
import "./yourCustomCss.css";

@import "@govtechsg/sgds-web-component/themes/day.css";
@import "@govtechsg/sgds-web-component/themes/gt/blue.css"; /* pick one colour only */
@import "./yourCustomCss.css";

同様に、--sgds-product-primary-* を変更すると、主要なカラーを使用するすべてのコンポーネントに自動的に反映されます。

---

昼間モード（デフォルト）

昼間モードがデフォルトです。themes/day.css をインポートするだけでよく、追加の設定は必要ありません。

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

---

夜間モード（任意）

夜間モードはオプトイン方式です。<html> 要素にクラス sgds-night-theme を追加すると有効になり、themes/night.css で定義されている :root.sgds-night-theme セレクターが適用されます。

セットアップ

両方のテーマファイルをインポートします。

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

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

夜間モードを有効にする

<html> 要素にクラスを追加すると、すべてのトークンがダークモード用の値に切り替わります。

<html class="sgds-night-theme">

JavaScript を使って実行時に切り替えます。

document.documentElement.classList.toggle("sgds-night-theme");

仕組み

themes/night.css は、themes/day.css と同じセマンティックトークンを :root.sgds-night-theme のスコープで再定義します。すべての SGDS コンポーネントは同じセマンティックトークンを参照するため、クラスを切り替えるだけで、コンポーネントのマークアップを変更せずにUI全体を切り替えられます。

---

フォントの変更

SGDS ではデフォルトで --sgds-font-family-brand を通じて Inter を使用します。このトークンを上書きすると、別の書体を使用できます。

:root {
  --sgds-font-family-brand: "Your Font", system-ui, sans-serif;
}

フォントアセットの読み込みは、ご自身で行ってください。<link> タグまたは @font-face を使用できます。SGDS がカスタムフォントを自動的に読み込むことはありません。デフォルトのフォントを使用する場合は、最適化された Inter Google Fonts の URL について sgds-getting-started を参照してください。

---

角丸の変更

完全なリファレンス（セマンティックトークンの表、上書き例、使用可能なプリミティブ値）については、border-radius.md を参照してください。

---

余白の密度の変更

完全なリファレンス（密度モード、トークンの表、影響を受けるコンポーネント、インポート順序）については、density.md を参照してください。

---

AI エージェント向け

1. ユーザーには、カスタム CSS を必ず themes/day.css の後にインポートするよう伝えてください。そうしないと、上書きが適用されません。
2. ブランドカラーの上書きでは、セマンティックトークンではなくプリミティブトークン（--sgds-product-primary-{100–900}）を対象にします。プリミティブを変更するのが正しい方法です。個々のセマンティックトークンを直接上書きしないでください。
3. ナイトモードには、themes/night.css のインポートと <html> の sgds-night-theme クラスの両方が必要です。どちらか一方だけでは不十分です。
4. ナイトモードは任意です。ユーザーがダークモードのサポートを明示的に必要としている場合にのみ、themes/night.css を追加してください。
5. デイモードはデフォルトで常に有効です。追加する sgds-day-theme クラスはありません。
6. --sgds-font-family-brand を上書きする場合は、フォントファイルもユーザー自身で読み込む必要があることを伝えてください。
7. カスタムの上書きは :root を対象とするため、両方のテーマセレクターがそこから継承し、デイモードとナイトモードの両方に同時に適用されます。
8. ブランドカラーのテーマ設定については、brand-colour.md を読んでください。
9. タイポグラフィ／フォントのテーマ設定については、typography.md を読んでください。
10. 角丸のテーマ設定については、border-radius.md を読んでください。プリミティブ値を var(--sgds-border-radius-{size}) で参照しながら、セマンティックトークン（--sgds-{purpose}-border-radius）を上書きしてください。
11. 密度のテーマ設定については、density.md を読んでください。色のテーマの後に、密度ファイル（compact.css または spacious.css）を1 つインポートしてください。密度が変えるのはパディングとギャップのみです。フォントサイズ、色、角丸は変わりません。