# 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`).