sgds-blocks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SGDS Block Templates

SGDS组件块模板

Reusable UI blocks that slot into any page layout. Each block is a self-contained section — drop it into a page template from sgds-templates to assemble complete pages without writing layout code from scratch.

可嵌入任意页面布局的可复用UI组件块。每个组件块都是一个独立的区块——将其放入**sgds-templates**中的页面模板，无需从头编写布局代码即可组装完整页面。

What is a block?

什么是组件块？

A block is a chunk of UI that:

Has a single, focused responsibility (filter content, display a stat, show a form section, create a hero banner)
Works standalone inside any container
Can appear multiple times on a page or alongside other blocks

The Application Shell is a special mandatory block — it is the page chrome (

<sgds-masthead>

<sgds-mainnav>

<sgds-footer>

) that every SGDS page must include. All other blocks are content blocks that slot inside the shell.

Blocks are the ingredients. Page templates are the recipes.

组件块是一段UI内容，具备以下特性：

单一且明确的职责（筛选内容、展示统计数据、显示表单区块、创建Hero横幅）
可在任意容器中独立运行
可在页面中多次出现，或与其他组件块搭配使用

**应用外壳（Application Shell）**是一种特殊的必填组件块——它是页面的基础框架（

<sgds-masthead>

、

<sgds-mainnav>

、

<sgds-footer>

），每个SGDS页面都必须包含。其他所有组件块都是可嵌入外壳中的内容区块。

组件块是原料，页面模板是配方。

Prerequisites

前置依赖

javascript

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

See sgds-components for full installation details.

javascript

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

查看**sgds-components**获取完整安装说明。

Quick Decision Guide

快速决策指南

What you need	Block to use
Mandatory page chrome (masthead, mainnav, footer, container) for any SGDS page	Application Shell
Full-bleed hero section with headline, description, CTA button and optional image	Hero
Feature showcase section with image/component positioning and grid ratios	Feature
Call-to-action section (primary, raised, alternate, centered, or full-bleed)	CTA
Statistics/metrics display (3, 4, 5, or 6 columns)	Stats
Card grid layout (3-column or 4-column)	Cards
Page-level header with breadcrumb, icon + title, description, and primary CTA	Page Header
Read-only entity summary card with key-value fields and an edit action	Basic Details Card
Filter interfaces and search results layout	Filter
Multi-field form with proper component sizing, grouping, and layout rules	Form

需求	应使用的组件块
任意SGDS页面所需的必填页面框架（页眉导航、主导航页脚、容器）	应用外壳
包含标题、描述、CTA按钮及可选图片的通栏Hero区块	Hero
具备图片/组件定位和网格比例的功能展示区块	功能展示
行动召唤区块（主样式、凸起样式、替代样式、居中或通栏）	CTA
统计/指标展示（3、4、5或6列布局）	统计数据
卡片网格布局（3列或4列）	卡片
包含面包屑导航、图标+标题、描述及主要CTA按钮的页面级页眉	页面页眉
包含键值字段和编辑操作的只读实体摘要卡片	基础详情卡片
筛选界面和搜索结果布局	筛选器
具备合理组件尺寸、分组和布局规则的多字段表单	表单

→ Read reference/application-shell.md

→ 阅读 reference/application-shell.md

Required for every page. The application shell wraps all page content with the mandatory Singapore Government chrome:

<sgds-masthead>

<sgds-mainnav>

, and

<sgds-footer>

. Provides two layout variants — Simple App (

.sgds-container

, public-facing) and Sidebar App (

.sgds-container-sidebar

, dashboards and internal tools) — with full breakpoint tables and sticky-header patterns.

每个页面都必须使用。应用外壳会用新加坡政府规定的基础框架（

<sgds-masthead>

、

<sgds-mainnav>

和

<sgds-footer>

）包裹所有页面内容。提供两种布局变体——简易应用（

.sgds-container

，面向公众）和侧边栏应用（

.sgds-container-sidebar

，适用于仪表板和内部工具），包含完整的断点表格和粘性页眉模式。

→ Read reference/hero.md

→ 阅读 reference/hero.md

Hero sections with multiple layout and background options. Use for above-the-fold content on landing pages, campaign pages, or section introductions.

具备多种布局和背景选项的Hero区块。用于着陆页、活动页面或区块介绍的首屏内容。

→ Read reference/feature.md

→ 阅读 reference/feature.md

Feature showcase sections with image/component positioning and grid ratios. Use to highlight key product benefits, capabilities, or features.

具备图片/组件定位和网格比例的功能展示区块。用于突出关键产品优势、功能或特性。

→ Read reference/cta.md

→ 阅读 reference/cta.md

Call-to-action sections with multiple style and alignment options (primary, raised, alternate, centered, contained, or full-bleed). Use to drive user action throughout the page.

具备多种样式和对齐选项（主样式、凸起样式、替代样式、居中、容器内或通栏）的行动召唤区块。用于在页面中引导用户操作。

→ Read reference/stats.md

→ 阅读 reference/stats.md

Statistics/metrics display with multiple column counts (3, 4, 5, or 6 columns, with optional right-aligned variants). Use to showcase key metrics, achievements, or impact numbers.

具备多种列数（3、4、5或6列，可选右对齐变体）的统计/指标展示。用于展示关键指标、成果或影响数据。

→ Read reference/cards.md

→ 阅读 reference/cards.md

Grid layouts for card components (3-column or 4-column). Use to display collections of items in structured card grids.

卡片组件的网格布局（3列或4列）。用于在结构化卡片网格中展示项目集合。

→ Read reference/page-header.md

→ 阅读 reference/page-header.md

Breadcrumb trail + icon-tinted container + h1 heading + description + primary CTA button. Use at the top of any content page to orient the user and surface the primary action.

面包屑导航 + 图标着色容器 + h1标题 + 描述 + 主要CTA按钮。用于在任意内容页面顶部帮助用户定位，并展示主要操作。

→ Read reference/basic-details.md

→ 阅读 reference/basic-details.md

Bordered card with a subtitle heading, stacked key-value field pairs, and an optional edit button. Use to display read-only entity metadata (IDs, names, descriptions, contact info) on detail or profile pages.

带副标题、堆叠键值字段对及可选编辑按钮的边框卡片。用于在详情页或个人资料页展示只读实体元数据（ID、名称、描述、联系信息）。

→ Read reference/filter.md

→ 阅读 reference/filter.md

Filter interfaces and search results layout. Use for advanced filtering and search result displays.

筛选界面和搜索结果布局。用于高级筛选和搜索结果展示。

→ Read reference/form.md

→ 阅读 reference/form.md

Form layout rules: grid math, component pairing, validation feedback, and canonical patterns. All forms use

.sgds-grid

with 12 columns. Form containers are 8 columns wide (left/center-aligned). Paired fields take 6 columns each (max 2 per row). Full-width fields (textarea, checkbox-group, radio-group, file-upload) always span 12 columns. Includes 5 reusable patterns: full-width only, paired fields, mixed layout, multiple sections, and sidebar navigation.

表单布局规则：网格计算、组件配对、验证反馈及标准模式。所有表单均使用

.sgds-grid

的12列布局。表单容器宽度为8列（左对齐/居中对齐）。配对字段各占6列（每行最多2个）。全宽字段（文本域、复选框组、单选框组、文件上传）始终占12列。包含5种可复用模式：仅全宽、配对字段、混合布局、多区块、侧边栏导航。

Composing blocks with page templates

组件块与页面模板的组合

Blocks live inside the content area of a page template. The typical pattern:

html

<!-- Page template provides the chrome -->
<sgds-masthead></sgds-masthead>
<sgds-mainnav>...</sgds-mainnav>

<div class="sgds:bg-surface-default sgds:min-h-screen">
  <div class="sgds:w-container sgds:mx-auto sgds:py-layout-md">

    <!-- Two-column layout: block on the left, content on the right -->
    <div class="sgds:flex sgds:gap-layout-md sgds:items-start">

      <!-- Drop the block here -->
      <aside class="sgds:shrink-0 sgds:w-64">
        <!-- Filter Sidebar block -->
      </aside>

      <!-- Content area -->
      <div class="sgds:flex-1">
        <!-- Cards, table, results, etc. -->
      </div>

    </div>
  </div>
</div>

<sgds-footer></sgds-footer>

组件块位于页面模板的内容区域内。典型模式如下：

html

<!-- Page template provides the chrome -->
<sgds-masthead></sgds-masthead>
<sgds-mainnav>...</sgds-mainnav>

<div class="sgds:bg-surface-default sgds:min-h-screen">
  <div class="sgds:w-container sgds:mx-auto sgds:py-layout-md">

    <!-- Two-column layout: block on the left, content on the right -->
    <div class="sgds:flex sgds:gap-layout-md sgds:items-start">

      <!-- Drop the block here -->
      <aside class="sgds:shrink-0 sgds:w-64">
        <!-- Filter Sidebar block -->
      </aside>

      <!-- Content area -->
      <div class="sgds:flex-1">
        <!-- Cards, table, results, etc. -->
      </div>

    </div>
  </div>
</div>

<sgds-footer></sgds-footer>

Before Writing Form Code

编写表单代码前须知

Forms are complex because SGDS components have specific constraints. Read reference/form.md FIRST — it contains all grid math, component pairing rules, 5 canonical patterns, and positioning variants.

表单较为复杂，因为SGDS组件有特定约束。请先阅读reference/form.md——其中包含所有网格计算、组件配对规则、5种标准模式及定位变体。

Component API Verification

组件API验证

Read the component reference for every

<sgds-*>

element you use:

Child element naming: Each component has specific child element names.
```
<sgds-select>
```
uses
```
<sgds-select-option>
```
(not
```
<sgds-option>
```
).
```
<sgds-combo-box>
```
uses
```
<sgds-combobox-option>
```
. Always verify in the sgds-components skill reference.
Slot requirements:
```
<sgds-file-upload>
```
slots require text labels (not just icons). Check if the component expects child elements, slot content, or JS properties.
Optional properties:
```
<sgds-stepper>
```
uses a JS property (
```
steps
```
array), not HTML child elements like
```
<sgds-stepper-item>
```
. Verify which components accept attributes vs. JS properties.

阅读你使用的每个

<sgds-*>

元素的组件参考：

子元素命名：每个组件都有特定的子元素名称。
```
<sgds-select>
```
使用
```
<sgds-select-option>
```
（而非
```
<sgds-option>
```
）。
```
<sgds-combo-box>
```
使用
```
<sgds-combobox-option>
```
。请务必在sgds-components技能参考中验证。
插槽要求：
```
<sgds-file-upload>
```
的插槽需要文本标签（不能仅使用图标）。检查组件是否需要子元素、插槽内容或JS属性。
可选属性：
```
<sgds-stepper>
```
使用JS属性（
```
steps
```
数组），而非
```
<sgds-stepper-item>
```
这类HTML子元素。验证哪些组件接受属性，哪些接受JS属性。

Form-Specific Constraints

表单特定约束

From reference/form.md:

Forms take exactly 8 columns within
```
.sgds-container
```
Pairable fields (Input, Select, Datepicker, Combo-box single-select): Take 6 columns each at lg+ (4 columns at sm)
Full-width fields (Textarea, Checkbox-group, Radio-group, Combo-box multi-select, File-upload): Always 12 columns

Grid math:

sidebar_cols + form_cols + toc_cols ≤ 12

Multi-select combo-box: ⚠️ CRITICAL — must be full-width, never pair with any other component

Always cross-check against reference/form.md before coding.

来自reference/form.md：

表单在
```
.sgds-container
```
中恰好占8列
可配对字段（输入框、选择器、日期选择器、单选组合框）：在lg+尺寸下占6列（sm尺寸下占4列）
全宽字段（文本域、复选框组、单选框组、多选组合框、文件上传）：始终占12列

网格计算：

sidebar_cols + form_cols + toc_cols ≤ 12

多选组合框：⚠️ 重要提示——必须为全宽，切勿与其他组件配对

编写代码前务必对照reference/form.md进行交叉检查。

Building Custom Blocks

构建自定义组件块

Users are free to design their own blocks with full creative latitude — layout, composition, and visual hierarchy are all open. The only constraint is that every block must stay within the SGDS system rails:

Requirement	How
UI components	Use `<sgds-*>` web components. Do not reach for plain HTML equivalents when an SGDS component exists (e.g. use `<sgds-badge>` , not a hand-rolled `<span>` chip).
Styling	Use `sgds:` Tailwind utilities exclusively for colours, spacing, typography, and layout. Do not write arbitrary CSS values that duplicate what the design token system already expresses.
Typography	Use semantic role tokens ( `sgds:text-heading-md` , `sgds:text-body-md` , `sgds:text-overline-md` , etc.) paired with matching weight, line-height, and tracking tokens. Do not use raw scale tokens ( `sgds:text-base` , `sgds:text-sm` ) which are not part of the public API.
Icons	Use `<sgds-icon name="...">` exclusively. Do not embed raw SVG or third-party icon libraries.
External inspiration	Fine to reference sites like shadcnblocks.com, Tailwind UI, or any other design gallery for layout ideas — but always re-implement using SGDS components and tokens, not the source site's CSS or component library.

→ Read reference/custom-block-rules.md for the full token reference, anti-patterns, and annotated examples.

用户可自由设计自己的组件块，拥有充分的创作空间——布局、组合和视觉层次均可自定义。唯一的约束是每个组件块必须遵循SGDS系统规则：

要求	实现方式
UI组件	使用 `<sgds-*>` Web组件。当存在SGDS组件时，请勿使用纯HTML等效元素（例如，使用 `<sgds-badge>` ，而非自定义的 `<span>` 标签）。
样式	仅使用 `sgds:` Tailwind工具类设置颜色、间距、排版和布局。请勿编写重复设计令牌系统已有样式的任意CSS值。
排版	使用语义角色令牌（ `sgds:text-heading-md` 、 `sgds:text-body-md` 、 `sgds:text-overline-md` 等），并搭配匹配的字重、行高和字距令牌。请勿使用不属于公共API的原始比例令牌（ `sgds:text-base` 、 `sgds:text-sm` ）。
图标	仅使用 `<sgds-icon name="...">` 。请勿嵌入原始SVG或第三方图标库。
外部灵感	可以参考shadcnblocks.com、Tailwind UI或其他设计图库的布局思路——但务必使用SGDS组件和令牌重新实现，而非使用源网站的CSS或组件库。

→ 阅读**reference/custom-block-rules.md**获取完整令牌参考、反模式及带注释的示例。

For AI agents

面向AI Agent的说明

⚠️ CRITICAL RULE — ALWAYS LOAD THESE SKILLS FIRST

⚠️ 重要规则——务必先加载以下技能

Before you write ANY block code:

LOAD
sgds-utilities
skill — You need the complete utility class reference
LOAD
sgds-components
skill — You need component APIs and child element names
Then READ
reference/custom-block-rules.md
in this skill

STYLING RULE (applies to ALL blocks):

Use
```
sgds:
```
Tailwind utilities EXCLUSIVELY for spacing, colors, typography, layout
Use
```
<sgds-*>
```
components EXCLUSIVELY for UI elements
NEVER use inline
<style>
blocks to replicate design tokens (e.g.,
```
margin: 24px
```
,
```
var(--sgds-*)
```
)
NEVER write arbitrary CSS that duplicates what design tokens already express

If you skip loading utilities/components first, you will default to inline styles and break the design system. This is the #1 mistake agents make with blocks.

在编写任何组件块代码之前：

加载
sgds-utilities
技能——你需要完整的工具类参考
加载
sgds-components
技能——你需要组件API和子元素名称
然后阅读本技能中的
reference/custom-block-rules.md

样式规则（适用于所有组件块）：

仅使用
```
sgds:
```
Tailwind工具类设置间距、颜色、排版和布局
仅使用
```
<sgds-*>
```
组件作为UI元素
切勿使用内联
<style>
块来复现设计令牌（例如，
```
margin: 24px
```
、
```
var(--sgds-*)
```
）
切勿编写重复设计令牌已有样式的任意CSS

如果跳过先加载工具类/组件技能，你会默认使用内联样式并破坏设计系统。这是Agent处理组件块时最常犯的错误。

Agent workflow (in order)

Agent工作流程（按顺序）

Load
```
sgds-utilities
```
skill
Load
```
sgds-components
```
skill
Load this skill
Read
```
reference/custom-block-rules.md
```
THEN write block code using utilities + components

加载
```
sgds-utilities
```
技能
加载
```
sgds-components
```
技能
加载本技能
阅读
```
reference/custom-block-rules.md
```
然后使用工具类+组件编写组件块代码

Guidelines

指南

Every page must have the Application Shell —
```
<sgds-masthead>
```
,
```
<sgds-mainnav>
```
, and
```
<sgds-footer>
```
are mandatory on every SGDS page. Read reference/application-shell.md for layout patterns and container classes.
When a user asks for a filtered list page, combine the Filter Sidebar block with the List Page template from sgds-templates.
Adapt category labels, values, and counts to the user's actual data domain — do not copy the conference example verbatim.
When a user says "I want to build a custom block" or references an external design (shadcnblocks, Figma, screenshot), read reference/custom-block-rules.md before generating any output.

每个页面都必须包含应用外壳——
```
<sgds-masthead>
```
、
```
<sgds-mainnav>
```
和
```
<sgds-footer>
```
是每个SGDS页面的必填项。阅读**reference/application-shell.md**获取布局模式和容器类。
当用户请求带筛选的列表页面时，将侧边栏筛选组件块与**sgds-templates**中的列表页面模板组合使用。
根据用户的实际数据领域调整分类标签、值和数量——不要直接复制会议示例内容。
当用户表示“我想构建一个自定义组件块”或引用外部设计（shadcnblocks、Figma、截图）时，在生成任何输出前先阅读**reference/custom-block-rules.md**。