sgds-utilities

SGDS Utilities

Utilities API — 一组由 Tailwind v4 提供支持的原子类，使用 sgds: 前缀进行作用域限定。开发者可使用此语法直接在标记中应用 SGDS 设计规范，而无需编写自定义 CSS。

核心概念：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 后，将 SGDS @import 添加到 Tailwind 处理的同一个 CSS 文件中（通常是 globals.css、main.css 或 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";

---

可用工具

类别	工具	是否需要主题文件	参考
布局	网格系统（.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 Agent：

1. 建议使用工具类之前，务必确认用户已完成设置（导入 utility CSS）。
2. 主题文件（day.css、night.css）仅用于颜色工具类（背景、文本、边框颜色），不用于间距、排版、边框圆角或不透明度。
3. 用户询问特定工具类类别时，生成输出前先阅读对应的参考文件。
4. 始终优先使用网格系统（.sgds-container、.sgds-grid、.sgds-col-*），而不是通用 Tailwind sgds:grid-cols-*；参见 reference/grid.md。
5. 优先使用语义化间距工具类（sgds:gap-layout-*、sgds:p-component-*），而不是原始数值工具类（sgds:p-4、sgds:gap-6）；前者具有响应式特性并体现设计意图。
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。