Skip to content
KinetixUI

Installation

KinetixUI is cross-platform design system infrastructure, so the first question is not how but which starting point. There are four, and only the first is this page.

  • Add KinetixUI to a React app — the rest of this page. Two routes: copy the source into your repo, or take a versioned npm dependency. Both use the same tokens.
  • Add it to Angular, SwiftUI, Compose or Flutter — other platforms below. Each has its own setup page, and the React CLI installs none of them.
  • Design a theme first — Kinetix Create lets you change the design in the browser, then apply it to any of the five platforms. It customises an existing project; it does not create one.
  • Decide whether to adopt it at all — Platforms carries the coverage and verification evidence, and the guide below is written for that question.

Further reading: What a cross-platform component library should actually give you.

Before you start#

The CLI adds component source and tokens. It does not create an app, configure Tailwind, or configure your import aliases — so start from an app that already:

  • renders React 18 or newer (react and react-dom are peer dependencies),
  • loads a global stylesheet you can add imports to,
  • builds with Tailwind CSS 3. Tailwind 4 setup is not verified here,
  • runs on Node 18 or newer, which is what @kinetixui/cli requires.

Versions in this repository, which is what the next release publishes:

@kinetixui/ui 0.27.0@kinetixui/tokens 0.27.0@kinetixui/cli 0.27.0

React is the reference implementation and the most complete library: every catalogue entry has a React implementation, and the other platforms are compared with it. In one place:

Package
@kinetixui/ui · stable package
Distribution
On npm.
Catalogue
109 of 109 catalogue entries. Browse components
Not implemented
Nothing in the catalogue.
Verification
Catalogue verified to beta (the weakest component sets it). Components with test evidence: Interaction 49/109 · Accessibility 109/109 · RTL 38/109 · Large text 39/109. CI: ci.yml, a11y-browser.yml.
Tokens
CSS variables, Tailwind preset, typed TS object How tokens reach React

Two React routes#

React ships two ways. Both use the same tokens.

What you installRegistry (own the code)npm (versioned dependency)
Componentsthe CLI's add commandthe @kinetixui/ui package
Tokensthe CLI's init commandthe @kinetixui/tokens package

Every command below is shown for npm, pnpm, Yarn and Bun; pick yours once and the rest of the documentation follows it. Each one was run in a clean project outside this repository: npm, pnpm and Bun install and build with no extra steps; Yarn needs one more package, for the reason in the callout below. Running the CLI works on all four, except that Yarn Classic has no dlx — the Yarn tab says so where it matters.

@kinetixui/ui on npm@kinetixui/tokens on npm@kinetixui/cli on npm

The registry drops source into your repo (you edit it freely) via the kinetixui CLI. The npm packages update with npm update. Tokens are a good npm dependency; components are often nicer copied.

Tokens#

Registry — writes :root (light) + .dark + the shadow / type composites into your global stylesheet:

npx @kinetixui/cli init

npm — import the generated CSS, or the typed object:

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

All four, in this order. css carries colour, spacing and radius; css/extras carries the shadow and type ramps, including the focus ring. Each /dark sheet redefines its half under .dark, so leaving one out keeps that half light in dark mode — css/extras/dark is where the stronger dark focus halo lives.

import tokens from "@kinetixui/tokens";
tokens.color.blue[500]; // "#1b3c53"

Native text styles ship too: KinetixType.swift, KinetixType.kt, app_text.dart under the package's dist/{ios,android,flutter}.

A component#

Registry:

npx @kinetixui/cli add button

The CLI resolves tokens first (a registry dependency), installs every npm package the delivered files import — for button that is @radix-ui/react-slot, class-variance-authority, clsx and tailwind-merge — then drops button.tsx into your configured components directory.

clsx and tailwind-merge are there because button.tsx imports cn(), so the item also delivers lib/utils.ts, which imports both. You do not install them yourself: each item's dependencies are derived from every file it ships, and pnpm check:registry-deps fails the build if one is ever missing.

Name several at once (add button card dialog), run npx @kinetixui/cli list to see everything available, or pull the whole library in one go with npx @kinetixui/cli add --all. See the CLI reference for every flag.

npm — every component ships in the one package, so there's no per-component step:

npm install @kinetixui/ui @kinetixui/tokens
import { Button, Field, FieldLabel } from "@kinetixui/ui";

Tailwind#

Install the preset's package for either React route, and install Tailwind's build tools if your app does not already have them:

npm install @kinetixui/ui @kinetixui/tokens
npm install -D tailwindcss@3 postcss autoprefixer

On Yarn, add one more package. @kinetixui/ui includes charts built on recharts, which declares react-is as a peer dependency. npm, pnpm and Bun install a transitive peer for you; neither Yarn Classic nor Yarn 4 does, so a Yarn build fails to resolve react-is. Run yarn add react-is as well. Measured on Yarn 1.22.22 and Yarn 4.18.1 with node scripts/adoption/pm-matrix.mjs. Yarn 4 also refuses a version published in the last week by default (npmMinimalAgeGate), so a brand-new KinetixUI release needs yarn config set npmMinimalAgeGate 0 or a few days' patience.

Map the utilities onto the contract — KinetixUI ships a preset:

// tailwind.config.ts
import preset from "@kinetixui/ui/tailwind.config";
 
export default {
  presets: [preset],
  darkMode: ["class"],
  content: [
    "./src/**/*.{ts,tsx}",
    "./app/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
    // npm components live outside src; scan their shipped source for utilities.
    "./node_modules/@kinetixui/ui/src/**/*.{ts,tsx}",
  ],
};

The preset wires colors, borderRadius, spacing, fontFamily and the motion durations and easings to CSS variables. It also adds the tailwindcss-animate plugin, the accordion, collapsible, marquee, typing and caret keyframes, and a base rule that shortens every animation and transition to 0.01ms under prefers-reduced-motion: reduce. It adds no reset.

The registry (npx @kinetixui/cli add) delivers component source and the token stylesheet, not the preset. Without it, utilities such as animate-in, duration-fast and ease-standard do not exist, so those animations simply do not run, and there is no global reduced-motion rule. What a registry component does promise on its own is that every loop it ships stops under reduced motion. See Foundations.

First working React component#

For the npm route, load the token CSS and Tailwind layers in the global stylesheet that your app imports:

@import "@kinetixui/tokens/css";
@import "@kinetixui/tokens/css/dark";
@import "@kinetixui/tokens/css/extras";
@import "@kinetixui/tokens/css/extras/dark";
 
@tailwind base;
@tailwind components;
@tailwind utilities;

Use your existing PostCSS configuration, or create postcss.config.cjs:

module.exports = {
  plugins: { tailwindcss: {}, autoprefixer: {} },
};

Replace your app's component with this example, then run its usual development command:

"use client";
 
import { useState } from "react";
import { Button } from "@kinetixui/ui";
 
export default function App() {
  const [saved, setSaved] = useState(false);
  return (
    <Button variant="Primary" onClick={() => setSaved(true)}>
      {saved ? "Saved" : "Save"}
    </Button>
  );
}

You should see a styled Save button; clicking it changes the label to Saved. An unstyled button usually means Tailwind is not running, the package source is absent from content, or the global token stylesheet is not loaded.

For the registry route, run npx @kinetixui/cli init before add button, choose your real global stylesheet, and configure @/* to resolve to the directory containing components and lib in both TypeScript and your bundler. Import the copied Button from @/components/ui/button instead of @kinetixui/ui (adjust to your configured components directory). Keep the CLI's token stylesheet and add the Tailwind layers there; you do not need to import a second copy of the token CSS.

Explore components once your first button works.

Applying a theme you designed#

Kinetix Create is where you change the design — brand colour, radius, surface — and watch the components move. It exports the same design four ways, and the Export panel shows both the file and the command that writes it:

TargetWhat you getHow to apply it
Web CSSa :root + .dark override blockpaste it after the token imports, or write it with the command below
SwiftUIKinetixColors, light and darkpass it to KinetixTheme
Jetpack ComposeKinetixColors, light and darkpass it to the Compose theme
FlutterKinetixColors, light and darkpass it to the Flutter theme

Every design is also a portable KX1_… preset code, so the same design can be regenerated from a terminal without reopening the browser:

npx @kinetixui/cli preset css <KX1_…> -o src/theme.css

Replace the value in angle brackets before running this.

What this does not do: Create does not scaffold an application, and it does not install anything. It produces a theme file for a project you already have. Radius and elevation reach the web CSS; on the three native targets the exporter writes colours, and the Export panel says so per target.

Other platforms#

The React CLI installs React components only. Each other platform has its own setup page, and its own distribution reality:

  • Angular (Preview) — @kinetixui/angular on npm, Angular 21, standalone components and plain CSS. Published, and still Preview: see the graduation contract.
  • SwiftUI — a local SwiftPM package from a repository checkout; iOS 16 / macOS 13 or newer. Not published to any registry.
  • Jetpack Compose — the Android library module from a repository checkout. Not on Maven Central.
  • Flutter — a local path dependency from a repository checkout. Not on pub.dev.

For the three source-only platforms that means pinning a commit of this repository rather than resolving a version range, and taking an upgrade by moving that pin. Platforms carries what each one is verified for.

Dark mode#

KinetixUI's dark theme is a class toggle on <html>. See Dark Mode.

Next steps#

  • Design tokens and theming: change the look without forking components.
  • Accessibility: what the React library is tested for.
  • Blocks: sign-in, settings and dashboard sections built from the components.