sgds-getting-started

SGDS 入门指南

刚接触 SGDS？ 继续阅读之前，请先参阅 sgds-workflow，了解完整的技能图谱和阅读顺序。

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

---

第 1 步 — 设置字体

SGDS 基础样式默认使用 Inter 字体。在 HTML 文档的 <head> 中、任何 SGDS CSS 之前添加 Google Fonts 导入。以下 URL 仅加载 SGDS 设计令牌定义的四种字重（300、400、600、700），包括常规和斜体样式。

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

---

第 2 步 — 导入基础样式和实用工具 CSS

在项目的主 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 包含 Tailwind v4 指令，必须通过 Tailwind 处理流程进行处理，不能作为普通 JS 导入项导入。

关于实用工具类设置的完整详情，请参阅 sgds-utilities。

---

第 3 步 — 注册 SGDS Web 组件

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

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

这会全局注册所有 <sgds-*> 自定义元素。

关于 React、Vue、Angular 和 Next.js 的具体集成详情，请参阅 sgds-components。

---

第 4 步 — 使用 SGDS 应用布局

每个 SGDS 应用都应采用两个推荐布局模板之一进行组织。请根据应用类型选择：

应用类型	布局	容器类
面向公众、通用型	简易应用	.sgds-container
内部工具、仪表板、事务处理	侧边栏应用	.sgds-container-sidebar

简易应用（面向公众）：

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

侧边栏应用（仪表板／内部工具）：

<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。

---

面向 AI Agent

组件优先规则：使用纯 HTML 和实用工具类构建 UI 元素之前，务必先确认是否已有 SGDS Web 组件满足需求。请先查阅 components-* 技能。只有在该用例没有对应 SGDS 组件时，才使用自定义标记。

1. 为新的 SGDS 项目生成任何组件或页面代码之前，务必先完成全部四个步骤。
2. 字体 <link> 标签必须放在 HTML <head> 中，不能放在 CSS 或 JS 导入中。关于字体自定义或主题设置，请参阅 sgds-theming。
3. CSS 导入顺序很重要：themes/day.css → css/sgds.css → css/utility.css。主题文件必须放在最前面，这样处理基础样式和实用工具样式时才能使用 CSS 变量令牌。
4. css/utility.css 必须在由 Tailwind v4 处理的 CSS 文件中导入，直接在 JavaScript 中导入不会生成 sgds: 实用工具类。
5. 单个 JS 导入语句 import "@govtechsg/sgds-web-component" 会注册所有组件。除非明确要进行 tree-shaking，否则不要单独导入组件。
6. 页面内容务必放在 .sgds-container（简易应用）或 .sgds-container-sidebar（侧边栏应用）中，切勿使用原始 sgds:max-w-* 实用工具类来复现容器行为。
7. 不确定应用类型时：面向公众的数字服务 → 简易应用；内部工具、仪表板、管理门户 → 侧边栏应用。