Pre-alphaThe registry and the CLI are not published yet.Roadmap

Styling

One component, four styling variants. Axiom adapts to the tool your project already uses.

One component, four styling toolsSame props · same behavior · same look

Axiom doesn’t come with its own styling syntax. Each component exists in several variants, and your project uses the one that matches its stack.

VariantToolDependency
stylesheetReact Native StyleSheetnone
unistylesreact-native-unistylesreact-native-unistyles
nativewindNativeWind 4 (Tailwind 3)nativewind
uniwindUniwind (Tailwind 4)uniwind

NativeWind and Uniwind each have their variant. The class names are almost always the same; what differs is the setup (config, Babel or Metro plugin, Tailwind version) and how a component gives a color to an icon or a spinner. init installs the tool’s package; set it up following the NativeWind or Uniwind guide, then import the Axiom theme.

Rollout

All four variants ship for every component, compositions and blocks included.

Choosing a variant

  • stylesheet if you don’t use a styling library, or want zero extra dependencies. It needs no global provider.
  • unistyles if your project already uses Unistyles.
  • nativewind if your project uses NativeWind.
  • uniwind if your project uses Uniwind.

You choose once, at npx axiom init. The choice is stored in axiom.json and every add copies that variant.

Behavior and style are separate

What makes a component useful on mobile (state, gestures, animation, accessibility, touch targets) doesn’t depend on the styling tool. It is written once and shared by every variant.

In the registry
core# shared: Tappable, Overlay…
hooks# shared: useControllableState…
atoms/switch
use-switch.ts# shared behavior
switch.tsx# shared: structure, states and accessibility
switch.styles.stylesheet.ts# StyleSheet.create + useTheme
switch.styles.unistyles.ts# StyleSheet.create((theme) => …)
switch.styles.nativewind.ts# className, from the Tailwind theme
switch.styles.uniwind.ts# className, from the Tailwind theme
  • Non-trivial logic lives in core/, hooks/ or a hook next to the component.
  • The component itself (its elements, states and accessibility) is written once too. Only its styles are written per variant, by hand.
  • A variant never reimplements a behavior.

In your project there is one variant, so you get one file: the CLI writes the component and the styles of your variant together, the way you would write them by hand. Nothing in it reads a variant at runtime.

components/ui/switch
use-switch.ts# shared behavior
switch.tsx# the component, with the styles of your variant
index.ts# so "@/components/ui/switch" resolves here

A component without shared behavior is a single file: components/ui/badge.tsx.

See Where files go.

The theme in each variant

The theme contracts (Tokens, ThemeColors, Components) and the default values don’t depend on the styling tool. Each variant translates them into its own form:

// `light` and `dark` objects, picked by a hook based on the system color scheme.
import { useColorScheme } from "react-native";

export const light = { tokens, colors: lightColors };
export const dark = { tokens, colors: darkColors };

export function useTheme() {
	return useColorScheme() === "dark" ? dark : light;
}
// Themes registered once, then switched automatically by Unistyles.
import { StyleSheet } from "react-native-unistyles";

StyleSheet.configure({
	themes: { light, dark },
	settings: { adaptiveThemes: true },
});
/* global.css: colors, radius, sizes and typography become Tailwind names
   (`bg-primary`, `rounded-md`, `text-callout`), with a light and a dark value. */
@import "./theme/nativewind.css";

@tailwind base;
@tailwind components;
@tailwind utilities;

/* And in tailwind.config.js:
   presets: [require("nativewind/preset"), require("./theme/nativewind-preset")] */
/* global.css: colors, radius, sizes and typography become Tailwind names
   (`bg-primary`, `rounded-md`, `text-callout`), with a light and a dark value. */
@import "tailwindcss";
@import "uniwind";

@import "./theme/uniwind.css";
/* The tokens of each component, listed by `axiom add`. */
@import "./theme/components/index.css";

With NativeWind and Uniwind the theme is CSS: the files above are copied into your theme folder, and you import them once. useTheme() is still there, the same hook as stylesheet, for the few values a class can’t give. The theme also exports cx, which joins class names and lets the last class that sets a property win.

See Foundations for the contracts.

How the tools differ

The variants don’t only differ in syntax:

stylesheetunistylesnativewind and uniwind
Theme accessuseTheme()built inclass names (bg-primary, bg-button-solid)
Variants (size, variant)style objects picked by handnative variantsclasses picked from a table
Dark modeuseColorSchemeadaptive themesCSS variables with a light and a dark value
Component tokenstheme/components/<name>.tstheme/components/<name>.tstheme/components/<name>.css
Animated styles (Reanimated)animated styleanimated styleanimated style (animated views take no className)

What the Tailwind variants put in classes

  • Colors, radius, sizes and typography are classes. They are written whole (bg-button-solid, active:bg-button-solid-pressed), so Tailwind finds them, and they follow light and dark without dark:.
  • Each component has its own names. bg-button-solid comes from theme/components/button.css, generated from the same tokens the other variants read. Edit that file to restyle the component.
  • Sizes outside the spacing scale are in pixels. A rem is 14px in NativeWind and 16px in Uniwind, so a size the tokens don’t name is written h-[24px].
  • Your className wins. A component writes cx("its classes", className), and of two classes that set the same property the last one is kept: className="bg-highlight" replaces the component’s background.
  • style keeps what no class can say: a number the device or the caller gives (a safe-area inset, a width), and colors a prop wants as a value, like the stroke of an SVG path.

Switch, Slider, Segmented Control and Skeleton animate their colors, so in these two variants they still read their tokens from useTheme().components, in TypeScript.

Same contract everywhere

For a given component, every variant has:

  • the same props: names, types and defaults;
  • the same behavior and accessibility;
  • the same look with the default theme.

The one exception is each tool’s natural extension: every variant accepts style, and nativewind and uniwind also accept className.

Parity is checked in the demo app and in CI.

Switching later

Changing styling in axiom.json only affects components you add afterwards. Files already copied stay as they are, because they belong to your project. To move an existing component to another variant, add it again and confirm the overwrite, or port your version by hand.