Skip to content
KinetixUI

Tokens

KinetixUI's design decisions (colour, spacing, radius, type, motion) live in one set of DTCG token files. Style Dictionary compiles them into each platform's own idiom: CSS custom properties and a typed object for the web, Swift for iOS, Kotlin for Android and Dart for Flutter. The generated files are committed, so you can read every platform's output without building anything.

Tokens are generated; components are not. Each platform's components are written natively against the same token contract, which is why a SwiftUI button behaves like a SwiftUI button. See Platforms for what is implemented where.

Architecture#

tokens/**/*.json            DTCG source: the only place a value is written
  │
  ▼  style-dictionary/build.mjs   (Style Dictionary, once per theme)
  │
packages/tokens/dist/
  ├─ web/       CSS custom properties + typed TypeScript object
  ├─ ios/       Swift
  ├─ android/   Kotlin + Android XML resources
  └─ flutter/   Dart

The source is organised in two layers:

tokens/
├─ primitives/
│  ├─ color.json        11 colour ramps (Kinetic Weave indigo/violet/cyan/navy + the inherited
│  │                    azure, blue, green, taupe, cream, amber, red) + synthesized neutral + static
│  ├─ dimension.json    spacing, radius, border width
│  ├─ typography.json   Material-3 scale, Montserrat
│  ├─ motion.json       duration + easing (cubicBezier)
│  ├─ opacity.json      hidden/disabled/muted/visible scale
│  ├─ interaction.json  target size, focus ring, press, drag threshold
│  └─ z-index.json      base/raised/docked/focus/sticky/overlay scale
└─ semantic/
   ├─ color.light.json  aliases → semantic contract
   ├─ color.dark.json   the same names, dark values
   ├─ shadow.json       elevation + focus ring (+ shadow.dark.json)
   └─ typography.json   composite text styles

All DTCG format ($value / $type). The palette, spacing and type scale originate in the KinetixUI Figma file; once a value is in these files it is authoritative, and the dark theme, motion, opacity and z-index are owned here rather than in Figma (TOKENS.md records every decision).

The build is a repository step, not something you run to use the tokens:

pnpm build:tokens   # node style-dictionary/build.mjs — maintainers, inside this repository

CI runs the same build and fails if the committed output differs from a fresh generation, so a generated file cannot be hand-edited without the pull request going red.

Primitive and semantic tokens#

Primitives are the palette and scales: color.indigo.600, spacing.4, radius.md. They say what a value is.

Semantic tokens say what a value is for: color.primary, color.card, color.border, color.ring. Components read only semantic tokens. A semantic token is usually an alias of a primitive, which is how two roles can share a value today and diverge later with a one-line change. The light theme's primary and ring both resolve to color.indigo.600; brand is the Kinetic Weave identity indigo color.indigo.500, which primary is deliberately a step away from so the interactive colour can hold contrast without moving the identity.

One token on every platform#

Here is color.primary, the interactive colour, from its source definition to the declaration each platform's generated file contains. Every line below is read from the repository's DTCG source and from packages/tokens/dist when this page is built (excerpts: each file holds the full set).

Source — DTCG, in tokens/
TokenTheme$valueFile
color.primarylight{color.indigo.600}semantic/color.light.json
color.primarydark{color.indigo.300}semantic/color.dark.json
color.indigo.600primitive#5143DBprimitives/color.json
color.indigo.300primitive#BBB3FFprimitives/color.json
Web · CSSuse as hsl(var(--primary))
/* web/globals.css */:root {  --indigo-600: 246 68% 56%;  --primary: var(--indigo-600);} /* web/globals.dark.css */.dark {  --primary: 246 100% 85%;}
iOS · Swift · SwiftUIuse as KinetixColorsSwiftUI.primary
// ios/KinetixColorsSwiftUI.swiftpublic enum KinetixColorsSwiftUI {    public static let primary = Color(red: 0.318, green: 0.263, blue: 0.859)} // ios/KinetixColorsSwiftUI.dark.swiftpublic enum KinetixColorsSwiftUIDark {    public static let primary = Color(red: 0.733, green: 0.702, blue: 1)}
Android · Kotlin · Jetpack Composeuse as KinetixTheme.colorPrimary
// android/Theme.ktobject KinetixTheme {  val colorPrimary = Color(0xff5143db)} // android/Theme.dark.ktobject KinetixThemeDark {  val colorPrimary = Color(0xffbbb3ff)}
Flutter · Dart · Flutteruse as KinetixColorScheme.primary
// flutter/kinetix_color_scheme.dartclass KinetixColorScheme {  static const primary = Color(0xFF5143DB);} // flutter/kinetix_color_scheme.dark.dartclass KinetixColorSchemeDark {  static const primary = Color(0xFFBBB3FF);}

The names follow each language's convention and the values follow each platform's colour type: an HSL channel triplet for CSS, sRGB components for SwiftUI, ARGB integers for Compose and Flutter. They are the same colour. A test resolves every one of them back to the source hex and fails if a platform disagrees.

Light and dark#

Dark is a second set of values for the same semantic names, not a second set of names. primary means "interactive colour" in both themes; only its value changes, from indigo.600 to the lighter indigo.300 that holds contrast on a dark surface. brand moves independently — identity indigo in light, Soft Violet in dark — which is why the two roles exist separately.

Style Dictionary runs once per theme, because two files defining the same token path would collide in a single run. The light pass emits every platform; the dark pass emits the web globals.dark.css and the native semantic theme files that need real dark values: Theme.dark.kt (Compose), KinetixColorsSwiftUI.dark.swift (SwiftUI) and kinetix_color_scheme.dark.dart (Flutter).

On the web, dark applies under a .dark ancestor; see Dark mode. The semantic foreground and background pairs components render are checked against WCAG AA contrast in CI (check:contrast, on the resolved source values), in both themes; on iOS, swift test repeats the check on the generated Swift colour sets themselves.

Platform outputs#

PlatformFiles
Webweb/globals.css, web/globals.dark.css, web/tokens.ts; web/extras.css + .dark.css (shadows, text styles)
iOSios/KinetixColors.swift, ios/Theme.swift (UIColor), ios/KinetixType.swift; ios/KinetixColorsSwiftUI.swift + .dark.swift (SwiftUI Color, for packages/ui-swiftui); ios/KinetixMotion.swift
Androidandroid/Color.kt, android/Theme.kt + Theme.dark.kt, android/KinetixType.kt, res/values/{colors,dimens}.xml; android/KinetixMotion.kt
Flutterflutter/app_colors.dart, flutter/app_theme.dart, flutter/app_text.dart; flutter/kinetix_color_scheme.dart + .dark.dart (for packages/ui-flutter); flutter/kinetix_shadow.dart + .dark.dart; flutter/kinetix_motion.dart

The KinetixColorsSwiftUI / KinetixColorScheme pairs are additive: the older Theme.swift / app_theme.dart outputs (light-only, colliding class names) are untouched. See SwiftUI and Flutter for why.

Using the tokens#

What you can adopt today depends on the platform. Generated output exists for all four; a package you can install exists for the web only.

PlatformGenerated outputHow you get it todayPackage registryAdapter for stock UI
WebYes@kinetixui/tokens from npmnpmTailwind preset in @kinetixui/ui
iOS (SwiftUI)YesCopy the Swift files from dist/ios into your projectNone: not on Swift Package Manager or CocoaPodsNone for stock SwiftUI views
Android (Compose)YesCopy the Kotlin files from dist/android into your projectNone: not on Maven CentralNone for stock Material components
FlutterYesCopy the Dart files from dist/flutter, or depend on kinetix_ui from a repository checkoutNone: not on pub.devKinetixMaterialTheme, KinetixCupertinoTheme (in kinetix_ui)

Web#

npm install @kinetixui/tokens

Import the stylesheets once, globally. Light is the base; dark applies under a .dark ancestor. The extras pair carries the shadow and type ramps and the focus ring, and its dark half the dark focus halo.

@import "@kinetixui/tokens/css";
@import "@kinetixui/tokens/css/dark";
@import "@kinetixui/tokens/css/extras";
@import "@kinetixui/tokens/css/extras/dark";

Then refer to semantic roles, never to a raw value:

.panel {
  background: hsl(var(--card));
  color: hsl(var(--card-foreground));
  border: 1px solid hsl(var(--border));
  border-radius: var(--radius-control);
}

The typed object is import { tokens } from "@kinetixui/tokens". Tailwind projects should use the preset from @kinetixui/ui/tailwind.config, which maps these variables onto Tailwind's scales. The Installation page covers the other web route, the CLI, which writes the same variables into your own stylesheet.

This page is built from the repository's current output. The npm package carries the output of its last release and can trail it in between; the changelog lists what each release contains.

iOS, Android and Flutter#

The generated Swift, Kotlin and Dart files are real, and they are the same values as the web output. What does not exist yet is a native package: none of them is on Swift Package Manager, Maven Central or pub.dev. To use them today you vendor the files: copy them from dist/ios, dist/android or dist/flutter, which are in the repository and inside the @kinetixui/tokens npm tarball. You then update them by copying again.

Two things change that on Flutter. KinetixMaterialTheme and KinetixCupertinoTheme turn the tokens into a Material ThemeData or a CupertinoThemeData, so stock widgets you already use take on the colours, radius and type scale without any Kinetix widget in the tree; see Using KinetixUI without Kinetix widgets. They live in the kinetix_ui package, which is consumed from a repository checkout, not from pub.dev.

SwiftUI and Compose have no equivalent adapter for stock controls yet. Their KinetixTheme supplies the token colours to KinetixUI's own native components; see SwiftUI and Jetpack Compose.

Why tokens are generated and components are not#

A token is a named value. Translating color.primary into a CSS custom property, a Swift Color, a Kotlin constant and a Dart Color is mechanical, and it is checkable: the test described above resolves every platform's value back to the source and fails if one disagrees. So the translation is generated, and nobody types a value twice.

A component is behaviour as well as values: how focus moves, which gestures it answers, which accessibility API announces it, how it mirrors in a right-to-left layout. Those differ per platform, and a generator would have to pick one platform's answer for all of them. KinetixUI writes each platform's components by hand against the same token contract instead, and says how far each implementation is tested on Supported platforms rather than assuming that shared tokens mean shared behaviour.

Further reading: Generated tokens vs generated components.

See the tokens in a component#

The Button is the most direct place to watch this token at work. Its primary variant fills with action, which aliases primary; its label is action-foreground; its keyboard focus is the shadow.focus ring, drawn in the same indigo; its corners are the md radius and its padding comes from the spacing scale. On its page:

  • Toggle the site theme and the fill moves from indigo.600 to indigo.300 with no change to the component, because only the token's value changed.
  • Tab to a button to see the focus ring, and hover or press it to see the fill step down to action at 90% and 85%, values bounded by the contrast check rather than chosen by eye.
  • Open the Code tab and switch platform to read the SwiftUI, Compose and Flutter implementations. Each is written natively, and each reads the same action role from its platform's generated tokens.

Next steps#

Reference#

Semantic contract#

The values every component actually resolves to, in both themes:

TokenLightDark
--background#ffffff#0c1229
--foreground#17233d#f6f7fc
--cardsynthesized#ffffff#1c2945
--popoversynthesized#ffffff#1c2945
--primaryaccessible action step; identity stays on brand#5143db#bbb3ff
--primary-foreground#f6f7fc#0c1229
--secondary#c7cfc7#2e362e
--secondary-foreground#465245#e3e7e3
--muted#f6f6f6#283656
--muted-foreground#6d6d6d#adb8d1
--surface-groupedgrouped section under a card#f6f6f6#111b35
--accent#f0eeff#283656
--accent-foreground#5143db#f6f7fc
--destructivestepped for AA on the Kinetic Weave dark surfaces#c60a0a#e89999
--success#5d6d5c#90a08f
--warningdarkened for AA#7f5b21#ffc975
--border#92b2c8#4a5673
--ringsynthesized#5143db#bbb3ff
--brandidentity — Kinetic Weave indigo / violet#6054f4#a78bfa
--brand-foreground#f6f7fc#0c1229
--actiondefaults to primary#5143db#bbb3ff
--action-foregrounddefaults to primary-foreground#f6f7fc#0c1229
--action-hoveraction @ 90% — native#6256df#aaa3ea
--action-pressedaction @ 85% — native#6b5fe0#a19bdf
--linkdefaults to primary#5143db#bbb3ff
--focusdefaults to ring#5143db#bbb3ff

Motion and scale#

duration, easing, opacity, and z-index are theme-independent, like typography — defined once, the same in light and dark. Each platform's output groups them into KinetixDuration / KinetixEasing / KinetixOpacity / KinetixZIndex (native — which also get the spatial scale as KinetixSpacing and KinetixRadius, see Foundations) or --duration-* / --easing-* / --opacity-* / --z-index-* custom properties (web), and packages/ui's tailwind.config.ts wires the web ones into real Tailwind utilities — duration-fast, ease-standard, opacity-disabled, z-overlay — used directly in component source instead of the ad hoc duration-200 / z-50 literals components used to carry. A handful of pre-existing values that don't cleanly match a token step (e.g. a couple of opacity-40/opacity-60 icon dimmings) are left as literals with a comment, rather than silently changed to the nearest token.

Motion tokens not yet consumed by components: easing.emphasized (reserved for travelling selection indicators; see the motion roles in Foundations) and duration.slower (reserved for loop periods; no loop reads it yet). Both are generated for every platform and reachable as ease-emphasized and duration-slower. The other durations and easings are in use.

Newly defined, not yet consumed by components: the larger spacing steps (spacing.10–spacing.32, 40–128) and radius.xxl (24). They are part of the contract and generated for every platform, but no component reads them yet — adopting them is incremental, component by component.

Interaction tokens#

Behavioral values, not visual ones — how big a target has to be, how far a focus ring sits, how a press or a drag reads. Theme-independent, like motion:

TokenValueWired up?
interaction.target.minimum44pxNot yet — WCAG 2.5.5 (AAA) / iOS HIG / Material's converged minimum hit-target size. No component in this package currently has an explicit hit-target smaller than 44px that would benefit without a bigger layout change (Checkbox/Radio/Switch's ~18–20px visual controls rely on callers wrapping them in a Label for the larger click area, the same pattern their Radix primitives assume) — defined for app authors and future components to reach for, not retrofitted here.
interaction.target.default40pxNot yet — the default a standalone control should target when nothing else constrains its size.
interaction.focus.width1pxYes — backs the spread of every shadow.focus* entry's inner layer (tokens/semantic/shadow.json), replacing a hardcoded literal. Compiled CSS output is unchanged (still 0 0 0 1px …).
interaction.focus.offset2pxNot yet as a token reference — matches the dominant ring-offset-2 already used across packages/ui/src/components (4 of 6 current call sites; the other 2 intentionally use ring-offset-1 for tightly-bordered controls). Tailwind's ring-offset-* utilities are static classes, not CSS-var-driven, so wiring this one needs either a custom Tailwind token or a run of literal replacements — left for a follow-up slice.
interaction.press.opacity0.8Not yet — Button's own active state is a color shift (active:bg-primary/90), not opacity-based, so there's no current opacity-driven press consumer to point this at. Defined for components that do reach for opacity feedback.
interaction.drag.threshold4Yes — KanbanBoard's PointerSensor activationConstraint.distance, via tokens.interaction.drag.threshold imported from @kinetixui/tokens. Matches the value KanbanBoard already shipped tuned at, not dnd-kit's textbook default of 8 — this token records the deliberate existing value rather than silently changing drag feel.

Web-only in this slice — none of the native platform ports (ui-compose, ui-swiftui, ui-flutter) consume interaction.* yet.

Deviations from raw Figma#

The build fixes the Primay typo, rounds letterSpacing float artifacts, and synthesizes what Figma lacks (--card, --popover, --ring, the neutral ramp, the dark theme, radius.lg, spacing.7). Each is documented in TOKENS.md with its rationale.