Design tokens as props: inside Wix react-native-ui-lib

Colors, typography and spacings load into three separate registries

The theming entry point is not one theme object but three loaders: Colors.loadColors, Typography.loadTypographies and Spacings.loadSpacings. Each writes into its own registry, and the keys you choose become the names your components refer to later. Foundations live in a file the README calls FoundationConfig.js.

import {Colors, Typography, Spacings} from 'react-native-ui-lib';

Colors.loadColors({
  primaryColor: '#2364AA',
  secondaryColor: '#81C3D7',
  textColor: '##221D23',
  errorColor: '#E63B2E',
  successColor: '#ADC76F',
  warnColor: '##FF963C'
});

Those last two entries are the trap. textColor and warnColor are written with two hash characters, which is not a hex color, so copy the structure and fix those two values in your own file. Typography follows the same shape, with heading at fontSize 36 and fontWeight '600', subheading at 28 and '500', and body at 18 and '400'.

Spacing is loaded last, and this is the block your modifiers will read:

Spacings.loadSpacings({
  page: 20,
  card: 12,
  gridGutter: 16
});

ThemeManager.setComponentTheme takes a function that can return nothing

Foundations decide what a token is worth. Component defaults are a separate step, in a file the README calls ComponentsConfig.js, and ThemeManager.setComponentTheme accepts either a plain object or a function.

ThemeManager.setComponentTheme('Button', (props, context) => {
  // 'square' is not an original Button prop, but a custom prop that can
  // be used to create different variations of buttons in your app
  if (props.square) {
    return {
      borderRadius: 0
    };
  }
});

The comment matters more than the code. 'square' is not a Button prop the library ships, so you declare it in your app and the theme function reads it. That is how one Button renders two shapes without a second component.

Two gaps sit in the same snippet. The function falls through and returns undefined whenever props.square is false, and the README does not say what the library does with an undefined return. The second parameter, context, appears in the signature and is never explained, so a theme function that depends on it has nothing to read.

Modifier names come from your own keys, and the s4 scale is never defined

The third README step is where the halves meet: modifiers applied as props. A screen writes padding-page, marginB-s4, padding-card, bg-primaryColor, heading and body. Five of those resolve to keys somebody loaded. page and card come from Spacings.loadSpacings, primaryColor from Colors.loadColors, heading and body from Typography.loadTypographies.

The other one resolves to nothing in that file. marginB-s4 implies a numbered spacing scale, and the README never defines one: its loadSpacings example registers page, card and gridGutter only. The README also does not list which components accept modifiers, and does not say what a component renders when it receives a modifier whose key was never loaded.

Keep your foundation keys in one file and grep it before you debug a view.

React Native support stops at 0.73 while the lint config pins 0.78.3

The README carries one short note and it is the entire roadmap: the library is being upgraded for the new React Native Architecture, currently supports React Native 0.73, plans React Native 0.77 next, and has no timeline for it. If your app already runs the new architecture, that note tells you nothing about whether the library will work there.

The repository itself sits further ahead than the note. The root package.json pins @react-native/eslint-config at 0.78.3, past both the 0.73 the library claims to support and the 0.77 it names as the next target. That gap matters if you read the code as documentation: the lint configuration the maintainers run over packages/ targets a newer React Native than the one the README tells users to stay on.

Activity is not the problem. The last push to master was on 2026-11-02, and the newest release is [email protected] from 2026-06-28, so master moves ahead of what the registry carries while the architecture work stays dateless.

The repository root is a private workspace, not the package you install

The root package.json is named react-native-ui-lib-components and marked private, with workspaces pointing at packages/*. The package you add to your app, react-native-ui-lib, is one of those workspaces. That split explains most of the top-level tree: demo/, expoDemo/, webDemo/, docuilib/, docs/ and extensions/ are development surfaces rather than shipped code.

What the scripts cover is narrow. Linting runs over packages only:

eslint packages -c .eslintrc.js --ext .tsx,.ts,.js

The TypeScript side has its own entry points. build:dev runs tsc against tsconfig.dev.json while a separate tsconfig.build.json and a jsconfig.json sit at the root. Before a push, pre-push chains build:dev and test, and a separate prepush script runs node ./scripts/prepush.js.

There is a Ruby half beside the JavaScript one: Gemfile, Gemfile.lock and .ruby-version at the root, next to metro.config.js and babel.config.js. Expect to budget for that on the iOS path.

Installing by React Native version, then rendering one card and one button

The README prints no install command. It gives you the package name and two branches: react-native-ui-lib for React Native 0.60.0 and above, react-native-ui-lib@^3.0.0 for anything below 0.60.0. The actual setup steps live behind wix.github.io/react-native-ui-lib/docs/getting-started/setup, and people moving to the new major version 6.0 are sent to a separate breaking-changes page. For a look before you commit, there is a demo app to open in the Expo App.

Order matters once the package is in. Load foundations first, then component defaults, then read both from props. ComponentsConfig.js is where the plain case goes:

ThemeManager.setComponentTheme('Card', {
  borderRadius: 8
});

With that in place, a screen reads foundation keys and component defaults as props on the same element:

<View flex padding-page>
  <Text heading marginB-s4>
    My Screen
  </Text>
  <Card height={100} center padding-card marginB-s4>
    <Text body>This is an example card </Text>
  </Card>

  <Button label="Button" body bg-primaryColor square></Button>
</View>

That last Button carries three instructions at once: body from typography, bg-primaryColor from your colors, square from the theme function. On iOS, run the pod-install script in the root package.json before the first build.

No runtime theme switch and no documented failure paths

This is where the documentation runs out. Nothing covers changing themes while the app runs. The loaders are shown once, at module load, and no unload, reload or reset call appears in the README. If your product needs a light and a dark palette, or a different color set per tenant, you are editing the loader calls or writing your own context, and the library's own documentation will not tell you which one is intended.

Other silences are worth knowing before you commit. There is no list of components that accept modifiers. There are no accessibility notes, no dark mode guidance, no statement of which React Native versions each 9.x release supports, and nothing about how to roll back a bad upgrade. setComponentTheme matches components by string name, and the README does not say what happens for a name that does not exist.

Treat this as a component set plus a token layer, and treat the token layer as yours. Every value in FoundationConfig.js is code you own, loaded once, with no documented way to swap it while the app runs.

React Native Paper organizes one theme object where this library loads three

The README names no alternative, so choose your comparison carefully. React Native Paper organizes styling around a single theme object and Material Design components, where a component and its color scheme arrive together from one provider, and the palette comes from Material rather than from keys your app invents. react-native-ui-lib splits the same job into three registries, a theme manager and modifier props. That buys arbitrary token names and per-component defaults, and charges you a convention every screen has to follow.

The trade pays off when a design system already exists as a token set written by your designers. It is the wrong shape when you want a component library to hand you a finished look on day one, because the README's colors all come from your own Colors.loadColors call, and it does not enumerate any defaults the components fall back to.

Editorial conclusion

Adopt it if your team already has a token set and wants those tokens applied through props rather than one theme provider, and if you can live inside the version window the README states. Skip it if you need the new React Native Architecture today or a documented runtime theme switch. Before the first screen, copy the foundations file yourself and check its hex strings, because two values in the README snippet are written with a doubled hash character.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes