Roadmap
What ships first, and what comes after.
Phase 0: specification
Done. The whole system exists on paper first — foundations, core, hooks, the component catalog, the behaviors and the patterns. Nothing gets built twice because the API was decided while writing it down.
Where we are
The specification is done: every foundation, component, behavior and pattern is written down, with its API, its states and its tokens. Phase 1 turns that into code.
Every primitive of this phase now runs in code, along with tokens, theme and the six core pieces: Title and Text, the 34 atoms, the three molecules, Passcode and the five templates. All 75 entries with styling variants ship in stylesheet, unistyles, nativewind and uniwind. The first 30 compositions and the first block are in, and the four demo apps show them. The theme builder is public, add --standalone writes any entry as one theme-free file, and the CLI has add, init and sync. The CI typechecks every styling variant, checks that they expose the same props, runs the component tests in every demo, lints and bundles the apps.
Styling variants
- Done: stylesheetbehavior / style split in place
- Done: unistyles75 entries, same API, other engine
- Done: nativewind75 entries, the theme as a Tailwind preset
- Done: uniwind75 entries, the theme as a Tailwind 4 file
Components
- Done: Foundationstokens, ThemeColors, Theme, light / dark
- Done: CoreSlot, Portal, Overlay, OverlayStack, Tappable, Haptics
- Done: HooksuseRefreshControl, useControllableState, useOverlayBackHandler
- Done: Primitivestypography, 34 atoms, 3 molecules, Passcode, 5 templates
- In progress: CompositionsIn progress30 entries: cards, items, app bars
- In progress: BlocksIn progressSettingsSection
Tooling
- Done: registry.jsoncomponent manifest, 88 entries
- Done: CLIadd, init and sync ship
- Done: Standalone modeadd --standalone: one file, no theme; portal-based entries later
- Done: Demo appsone per styling tool: StyleSheet, Unistyles, NativeWind, Uniwind
- Done: Theme builderpublic: overrides, presets, previews, agent export
- Done: Foundations screencolors, typography, spacing, radius, icons, targets, states
- Done: CICLI tests, typecheck per variant, props parity, lint and app bundles run
Phase 1: the foundation
Styling variants
stylesheetfor every item in this phase, with the behavior / style split in place. Shipped.unistylesfor all 75 entries with styling variants, compositions and block included, with matching APIs and a demo app. Shipped.nativewindanduniwindfor the same 75 entries, with matching APIs and a demo app per tool. Colors, radius, sizes and typography are Tailwind names generated from the tokens, each component’s tokens included, so a class follows light and dark on its own. Shipped.
Each component is written once in the registry, with one styles file per variant. The CLI writes the two as a single file in the project.
Standalone mode
Shipped for all four variants. By default a component arrives with everything it stands on: ask for Tab and you also get the theme, the tokens and the headless core it imports. That is the right default for an app built on Axiom, and the wrong one for an app that already has its own design system and wants a single component out of the catalog.
axiom add tab --standalone breaks that chain. It writes one self-contained file: token values resolved inline, no useTheme, no import outside React, React Native and the npm packages the component uses. Nothing else is added to the project. See the CLI.
The trade is explicit. A standalone component no longer follows a theme, so light / dark and any restyling are the user’s job, in a file that is already theirs to edit. What Axiom still guarantees is the behavior: the touch targets, the gestures, the states, the safe areas.
The theme-free form isn’t written by hand. The CLI derives it from the registry: it inlines the items the component depends on, replaces each read of the theme with the light theme’s values, and keeps the registry’s types for the token groups and component tokens. The registry typechecks the standalone form of every entry in every variant, so a new entry gets one for free. Entries that render through a portal (Dialog, Menu, Bottom Sheet, Toast, Snackbar) are refused for now: a portal needs a host at the root of the app.
Components
| Group | Items | State |
|---|---|---|
| Foundations | Tokens, ThemeColors, component tokens, Theme, light / dark, components(colors, tokens) | Shipped |
| Core | Slot, Portal / PortalHost, Overlay, OverlayStack, Tappable, Haptics | Shipped |
| Hooks | useControllableState, useOverlayBackHandler, useRefreshControl, useKeyboardVisible | Shipped |
| Primitives: typography | Title, Text | Shipped |
| Primitives: atoms | All 34 atoms | Shipped |
| Primitives: molecules | SearchBar, Attachment, DatePicker | Shipped |
| Primitives: organisms | Passcode | Shipped |
| Primitives: templates | AppBar, BottomTabBar, Tab, ToolBar, Scaffold | Shipped |
| Compositions | 30 entries: cards (product, listing, recipe, article, event, profile, offer, pricing, stats, several with variants), items (settings, track, conversation, notification, search result), app bars (search, profile) | In progress |
| Blocks | SettingsSection | In progress |
useOverlayBackHandler was not in the original plan: BottomSheet, Dialog and Menu need to close on a back gesture instead of leaving the screen, so the hook ships in three versions — react-native, expo-router and react-navigation — and add picks one from the project’s package.json.
Two core entries were added along the way. OverlayStack lets BottomSheet, Dialog and Menu know what is open on top of them, so a sheet scales down when another opens over it. Haptics is a single haptic() function that switches, pickers and long presses call; it does nothing until the app connects its own library.
Tooling
registry.jsonShipped — 88 entries, compositions and block included.- CLI Shipped —
add,initandsyncare shipped.addresolves internal dependencies, icon source and navigation, and has a--watchmode;initpicks the styling, resolves the aliases againsttsconfig.json, copies the foundations and the headless core, installs what they need and writesaxiom.json.synccopies every item listed inaxiom.json, and asks which levels (core, theme, components) keep their existing files. - Standalone mode Shipped —
add --standalonefor 77 entries in all four variants, typechecked on their own. Portal-based entries come later. - Demo apps Shipped — one per styling tool (StyleSheet, Unistyles, NativeWind, Uniwind): one screen per primitive, in groups from Foundations to Templates, then the compositions and the block, and a light / dark switch.
- Theme builder Shipped — public at
/theme-builder: role overrides, presets, app and component previews, a design-system view, a canvas toolbar with slide mode and a dark-mode toggle, Google Fonts, and an export an agent can apply. - Foundations screen Shipped — colors, typography, spacing, radius, icons, touch targets, states.
- CI Shipped — the CLI is typechecked and tested; the registry is typechecked per styling variant, standalone forms included, and each variant must expose the same exports, props and parts as
stylesheet; ESLint runs over the registry, the CLI and the apps; each Expo app is typechecked, runs the component tests on its copy of the registry, and is bundled for Android and iOS. Another workflow streams an iOS simulator preview.
Phase 2: blocks
Complete sections of an app, built from primitives and compositions, once the system is stable. Settings section comes first, in phase 1; then authentication, onboarding, monetization, profile and commerce.
Later
- Agent integration: the CLI commands an agent needs to find, plan and verify a screen —
search,info,plan,doctor,--jsonoutput — plus the AGENTS.md, skill and MCP entry points. Specified, not built: onlyadd,initandsyncare available today. - Patterns: selection mode, search experience, async content state…
- More hooks: hide-on-scroll, collapsible header, keyboard-aware behavior…
- CI on Android and iOS devices, screenshots, visual tests (including parity between styling variants), accessibility checks.