Semantic Tokens
Semantic tokens associate primitive values with functional roles: brand, text, backgrounds, borders, states, and shadows. Always use semantic tokens in components — never raw primitives.
How to read token names
Knowing how to read token names will help you find the right token faster when working in design and in code.
color
.
brand
.
primary
A token name describes how it should be used. Each segment communicates one piece of its purpose.
1
Category
The type of design value: color, font, spacing, border. Always first — it describes what the token is technically.
colorfontspacingborder
2
Group
The semantic intent or UI context the token belongs to. This is the core meaning — it describes why the token exists.
brand— identity and primary actionstext— text content and linkssurface— background layersstate— feedback (danger, success, warning…)faculty— faculty-specific colorsnavigation— header, footer, menus
3
Variant
Optional detail about role, state, or emphasis. Omitted when the group alone is unambiguous (e.g. color.text for default body text).
primary/secondaryhoversubtle/muteddanger-bg/danger-textdroit-primary
Key principle: Choose tokens based on meaning, not visual appearance. Use
color.brand.primary because it represents the primary brand action — not because it happens to be blue #004687. When the brand evolves, only the primitive value changes; all semantic tokens follow automatically.
Token examples
| Token | CSS variable | Usage |
|---|---|---|
color.brand.primary |
--funid-color-brand-primary |
Primary buttons, key links, main brand color |
color.brand.primary-hover |
--funid-color-brand-primary-hover |
Hover state of primary interactive elements |
color.surface.page |
--funid-color-surface-page |
Main page background |
color.surface.brand |
--funid-color-surface-brand |
Dark blue hero sections |
color.text.primary |
--funid-color-text-primary |
Default body text |
color.text.secondary |
--funid-color-text-secondary |
Captions, metadata, muted labels |
color.state.danger-bg |
--funid-color-state-danger-bg |
Background of error messages |
color.state.focus |
--funid-color-state-focus |
Keyboard focus outline |
color.faculty.droit-primary |
--funid-color-faculty-droit-primary |
Faculty of Law — primary color |
color.navigation.header |
--funid-color-navigation-header |
Header background |
font.body.size |
--funid-font-body-size |
Default body font size |
font.heading.weight |
--funid-font-heading-weight |
Font weight for all heading levels |
Brand
$color-brand-primary
#004687
← $blue-500
$color-brand-primary-light
#A4C0E6
← $blue-100
$color-brand-primary-bg
#F5F8FD
← $blue-25
$color-brand-secondary
#0071B9
← $blue-300
$color-brand-secondary-light
#D7E3F5
← $blue-50
Text
| Token | Value | Primitive | Preview |
|---|---|---|---|
$color-text-default | #1D1D1D | $gray-1000 | Default text |
$color-text-subtle | #616161 | $gray-700 | Subtle text |
$color-text-muted | #9E9E9E | $gray-500 | Muted text |
$color-text-disabled | #BDBDBD | $gray-400 | Disabled text |
$color-text-link | #0071B9 | $blue-300 | Link |
$color-text-link-hover | #004687 | $blue-500 | Link hover |
$color-text-inverse | #FFFFFF | $gray-25 | Inverse text |
Backgrounds & Borders
| Token | Value | Primitive | Use case |
|---|---|---|---|
$color-bg-page | #FAFAFA | $gray-50 | Page background |
$color-bg-surface | #FFFFFF | $gray-25 | Cards, panels, sidebar |
$color-border-default | #D7E3F5 | $blue-50 | Dividers, section borders |
$color-border-subtle | #EEEEEE | $gray-200 | Card borders, inputs |
States
Success
$color-success-default
#749719
← $green-300
$color-success-light
#AECC53
← $green-100
$color-success-bg
#EBF2D4
← $green-25
$color-success-text
#5B7813
← $green-400
$color-success-border
#AECC53
← $green-100
Warning
$color-warning-default
#F39200
← $orange-300
$color-warning-light
#FBBE5E
← $orange-100
$color-warning-bg
#FFF7E9
← $orange-25
$color-warning-text
#CE7E00
← $orange-400
$color-warning-border
#FBBE5E
← $orange-100
Danger
$color-danger-default
#E30613
← $red-300
$color-danger-light
#F8C1C4
← $red-50
$color-danger-bg
#FCE6E7
← $red-25
$color-danger-text
#C00D0D
← $red-400
$color-danger-border
#F4A79A
← $red-100
Disabled
$color-disabled-default
#BDBDBD
← $gray-400
$color-disabled-bg
#EEEEEE
← $gray-200
$color-disabled-border
#E0E0E0
← $gray-300
$color-disabled-text
#BDBDBD
← $gray-400
Semantic border radii
| Token | Primitive | Value | Use case |
|---|---|---|---|
$radius-btn | $border-radius-md | 0.25rem | Buttons |
$radius-input | $border-radius-md | 0.25rem | Form inputs |
$radius-card | $border-radius-lg | 0.5rem | Cards |
$radius-tag | $border-radius-circle | 624rem | Tags & badges |
$radius-modal | $border-radius-lg | 0.5rem | Modals |
$radius-logo | — | 18.75% | Faculty icons |
Semantic shadows
| Token | Primitive | Use case |
|---|---|---|
$shadow-card | $box-shadow-sm | Slight card elevation |
$shadow-dropdown | $box-shadow-md | Dropdown menus |
$shadow-modal | $box-shadow-lg | Modals & dialogs |
$shadow-sticky | $box-shadow-sm | Sticky navbar |