---
name: lumioui
description: Use when building or changing React Native / Expo UI in a project that uses LumioUI (has lumioui.json, components/ui or lib/lumioui). Covers finding the right LumioUI component or screen before writing one, installing it with the CLI, importing it, theming with tokens and accents, motion tokens, accessibility, and checking the setup.
---

# LumioUI

LumioUI is a React Native component library for Expo and bare React Native. Components and
screens are copied into the project as source by `npx @lumioui/cli`, so they live in this repo
and can be edited like any other file. Styling is NativeWind (`className`) on theme tokens;
motion is Reanimated.

## 1. Before writing UI, look for it

1. Check what is already installed: `components/ui/<name>/` (components) and `screens/<flow>/`
   (screen templates).
2. Check the catalogue: https://lumioui.com/llms.txt lists every component, variant and screen
   with one line each. Read a component's props and examples at
   `https://lumioui.com/components/<name>.md`, a screen's at `https://lumioui.com/screens/<name>.md`.
3. Prefer composing LumioUI components over writing new ones. Write a new component only when
   nothing in the catalogue fits, and build it from the same tokens and motion rules below.

## 2. Install

```sh
npx @lumioui/cli add button card input          # free components
npx @lumioui/cli add accordion-multiple          # a variant: <family>-<slug>
npx @lumioui/cli add pro/bottom-sheet            # Pro components need the pro/ prefix
npx @lumioui/cli add pro/ecommerce-checkout      # Pro screens: pro/<flow>-<name>
```

- Pro items need a licence: `npx @lumioui/cli login` once per computer (`whoami` shows the plan).
  If a Pro install is refused, tell the user; don't recreate the component by hand.
- `add` installs everything an item depends on (other components, `react-native-gesture-handler`
  and similar) and prints the import line for each item.
- Items marked "requires a dev build" don't run in Expo Go; say so when you add one.
- Never edit `lib/lumioui` to change one screen; style at the call site instead.

## 3. Import and use

```tsx
import { Button } from "./components/ui/button";          // a family: import its folder
import { AccordionMultiple } from "./components/ui/accordion/variants/multiple";
import { useTheme, Accent, spring, timing, useReducedMotion, useHaptic } from "./lib/lumioui";
```

Paths are relative to the file you're editing; `add` prints them from the project root.
Components are named exports with full TypeScript props; read the installed source for the exact
API rather than guessing.

## 4. Theme

- The app root is wrapped in `<ThemeProvider>` from `lib/lumioui` (`init` does this). Light and
  dark follow the device unless the app overrides it.
- Colour comes from semantic classes, never raw hex in `className`:
  `bg-background`, `bg-card`, `text-foreground`, `text-muted-foreground`, `bg-primary`,
  `text-primary-foreground`, `text-primary-text` (accent-coloured text), `bg-secondary`,
  `bg-muted`, `border-border`, `border-input`, `bg-destructive`, `bg-success`, `bg-warning`.
- `bg-primary` is neutral ink until a screen picks an accent. Give a screen colour by wrapping it:
  `<Accent color="orange">…</Accent>`. Accents: blue, indigo, violet, pink, red, coral, orange,
  amber, lime, green, mint, teal, sky, or a `#RRGGBB`. One accent per screen.
- Use `useTheme().colors` only where a colour can't be a class (SVG strokes, `interpolateColor`,
  `ActivityIndicator`).

## 5. Motion

- Animate with Reanimated shared values. Use the tokens from `lib/lumioui`: `spring.press`,
  `spring.surface`, `spring.layout`, `spring.swap`, `spring.panel`, `spring.dismiss`, and
  `timing.fast` / `timing.normal` / `timing.recede`. No one-off spring numbers.
- Respect `useReducedMotion()`: keep opacity and colour changes, drop movement and scale.
- Haptics through `useHaptic()` (`selection` for toggles, `light` for buttons, `warning` when
  something is refused). Don't import `expo-haptics` directly.
- Press feedback through `usePressAnimation()`.
- Continuous gestures (sliders, drags) update shared values on the UI thread and set React state
  only when the stepped value changes or on release.

## 6. Layout and accessibility

- Touch targets at least 44pt (use `hitSlop` when the visual is smaller).
- Set `accessibilityRole`, `accessibilityLabel` and `accessibilityState` on anything tappable.
- No text under 12pt. Pad scroll content clear of docked bars and the home indicator
  (`useSafeAreaInsets`).
- Rows that hold a value and a label: the label must stay readable; let the value truncate.

## 7. Screens (Pro)

A screen template installs to `screens/<flow>/<name>.tsx` plus `screens/shared.tsx` (shared
helpers such as `World`, `SoftCard`, `Amount`, `StickyBottomBar`). Render it from a route file and
pass its props (`onBack`, data, callbacks). Replace the sample data with the app's real data; keep
the structure and motion. For how to design screens that look like Lumio, use the
`lumio-taste` skill if it's installed.

## 8. When something looks wrong

Run `npx @lumioui/cli doctor`. It checks NativeWind, Babel/Metro, the theme files, the root
`ThemeProvider` and the licence key. Unstyled components usually mean `global.css` isn't imported
in the root file or Metro needs `npx expo start -c`.