sgds-getting-started

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Getting Started with SGDS

SGDS 入门指南

New to SGDS? See sgds-workflow for the full skill map and reading order before continuing.

When building any application with the SGDS web component library, complete these four steps in order before writing any component or page code.

刚接触SGDS？ 在继续之前，请查看**sgds-workflow**获取完整技能图谱和阅读顺序。

使用SGDS Web组件库构建任何应用时，请在编写任何组件或页面代码之前，按顺序完成以下四个步骤。

Step 1 — Set the Font

步骤1 — 设置字体

SGDS foundation styles use the Inter typeface by default. Add the Google Fonts import to the

<head>

of your HTML document before any SGDS CSS. The URL below loads only the four weights defined by the SGDS design tokens (300, 400, 600, 700) in both normal and italic styles.

html

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link
    href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,300;0,14..32,400;0,14..32,600;0,14..32,700;1,14..32,300;1,14..32,400;1,14..32,600;1,14..32,700&display=swap"
    rel="stylesheet"
  />
</head>

SGDS基础样式默认使用Inter字体。在所有SGDS CSS之前，将Google Fonts的引入代码添加到HTML文档的

<head>

中。以下URL仅加载SGDS设计令牌定义的四种字重（300、400、600、700）的常规和斜体样式。

html

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link
    href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,300;0,14..32,400;0,14..32,600;0,14..32,700;1,14..32,300;1,14..32,400;1,14..32,600;1,14..32,700&display=swap"
    rel="stylesheet"
  />
</head>

Step 2 — Import Foundation and Utility CSS

步骤2 — 导入基础和工具类CSS

Import these files in your project's main CSS entry point (the file processed by your build tool):

css

/* e.g. globals.css, index.css, main.css */

/* 1. Theme tokens — must come first */
@import "@govtechsg/sgds-web-component/themes/day.css";
/* Optional — add only if supporting dark/night mode */
@import "@govtechsg/sgds-web-component/themes/night.css";

/* 2. Foundation styles (typography, headings, body, grid) */
@import "@govtechsg/sgds-web-component/css/sgds.css";

/* 3. Utility classes (sgds: prefix) — must be processed by Tailwind */
@import "@govtechsg/sgds-web-component/css/utility.css";

utility.css

contains Tailwind v4 directives and must be processed by your Tailwind pipeline — it cannot be imported as a plain JS import.

For full details on utility class setup, see sgds-utilities.

在项目的主CSS入口文件（由构建工具处理的文件）中导入以下文件：

css

/* e.g. globals.css, index.css, main.css */

/* 1. 主题令牌 — 必须放在最前面 */
@import "@govtechsg/sgds-web-component/themes/day.css";
/* 可选 — 仅在支持深色/夜间模式时添加 */
@import "@govtechsg/sgds-web-component/themes/night.css";

/* 2. 基础样式（排版、标题、正文、网格） */
@import "@govtechsg/sgds-web-component/css/sgds.css";

/* 3. 工具类（sgds: 前缀） — 必须由Tailwind处理 */
@import "@govtechsg/sgds-web-component/css/utility.css";

utility.css

包含Tailwind v4指令，必须由你的Tailwind流水线处理 — 不能作为普通JS导入。

关于工具类设置的完整细节，请查看**sgds-utilities**。

Step 3 — Register SGDS Web Components

步骤3 — 注册SGDS Web组件

Import the component library once at your app entry point (JS/TS):

import "@govtechsg/sgds-web-component";

This registers all

<sgds-*>

custom elements globally.

For React, Vue, Angular, and Next.js-specific integration details, see sgds-components.

在应用入口点（JS/TS）中导入一次组件库：

import "@govtechsg/sgds-web-component";

这会全局注册所有

<sgds-*>

自定义元素。

关于React、Vue、Angular和Next.js的特定集成细节，请查看**sgds-components**。

Step 4 — Use an SGDS App Layout

步骤4 — 使用SGDS应用布局

Every SGDS application should be structured using one of the two recommended layout templates. Choose based on your app type:

App type	Layout	Container class
Public-facing, general-purpose	Simple App	`.sgds-container`
Internal tool, dashboard, transactional	Sidebar App	`.sgds-container-sidebar`

Simple App (public-facing):

html

<div>
  <sgds-masthead fluid></sgds-masthead>
  <sgds-mainnav fluid>
    <strong slot="brand">My App</strong>
  </sgds-mainnav>
</div>
<div class="sgds:flex sgds:flex-col sgds:w-full">
  <div class="sgds-container sgds:py-2-xl">
    <!-- Page content -->
  </div>
  <sgds-footer></sgds-footer>
</div>

Sidebar App (dashboards / internal tools):

html

<div class="sgds:sticky sgds:top-0">
  <sgds-masthead fluid></sgds-masthead>
  <sgds-mainnav fluid>
    <strong slot="brand">My App</strong>
  </sgds-mainnav>
</div>
<div class="sgds:flex sgds:flex-row">
  <div class="sgds:sticky sgds:h-[calc(100vh-108px)] sgds:overflow-y-scroll sgds:top-27 sgds:w-68 sgds:border-r sgds:border-muted">
    <!-- Sidebar navigation -->
  </div>
  <div class="sgds:flex sgds:flex-col sgds:w-full">
    <div class="sgds-container-sidebar sgds:py-2-xl">
      <!-- Page content -->
    </div>
    <sgds-footer></sgds-footer>
  </div>
</div>

For full layout details and responsive container breakpoints, see Application Shell.

每个SGDS应用都应使用两种推荐布局模板之一进行结构化。根据你的应用类型选择：

应用类型	布局	容器类
面向公众的通用型	简单应用	`.sgds-container`
内部工具、仪表盘、事务型	侧边栏应用	`.sgds-container-sidebar`

简单应用（面向公众）：

html

<div>
  <sgds-masthead fluid></sgds-masthead>
  <sgds-mainnav fluid>
    <strong slot="brand">My App</strong>
  </sgds-mainnav>
</div>
<div class="sgds:flex sgds:flex-col sgds:w-full">
  <div class="sgds-container sgds:py-2-xl">
    <!-- 页面内容 -->
  </div>
  <sgds-footer></sgds-footer>
</div>

侧边栏应用（仪表盘/内部工具）：

html

<div class="sgds:sticky sgds:top-0">
  <sgds-masthead fluid></sgds-masthead>
  <sgds-mainnav fluid>
    <strong slot="brand">My App</strong>
  </sgds-mainnav>
</div>
<div class="sgds:flex sgds:flex-row">
  <div class="sgds:sticky sgds:h-[calc(100vh-108px)] sgds:overflow-y-scroll sgds:top-27 sgds:w-68 sgds:border-r sgds:border-muted">
    <!-- 侧边栏导航 -->
  </div>
  <div class="sgds:flex sgds:flex-col sgds:w-full">
    <div class="sgds-container-sidebar sgds:py-2-xl">
      <!-- 页面内容 -->
    </div>
    <sgds-footer></sgds-footer>
  </div>
</div>

关于布局的完整细节和响应式容器断点，请查看**Application Shell**。

For AI agents

针对AI Agent的提示

Component-first rule: Before building any UI element with plain HTML and utility classes, always check whether an SGDS web component already covers the need. Consult the

components-*

skills first. Only fall back to custom markup when no SGDS component exists for the use case.

Always complete all four steps before generating any component or page code for a new SGDS project.
The font
```
<link>
```
tags must go in the HTML
```
<head>
```
— not in CSS or JS imports. For font customisation or theming, refer to sgds-theming.
CSS import order matters:
```
themes/day.css
```
→
```
css/sgds.css
```
→
```
css/utility.css
```
. The theme file must come first so CSS variable tokens are available when foundation and utility styles are processed.
```
css/utility.css
```
must be imported inside a CSS file processed by Tailwind v4 — importing it directly in JavaScript will not generate the
```
sgds:
```
utility classes.
The single JS import
```
import "@govtechsg/sgds-web-component"
```
registers all components. Do not import individual components unless explicitly doing tree-shaking.
Always wrap page content in
```
.sgds-container
```
(simple app) or
```
.sgds-container-sidebar
```
(sidebar app) — never use raw
```
sgds:max-w-*
```
utilities to replicate container behaviour.
When in doubt about app type: public-facing digital services → simple app; internal tools, dashboards, admin portals → sidebar app.

组件优先规则：在使用纯HTML和工具类构建任何UI元素之前，请始终检查是否已有SGDS Web组件满足需求。首先查阅

components-*

相关技能。仅当没有适合该用例的SGDS组件时，才退回到自定义标记。

在为新SGDS项目生成任何组件或页面代码之前，务必完成所有四个步骤。
字体
```
<link>
```
标签必须放在HTML
```
<head>
```
中 — 不能放在CSS或JS导入里。如需自定义字体或主题，请参考**sgds-theming**。
CSS导入顺序很重要：
```
themes/day.css
```
→
```
css/sgds.css
```
→
```
css/utility.css
```
。主题文件必须放在最前面，这样在处理基础和工具类样式时，CSS变量令牌才可用。
```
css/utility.css
```
必须导入到由Tailwind v4处理的CSS文件中 — 直接在JavaScript中导入不会生成
```
sgds:
```
工具类。
单次JS导入
```
import "@govtechsg/sgds-web-component"
```
即可注册所有组件。除非明确进行摇树优化，否则不要导入单个组件。
始终将页面内容包裹在
```
.sgds-container
```
（简单应用）或
```
.sgds-container-sidebar
```
（侧边栏应用）中 — 切勿使用原始
```
sgds:max-w-*
```
工具类来模拟容器行为。
不确定应用类型时：面向公众的数字服务 → 简单应用；内部工具、仪表盘、管理门户 → 侧边栏应用。