@flipdish/ui-library

Atomic-design React component library for Flipdish products, built on Tailwind CSS v4, Untitled UI primitives, and React Aria Components. Web-first today, with React Native (via NativeWind) support rolling out per component.

Internal design system, published publicly. This package is built for and tuned to Flipdish's brand and tooling. It's on the public npm registry so it can be shared across Flipdish micro-frontends and apps — it isn't intended as a general-purpose UI kit.

Part of the Flipdish Design System:

Installation

pnpm add @flipdish/ui-library @flipdish/ui-tokens @flipdish/ui-icons

For the full setup walkthrough (Vite config, CSS entry, providers, first component), see Getting Started → Installation.

Peer dependencies

Shared — required on every platform:

Web:

React Native:

lightningcss must be pinned to 1.30.1. NativeWind v5 + react-native-css can hit a failed to deserialize error on versions >=1.30.2 (see the NativeWind installation guide). This only affects your app's install — a library's own version pin can't propagate to consumers — so add this to your app's package.json:

{ "overrides": { "lightningcss": "1.30.1" } }

(pnpm projects: nest this under a top-level "pnpm" key instead — { "pnpm": { "overrides": { "lightningcss": "1.30.1" } } }.)

Component-specific peer dependencies

A handful of components are backed by larger third-party libraries declared as optional peers — importing Button never pulls in the charting or rich-text stack. Install only the peer(s) for the components you actually use; a missing peer causes a build/runtime error.

Tailwind setup

Import the library's shared runtime from your CSS entry in this exact layer order:

@layer theme, base, components, utilities;

@import 'tailwindcss/theme.css' layer(theme);
@import '@flipdish/ui-tokens/css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import '@flipdish/ui-library/styles';
@import 'tailwindcss/utilities.css' layer(utilities);

React Native

Components are web-first and opt in per component. A component is available on React Native only once it has a .native.tsx implementation; the rest are web-only and are deliberately not resolvable from an RN app.

For the full Expo walkthrough (Metro config, NativeWind CSS entry, TypeScript, first component), see Getting Started → Installation (React Native). The summary below covers the essentials.

Available on React Native today: Avatar, Button, plus the cx, testIdUtils and isReactComponent utilities. Storybook is the live reference: each component's docs page carries a React Native section listing exactly which props that platform supports, and the Platform switch in the toolbar re-renders its stories with the React Native implementation.

Import paths are identical across platforms — Metro picks the native build via the react-native export condition:

// Resolves to the web build under Vite/webpack, the native build under Metro.
import { Avatar } from '@flipdish/ui-library/components/atoms/Avatar';

react-native >= 0.81 is load-bearing, not just a version floor. Every public subpath of this package is exposed through a wildcard exports map, and Metro only consults exports with Package Exports enabled — the default from Metro 0.82 / RN 0.79 onward. On anything older, no subpath of this package resolves at all.

Tailwind setup (NativeWind)

Use the styles.native entry, not styles. The web runtime declares Tailwind plugins, ::-webkit-scrollbar utilities and html/input resets that don't apply under NativeWind, and its @source scans the web build output for classes.

In your app's global.css — the file you import from your root component and point withNativewind at in metro.config.js:

@import 'tailwindcss/theme.css' layer(theme);
@import '@flipdish/ui-tokens/css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);

/* NativeWind's own theme variables — required by its Metro transformer. */
@import 'nativewind/theme';

@import '@flipdish/ui-library/styles.native';
@import 'tailwindcss/utilities.css';

styles.native contributes exactly one thing: @source "./native", which tells Tailwind to scan this package's React Native build output so the class strings inside Avatar, Button (and every component that follows) generate utilities. Without it those components render unstyled — Tailwind ignores node_modules unless a source is declared explicitly.

Dark mode follows the device colour scheme via NativeWind's useColorScheme. (The web runtime instead remaps dark: onto [data-theme="dark"], which has no RN equivalent.)

The @source mechanism mirrors what ./styles already does on web, where it's proven in production. The exact import order above is modelled on NativeWind v5's documented install and has not yet been executed against a real Expo app — confirm it during the pre-publish verification described below.

TypeScript setup

Add the react-native condition to your app's tsconfig.json so TypeScript resolves the same files Metro does:

{
  "compilerOptions": {
    "moduleResolution": "bundler", // or "node16" / "nodenext"
    "customConditions": ["react-native"],
  },
}

Without it you get the web type definitions — Avatar would appear to accept src and badge, neither of which the native implementation supports (initials IS supported natively).

Importing a component that isn't available yet

Both TypeScript and Metro reject it, so the mistake can't reach a device:

error TS2305: Module '"@flipdish/ui-library/components/atoms/Button"'
              has no exported member 'Button'.

Unable to resolve module .../dist/native/components/atoms/Button/index.js

Scoping Tailwind CSS to a subtree

When your app doesn't own the whole page — a widget, an embed, a Storybook preview, a multi-tenant host, or a micro-frontend — its Tailwind v4 output (utilities and Preflight resets) can leak into or clash with the surrounding CSS. The fix is to scope every emitted selector under a single element the app renders itself: UIProvider's scopeId stamps data-mfe-scope on the themed root for this. Never scope to a host container id (#flipdish-micro-frontend) or a union of ids; several apps share those containers, so the rules leak across them.

@flipdish/ui-library/utilities/cssScopeUtils ships createScopedPrefixTransform, a small factory for postcss-prefix-selector that consolidates the scoping rules (scope :root/html so @theme tokens and base typography cascade only within the subtree, leave :host and @keyframes steps alone, never double-prefix, etc.) so you write one line instead of copy-pasting a bespoke transform.

Install the companion plugin (an optional peer):

pnpm add -D postcss-prefix-selector

Then add it to your PostCSS config:

// postcss.config.mjs
import prefixSelector from 'postcss-prefix-selector';
import { createScopedPrefixTransform } from '@flipdish/ui-library/utilities/cssScopeUtils';

// Your Portal microFrontendWindowName; must match <UIProvider scopeId="sale-service">.
const SCOPE = '[data-mfe-scope="sale-service"]';

export default {
  plugins: [
    prefixSelector({
      prefix: SCOPE,
      transform: createScopedPrefixTransform(SCOPE),
    }),
  ],
};

Tailwind's output becomes plain [data-mfe-scope="sale-service"] .px-4 { … }, which every downstream tool (Vite, lightningcss) understands.

Options

createScopedPrefixTransform(scopeSelector, options?):

createScopedPrefixTransform('[data-tailwind]', {
  shouldScope: (file) => !file || !file.includes('node_modules'),
  scopeBody: true,
});

Why PostCSS and not Tailwind's important(#selector)? Tailwind v4's important(...) syntax emits non-standard @media important(...) blocks that lightningcss can't parse during minification, so scoping is done as a PostCSS pass over Tailwind's output instead.

Micro-frontends are one use case; the same transform applies to widgets, embeds, Storybook, and multi-tenant UIs.

Documentation

Full component docs, interactive examples, and design guidance live in the Storybook.

Changelog

See CHANGELOG.md for release history.

Contributing

This package lives in the flipdish-design-system monorepo. Contributor documentation — folder conventions, how Untitled UI components are adapted, the web/native file split, and dependency rules — lives alongside the source there.