Styling
One component, four styling variants. Axiom adapts to the tool your project already uses.
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.
| Variant | Tool | Dependency |
|---|---|---|
stylesheet | React Native StyleSheet | none |
unistyles | react-native-unistyles | react-native-unistyles |
nativewind | NativeWind 4 (Tailwind 3) | nativewind |
uniwind | Uniwind (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
stylesheetif you don’t use a styling library, or want zero extra dependencies. It needs no global provider.unistylesif your project already uses Unistyles.nativewindif your project uses NativeWind.uniwindif 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.
atoms/switch
- 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
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:
stylesheet | unistyles | nativewind and uniwind | |
|---|---|---|---|
| Theme access | useTheme() | built in | class names (bg-primary, bg-button-solid) |
Variants (size, variant) | style objects picked by hand | native variants | classes picked from a table |
| Dark mode | useColorScheme | adaptive themes | CSS variables with a light and a dark value |
| Component tokens | theme/components/<name>.ts | theme/components/<name>.ts | theme/components/<name>.css |
| Animated styles (Reanimated) | animated style | animated style | animated 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 withoutdark:. - Each component has its own names.
bg-button-solidcomes fromtheme/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
classNamewins. A component writescx("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. stylekeeps 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.