Skip to content
KinetixUI

Theming

KinetixUI colour is built in four layers, and a product team should only ever need to touch the second one.

primitive palette   azure.700 = #1d4ed8         tokens/primitives/color.json   (raw ramps, never themed)
        ↓
semantic role       primary = {color.azure.700}  tokens/semantic/color.light.json / color.dark.json
        ↓
theme               :root { … }  .dark { … }     the generated CSS / Swift / Kotlin / Dart, plus your overrides
        ↓
component           Button → bg-action, focus ring → --focus, Input border → --input

Components reference semantic roles — no component in @kinetixui/ui, @kinetixui/angular or the native ports reads a colour ramp directly (the one primitive read is static.white, for the Angular switch thumb; the colour-picker visualisation is the other reviewed exception, and pnpm check:component-colors holds the line). That is what makes a rebrand a theme change rather than a component change: you move --primary, and every button, checkbox, tab and focus ring that means "interactive" moves with it. Edit a component instead and the next one you forget keeps the old colour.

Choose how much to customise#

LevelYou changeWhereWho it is for
Simpleone theme colour (plus neutral, radius, surface)Createmost teams: a brand colour, safe light + dark roles derived for you
Advancedindividual semantic roles (--background, --action, --focus, …)Create's Advanced panel, or a CSS / native overridebrands that need a specific surface, status or focus colour
Expertthe DTCG token sourcetokens/** in a fork, then pnpm build:tokensteams maintaining their own distribution of the system

Start at Simple. Create derives action, hover, pressed, foreground, accent, link and focus from one colour in OKLCH, in both appearances, and holds every generated text pair to WCAG AA; the export is the override block (or native KinetixColors pair) your app pastes in. Reach for Advanced only for the roles Create cannot infer from a brand.

Brand colour is not always a UI colour#

A brand hex is an identity value. It is not guaranteed to work as button fill, link text, a focus ring or a dark-mode surface: a pale yellow brand has no readable white label, and a navy brand vanishes on a dark page. KinetixUI keeps the two apart — --brand is identity (logos, headers), --action is the interactive colour — and Create moves the action colour into a lightness band that can carry text in each mode while keeping its hue. Expect the button colour to be your hue, not always your exact hex.

The contract#

The light value of the most-used roles. Every role, both modes, all four platforms: /docs/tokens.

VariableLightSource
--background#ffffffneutral.0
--foreground#050c11blue.900
--primary / --action#1d4ed8azure.700 — action blue (replaces the Figma navy, which is now --brand)
--primary-foreground#f0f7ffblue.50
--secondary#c7cfc7green.200 (deepened for surface contrast)
--muted / --muted-foreground#f6f6f6 / #6d6d6dneutral.100 / neutral.600
--accent#f0f7ffblue.50
--destructive#c60a0ared.500 (the Figma error #ec5047 fails AA as text)
--border / --input#92b2c8blue.100
--ring / --focus#1d4ed8azure.700 — the keyboard focus ring

Corner radius is a separate ladder — --radius-sm / -md / -lg / -xl, with role aliases --radius-field, -control, -container and -surface — not a single --radius.

Both themes#

Light and dark are two independent palettes — not one value set flipped. Each role is mapped to a primitive step chosen for its own surface: --primary is azure.700 on the white page and azure.400 on the near-black one, because the light value would be ~2.9:1 there. The dark surfaces are a navy ladder (blue.900 page, blue.850 grouped section, blue.800 card, blue.700 muted) so a card reads as raised in both modes.

A custom theme needs a dark value for every role it overrides. Create generates both from one configuration; a hand-written override must state both, or your light colour shows up in dark mode.

light

Card surface with muted foreground text.

dark

Card surface with muted foreground text.

Retheme by hand (Advanced)#

Override the semantic variables after importing the contract. Primitives stay put; only the mapping changes. Set the role and its foreground, and set it for both modes:

@import "@kinetixui/tokens/css";
@import "@kinetixui/tokens/css/dark";
@import "@kinetixui/tokens/css/extras";
@import "@kinetixui/tokens/css/extras/dark";
 
:root {
  --primary: var(--green-700);            /* #465245 */
  --primary-foreground: var(--green-50);  /* 7.38:1 on it */
  --ring: var(--green-700);               /* the focus ring follows --ring, not --primary */
}
 
.dark {
  --primary: var(--green-300);            /* #acb8ab — a lighter step for the dark page */
  --primary-foreground: var(--green-950); /* 9.41:1 on it */
  --ring: var(--green-300);
}

--ring is not derived from --primary — it is its own role, so a theme that changes only --primary keeps the azure focus ring. Set both. Every Kinetix focus ring (the shadow-focus utility, Angular's .kx-*:focus-visible) reads --focus, which defaults to --ring. The error, success and warning focus rings (shadow-focus-destructive, -success, -warning) read --destructive, --success and --warning the same way, so a theme that recolours a status role recolours its focus ring with it. Controls that draw their ring with ring-ring (the NavigationMenu trigger among them) follow --ring. Both mechanisms are deliberate: one is a two-layer composite, the other a single utility.

Contrast is yours to keep when you write values by hand. Check them with pnpm check:contrast's rules in mind, or paste them into Create's Advanced panel, which reports every text pair at 4.5:1 and the focus ring against the page and cards at 3:1.

Apply a theme on each platform#

One design, four renderings. Create's Export (or the matching kinetixui preset … command) writes the file for each; the snippets below show where it plugs in.

React / web and Angular read the same CSS custom properties, so the same override block themes both:

/* after the four @kinetixui/tokens imports — the block from "Retheme by hand", or Create's Web CSS export */
:root { --primary: var(--green-700); --primary-foreground: var(--green-50); --ring: var(--green-700); }
.dark { --primary: var(--green-300); --primary-foreground: var(--green-950); --ring: var(--green-300); }

Dark mode is the .dark class on <html> (Dark mode).

SwiftUI — kinetixui preset swiftui KX1_… --name AcmeTheme writes a KinetixColors pair:

KinetixTheme(light: AcmeTheme.light, dark: AcmeTheme.dark) {
    ContentView()
}

Jetpack Compose — from an exported preset, or by copying one role off the shipped set:

KinetixTheme(
    light = LightKinetixColors.copy(action = Color(0xFF465245), primary = Color(0xFF465245)),
    dark = DarkKinetixColors.copy(action = Color(0xFFACB8AB), primary = Color(0xFFACB8AB)),
) {
    App()
}

Flutter — the custom constructor for Kinetix widgets, and the adapter for stock Material widgets:

KinetixTheme.custom(
  light: AcmeTheme.light,
  dark: AcmeTheme.dark,
  child: MaterialApp(
    theme: KinetixMaterialTheme.fromColors(Brightness.light, AcmeTheme.light),
    darkTheme: KinetixMaterialTheme.fromColors(Brightness.dark, AcmeTheme.dark),
    home: const App(),
  ),
)

What each platform themes for you, and what stays your app's job:

PlatformKinetix componentsStock platform controls
Web (React / Angular)every role, live, through CSS variablesnot applicable — style your own markup with the Tailwind preset (bg-action, text-muted-foreground)
SwiftUIevery field of KinetixColors, through KinetixThemenot themed — stock SwiftUI controls keep the system tint
Composeevery field of KinetixColors, through KinetixThemenot themed — MaterialTheme is wrapped, not mapped
Flutterevery field of KinetixColors, through KinetixThemeyes — KinetixMaterialTheme and KinetixCupertinoTheme map the contract onto stock widgets

The native colour sets are a subset of the web contract: they carry the roles their components read (no surface-grouped, sidebar-* or the semantic-* container colours, and five chart colours rather than eight), and Compose has no input, ring or tertiaryForeground field. Only @kinetixui/tokens is installed from a registry today; the native token files are copied in.

Accessibility rules a theme must keep#

  • Text — every foreground on its surface at 4.5:1 (WCAG AA), including hover and pressed fills. Create enforces this for everything it generates; values you type are reported, not corrected.
  • Focus — the focus ring (--focus, defaulting to --ring) at 3:1 against the page and against cards. Do not assume your brand colour qualifies: a ring the colour of your page background is invisible. Create's contrast panel checks both.
  • Boundaries — --border, --input and the switch's off track are intentionally below 3:1 in the shipped theme and are never the only cue (a focus ring, a thumb or a label carries the state). Darken them if your product needs stronger boundaries; do not lighten them further.
  • Colour is never the only signal — error and success states also carry text or an icon in FieldMessage, Banner and Inform. Alert, Badge and the invalid border on fields do not add one for you: put the word in the content.
  • Both modes — check the dark values too; a theme that passes on white can fail on the dark page.

Back to the defaults#

Everything here is an override layer, so removing it is the reset: delete your :root / .dark block (or stop passing light: / dark: to the native KinetixTheme) and the shipped contract applies again. In Create, Reset returns every control to the shipped theme and drops the preset from the URL, and the ↺ beside an Advanced value resets that one role. Create stores nothing in the browser; a design lives only in its KX1_ preset.

primary is doing several jobs in a shadcn-style contract: the fill of a button, the colour of a link, the focus ring, and — in a lot of brands — the brand colour itself. Those diverge as soon as your brand colour isn't a good button colour (KinetixUI's own navy wasn't, which is why primary is azure). Four role tokens sit on top of it so you can split them:

TokenMeaningDefault
--action / --action-foregroundthe interactive fill: buttons, checkboxes, selected states, spinnersvar(--primary) / var(--primary-foreground)
--linkLink button, inline linksvar(--primary)
--focusfocus indicatorvar(--ring)
--brand / --brand-foregroundidentity: logos, headers, brand surfaces — not a control colourthe navy blue.500

Because action, link and focus default to primary / ring, a theme that only sets --primary (everything above, and everything the CLI's theme command writes) keeps working unchanged. Override a role on its own to split it off:

:root {
  --primary: var(--green-500);        /* everything follows… */
  --action: var(--azure-700);         /* …except buttons and controls, which stay azure */
  --brand: var(--green-700);
}

Components read the role tokens (bg-action, text-link), not primary, so overriding --primary still recolours them via the default and overriding --action recolours only the interactive layer. Contrast is on you when you split them: kinetixui theme build reports action / action-foreground and brand / brand-foreground when you set them.

What pinning primary means in Create. The table above is one rule, not a default that happens to hold on the web: action, action-foreground and link follow primary / primary-foreground, and focus follows ring — in light and in dark, in the token source and in every export. In Create's Advanced panel, pinning primary therefore moves Action and Link too, and the row says so ("from primary") until you pin that role yourself, which always wins. The preview, the CSS block and the SwiftUI, Compose and Flutter files all say the same thing; role-equivalence.test.ts pins that. To keep buttons on the old colour while changing primary, pin action (and action-foreground). Hover and pressed are regenerated from whichever action results, so they never lag behind it. brand is identity and is never derived from primary.

Hover and pressed. On the web the Button derives its states from action (bg-action/90, bg-action/85), so they follow whatever you set. The contract also carries explicit --action-hover / --action-pressed values — the same two colours, precomputed over the page background — for the SwiftUI, Compose and Flutter ports, which have no alpha-derivation to lean on. pnpm check:contrast asserts the explicit values equal the derivation and that text on them clears AA.

A theme generated in Create derives the same two states the same way, with one constraint on top: the label has to stay readable on all three fills. action-foreground is chosen against action, action-hover and action-pressed together rather than the resting colour alone, and where no foreground can carry the full 90% / 85% move, both states scale back in step until it can. Some brand colours therefore get a slightly subtler hover than the shipped blue does — the alternative was a button label at 3.4:1 while pressed, which is what this used to do.

Native. The SwiftUI, Compose and Flutter components read the same role tokens: KinetixColors has action, actionForeground, actionHover, actionPressed, link, focus, brand and brandForeground alongside primary / ring, and the components use the role fields (the Button's Link variant reads link; focus rings read focus). Two roles exist so the native Banner/Inform and the overlays do not need a literal: onInfoContainer is the text colour on a tinted info container (the plain info role is 4.19:1 there; onInfoContainer clears AA), and scrim is the backdrop behind Dialog, Sheet and Sidebar. The Compose Dialog keeps the platform's own window dim, which cannot be recoloured; its Sheet and Sidebar read scrim. The primary Button uses actionHover on pointer hover and actionPressed while pressed; other components keep the platform's own interaction feedback. primary remains as the source they default to.

Upgrading: components that use bg-action / text-link need the matching @kinetixui/ui/tailwind.config preset (it defines the new colours) — update the package when you re-add components with the CLI.

Scrim and container text#

TokenMeaningLightDark
--scrim (bg-scrim)the veil behind a modal: Dialog, Alert dialog, Sheet, Drawer, command menu, Tour, Angular <dialog>black 40%black 60%
--on-info-container (text-info-on-container)text on bg-info/10: Banner and Inform "information"blue.400blue.100

The scrim is black in both themes and denser in dark, because black over a dark page needs more opacity to set the dialog back. It was foreground at 40%, which is near-white in dark mode and lifted the page toward the dialog instead. A theme can override --scrim like any other role; it is a role, not a palette step, and is not exposed as one.

Primitive ramps#

Seven ramps (azure, blue, green, taupe, cream, amber, red) plus a synthesized neutral, each 0–1000. Browse them on the Colors page.

Building a theme visually#

Create generates a theme from a handful of choices rather than a list of hex values. Pick a theme colour and it derives the brand, action, link and focus roles from it, along with the hover and pressed states and a foreground that clears AA — in OKLCH, so the same rule produces the same perceptual step on every hue. A separate neutral control sets the personality of the greys, and radius and surface presets write the --radius-* and --shadow-* variables documented above.

Its Export panel then generates that design for one of four targets: web CSS, SwiftUI, Jetpack Compose or Flutter. The web CSS is an override block containing only what differs from the shipped theme, with a :root and a .dark section — one configuration describes both appearances. The three native targets are a KinetixColors pair each, light and dark. Manual values set in the Advanced panel beat everything generated, and a contrast failure you introduce there is reported rather than quietly corrected.

Each target also shows the kinetixui preset … command that writes the same file, because the CLI and the workspace run the same exporter.

Radius and surface reach SwiftUI and stop there. KinetixRadii and KinetixElevations are part of its theme, its components read them, and preset swiftui writes them — so a design's corners and shadows arrive intact, minus shadow spread, which SwiftUI has no equivalent for. Compose and Flutter still read generated constants rather than a runtime theme, so there is nowhere for either to land on those two. Colours and the chart palette travel everywhere. kinetixui theme build is a separate, older path — a CSV of literal colours compiled to CSS — and is web-only; see the CLI page for its scope.

Presets#

A configuration can be saved as a preset: a short code beginning KX1_ that describes the design and nothing else. It carries the theme colour, the neutral, the radius, the surface treatment, the chart palette and any manual overrides — not the generated colours, not the CSS, and not which appearance or demo scene you happened to be looking at. Those are regenerated from the preset by the same engine that produced them the first time.

Share copies a /create?preset=KX1_… link that reopens the workspace with that design. Copy preset copies the bare code, which is what kinetixui preset decode reads and kinetixui preset css resolves into this same stylesheet without a browser — and preset swiftui, preset compose and preset flutter resolve into native theme files.

The workspace's Export panel is the same four targets in the browser: one design, one resolved theme, and the exporter for whichever target is selected. A preset stays a different artifact from any of them — a preset is the design, generated code is one rendering of it.

The preview is always web. Selecting SwiftUI, Jetpack Compose or Flutter changes what Export generates, not what is drawn: those targets carry colours, and radius and surface apply on the web only, because no native package has a runtime token for them.

The version is in the prefix, so a code made today stays readable, and a future format is refused with an explanation rather than misread. A preset can only name tokens from the contract above — it is structured configuration, never arbitrary CSS.

Presets reach web CSS and all three native colour contracts. preset swiftui, preset compose and preset flutter resolve a preset into a KinetixColors pair for SwiftUI, Compose and Flutter. Colours only in all three: a design's radius and surface treatment apply on the web and have no runtime token to land on natively. Flutter carries the whole semantic contract; Compose is missing fields for input, ring and tertiary-foreground, and its generated file says so.