Design primitives are basic building blocks that a design system uses to compose more specific decisions or interfaces. In a token model, a primitive usually means a named base value. In a component library, it can mean a small reusable component for a basic task such as layout.
What are primitive tokens?
A primitive token names a base value such as a palette color or a spacing step. For example, space.200 might represent 8 pixels. A token scoped to a component, such as card.padding, can reference it. The base token gives multiple decisions a shared value, while the card token identifies the decision the component is using.
| Term | Example | What it provides |
|---|---|---|
| Primitive token | space.200 |
A named value on a spacing scale |
| Semantic token | color.text.link |
A value for a named purpose |
| Primitive component | Stack | A reusable way to arrange elements vertically |
These layers are conventions. A team may let a layout component expose steps from a spacing scale and use semantic color tokens for interface text. Document the choice so teams can tell which values are intended for direct use.
What does a primitive component do?
A layout primitive provides a small piece of reusable structure. Atlassian’s primitives include Stack for vertical arrangement and Inline for horizontal arrangement. A team could use a Stack to arrange a field label, input, and hint with a consistent gap. The field component still defines how those parts relate and how errors are communicated.
When should you change a base value?
Suppose cards need more padding, while form layouts should stay as they are. Find the token or setting specific to cards and choose the spacing value it should use. If you change the base scale itself, trace its references and check representative screens. The same step may set card padding and the gaps between form fields.
Start with base values and components that solve recurring problems. Add a named layer when it helps people understand a decision or change it at the right scope.