sgds-getting-started
Getting Started with 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.
Step 1 — Set the Font
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.
<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
Import these files in your project's main CSS entry point (the file processed by your build tool):
/* 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.
Step 3 — Register SGDS Web Components
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.
Step 4 — Use an SGDS App Layout
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):
<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):
<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.
For AI agents
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.cssmust be imported inside a CSS file processed by Tailwind v4 — importing it directly in JavaScript will not generate thesgds: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 rawsgds: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.
More from govtechsg/sgds-web-component
sgds-components
Complete reference for all SGDS web components including installation and framework integration. Use when users ask about any <sgds-*> component — accordion, alert, badge, breadcrumb, button, card, checkbox, close-button, combo-box, datepicker, description-list, divider, drawer, dropdown, file-upload, footer, icon, icon-button, icon-card, icon-list, image-card, input, link, mainnav, masthead, modal, overflow-menu, pagination, progress-bar, quantity-toggle, radio, select, sidebar, sidenav, skeleton, spinner, stepper, subnav, switch, system-banner, tab, table, table-of-contents, textarea, thumbnail-card, toast, or tooltip. Also covers React 19+, React ≤18, Vue, Angular, and Next.js integration.
58sgds-theming
Customising the visual theme of an SGDS application — product brand colours, day/night mode, and font. Use when users ask about changing the primary colour, theming their app, enabling dark mode, night mode, overriding CSS tokens, or customising the font. Apply this skill whenever theming, branding, or CSS token overrides are mentioned.
55sgds-workflow
ALWAYS use this skill when building UI with @govtechsg/sgds-web-component or when a user mentions SGDS or Singapore Design System — even if they don't explicitly ask for help. This is the mandatory entry point for all SGDS development: it guides you to the right skill for setup, components, utilities, forms, theming, page layouts, block templates, and data visualisation. Read this before writing any SGDS application code.
53sgds-data-visualisation
Use this skill when users ask about data visualisation, charts, graphs, or dashboards in an SGDS application. Covers ECharts setup and applying the SGDS colour palette to charts.
53sgds-forms
Use this skill when users ask about form validation in SGDS, hasFeedback prop, constraint validation, custom validation, noValidate, setInvalid, form submission, or reading FormData from SGDS form components.
53sgds-utilities
Complete reference for all SGDS utility classes with the sgds: prefix. Use when users ask about setup, background-color, text-color, border-color, border-width, border-radius, typography, spacing, grid, dimension, opacity, color-semantics, or any sgds: Tailwind utility class. Also covers Tailwind v4 imports, theme switching, and framework integration for utilities.
53