Quick Reference
Intent → token cheatsheet. Pick tokens fast here; read the family docs for the full contract.
This page is the single source for the intent → token mapping — the @ttoss/fsl-theme README links here rather than carrying its own copy. The one deliberate duplicate is the package's llms.txt, which ships the same mapping inside the npm tarball so agents have it offline.
Rule of thumb: components consume semantic tokens only. If the token you need is not listed, check the family doc; if it still does not exist, open a governance request.
Grammar reminder:
- colors:
semantic.colors.{ux}.{role}.{dimension}.{state?}ux:action|input|navigation|feedback|informationalrole:primary|secondary|accent|muted|positive|caution|negativedimension:background|border|textstate(optional):hover|active|focused|disabled|selected|pressed|checked|indeterminate|expanded|current|visited|droptarget|invalid(legality varies perux— see colors.md)
- everything else:
semantic.{family}.{group}.{step?}
Colors — by intent
| I want… | Token |
|---|---|
| Primary button (filled, strongest CTA) | semantic.colors.action.primary.{background,border,text} |
| Secondary button (neutral chrome) | semantic.colors.action.secondary.{background,border,text} |
| Accent button (brand color, high emphasis) | semantic.colors.action.accent.{background,border,text} |
| Destructive button | semantic.colors.action.negative.{background,border,text} |
| Ghost / low-emphasis button | semantic.colors.action.muted.{background,border,text} |
| Text input (default) | semantic.colors.input.primary.{background,border,text} |
| Text input (error) | semantic.colors.input.negative.{background,border,text} |
| Text input (success / validated) | semantic.colors.input.positive.{background,border,text} |
| Text input (warning) | semantic.colors.input.caution.{background,border,text} |
| Nav link (default / current / visited) | semantic.colors.navigation.primary.text.{default,current,visited} |
| Toast / alert — info | semantic.colors.feedback.primary.{background,border,text} |
| Toast / alert — success | semantic.colors.feedback.positive.{background,border,text} |
| Toast / alert — warning | semantic.colors.feedback.caution.{background,border,text} |
| Toast / alert — error | semantic.colors.feedback.negative.{background,border,text} |
| Page / content body text | semantic.colors.informational.primary.text |
| Muted / helper text | semantic.colors.informational.muted.text |
| Page background | semantic.colors.informational.primary.background |
| Divider line | semantic.colors.informational.muted.border |
Focus ring color (system default — use when no {ux} applies) | semantic.focus.ring.color |
Focus ring color (per-context — {ux} is Action / Input / Navigation / Feedback) | semantic.colors.{ux}.{role}.border.focused |
Full grammar + role decision table: Colors.
Spacing — by intent
| I want… | Token |
|---|---|
| Padding inside a button/input | semantic.spacing.inset.control.{sm,md,lg} |
| Padding inside a card/surface | semantic.spacing.inset.surface.{sm,md,lg} |
| Gap between stacked items (form fields) | semantic.spacing.gap.stack.{xs,sm,md,lg,xl} |
| Gap between inline items (icon + label) | semantic.spacing.gap.inline.{xs,sm,md,lg,xl} |
| Page horizontal gutter (responsive) | semantic.spacing.gutter.page |
| Section vertical gutter (responsive) | semantic.spacing.gutter.section |
| Minimum distance between hit targets | semantic.spacing.separation.interactive.min |
See Spacing.
Sizing — by intent
| I want… | Token |
|---|---|
| Hit target (min interactive floor) | semantic.sizing.hit |
| Inline icon with text | semantic.sizing.icon.{sm,md,lg} |
| Avatar / identity chip | semantic.sizing.identity.{sm,md,lg,xl} |
| Paragraph max reading width | semantic.sizing.measure.reading |
| Surface (card/dialog) max width | semantic.sizing.surface.maxWidth |
See Sizing.
Typography — by intent
Token prefix: semantic.text.
| I want… | Token |
|---|---|
| Hero / marketing title | semantic.text.display.{lg,md,sm} |
| Page title / top-level headline | semantic.text.headline.{lg,md,sm} |
| Section / card title | semantic.text.title.{lg,md,sm} |
| Paragraph / body copy | semantic.text.body.{lg,md,sm} |
| UI label, button label, form label | semantic.text.label.{lg,md,sm} |
| Inline / block code | semantic.text.code.{md,sm} |
See Typography.
Borders, radii, elevation — by intent
| I want… | Token |
|---|---|
| 1px divider (width + style) | semantic.border.divider.{width,style} |
| Control outline (button, input) | semantic.border.outline.control.{width,style} |
| Surface outline (card) | semantic.border.outline.surface.{width,style} |
| Selected-state line | semantic.border.outline.selected.{width,style} |
| Focus ring (width + style) | semantic.focus.ring.{width,style} |
| Focus ring color | see Borders § Which focus colour |
| Control corner radius (buttons, inputs) | semantic.radii.control |
| Surface corner radius (cards, dialogs) | semantic.radii.surface |
| Pill / fully round | semantic.radii.round |
| Resting surface (no shadow) | semantic.elevation.surface.flat |
| Card shadow | semantic.elevation.surface.raised |
| Dropdown / popover shadow | semantic.elevation.surface.overlay |
| Modal / drawer shadow | semantic.elevation.surface.blocking |
See Borders, Radii, Elevation.
Motion, opacity, z-index — by intent
| I want… | Token |
|---|---|
| Immediate UI feedback (hover, press) | semantic.motion.feedback.{duration,easing} |
| Element entering the screen | semantic.motion.transition.enter.{duration,easing} |
| Element leaving the screen | semantic.motion.transition.exit.{duration,easing} |
| Attention / emphasis animation | semantic.motion.emphasis.{duration,easing} |
| Decorative / ambient animation | semantic.motion.decorative.{duration,easing} |
| Scrim over content | semantic.opacity.scrim |
| Loading / in-progress dim | semantic.opacity.loading |
| Disabled dim | semantic.opacity.disabled |
| Document flow layer | semantic.zIndex.layer.base |
| Sticky header / toolbar | semantic.zIndex.layer.sticky |
| Dropdown / popover / tooltip | semantic.zIndex.layer.overlay |
| Modal / drawer (blocks interaction) | semantic.zIndex.layer.blocking |
| Toast / snackbar (transient, non-blocking) | semantic.zIndex.layer.transient |
Data visualization — by intent
| I want… | Token |
|---|---|
| Nth categorical series color | semantic.dataviz.color.series.{1..8} |
| Sequential (ordered) scale step | semantic.dataviz.color.scale.sequential.{1..7} |
| Diverging scale step | semantic.dataviz.color.scale.diverging.{neg3..pos3} |
| Reference line (target/baseline) | semantic.dataviz.color.reference.{baseline,target} |
| Highlighted / selected series | semantic.dataviz.color.state.{highlight,selected} |
| De-emphasized (context) series | semantic.dataviz.color.state.muted |
| Missing / not-applicable data | semantic.dataviz.color.status.{missing,suppressed,notApplicable} |
| Non-color differentiator — shape | semantic.dataviz.encoding.shape.series.{1..8} |
| Non-color differentiator — pattern | semantic.dataviz.encoding.pattern.series.{1..6} |
| Analytical stroke role | semantic.dataviz.encoding.stroke.{reference,forecast,uncertainty} |
See Data Visualization.
If you can't find what you need
- Token missing → read the family doc; if still absent, open a governance request.
- Want a raw value → you need a new semantic token, not a core reference. Core is never consumed by components.
- Repeating the same combo in many places → extract a component or pattern, not a new token.
- Building a chart → start in Data Visualization, not in foundation colors.