Skip to content

Commit fad6990

Browse files
petrinetangth-94
petrinetang
authored and
th-94
committed
chore: update SGDS skills and token diagram
1 parent 667c62c commit fad6990

46 files changed

Lines changed: 3517 additions & 92 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/sgds-blocks/SKILL.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
name: "sgds-blocks"
3+
description: "Reusable UI blocks for building full SGDS pages and sections. Use this skill whenever the user wants to build pages, design layouts, create sections, or compose multiple sections together. Trigger on ANY mention of: app layout, application shell, page structure, hero sections, CTAs (call-to-action), cards, card grids, feature sections, product benefits, statistics displays, metrics, page headers, page titles, filter interfaces, search filters, data tables, forms, landing pages, dashboards, sidebar navigation, or any major page component — even if they don't name it a 'block'. Also use for: 'I need a filter', 'build a form', 'create a call to action', 'design a landing page', 'show statistics', 'sidebar layout', or similar requests for page-level UI. These are drop-in sections and shell structures, not full pages. Compose them with sgds-templates to build complete pages."
4+
metadata:
5+
author: singapore-design-system
6+
version: "0.0.0"
7+
audience: external
8+
category: pattern
9+
---
10+
11+
# SGDS Block Templates
12+
13+
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](../sgds-templates/SKILL.md)** to assemble complete pages without writing layout code from scratch.
14+
15+
## What is a block?
16+
17+
A block is a chunk of UI that:
18+
19+
- Has a single, focused responsibility (filter content, display a stat, show a form section, create a hero banner)
20+
- Works standalone inside any container
21+
- Can appear multiple times on a page or alongside other blocks
22+
23+
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.
24+
25+
Blocks are the ingredients. Page templates are the recipes.
26+
27+
## Prerequisites
28+
29+
```javascript
30+
import "@govtechsg/sgds-web-component/themes/day.css";
31+
import "@govtechsg/sgds-web-component/css/sgds.css";
32+
import "@govtechsg/sgds-web-component/css/utility.css";
33+
```
34+
35+
See **[sgds-components](../sgds-components/SKILL.md)** for full installation details.
36+
37+
---
38+
39+
## Quick Decision Guide
40+
41+
| What you need | Block to use |
42+
|---|---|
43+
| Mandatory page chrome (masthead, mainnav, footer, container) for any SGDS page | [Application Shell](reference/application-shell.md) |
44+
| Full-bleed hero section with headline, description, CTA button and optional image | [Hero](reference/hero.md) |
45+
| Feature showcase section with image/component positioning and grid ratios | [Feature](reference/feature.md) |
46+
| Call-to-action section (primary, raised, alternate, centered, or full-bleed) | [CTA](reference/cta.md) |
47+
| Statistics/metrics display (3, 4, 5, or 6 columns) | [Stats](reference/stats.md) |
48+
| Card grid layout (3-column or 4-column) | [Cards](reference/cards.md) |
49+
| Page-level header with breadcrumb, icon + title, description, and primary CTA | [Page Header](reference/page-header.md) |
50+
| Read-only entity summary card with key-value fields and an edit action | [Basic Details Card](reference/basic-details.md) |
51+
| Filter interfaces and search results layout | [Filter](reference/filter.md) |
52+
| Multi-field form with proper component sizing, grouping, and layout rules | [Form](reference/form.md) |
53+
54+
---
55+
56+
## → Read [reference/application-shell.md](reference/application-shell.md)
57+
58+
**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.
59+
60+
---
61+
62+
## → Read [reference/hero.md](reference/hero.md)
63+
64+
Hero sections with multiple layout and background options. Use for above-the-fold content on landing pages, campaign pages, or section introductions.
65+
66+
---
67+
68+
## → Read [reference/feature.md](reference/feature.md)
69+
70+
Feature showcase sections with image/component positioning and grid ratios. Use to highlight key product benefits, capabilities, or features.
71+
72+
---
73+
74+
## → Read [reference/cta.md](reference/cta.md)
75+
76+
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.
77+
78+
---
79+
80+
## → Read [reference/stats.md](reference/stats.md)
81+
82+
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.
83+
84+
---
85+
86+
## → Read [reference/cards.md](reference/cards.md)
87+
88+
Grid layouts for card components (3-column or 4-column). Use to display collections of items in structured card grids.
89+
90+
---
91+
92+
## → Read [reference/page-header.md](reference/page-header.md)
93+
94+
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.
95+
96+
---
97+
98+
## → Read [reference/basic-details.md](reference/basic-details.md)
99+
100+
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.
101+
102+
---
103+
104+
## → Read [reference/filter.md](reference/filter.md)
105+
106+
Filter interfaces and search results layout. Use for advanced filtering and search result displays.
107+
108+
---
109+
110+
## → Read [reference/form.md](reference/form.md)
111+
112+
**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.
113+
114+
---
115+
116+
## Composing blocks with page templates
117+
118+
Blocks live inside the content area of a page template. The typical pattern:
119+
120+
```html
121+
<!-- Page template provides the chrome -->
122+
<sgds-masthead></sgds-masthead>
123+
<sgds-mainnav>...</sgds-mainnav>
124+
125+
<div class="sgds:bg-surface-default sgds:min-h-screen">
126+
<div class="sgds:w-container sgds:mx-auto sgds:py-layout-md">
127+
128+
<!-- Two-column layout: block on the left, content on the right -->
129+
<div class="sgds:flex sgds:gap-layout-md sgds:items-start">
130+
131+
<!-- Drop the block here -->
132+
<aside class="sgds:shrink-0 sgds:w-64">
133+
<!-- Filter Sidebar block -->
134+
</aside>
135+
136+
<!-- Content area -->
137+
<div class="sgds:flex-1">
138+
<!-- Cards, table, results, etc. -->
139+
</div>
140+
141+
</div>
142+
</div>
143+
</div>
144+
145+
<sgds-footer></sgds-footer>
146+
```
147+
148+
---
149+
150+
## Before Writing Form Code
151+
152+
Forms are complex because SGDS components have specific constraints. **Read [reference/form.md](reference/form.md) FIRST** — it contains all grid math, component pairing rules, 5 canonical patterns, and positioning variants.
153+
154+
### Component API Verification
155+
Read the component reference for every `<sgds-*>` element you use:
156+
157+
- **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](../sgds-components/SKILL.md) reference.
158+
- **Slot requirements**: `<sgds-file-upload>` slots require text labels (not just icons). Check if the component expects child elements, slot content, or JS properties.
159+
- **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.
160+
161+
### Form-Specific Constraints
162+
163+
From [reference/form.md](reference/form.md):
164+
165+
- Forms take exactly **8 columns** within `.sgds-container`
166+
- **Pairable fields** (Input, Select, Datepicker, Combo-box single-select): Take **6 columns each** at lg+ (4 columns at sm)
167+
- **Full-width fields** (Textarea, Checkbox-group, Radio-group, Combo-box multi-select, File-upload): Always 12 columns
168+
- **Grid math**: `sidebar_cols + form_cols + toc_cols ≤ 12`
169+
- **Multi-select combo-box**: ⚠️ CRITICAL — must be full-width, never pair with any other component
170+
171+
**Always cross-check** against [reference/form.md](reference/form.md) before coding.
172+
173+
---
174+
175+
## Building Custom Blocks
176+
177+
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:
178+
179+
| Requirement | How |
180+
|---|---|
181+
| **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). |
182+
| **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. |
183+
| **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. |
184+
| **Icons** | Use `<sgds-icon name="...">` exclusively. Do not embed raw SVG or third-party icon libraries. |
185+
| **External inspiration** | Fine to reference sites like [shadcnblocks.com](https://www.shadcnblocks.com/blocks/about), 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. |
186+
187+
→ Read **[reference/custom-block-rules.md](reference/custom-block-rules.md)** for the full token reference, anti-patterns, and annotated examples.
188+
189+
---
190+
191+
## For AI agents
192+
193+
### ⚠️ CRITICAL RULE — ALWAYS LOAD THESE SKILLS FIRST
194+
195+
Before you write ANY block code:
196+
197+
1. **LOAD `sgds-utilities` skill** — You need the complete utility class reference
198+
2. **LOAD `sgds-components` skill** — You need component APIs and child element names
199+
3. **Then READ `reference/custom-block-rules.md`** in this skill
200+
201+
**STYLING RULE (applies to ALL blocks):**
202+
- Use `sgds:` Tailwind utilities EXCLUSIVELY for spacing, colors, typography, layout
203+
- Use `<sgds-*>` components EXCLUSIVELY for UI elements
204+
- **NEVER use inline `<style>` blocks** to replicate design tokens (e.g., `margin: 24px`, `var(--sgds-*)`)
205+
- **NEVER write arbitrary CSS** that duplicates what design tokens already express
206+
207+
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.
208+
209+
---
210+
211+
### Agent workflow (in order)
212+
213+
1. Load `sgds-utilities` skill
214+
2. Load `sgds-components` skill
215+
3. Load this skill
216+
4. Read `reference/custom-block-rules.md`
217+
5. THEN write block code using utilities + components
218+
219+
### Guidelines
220+
221+
1. **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](reference/application-shell.md)** for layout patterns and container classes.
222+
2. When a user asks for a filtered list page, combine the Filter Sidebar block with the List Page template from **[sgds-templates](../sgds-templates/SKILL.md)**.
223+
3. Adapt category labels, values, and counts to the user's actual data domain — do not copy the conference example verbatim.
224+
4. 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](reference/custom-block-rules.md)** before generating any output.

0 commit comments

Comments
 (0)