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):default|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 — neutral, no-valence status ("Auto-saved") | semantic.colors.feedback.primary.{background,border,text} |
| Toast / alert — informative (info / in-progress / new) | semantic.colors.feedback.accent.{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 |
| Destructive ink on a part that paints no surface (quiet menu row / text action) | semantic.consequence.destructive.ink |
| Valence ink on a part that reports an outcome and paints no surface (status mark, summary) | semantic.valence.{positive|caution|negative}.ink |
Unfilled part of a ProgressBar/Meter/Slider track (darkens in dark mode, unlike a border) | semantic.rail.track |
| Edge of a surface that covers content (popover, menu, tooltip, dialog, drawer, toast) | semantic.overlay.outline |
| Edge of a surface in the flow (card, panel, divider) | semantic.colors.informational.{role}.border |
Full grammar + role decision table: Colors.
Spacing — by intent
| I want… | Token |
|---|---|
| Padding inside a button/input | semantic.spacing.inset.control.{sm,md,lg} |
| Block (vertical) padding of a command trigger (CTA taller than generic controls) | semantic.spacing.inset.action.block |
| Padding inside a card/surface | semantic.spacing.inset.surface.{sm,md,lg} |
| Gutter inside an anchored surface or a row container (popover, menu, tooltip, list) | semantic.spacing.inset.surface.xs |
| 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 |
Glyph on the same line as text (button icon, chevron — resolves to 1em) | semantic.sizing.icon.text |
| Standalone icon | 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 (page shell / content column) max width | semantic.sizing.surface.maxWidth |
| Narrow standalone centered card (auth form, confirmation) | semantic.sizing.surface.card |
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, form label, badge | semantic.text.label.{lg,md,sm} |
| Command trigger label (Button CTA) | semantic.text.action.md |
| 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 + offset) | semantic.focus.ring.{width,style,offset} |
| Focus ring color | see Borders § Which focus colour |
| Command trigger / CTA radius (pill in the base theme) | semantic.radii.action |
| Control corner radius (inputs, utility triggers) | 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.