SGDS Utilities
The Utilities API — a set of atomic classes powered by Tailwind v4, scoped under the sgds: prefix. Developers apply SGDS design decisions directly in markup using this syntax rather than writing custom CSS.
Core Concept: sgds: Prefix
All SGDS utility classes use the sgds: prefix (Tailwind v4 @theme syntax):
<!-- ✅ Correct -->
<div class="sgds:p-4 sgds:bg-primary-default sgds:text-white">Content</div>
<!-- ❌ Wrong - missing prefix -->
<div class="p-4 bg-primary-default text-white">Content</div>
Required Setup
Import Utility CSS
utility.css is a Tailwind source file — it contains Tailwind v4 directives (@theme, @import "tailwindcss/theme.css") that must be processed by Tailwind's build pipeline. It cannot be imported directly in JavaScript.
Import it inside your project's main CSS file (the one Tailwind processes):
/* e.g. globals.css, index.css, main.css */
@import "@govtechsg/sgds-web-component/css/utility.css";
Tailwind will resolve and process the nested imports at build time, generating all sgds: utility classes.
Without this import, utility classes will not work.
Optional: Theme Setup
For theme-aware utilities that adapt to light/dark mode (background colors, text colors, border colors), import the theme files in your project's CSS file:
/* e.g. globals.css, index.css, main.css */
@import "@govtechsg/sgds-web-component/themes/day.css";
@import "@govtechsg/sgds-web-component/themes/night.css";
When Theme Setup is Required
Import theme files when using:
- Background colors:
sgds:bg-surface-default, sgds:bg-primary-default, etc.
- Text colors:
sgds:text-default, sgds:text-primary-default, etc.
- Border colors:
sgds:border-default, sgds:border-primary-default, etc.
When Theme Setup is Optional
Theme files are NOT required for:
- Spacing:
sgds:p-4, sgds:m-2, sgds:gap-6
- Typography sizing:
sgds:text-xl, sgds:font-bold
- Border radius:
sgds:rounded-lg
- Opacity:
sgds:opacity-50
- Layout:
sgds:flex, sgds:grid
Theme Switching
To toggle between light and dark themes programmatically:
<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>
Classes with theme-aware tokens automatically update when the theme changes.
Verification
Test that setup is complete:
<!DOCTYPE html>
<html>
<head>
<!-- processed by your Tailwind build -->
</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"
>
Toggle Theme
</button>
</div>
</body>
</html>
Framework-Specific Setup
Since SGDS utilities are built on Tailwind v4, you must first set up Tailwind CSS for your framework before importing the SGDS CSS files.
Step 1: Follow the Tailwind CSS guide for your framework:
Not listed? See the full list at https://tailwindcss.com/docs/installation/framework-guides.
Step 2: After Tailwind is set up, add the SGDS @import to the same CSS file that Tailwind processes (usually globals.css, main.css, or index.css):
@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";
Available Utilities
| Category |
Utility |
Theme files required |
Reference |
| Layout |
Grid system (.sgds-container, .sgds-grid, .sgds-col-*) |
No |
→ reference/grid.md |
| Layout |
Container dimensions (sgds:w-container, sgds:max-w-container-*) |
No |
→ reference/dimension.md |
| Spacing |
Margin, padding, gap (sgds:p-*, sgds:m-*, sgds:gap-*, semantic tokens) |
No |
→ reference/spacing.md |
| Color |
Color token suffix semantics (default, emphasis, muted, fixed, etc.) |
— |
→ reference/color-semantics.md |
| Color |
Background colors (sgds:bg-*) |
Yes |
→ reference/background-color.md |
| Color |
Text colors (sgds:text-*) |
Yes |
→ reference/text-color.md |
| Color |
Border colors (sgds:border-* color) |
Yes |
→ reference/border-color.md |
| Border |
Border width and sides (sgds:border, sgds:border-2, sgds:border-l-4, etc.) |
No |
→ reference/border-width.md |
| Border |
Border radius (sgds:rounded-*, sgds:rounded-form-*) |
No |
→ reference/border-radius.md |
| Typography |
Font size, weight, line height, letter spacing, font family |
No |
→ reference/typography.md |
| Visual |
Opacity (sgds:opacity-*) |
No |
→ reference/opacity.md |
| Visual |
Elevation / box shadows (sgds:shadow-*, sgds:shadow-edge-*) |
No |
→ reference/elevation.md |
| Responsive |
Breakpoint prefixes (sgds:xs:, sgds:sm:, sgds:md:, sgds:lg:, sgds:xl:, sgds:2-xl:) |
No |
→ reference/breakpoint.md |
| Patterns |
Cross-category component patterns (card, alert, form, modal) |
— |
→ reference/overview-patterns.md |
Quick Reference by Use Case
Page layout, columns, responsive grid → reference/grid.md
Container width, max-width → reference/dimension.md
Spacing between sections, components, text → reference/spacing.md
Color token suffixes (default, emphasis, muted, etc.) → reference/color-semantics.md
Card backgrounds, surface colors → reference/background-color.md
Text content colors → reference/text-color.md
Borders and rounded corners → reference/border-color.md, reference/border-width.md, reference/border-radius.md
Headings, body text, font sizes → reference/typography.md
Transparent overlays, disabled states → reference/opacity.md
Card shadows, modal depth, sticky header/footer edges → reference/elevation.md
Responsive breakpoints, show/hide at viewport sizes → reference/breakpoint.md
For AI Agents:
- Always verify users have completed setup (utility CSS import) before suggesting utility classes.
- Theme files (
day.css, night.css) are only needed for color utilities (background, text, border colors) — not for spacing, typography, border radius, or opacity.
- When users ask about a specific utility category, read the corresponding reference file before generating output.
- The grid system (
.sgds-container, .sgds-grid, .sgds-col-*) is always preferred over generic Tailwind sgds:grid-cols-* — see reference/grid.md.
- Prefer semantic spacing utilities (
sgds:gap-layout-*, sgds:p-component-*) over raw numeric utilities (sgds:p-4, sgds:gap-6) — they are responsive and encode design intent.
- Prefer semantic font-size utilities (
sgds:text-display-*, sgds:text-heading-*, sgds:text-body-*) over raw scale utilities — they are responsive.
- Color suffix modifiers (
default, emphasis, muted, surface, fixed-light, fixed-dark, inverse) are shared across all color utilities — see reference/color-semantics.md.
- Never use inline
style attributes. If a layout or visual property is needed, find the equivalent sgds: utility class. If no utility class exists for the exact value, prefer the closest semantic utility. Only resort to a CSS custom property override as a last option, and never via a style attribute.
- Never use raw
sgds:max-w-* utilities for container sizing. Raw classes like sgds:max-w-2xl, sgds:max-w-lg, sgds:max-w-sm map to small Tailwind numeric values and are not part of the SGDS design system. Use sgds:max-w-container-* (md/lg/xl/2-xl/3-xl) for inner containers, or sgds:w-container for the top-level page wrapper. See reference/dimension.md.
1---2name: sgds-utilities3description: Complete reference for all SGDS utility classes with the sgds: prefix. Use when users ask about setup, background-color, text-color, border-color, border-width, border-radius, typography, spacing, grid, dimension, opacity, color-semantics, or any sgds: Tailwind utility class. Also covers Tailwind v4 imports, theme switching, and framework integration for utilities.4---56# SGDS Utilities78The **Utilities API** — a set of atomic classes powered by Tailwind v4, scoped under the `sgds:` prefix. Developers apply SGDS design decisions directly in markup using this syntax rather than writing custom CSS.910## Core Concept: sgds: Prefix1112All SGDS utility classes use the `sgds:` prefix (Tailwind v4 @theme syntax):1314```html15<!-- ✅ Correct -->16<div class="sgds:p-4 sgds:bg-primary-default sgds:text-white">Content</div>1718<!-- ❌ Wrong - missing prefix -->19<div class="p-4 bg-primary-default text-white">Content</div>20```2122## Required Setup2324### Import Utility CSS2526`utility.css` is a **Tailwind source file** — it contains Tailwind v4 directives (`@theme`, `@import "tailwindcss/theme.css"`) that must be processed by Tailwind's build pipeline. It cannot be imported directly in JavaScript.2728**Import it inside your project's main CSS file** (the one Tailwind processes):2930```css31/* e.g. globals.css, index.css, main.css */32@import "@govtechsg/sgds-web-component/css/utility.css";33```3435Tailwind will resolve and process the nested imports at build time, generating all `sgds:` utility classes.3637**Without this import, utility classes will not work.**3839## Optional: Theme Setup4041For theme-aware utilities that adapt to light/dark mode (background colors, text colors, border colors), import the theme files in your project's CSS file:4243```css44/* e.g. globals.css, index.css, main.css */45@import "@govtechsg/sgds-web-component/themes/day.css";46@import "@govtechsg/sgds-web-component/themes/night.css";47```4849### When Theme Setup is Required5051Import theme files when using:5253- **Background colors**: `sgds:bg-surface-default`, `sgds:bg-primary-default`, etc.54- **Text colors**: `sgds:text-default`, `sgds:text-primary-default`, etc.55- **Border colors**: `sgds:border-default`, `sgds:border-primary-default`, etc.5657### When Theme Setup is Optional5859Theme files are NOT required for:6061- **Spacing**: `sgds:p-4`, `sgds:m-2`, `sgds:gap-6`62- **Typography sizing**: `sgds:text-xl`, `sgds:font-bold`63- **Border radius**: `sgds:rounded-lg`64- **Opacity**: `sgds:opacity-50`65- **Layout**: `sgds:flex`, `sgds:grid`6667## Theme Switching6869To toggle between light and dark themes programmatically:7071```html72<button id="theme-toggle">Toggle Theme</button>7374<script>75 const toggleButton = document.getElementById("theme-toggle");76 toggleButton.addEventListener("click", () => {77 document.documentElement.classList.toggle("sgds-theme-night");78 });79</script>80```8182Classes with theme-aware tokens automatically update when the theme changes.8384## Verification8586Test that setup is complete:8788```html89<!DOCTYPE html>90<html>91 <head>92 <!-- processed by your Tailwind build -->93 </head>94 <body class="sgds:bg-default sgds:p-6">95 <div class="sgds:bg-surface-raised sgds:p-4 sgds:rounded-lg">96 <h1 class="sgds:text-heading-default sgds:text-2-xl sgds:font-bold sgds:mb-4">Setup Test</h1>97 <p class="sgds:text-body-default sgds:mb-4">If this text is styled correctly, your setup is complete.</p>98 <button99 class="sgds:bg-primary-default sgds:text-white sgds:px-4 sgds:py-2 sgds:rounded"100 onclick="document.documentElement.classList.toggle('sgds-theme-night')"101 >102 Toggle Theme103 </button>104 </div>105 </body>106</html>107```108109## Framework-Specific Setup110111Since SGDS utilities are built on Tailwind v4, you must first set up Tailwind CSS for your framework before importing the SGDS CSS files.112113**Step 1**: Follow the Tailwind CSS guide for your framework:114115| Framework | Guide |116| -------------- | ----------------------------------------------------------------------- |117| Next.js | https://tailwindcss.com/docs/installation/framework-guides/nextjs |118| Nuxt (Vue) | https://tailwindcss.com/docs/installation/framework-guides/nuxt |119| Angular | https://tailwindcss.com/docs/installation/framework-guides/angular |120| SvelteKit | https://tailwindcss.com/docs/installation/framework-guides/sveltekit |121| Astro | https://tailwindcss.com/docs/installation/framework-guides/astro |122| Gatsby | https://tailwindcss.com/docs/installation/framework-guides/gatsby |123| React Router | https://tailwindcss.com/docs/installation/framework-guides/react-router |124| Vite (generic) | https://tailwindcss.com/docs/installation/using-vite |125126Not listed? See the full list at https://tailwindcss.com/docs/installation/framework-guides.127128**Step 2**: After Tailwind is set up, add the SGDS `@import` to the same CSS file that Tailwind processes (usually `globals.css`, `main.css`, or `index.css`):129130```css131@import "@govtechsg/sgds-web-component/css/utility.css";132133/* Optional: theme-aware color tokens */134@import "@govtechsg/sgds-web-component/themes/day.css";135@import "@govtechsg/sgds-web-component/themes/night.css";136```137138---139140## Available Utilities141142| Category | Utility | Theme files required | Reference |143| -------------- | -------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------ |144| **Layout** | Grid system (`.sgds-container`, `.sgds-grid`, `.sgds-col-*`) | No | [→ reference/grid.md](reference/grid.md) |145| **Layout** | Container dimensions (`sgds:w-container`, `sgds:max-w-container-*`) | No | [→ reference/dimension.md](reference/dimension.md) |146| **Spacing** | Margin, padding, gap (`sgds:p-*`, `sgds:m-*`, `sgds:gap-*`, semantic tokens) | No | [→ reference/spacing.md](reference/spacing.md) |147| **Color** | Color token suffix semantics (default, emphasis, muted, fixed, etc.) | — | [→ reference/color-semantics.md](reference/color-semantics.md) |148| **Color** | Background colors (`sgds:bg-*`) | Yes | [→ reference/background-color.md](reference/background-color.md) |149| **Color** | Text colors (`sgds:text-*`) | Yes | [→ reference/text-color.md](reference/text-color.md) |150| **Color** | Border colors (`sgds:border-*` color) | Yes | [→ reference/border-color.md](reference/border-color.md) |151| **Border** | Border width and sides (`sgds:border`, `sgds:border-2`, `sgds:border-l-4`, etc.) | No | [→ reference/border-width.md](reference/border-width.md) |152| **Border** | Border radius (`sgds:rounded-*`, `sgds:rounded-form-*`) | No | [→ reference/border-radius.md](reference/border-radius.md) |153| **Typography** | Font size, weight, line height, letter spacing, font family | No | [→ reference/typography.md](reference/typography.md) |154| **Visual** | Opacity (`sgds:opacity-*`) | No | [→ reference/opacity.md](reference/opacity.md) |155| **Visual** | Elevation / box shadows (`sgds:shadow-*`, `sgds:shadow-edge-*`) | No | [→ reference/elevation.md](reference/elevation.md) |156| **Responsive** | Breakpoint prefixes (`sgds:xs:`, `sgds:sm:`, `sgds:md:`, `sgds:lg:`, `sgds:xl:`, `sgds:2-xl:`) | No | [→ reference/breakpoint.md](reference/breakpoint.md) |157| **Patterns** | Cross-category component patterns (card, alert, form, modal) | — | [→ reference/overview-patterns.md](reference/overview-patterns.md) |158159---160161## Quick Reference by Use Case162163**Page layout, columns, responsive grid** → [reference/grid.md](reference/grid.md)164**Container width, max-width** → [reference/dimension.md](reference/dimension.md)165**Spacing between sections, components, text** → [reference/spacing.md](reference/spacing.md)166**Color token suffixes (default, emphasis, muted, etc.)** → [reference/color-semantics.md](reference/color-semantics.md)167**Card backgrounds, surface colors** → [reference/background-color.md](reference/background-color.md)168**Text content colors** → [reference/text-color.md](reference/text-color.md)169**Borders and rounded corners** → [reference/border-color.md](reference/border-color.md), [reference/border-width.md](reference/border-width.md), [reference/border-radius.md](reference/border-radius.md)170**Headings, body text, font sizes** → [reference/typography.md](reference/typography.md)171**Transparent overlays, disabled states** → [reference/opacity.md](reference/opacity.md)172**Card shadows, modal depth, sticky header/footer edges** → [reference/elevation.md](reference/elevation.md)173**Responsive breakpoints, show/hide at viewport sizes** → [reference/breakpoint.md](reference/breakpoint.md)174175---176177**For AI Agents**:1781791. Always verify users have completed setup (utility CSS import) before suggesting utility classes.1802. Theme files (`day.css`, `night.css`) are only needed for color utilities (background, text, border colors) — not for spacing, typography, border radius, or opacity.1813. When users ask about a specific utility category, read the corresponding reference file before generating output.1824. The grid system (`.sgds-container`, `.sgds-grid`, `.sgds-col-*`) is always preferred over generic Tailwind `sgds:grid-cols-*` — see `reference/grid.md`.1835. Prefer semantic spacing utilities (`sgds:gap-layout-*`, `sgds:p-component-*`) over raw numeric utilities (`sgds:p-4`, `sgds:gap-6`) — they are responsive and encode design intent.1846. Prefer semantic font-size utilities (`sgds:text-display-*`, `sgds:text-heading-*`, `sgds:text-body-*`) over raw scale utilities — they are responsive.1857. Color suffix modifiers (`default`, `emphasis`, `muted`, `surface`, `fixed-light`, `fixed-dark`, `inverse`) are shared across all color utilities — see `reference/color-semantics.md`.1868. **Never use inline `style` attributes.** If a layout or visual property is needed, find the equivalent `sgds:` utility class. If no utility class exists for the exact value, prefer the closest semantic utility. Only resort to a CSS custom property override as a last option, and never via a `style` attribute.1879. **Never use raw `sgds:max-w-*` utilities for container sizing.** Raw classes like `sgds:max-w-2xl`, `sgds:max-w-lg`, `sgds:max-w-sm` map to small Tailwind numeric values and are not part of the SGDS design system. Use `sgds:max-w-container-*` (md/lg/xl/2-xl/3-xl) for inner containers, or `sgds:w-container` for the top-level page wrapper. See `reference/dimension.md`.
govtechsg