sgds-theming

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SGDS Theming Skill

SGDS主题定制指南

How to customise the product theme — brand colours, day/night mode, and font — using SGDS CSS token overrides.

如何通过覆盖SGDS CSS令牌来定制产品主题——包括品牌色彩、日夜模式及字体。

Prerequisites

前提条件

Import

themes/day.css

before your custom CSS. See sgds-getting-started for the full import order.

在自定义CSS之前导入

themes/day.css

。完整的导入顺序请参考**sgds-getting-started**。

Quick Decision Guide

快速决策指南

What you want to change	Token / mechanism
Product brand colour (custom)	Override `--sgds-product-primary-{100–900}`
Product brand colour (GovTech)	Import one `themes/gt/<colour>.css` + map to `--sgds-product-primary-*`
Enable dark/night mode	Import `themes/night.css` + add `.sgds-night-theme` to `<html>`
Font typeface	Override `--sgds-font-family-brand`

需更改的内容	令牌/实现方式
自定义产品品牌色彩	覆盖 `--sgds-product-primary-{100–900}`
GovTech产品品牌色彩	导入 `themes/gt/<colour>.css` 并映射到 `--sgds-product-primary-*`
启用深色/夜间模式	导入 `themes/night.css` 并为 `<html>` 添加 `.sgds-night-theme` 类
字体类型	覆盖 `--sgds-font-family-brand`

Changing the Product Brand Colour

更改产品品牌色彩

The default product colour is purple (

--sgds-product-primary-*

). Override the full 100–900 scale with your brand colour to retheme all primary UI elements at once.

Create a custom CSS file and override the primitive tokens in

:root

css

/* 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;
}

Import your custom CSS after the SGDS theme file so the overrides take effect:

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

css

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

The semantic tokens (

--sgds-primary-*

) reference the primitive scale, so changing the primitive values automatically flows through to all components that use the primary colour.

默认产品色彩为紫色（

--sgds-product-primary-*

）。通过覆盖100–900全范围的品牌色彩，可一次性重新设置所有主UI元素的主题。

创建自定义CSS文件，在

:root

中覆盖基础令牌：

css

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

css

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

语义令牌（

--sgds-primary-*

）引用基础令牌体系，因此修改基础值会自动应用到所有使用主色调的组件。

GovTech Brand Colours

GovTech品牌色彩

GovTech products should use one of the pre-approved colour palettes in

themes/gt/

rather than defining custom hex values. Each product picks exactly one colour — mixing multiple GT palettes is not allowed.

GovTech产品应使用

themes/gt/

中预先批准的调色板之一，而非自定义十六进制值。每个产品只能选择一种颜色——不允许混合多种GT调色板。

Available colours

可用颜色

File	Colour
`themes/gt/blue.css`	Blue
`themes/gt/cyan.css`	Cyan
`themes/gt/magenta.css`	Magenta
`themes/gt/pink.css`	Pink
`themes/gt/purple.css`	Purple
`themes/gt/red.css`	Red

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

How to apply

应用方法

Each GT file defines

--gt-color-100

through

--gt-color-900

:root

. Map those onto the SGDS product primary scale in your custom CSS file:

css

/* 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);
}

Import order — the GT file must come before your custom CSS so the

--gt-color-*

variables are defined when the mapping runs:

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

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

The same flow-through behaviour applies: changing

--sgds-product-primary-*

automatically updates all components that use the primary colour.

每个GT文件在

:root

中定义了

--gt-color-100

至

--gt-color-900

。在自定义CSS文件中将这些映射到SGDS产品主色调体系：

css

/* 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"; // 仅选择一种颜色
import "./yourCustomCss.css";

css

@import "@govtechsg/sgds-web-component/themes/day.css";
@import "@govtechsg/sgds-web-component/themes/gt/blue.css"; /* 仅选择一种颜色 */
@import "./yourCustomCss.css";

同样的联动规则适用：修改

--sgds-product-primary-*

会自动更新所有使用主色调的组件。

Day Mode (Default)

日间模式（默认）

Day mode is the default. Importing

themes/day.css

is all that is needed — no extra configuration required.

css

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

日间模式为默认模式。只需导入

themes/day.css

即可——无需额外配置。

css

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

Night Mode (Optional)

夜间模式（可选）

Night mode is opt-in. It is applied by adding the class

sgds-night-theme

to the

<html>

element, which activates the

:root.sgds-night-theme

selector defined in

themes/night.css

夜间模式为可选功能。通过为

<html>

元素添加

sgds-night-theme

类来启用，该类会激活

themes/night.css

中定义的

:root.sgds-night-theme

选择器。

Setup

设置步骤

Import both theme files:

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

css

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

css

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

Activating night mode

启用夜间模式

Add the class to the

<html>

element to switch all tokens to their dark equivalents:

html

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

Toggle it at runtime via JavaScript:

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

为

<html>

元素添加类，即可将所有令牌切换为深色等效值：

html

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

通过JavaScript在运行时切换：

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

How it works

工作原理

themes/night.css

redefines the same semantic tokens as

themes/day.css

but scoped to

:root.sgds-night-theme

. All SGDS components read from the same semantic tokens, so toggling the class switches the entire UI without changing any component markup.

themes/night.css

重新定义了与

themes/day.css

相同的语义令牌，但作用域限定为

:root.sgds-night-theme

。所有SGDS组件均读取相同的语义令牌，因此切换类即可切换整个UI，无需修改任何组件标记。

Changing the Font

更改字体

SGDS uses Inter by default via

--sgds-font-family-brand

. Override this token to use a different typeface:

css

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

You are responsible for loading the font assets — either via a

<link>

tag or

@font-face

. SGDS does not load custom fonts automatically. See sgds-getting-started for the optimised Inter Google Fonts URL if you are keeping the default font.

SGDS默认使用Inter字体，通过

--sgds-font-family-brand

令牌定义。覆盖此令牌即可使用其他字体：

css

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

您需要自行负责加载字体资源——可通过

<link>

标签或

@font-face

实现。SGDS不会自动加载自定义字体。如果保留默认字体，可参考**sgds-getting-started**获取优化后的Inter Google Fonts链接。

For AI Agents

面向AI Agent的提示

Always tell users to import their custom CSS after
```
themes/day.css
```
— otherwise the override will be overwritten.
Brand colour overrides target primitive tokens (
```
--sgds-product-primary-{100–900}
```
), not semantic tokens. Changing the primitives is the correct approach; do not override individual semantic tokens directly.
Night mode requires both the
```
themes/night.css
```
import and the
```
sgds-night-theme
```
class on
```
<html>
```
. Either alone is not enough.
Night mode is optional — only add
```
themes/night.css
```
when the user explicitly needs dark mode support.
Day mode is always active by default; there is no
```
sgds-day-theme
```
class to add.
When overriding
```
--sgds-font-family-brand
```
, remind the user to also load the font file themselves.
Custom overrides apply to both day and night mode simultaneously because they target
```
:root
```
, which both theme selectors inherit from.
GovTech products must use a colour from
```
themes/gt/
```
— not custom hex values. If a user is building a GovTech product and asks about brand colours, guide them to pick one GT colour and apply the
```
--gt-color-*
```
→
```
--sgds-product-primary-*
```
mapping pattern. Never let them import more than one GT colour file.
The GT colour file must be imported after
```
themes/day.css
```
and before the custom mapping CSS so that
```
--gt-color-*
```
variables are defined in time.

务必告知用户在
```
themes/day.css
```
之后导入自定义CSS——否则覆盖设置会被覆盖。
品牌色彩覆盖需针对基础令牌（
```
--sgds-product-primary-{100–900}
```
），而非语义令牌。修改基础令牌是正确的做法；请勿直接覆盖单个语义令牌。
启用夜间模式需要同时导入
```
themes/night.css
```
并为
```
<html>
```
添加
```
sgds-night-theme
```
类。仅其中一项不足以生效。
夜间模式为可选——仅当用户明确需要深色模式支持时才添加
```
themes/night.css
```
。
日间模式始终默认激活；无需添加
```
sgds-day-theme
```
类。
覆盖
```
--sgds-font-family-brand
```
时，提醒用户需自行加载字体文件。
自定义覆盖会同时应用于日间和夜间模式，因为它们针对的是
```
:root
```
，而两个主题选择器均继承自
```
:root
```
。
GovTech产品必须使用
```
themes/gt/
```
中的颜色——而非自定义十六进制值。如果用户正在构建GovTech产品并询问品牌色彩，引导他们选择一种GT颜色并应用
```
--gt-color-*
```
→
```
--sgds-product-primary-*
```
的映射模式。绝不允许导入多个GT颜色文件。
GT颜色文件必须在
```
themes/day.css
```
之后、自定义映射CSS之前导入，确保
```
--gt-color-*
```
变量及时定义。