SGDS organises tokens in a layered architecture. Each layer references the layer below it, so a single change cascades through the system. SGDS defines five token types. Each type has a different scope and a different rule for when to use it.
Raw values refer to the actual, hard-coded values, such as #5A42C0 for colours or 16px for spacing, used within design tokens.
Primitive tokens, also called Global or Core tokens, are the foundational tokens that define the core values of the design system. They represent the most fundamental design decisions, such as base colours, typography, spacing, and sizing.
Simplified semantic tokens, also called Alias tokens, provide a more general abstraction of the design system. They are broader and easier to use across various components and contexts. The focus is on simplifying how you access design decisions, particularly for common use cases.
Granular semantic tokens, also called Alias tokens, are more specific and tailored for particular components, groups, or contexts, such as forms, actions, and feedback. Granular tokens allow for more detailed control over styling decisions and can vary depending on the specific requirements of different design elements.
Component-specific tokens are used to customise or refine design elements for individual components. They reference global or alias tokens and apply them to specific components like buttons, cards, or modals.
Token categories
SGDS tokens group into the following categories, each covering one design dimension.
Some token values adapt across SGDS breakpoints. Typography, line-height, layout gap, component padding, and container width tokens keep the same name, but resolve to different primitive values on mobile, tablet, and desktop. These mappings live in themes/responsive.css.
Responsive remapping is not a separate token type. The token name stays the same; only the resolved value changes.
Start with simplified semantic tokens when the UI role is clear. Reach for granular semantic tokens when a context like forms, actions, or feedback needs a scoped variant. Use primitive tokens when documenting the system, defining a new semantic alias, or working with a low-level foundation scale. Use component hooks only when the component documentation exposes them.
Token changes affect different parts of the system depending on the token type and how widely it is used. Use this guide before adding, modifying, or removing tokens.
Adding tokens
Impact: Low to medium, depending on usage. New tokens increase the library's size and flexibility, but usually have little immediate impact until they are tied to components or styles.
Risks: Can lead to token bloat when added without a clear need. Teams also need guidance on when and how to use the new token.
Criteria: Check that the token solves a real design need, aligns with SGDS principles, and cannot be replaced by an existing token.
Process: Identify the gap, propose a name, value, and use case, submit it for review, then document and implement it after approval.
Modifying tokens
Impact: High, especially for semantic or primitive tokens. Changing a token value affects every component, style, and interface that references it.
Risks: Can introduce visual bugs or inconsistencies if dependencies are unclear. Large changes may become breaking changes.
Criteria: Use this for accessibility improvements, performance improvements, or alignment with updated design guidance.
Process: Audit token usage across design and code, propose the change with reasoning and comparisons, test it in staging, then announce and release it with a migration plan.
Removing tokens
Impact: Medium to high, depending on usage. Removing a token breaks any component or style that still relies on it.
Risks: Can cause production issues if the token is still active. Teams need deprecation warnings and clear alternatives.
Criteria: Remove a token only when it is unused, redundant, or no longer aligned with the system.
Process: Mark the token as deprecated, announce the deprecation with a transition period, then remove it only after no dependencies remain.
Singapore Government Design System
The Singapore Government Design System was developed to empower teams in creating fast, accessible and mobile-friendly digital services.