Design systems showed the semantic tier — names that say what a color is for rather than what it literally is. Tonex's semantic layer is a specific vocabulary: the Material Design 3 color roles. A color is primary, surface, or error because of the job it does, and each role has a defined relationship to the others.
Tonex borrows the MD3 role names, not the Material look — themes are meant to look like your brand, with the roles as the contract underneath. The exact seed color stays available separately as the brand pair.
A portable contract
Because roles describe intent, the same system can be expressed in shadcn, in Tailwind, in Material JSON, or in a custom agent workflow and still be one color system. A target may call its main action color brand, accent, or primary — the role is the common language, and target-specific tokens are mappings from it.
The semantic source is the contract; the mapping is the last mile. See How Tonex Thinks for the handoff model.
The six families
Every role belongs to one of six families. Each family expands into fills, containers, and text partners — the table below is the starting point, not the full set.
| Family | Job |
|---|---|
primary | Main action or accent color |
secondary | Supporting accent |
tertiary | Third accent for contrast and range |
surface | Neutral backgrounds behind content |
error | Error states and destructive actions |
outline | Borders and dividers |
Fills and their text
Every colored area needs readable content on top of it. For each fill there's an on- partner — on-primary, on-surface, and so on — built to read against it. Tonex derives the pair together and checks the contrast, so the text on a color is readable by construction. See HCT for how tone makes that reliable, and Contrast for the audit.
Surfaces and elevation
The surface family is more than one color. It comes as a range of containers at increasing separation — a base surface, then container levels — so you can show depth and grouping through subtle steps rather than borders alone. Each derives from the same neutral and stays in order by contrast. See Surfaces for tuning them.
Special roles
A few roles exist for specific needs:
- Inverse surfaces and their on colors, for elements like tooltips and snackbars that stand out by flipping light and dark.
- Fixed roles, for stable accent values that should not invert across light and dark in the same way as the main roles.
- Scrim and shadow, the colors behind modals and under raised elements.
- Surface tint, the accent overlay that conveys elevation on tinted surfaces.
The full token set
The six families above expand into the canonical token set. When Tonex exports to a specific tool, each token maps to that tool's own name. For shadcn, see Role bindings.
| Core | Extended |
|---|---|
primary | primary-fixed |
on-primary | primary-fixed-dim |
primary-container | on-primary-fixed |
on-primary-container | on-primary-fixed-variant |
secondary | primary-dim |
on-secondary | secondary-fixed |
secondary-container | secondary-fixed-dim |
on-secondary-container | on-secondary-fixed |
tertiary | on-secondary-fixed-variant |
on-tertiary | secondary-dim |
tertiary-container | tertiary-fixed |
on-tertiary-container | tertiary-fixed-dim |
error | on-tertiary-fixed |
on-error | on-tertiary-fixed-variant |
error-container | tertiary-dim |
on-error-container | error-dim |
surface | surface-tint |
on-surface | inverse-surface |
on-surface-variant | inverse-on-surface |
surface-dim | inverse-primary |
surface-bright | shadow |
surface-container-lowest | scrim |
surface-container-low | |
surface-container | |
surface-container-high | |
surface-container-highest | |
outline | |
outline-variant |
Tonal palettes
If you need raw tonal palettes, Tonex can expose tone stops for primary, secondary, tertiary, neutral, neutral-variant, and error: 0, 5, 10, 15, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95, 98, 99, 100.