sgds-theming

SGDS 主题技能

使用 SGDS CSS 令牌覆盖来自定义产品主题——品牌颜色、日间／夜间模式、字体、边框半径和间距密度。

---

前置条件

在自定义 CSS 之前导入 themes/day.css。完整的导入顺序请参阅 sgds-getting-started。

---

快速决策指南

想要更改的内容	令牌／机制	参考
产品品牌颜色（自定义）	覆盖 --sgds-product-primary-{100–900}	brand-colour.md
产品品牌颜色（GovTech）	导入一个 themes/gt/<colour>.css，并映射到 --sgds-product-primary-*	brand-colour.md
启用暗色／夜间模式	导入 themes/night.css，并将 .sgds-night-theme 添加到 <html>	见下文
字体字族（所有角色）	覆盖 --sgds-font-family-brand	typography.md
字体字族（按角色）	覆盖各个 --sgds-font-family-{display,heading,subtitle,body,label,code}	typography.md
边框半径	覆盖语义 --sgds-{purpose}-border-radius 令牌	border-radius.md
间距密度（紧凑／宽松）	导入 themes/density/compact.css 或 spacious.css	density.md

---

更改产品品牌颜色

默认产品颜色为紫色（--sgds-product-primary-*）。使用品牌颜色覆盖完整的 100–900 色阶，即可一次性为所有主要 UI 元素更换主题。

创建自定义 CSS 文件，并在 :root 中覆盖原始令牌：

/* yourCustomCss.css */
:root {
  --sgds-product-primary-100: #F5B6DA;
  --sgds-product-primary-200: #F186C0;
  --sgds-product-primary-300: #EE4FA6;
  --sgds-product-primary-400: #EE0290;
  --sgds-product-primary-500: #EF0078;
  --sgds-product-primary-600: #DD0074;
  --sgds-product-primary-700: #C6006E;
  --sgds-product-primary-800: #B0006A;
  --sgds-product-primary-900: #880061;
}

在 SGDS 主题文件之后导入自定义 CSS，使覆盖生效：

import "@govtechsg/sgds-web-component/themes/day.css";
import "./yourCustomCss.css";

@import "@govtechsg/sgds-web-component/themes/day.css";
@import "./yourCustomCss.css";

语义令牌（--sgds-primary-*）引用原始色阶，因此更改原始值会自动传递到所有使用主色的组件。

---

GovTech 品牌颜色

GovTech 产品应使用 themes/gt/ 中预先批准的调色板之一，而不是自行定义十六进制颜色值。每个产品必须恰好选择一种颜色，不允许混用多个 GT 调色板。

可用颜色

文件	颜色
themes/gt/blue.css	蓝色
themes/gt/cyan.css	青色
themes/gt/magenta.css	洋红色
themes/gt/pink.css	粉色
themes/gt/purple.css	紫色
themes/gt/red.css	红色

应用方法

每个 GT 文件都会在 :root 中定义 --gt-color-100 至 --gt-color-900。在自定义 CSS 文件中，将这些值映射到 SGDS 产品主色阶：

/* yourCustomCss.css */
:root {
  --sgds-product-primary-100: var(--gt-color-100);
  --sgds-product-primary-200: var(--gt-color-200);
  --sgds-product-primary-300: var(--gt-color-300);
  --sgds-product-primary-400: var(--gt-color-400);
  --sgds-product-primary-500: var(--gt-color-500);
  --sgds-product-primary-600: var(--gt-color-600);
  --sgds-product-primary-700: var(--gt-color-700);
  --sgds-product-primary-800: var(--gt-color-800);
  --sgds-product-primary-900: var(--gt-color-900);
}

导入顺序——GT 文件必须位于自定义 CSS 之前，这样执行映射时才能定义 --gt-color-* 变量：

import "@govtechsg/sgds-web-component/themes/day.css";
import "@govtechsg/sgds-web-component/themes/gt/blue.css"; // pick one colour only
import "./yourCustomCss.css";

@import "@govtechsg/sgds-web-component/themes/day.css";
@import "@govtechsg/sgds-web-component/themes/gt/blue.css"; /* pick one colour only */
@import "./yourCustomCss.css";

同样会自动传递：更改 --sgds-product-primary-* 会自动更新所有使用主色的组件。

---

日间模式（默认）

日间模式为默认模式。只需导入 themes/day.css，无需额外配置。

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

---

夜间模式（可选）

夜间模式需要主动启用。将 sgds-night-theme 类添加到 <html> 元素，即可激活 themes/night.css 中定义的 :root.sgds-night-theme 选择器。

设置

导入两个主题文件：

import "@govtechsg/sgds-web-component/themes/day.css";
import "@govtechsg/sgds-web-component/themes/night.css";

@import "@govtechsg/sgds-web-component/themes/day.css";
@import "@govtechsg/sgds-web-component/themes/night.css";

启用夜间模式

将该类添加到 <html> 元素，即可将所有令牌切换为对应的暗色版本：

<html class="sgds-night-theme">

通过 JavaScript 在运行时切换：

document.documentElement.classList.toggle("sgds-night-theme");

工作原理

themes/night.css 会在 :root.sgds-night-theme 作用域下重新定义与 themes/day.css 相同的语义令牌。所有 SGDS 组件都读取相同的语义令牌，因此切换该类即可切换整个 UI，无需更改任何组件标记。

---

更改字体

SGDS 默认通过 --sgds-font-family-brand 使用 Inter。覆盖此令牌即可使用其他字体：

:root {
  --sgds-font-family-brand: "Your Font", system-ui, sans-serif;
}

字体资源需由你负责加载，可以使用 <link> 标签或 @font-face。SGDS 不会自动加载自定义字体。如果要继续使用默认字体，请参阅 sgds-getting-started，获取经过优化的 Inter Google Fonts URL。

---

更改边框圆角

完整参考请参阅 border-radius.md，其中包含语义令牌表、覆盖示例和可用的基础值。

---

更改间距密度

完整参考请参阅 density.md，其中包含密度模式、令牌表、受影响的组件和导入顺序。

---

面向 AI Agent

1. 始终告知用户，应在 themes/day.css 之后导入自定义 CSS，否则覆盖设置会被覆盖。
2. 品牌颜色覆盖的目标是基础令牌（--sgds-product-primary-{100–900}），而不是语义令牌。更改基础令牌才是正确做法；不要直接覆盖单个语义令牌。
3. 夜间模式需要同时导入 themes/night.css，并在 <html> 上添加 sgds-night-theme 类。仅执行其中一项是不够的。
4. 夜间模式是可选的——仅当用户明确需要深色模式支持时，才添加 themes/night.css。
5. 默认始终启用日间模式；无需添加 sgds-day-theme 类。
6. 覆盖 --sgds-font-family-brand 时，提醒用户也要自行加载字体文件。
7. 自定义覆盖会同时应用于日间和夜间模式，因为它们以 :root 为目标，而两个主题选择器都继承自它。
8. 如需设置品牌颜色主题，请阅读 brand-colour.md。
9. 如需设置排版／字体主题，请阅读 typography.md。
10. 如需设置边框圆角主题，请阅读 border-radius.md。覆盖语义令牌（--sgds-{purpose}-border-radius），并通过 var(--sgds-border-radius-{size}) 引用基础值。
11. 如需设置密度主题，请阅读 density.md。在颜色主题之后导入一个密度文件（compact.css 或 spacious.css）。密度仅影响内边距和间距，不影响字号、颜色或边框圆角。