sgds-utilities

SGDS ユーティリティ

ユーティリティ API — Tailwind v4 を基盤とするアトミッククラスのセットで、sgds: プレフィックスのスコープ内で使用します。開発者はカスタム CSS を記述する代わりに、この構文を使ってマークアップに SGDS のデザイン決定を直接適用できます。

基本概念：sgds: プレフィックス

すべての SGDS ユーティリティクラスは sgds: プレフィックスを使用します（Tailwind v4 の @theme 構文）。

<div class="sgds:p-4 sgds:bg-primary-default sgds:text-white">Content</div>


<div class="p-4 bg-primary-default text-white">Content</div>

必須のセットアップ

ユーティリティ CSS をインポートする

utility.css はTailwind のソースファイルです。Tailwind v4 のディレクティブ（@theme、@import "tailwindcss/theme.css"）が含まれており、Tailwind のビルドパイプラインで処理する必要があります。JavaScript から直接インポートすることはできません。

プロジェクトのメイン CSS ファイル（Tailwind が処理するファイル）にインポートしてください。

/* e.g. globals.css, index.css, main.css */
@import "@govtechsg/sgds-web-component/css/utility.css";

Tailwind はビルド時にネストされたインポートを解決して処理し、すべての sgds: ユーティリティクラスを生成します。

このインポートがないと、ユーティリティクラスは機能しません。

任意：テーマのセットアップ

ライトモード／ダークモードに応じて変化するテーマ対応ユーティリティ（背景色、テキスト色、ボーダー色）を使用する場合は、プロジェクトの CSS ファイルにテーマファイルをインポートしてください。

/* e.g. globals.css, index.css, main.css */
@import "@govtechsg/sgds-web-component/themes/day.css";
@import "@govtechsg/sgds-web-component/themes/night.css";

テーマのセットアップが必要な場合

次を使用する場合は、テーマファイルをインポートしてください。

• 背景色：sgds:bg-surface-default、sgds:bg-primary-default など
• テキスト色：sgds:text-default、sgds:text-primary-default など
• ボーダー色：sgds:border-default、sgds:border-primary-default など

テーマのセットアップが任意の場合

次の場合、テーマファイルは不要です。

• スペーシング：sgds:p-4、sgds:m-2、sgds:gap-6
• タイポグラフィのサイズ：sgds:text-xl、sgds:font-bold
• ボーダーの角丸：sgds:rounded-lg
• 不透明度：sgds:opacity-50
• レイアウト：sgds:flex、sgds:grid

テーマの切り替え

ライトテーマとダークテーマをプログラムから切り替えるには、次のようにします。

<button id="theme-toggle">Toggle Theme</button>

<script>
  const toggleButton = document.getElementById("theme-toggle");
  toggleButton.addEventListener("click", () => {
    document.documentElement.classList.toggle("sgds-theme-night");
  });
</script>

テーマ対応トークンを含むクラスは、テーマが変更されると自動的に更新されます。

確認

セットアップが完了していることを確認します。

<!DOCTYPE html>
<html>
  <head>
    
  </head>
  <body class="sgds:bg-default sgds:p-6">
    <div class="sgds:bg-surface-raised sgds:p-4 sgds:rounded-lg">
      <h1 class="sgds:text-heading-default sgds:text-2-xl sgds:font-bold sgds:mb-4">Setup Test</h1>
      <p class="sgds:text-body-default sgds:mb-4">If this text is styled correctly, your setup is complete.</p>
      <button
        class="sgds:bg-primary-default sgds:text-white sgds:px-4 sgds:py-2 sgds:rounded"
        onclick="document.documentElement.classList.toggle('sgds-theme-night')"
      >
        Toggle Theme
      </button>
    </div>
  </body>
</html>

フレームワーク別のセットアップ

SGDS ユーティリティは Tailwind v4 を基盤としているため、SGDS の CSS ファイルをインポートする前に、使用するフレームワーク向けに Tailwind CSS をセットアップする必要があります。

ステップ 1：使用するフレームワークの Tailwind CSS ガイドに従ってください。

フレームワーク	ガイド
Next.js	https://tailwindcss.com/docs/installation/framework-guides/nextjs
Nuxt (Vue)	https://tailwindcss.com/docs/installation/framework-guides/nuxt
Angular	https://tailwindcss.com/docs/installation/framework-guides/angular
SvelteKit	https://tailwindcss.com/docs/installation/framework-guides/sveltekit
Astro	https://tailwindcss.com/docs/installation/framework-guides/astro
Gatsby	https://tailwindcss.com/docs/installation/framework-guides/gatsby
React Router	https://tailwindcss.com/docs/installation/framework-guides/react-router
Vite (generic)	https://tailwindcss.com/docs/installation/using-vite

記載されていない場合は、一覧全体を https://tailwindcss.com/docs/installation/framework-guides で確認してください。

ステップ 2：Tailwind のセットアップ後、Tailwind が処理する CSS ファイル（通常は globals.css、main.css、または index.css）に SGDS の @import を追加します。

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

/* Optional: theme-aware color tokens */
@import "@govtechsg/sgds-web-component/themes/day.css";
@import "@govtechsg/sgds-web-component/themes/night.css";

---

利用可能なユーティリティ

カテゴリー	ユーティリティ	テーマファイルが必要	リファレンス
レイアウト	グリッドシステム（.sgds-container、.sgds-grid、.sgds-col-*）	いいえ	→ reference/grid.md
レイアウト	コンテナーのサイズ（sgds:w-container、sgds:max-w-container-*）	いいえ	→ reference/dimension.md
スペーシング	マージン、パディング、ギャップ（sgds:p-*、sgds:m-*、sgds:gap-*、セマンティックトークン）	いいえ	→ reference/spacing.md
カラー	カラートークンのサフィックスの意味（デフォルト、強調、控えめ、固定など）	—	→ reference/color-semantics.md
カラー	背景色（sgds:bg-*）	はい	→ reference/background-color.md
カラー	テキストの色（sgds:text-*）	はい	→ reference/text-color.md
カラー	ボーダーの色（sgds:border-* の色）	はい	→ reference/border-color.md
ボーダー	ボーダーの幅と辺（sgds:border、sgds:border-2、sgds:border-l-4 など）	いいえ	→ reference/border-width.md
ボーダー	ボーダーの角丸（sgds:rounded-*、sgds:rounded-form-*）	いいえ	→ reference/border-radius.md
タイポグラフィ	フォントサイズ、太さ、行の高さ、文字間隔、フォントファミリー	いいえ	→ reference/typography.md
ビジュアル	不透明度（sgds:opacity-*）	いいえ	→ reference/opacity.md
ビジュアル	エレベーション／ボックスシャドウ（sgds:shadow-*、sgds:shadow-edge-*）	いいえ	→ reference/elevation.md
レスポンシブ	ブレークポイントのプレフィックス（sgds:xs:、sgds:sm:、sgds:md:、sgds:lg:、sgds:xl:、sgds:2-xl:）	いいえ	→ reference/breakpoint.md
パターン	複数のカテゴリーにまたがるコンポーネントパターン（カード、アラート、フォーム、モーダル）	—	→ reference/overview-patterns.md

---

ユースケース別クイックリファレンス

ページレイアウト、列、レスポンシブグリッド → reference/grid.md コンテナ幅、最大幅 → reference/dimension.md セクション、コンポーネント、テキスト間のスペーシング → reference/spacing.md カラー トークンのサフィックス（default、emphasis、muted など） → reference/color-semantics.md カードの背景、サーフェスカラー → reference/background-color.md テキストコンテンツのカラー → reference/text-color.md ボーダーと角丸 → reference/border-color.md、reference/border-width.md、reference/border-radius.md 見出し、本文、フォントサイズ → reference/typography.md 透明なオーバーレイ、無効状態 → reference/opacity.md カードのシャドウ、モーダルの奥行き、固定ヘッダー／フッターの端 → reference/elevation.md レスポンシブブレークポイント、ビューポートサイズに応じた表示／非表示 → reference/breakpoint.md

---

AI エージェント向け：

1. ユーティリティクラスを提案する前に、ユーザーがセットアップ（ユーティリティ CSS のインポート）を完了していることを必ず確認してください。
2. テーマファイル（day.css、night.css）が必要なのはカラーのユーティリティ（背景色、テキストカラー、ボーダーカラー）のみです。スペーシング、タイポグラフィ、角丸、透明度には必要ありません。
3. ユーザーから特定のユーティリティカテゴリについて質問された場合は、出力を生成する前に、対応するリファレンスファイルを読んでください。
4. グリッドシステム（.sgds-container、.sgds-grid、.sgds-col-*）は、汎用の Tailwind sgds:grid-cols-* より常に優先してください。reference/grid.md を参照してください。
5. 数値指定のユーティリティ（sgds:p-4、sgds:gap-6）より、セマンティックなスペーシングユーティリティ（sgds:gap-layout-*、sgds:p-component-*）を優先してください。これらはレスポンシブで、デザインの意図を表します。
6. 数値スケールのユーティリティより、セマンティックなフォントサイズユーティリティ（sgds:text-display-*、sgds:text-heading-*、sgds:text-body-*）を優先してください。これらはレスポンシブです。
7. カラーのサフィックス修飾子（default、emphasis、muted、surface、fixed-light、fixed-dark、inverse）は、すべてのカラー関連ユーティリティで共通です。reference/color-semantics.md を参照してください。
8. インラインの style 属性は絶対に使用しないでください。 レイアウトや視覚的なプロパティが必要な場合は、対応する sgds: ユーティリティクラスを探してください。値に完全一致するユーティリティクラスがない場合は、最も近いセマンティックユーティリティを優先してください。CSS カスタムプロパティによる上書きは最後の手段としてのみ使用し、style 属性を介して指定しないでください。
9. コンテナのサイズ指定に、生の sgds:max-w-* ユーティリティを絶対に使用しないでください。 sgds:max-w-2xl、sgds:max-w-lg、sgds:max-w-sm などの生のクラスは、小さな Tailwind の数値に対応しており、SGDS デザインシステムには含まれていません。内部コンテナには sgds:max-w-container-*（md/lg/xl/2-xl/3-xl）を、ページ最上位のラッパーには sgds:w-container を使用してください。reference/dimension.md を参照してください。