SGDS Utilities 是 SGDS 的原子类 API,由 Tailwind v4 驱动,全部类名带 sgds: 前缀,用于在标记中直接应用 SGDS 设计决策,而非编写自定义 CSS。
用途:提供布局、间距、颜色、边框、排版、透明度、阴影与响应式等工具类。
主要能力与分类:布局(网格系统 .sgds-container、.sgds-grid、.sgds-col-;容器宽度 sgds:w-container、sgds:max-w-container-)、间距(sgds:p-、sgds:m-、sgds:gap-)、颜色(sgds:bg-、sgds:text-、sgds:border-,及 default/emphasis/muted/fixed 等语义后缀)、边框(宽度、边、圆角)、排版(字号、字重、行高、字距、字体)、透明度、阴影(sgds:shadow-、sgds:shadow-edge-)、响应式断点(sgds:xs:、sgds:sm:、sgds:md:、sgds:lg:、sgds:xl:、sgds:2-xl:)。
使用方式:utility.css 是 Tailwind 源文件,含 @theme 等指令,必须由 Tailwind 构建管线处理,不能直接在 JavaScript 中导入。需先在框架中配置 Tailwind CSS,再在项目被处理的 CSS 文件(如 globals.css、main.css、index.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";。主题切换通过切换 document.documentElement 上的 sgds-theme-night 类实现。间距、排版、圆角、透明度、布局类不依赖主题文件。
适用场景:在支持 Tailwind v4 的框架(Next.js、Nuxt、Angular、SvelteKit、Astro、Gatsby、React Router、Vite 等)中构建符合 SGDS 的界面,按网格、容器尺寸、间距、颜色语义、排版、阴影、断点等用例查阅对应参考文件。
限制与约定:类名必须带 sgds: 前缀;未导入 utility.css 时工具类无效;颜色类需主题文件。建议优先使用语义化间距(如 sgds:gap-layout-、sgds:p-component-)与语义化字号(sgds:text-display-、sgds:text-heading-、sgds:text-body-);网格系统优先于通用 sgds:grid-cols-;容器尺寸用 sgds:max-w-container-* 或 sgds:w-container,不用原始 sgds:max-w-*;禁止使用内联 style 属性,无对应工具类时优先选最接近的语义类,仅在最后考虑 CSS 自定义属性覆盖且不得通过 style 属性。