Flint Design System
Workbench

Guides

Token tiers

Flint has three tiers. Each points at the one below it, so a change at the bottom flows everywhere above it, and nothing above can drift.

The three tiers

TierExampleUse it for
Primitivecolor.blue.700, space.16, radius.smNothing in UI. Primitives only feed the tiers above.
Semantictext.link points at color.blue.700Colors and roles in UI: surfaces, text, borders, feedback, charts.
Componentbutton.primary.bg points at semantic.action.primaryThe decisions a component makes, shared by MUI, shadcn, CSS and SwiftUI.

References

Semantic colors exist twice, once per mode, and each points at a ladder step. Component tokens point at a semantic token without naming a mode, so they follow light and dark on their own. The build resolves every reference and fails on one that points nowhere.

tokens.json 
"semantic": {
  "light": { "text": { "link": "{color.blue.700}" } },
  "dark":  { "text": { "link": "{color.blue.300}" } }
},
"component": {
  "button": { "primary": { "bg": "{semantic.action.primary}" } }
}

One token, every name

FigmaCSSJSSwift
text/link--color-text-linksemantic.light.text.linkFlint.Colors.textLink
feedback/success/text--color-feedback-success-textsemantic.light.feedback.success.textFlint.Colors.feedbackSuccessText
button/primary/bg--button-primary-bgcomponent.light.button.primary.bgFlint.Component.buttonPrimaryBg

Figma uses slashes, CSS uses kebab-case with a prefix, JS keeps the path, Swift joins the path in camelCase.

Adding or changing a token

  1. Edit tokens.json. Point at an existing token with a reference wherever you can.
  2. Run npm run build. It rebuilds every output, then runs the contrast, usage and parity checks.
  3. Check the result in these docs and in the workbench, light and dark.
  4. Bump the version: a new token is a minor, a value fix is a patch, a rename or removal is a major.