> For the complete documentation index, see [llms.txt](https://code-after-sex.gitbook.io/script-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-after-sex.gitbook.io/script-documentation/vip-shop/guides/ui-development.md).

# Customizing the UI

The storefront is a React 19 and TypeScript application built with Vite. You only need this page if you want to change the UI itself; the resource ships pre-built.

## Toolchain

```bash
node >= 18
npm install
npm run dev              # browser preview at http://localhost:5180
npm run build:resource   # production build, copied into vip_shop/nui/
```

## Browser preview

The app detects when it runs outside RedM and mocks the NUI layer: a scenic backdrop appears, purchases resolve locally, and URL parameters unlock every state:

| Parameter             | Effect                                                             |
| --------------------- | ------------------------------------------------------------------ |
| `?cat=weapons`        | Open a category directly                                           |
| `?item=wpn-schofield` | Open a product's purchase dialog                                   |
| `?redeem=1`           | Open the redeem modal (`OUTLAW` grants 250 demo coins)             |
| `?member=marshal`     | Preview the shop as an active member (discounts, ACTIVE tier card) |

Add `VITE_TEBEX_TOKEN=...` to `.env` to preview against your live Tebex store, including the real checkout window.

## Where things live

```
src/
├── components/     # One file per page (HotDealsPage, CoinsPage, WeaponsPage, ...)
├── styles/         # One stylesheet per page, plus theme.css (design tokens)
├── data/catalog.ts # Browser demo catalog (in game the server's config wins)
├── lib/nui.ts      # NUI bridge (fetchNui, useNuiEvent, isEnvBrowser)
├── lib/tebex.ts    # Headless API client and the checkout window
└── store.ts        # zustand state (balance, membership, products, checkout)
```

Design tokens (colors, fonts, easings) are CSS variables in `src/styles/theme.css`. The palette is strictly near black, off white and RDR red; gold is reserved for the coin currency.

## Asset pipeline

* **Game textures.** White, tintable RDR2 UI textures from the `rdr3_discoveries` mirror, applied through CSS `mask-image` (the `MaskIcon` component). `scripts/download-extra-assets.ps1` re-downloads them.
* **AI imagery.** Product and hero renders are generated with `scripts/generate-images.mjs` (fal.ai, requires `FAL_KEY`) and auto trimmed with sharp.
* **WebP everywhere.** `scripts/convert-webp.mjs` converts new PNG or JPG drops, and also strips the baked in shadows that RDR2 item icons carry. Run it after generating new images.
* **Torn edge masks.** High resolution panel and card masks are produced with the upscale and threshold processing in `scripts/make-masks.mjs`.

## Performance rules the UI follows

Keep these if you extend it: animate only `transform` and `opacity` (never filter, box-shadow or text-shadow), avoid infinite zoom effects on large images, isolate per second timers into leaf components, and respect `prefers-reduced-motion`.