Foundations
Token naming
How SGDS names design tokens — the four-part pattern, the principles behind it, and worked examples for each token type.
Naming convention
SGDS tokens are named in four ordered parts: namespace, object, base, and modifier. Each part narrows the meaning, so a token name reads from the broadest system context down to a specific design attribute. The legend below names each position; the worked example shows how the parts combine for a real token.
- Namespace
The system name:
sgdsfor the Singapore Government Design System. - Object
The thing the token applies to: a group like
action, a component likebtn, or a context likeform. - Base
The design element or property: the role (
primary,danger), the property (bg,border,padding), or the concept (heading,body). - Modifier
The design attribute: emphasis (
default,muted,subtle,emphasis), state (hover,focus), or scale (md,lg,100,200).
Example breakdown
Anatomy by token type
Each token type uses the four positions slightly differently. The diagrams below show how primitive, semantic, and component tokens combine namespace, object, base, and modifier.
Primitive token
For primitive tokens, the name usually identifies a foundation scale and a step:
Semantic token (simplified)
Names a role, the property it controls, and the emphasis level.
Semantic token (granular)
Adds a context segment, such as form, when the decision is scoped to a specific surface.
Component token
Names a component, then the role, property, and emphasis scoped to that component.
Naming principles
We follow five principles when naming SGDS tokens. They explain the choices behind every name shown above.
- Short: keep names compact enough to scan in code, design tools, and documentation.
- Meaningful: name the decision, not the current value. Prefer role-based words like
danger,warning,success,surface,border-color,heading, andbody. - Scalable: choose names that can support more products, themes, states, and component variants over time.
- Flexible: keep shared tokens broad enough for reuse. Add context, such as
formorbtn, only when the decision is genuinely scoped. - Clear: make each segment easy to understand without resolving the token value.
Full naming structure
For the full picture, the chart below maps every position, segment, and modifier the system can produce. Use it as the reference whenever a new token name needs to slot into the system.
Worked example
The button-with-hover-state example below traces every position through a real token name, from primitive to component.