sgds-utilities

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SGDS Utilities

SGDS 工具类

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.

工具类API——一套基于Tailwind v4的原子类，作用域限定在

sgds:

前缀下。开发者可以使用该语法直接在标记中应用SGDS设计规范，无需编写自定义CSS。

Core Concept: sgds: Prefix

核心概念：sgds: 前缀

All SGDS utility classes use the

sgds:

prefix (Tailwind v4 @theme syntax):

html

<!-- ✅ 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>

所有SGDS工具类均使用

sgds:

前缀（Tailwind v4 @theme语法）：

html

<!-- ✅ 正确写法 -->
<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>

Required Setup

必备安装配置

Import Utility CSS

导入工具类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):

css

/* 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.

utility.css

是一个Tailwind源文件——它包含Tailwind v4指令（

@theme

、

@import "tailwindcss/theme.css"

），必须通过Tailwind的构建流程处理。无法直接在JavaScript中导入。

在项目的主CSS文件（Tailwind处理的那个文件）中导入它：

css

/* 例如 globals.css、index.css、main.css */
@import "@govtechsg/sgds-web-component/css/utility.css";

Tailwind会在构建时解析并处理嵌套导入，生成所有

sgds:

工具类。

如果不进行此导入，工具类将无法生效。

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:

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";

对于可适配明暗模式的主题感知工具类（背景色、文字颜色、边框颜色），请在项目的CSS文件中导入主题文件：

css

/* 例如 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.

使用以下工具类时需导入主题文件：

背景色：

sgds:bg-surface-default

、

sgds:bg-primary-default

等

文字颜色：

sgds:text-default

、

sgds:text-primary-default

等

边框颜色：

sgds:border-default

、

sgds:border-primary-default

等

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
```

以下工具类不需要主题文件：

间距：
```
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
```

Theme Switching

主题切换

To toggle between light and dark themes programmatically:

html

<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.

如需通过代码切换明暗主题：

html

<button id="theme-toggle">切换主题</button>

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

带有主题感知标记的类会在主题切换时自动更新样式。

Verification

验证配置

Test that setup is complete:

html

<!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"
        onclick="document.documentElement.classList.toggle('sgds-theme-night')"
      >
        Toggle Theme
      </button>
    </div>
  </body>
</html>

测试配置是否完成：

html

<!DOCTYPE html>
<html>
  <head>
    <!-- 由你的Tailwind构建流程处理 -->
  </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">配置测试</h1>
      <p class="sgds:text-body-default sgds:mb-4">如果这段文字样式显示正确，说明你的配置已完成。</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')"
      >
        切换主题
      </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:

Framework	Guide
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

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

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";

由于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 (通用)	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

语句：

css

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

/* 可选：主题感知颜色标记 */
@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
Patterns	Cross-category component patterns (card, alert, form, modal)	—	→ reference/overview-patterns.md

分类	工具类	是否需要主题文件	参考文档链接
布局	网格系统（ `.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
颜色	颜色标记后缀语义（default、emphasis、muted、fixed等）	—	→ 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
组件模式	跨分类组件模式（卡片、提示框、表单、模态框）	—	→ 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

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
```
.

页面布局、列、响应式网格 → 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

针对AI Agent的提示:

在推荐工具类前，务必确认用户已完成安装配置（导入工具类CSS）。
主题文件（
```
day.css
```
、
```
night.css
```
）仅用于颜色工具类（背景色、文字颜色、边框颜色）——不适用于间距、排版、边框圆角或透明度工具类。
当用户询问特定工具类分类时，先阅读对应的参考文档再生成回复。

网格系统（

.sgds-container

.sgds-grid

.sgds-col-*

）始终优先于通用Tailwind

sgds:grid-cols-*

——详见

reference/grid.md

。

优先使用语义化间距工具类（
```
sgds:gap-layout-*
```
,
```
sgds:p-component-*
```
）而非纯数值工具类（
```
sgds:p-4
```
,
```
sgds:gap-6
```
）——它们具备响应式特性且能体现设计意图。
优先使用语义化字体大小工具类（
```
sgds:text-display-*
```
,
```
sgds:text-heading-*
```
,
```
sgds:text-body-*
```
）而非纯比例工具类——它们具备响应式特性。
颜色后缀修饰符（
```
default
```
、
```
emphasis
```
、
```
muted
```
、
```
surface
```
、
```
fixed-light
```
、
```
fixed-dark
```
、
```
inverse
```
）适用于所有颜色工具类——详见
```
reference/color-semantics.md
```
。
切勿使用内联
style
属性。如果需要布局或视觉属性，请查找对应的
```
sgds:
```
工具类。如果没有完全匹配的工具类，优先选择最接近的语义化工具类。仅在万不得已时才使用CSS自定义属性覆盖，且绝不能通过
```
style
```
属性实现。
切勿使用原生
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
```
。