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 (
reactandreact-domare 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/clirequires.
Versions in this repository, which is what the next release publishes:
@kinetixui/ui0.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 install | Registry (own the code) | npm (versioned dependency) |
|---|---|---|
| Components | the CLI's add command | the @kinetixui/ui package |
| Tokens | the CLI's init command | the @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.
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 initnpm — 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 buttonThe 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/tokensimport { 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/tokensnpm install -D tailwindcss@3 postcss autoprefixerOn 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:
| Target | What you get | How to apply it |
|---|---|---|
| Web CSS | a :root + .dark override block | paste it after the token imports, or write it with the command below |
| SwiftUI | KinetixColors, light and dark | pass it to KinetixTheme |
| Jetpack Compose | KinetixColors, light and dark | pass it to the Compose theme |
| Flutter | KinetixColors, light and dark | pass 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.cssReplace 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/angularon 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.