Setup: React app

This page lists every condition a React app has to meet for BigBang, whatever its bundler. For step-by-step examples, see the Vite and Next.js guides. Products are built with Vite as client-rendered single-page apps (D-05).

Requirements

Requirement	Why
React and React DOM 19.3.1	@bigbang/ui asks for them as peer dependencies
A bundler that compiles TypeScript and TSX	@bigbang/ui and @bigbang/icons ship as source (src/index.ts)
Tailwind CSS v4	@bigbang/ui/styles.css imports Tailwind; component classes are generated in the app’s build
ES modules	The packages are published with "type": "module"

1. Packages

package.json

{
  "dependencies": {
    "@bigbang/tokens": "workspace:*",
    "@bigbang/ui": "workspace:*",
    "@fontsource-variable/inter": "5.3.0",
    "react": "19.3.1",
    "react-dom": "19.3.1"
  },
  "devDependencies": {
    "tailwindcss": "4.3.3"
  }
}

The packages are used from this repository’s workspace with workspace:*. Tailwind’s bundler plugin (@tailwindcss/vite for Vite, @tailwindcss/postcss for Next.js) is added as well.

2. Stylesheet

src/app.css

@import '@bigbang/ui/styles.css';
@import '@bigbang/tokens/css/neutral-light.css';
@import '@bigbang/tokens/css/neutral-dark.css';

/* Tailwind does not scan node_modules; add the component source explicitly. */
@source '../node_modules/@bigbang/ui/src';

• @bigbang/ui/styles.css imports Tailwind and tailwind-theme.css; utility classes (bg-surface-default, gap-md) are bound to the token variables.
• Import only the files of the brands you use. Each brand and mode is its own file; no theme loads at run time.
• The @source path is relative to the stylesheet. In the workspace the package is linked under node_modules/@bigbang/ui.

3. Font

The typography tokens lead with the Inter Variable family. Import the font in the app’s entry file; the files are served with the app, from the same origin:

src/main.tsx

import '@fontsource-variable/inter';
import './app.css';

Without Inter, text falls back to the system font in the token stack; sizes stay the same and letter widths change.

4. Brand and mode

index.html

<html lang="en" data-brand="neutral" data-theme="light">

Changing the mode is changing the attribute. To follow the user’s system preference:

const query = window.matchMedia('(prefers-color-scheme: dark)');
const apply = () => (document.documentElement.dataset.theme = query.matches ? 'dark' : 'light');
apply();
query.addEventListener('change', apply);

5. Provider

Provider sets the language of the library’s own strings, the text direction and the motion preference. Wrap the app once:

src/main.tsx

import { Provider } from '@bigbang/ui';
import { createRoot } from 'react-dom/client';
import { App } from './App';

createRoot(document.getElementById('root')!).render(
  <Provider locale="en-GB" direction="ltr" reducedMotion="system">
    <App />
  </Provider>,
);

Prop	Values	Default
locale	'tr-TR', 'en-GB'	'tr-TR'
direction	'ltr', 'rtl'	'ltr'
reducedMotion	'system', 'reduce'	'system'

reducedMotion="reduce" is for an in-product setting; when the system asks for reduced motion, no value turns motion back on (MOT-03).

6. Check

import { Button } from '@bigbang/ui';

<Button variant="primary">Primary button</Button>;

If the button shows the brand colour, tokens and styles are loaded. If it is plain and unstyled, check the @source path; if colours are missing, check the data-brand and data-theme attributes and that the brand CSS files are imported.