> For the complete documentation index, see [llms.txt](https://suigar.gitbook.io/suigar-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suigar.gitbook.io/suigar-docs/end-to-end-ai-map/frontend-v3.md).

# Frontend v3

Reference sheet for AI and human passes inside the experimental Suigar casino-gacha frontend.

## TL;DR

* Vite 7 + React 19 + TypeScript prototype for a white-label casino/gacha UI.
* Default tenant is Suigar; VITE\_CASINO\_TENANT=tasty-crousty switches the branded tenant.
* Runtime art flows through CasinoArt; textures and identity generation are documented under poc-frontend-v3/docs/.
* Keep route copy, mock data, tenant overrides, art mapping, and theme tokens separated so future AI passes can change one layer without hunting through pages.

## Commands

Run from poc-frontend-v3/:

* pnpm run dev
* pnpm run typecheck
* pnpm run lint
* pnpm run validate:assets
* pnpm run validate:tenant-copy
* pnpm run build
* pnpm run test

## Project Shape

* src/app/: app shell and router.
* src/pages/: route-level page entry files.
* src/features/: route/page implementations by product area.
* src/components/casino/: casino-specific reusable primitives, hero stage, cards, art, tables, titles.
* src/components/ui/: small generic UI primitives.
* src/design/: global CSS, tokens, effects, and typed design mappings.
* src/tenants/: active tenant resolution, tenant content overrides, and tenant art maps.
* src/data/mock.ts: default and tenant-specific mock content feeding pages.
* src/assets/generated/: default Suigar generated art, textures, cutouts, and sprites.
* src/assets/tenants/: tenant-specific sourced/generated assets.
* docs/: architecture, design, texture, asset, and white-label generation contracts.

## Design System Rules

* Use src/design/tokens.css for semantic colors, shadows, fonts, and gradients.
* Use src/design/effects.css for shared casino surface texture classes and animation effects.
* Use src/design/accent.ts for typed accent-to-style mappings. Do not create local Record\<Accent, ...> maps in page components unless the map is truly page-specific.
* Use Panel, Button, Badge, ProgressBar, and casino primitives before adding bespoke div styling.
* Generated art should never include text, buttons, labels, balances, or fake UI.
* Texture generation rules live in docs/TEXTURE\_GENERATION\_FRAMEWORK.md.

## Tenant Rules

* Shared/default strings live in src/tenants/content.ts.
* Tenant-specific language stays in the tenant override object or tenant mock data.
* Tenant-specific art maps stay in src/tenants/.ts.
* Tenant-specific colors and texture overrides stay in src/themes/.css.
* Route components should not hardcode tenant names unless they are displaying a value passed from tenant content.
* `pnpm run validate:tenant-copy` checks shared app/feature/component layers for hardcoded tenant words.

## Art Rules

* Use CasinoArt semantic kinds instead of direct image imports in pages.
* Add a new art kind to src/types/casino.ts, CasinoArt.tsx, docs, and mock data together.
* Default generated texture slots are documented in docs/TEXTURE\_GENERATION\_FRAMEWORK.md and docs/ASSET\_MANIFEST.md.
* `pnpm run validate:assets` verifies generated texture dimensions/alpha, `CasinoArt` cutout presence/alpha, 1x4 sprite strip dimensions, and sprite manifest consistency.
* Sprite sheets are 1 row x 4 frames, centered in 512x512 cells, and tracked in src/assets/generated/spritesheets/manifest.json.

## Safe Refactor Pattern

1. Read the route/component and its mock data first.
2. Extract repeated constants into src/design/, src/tenants/, or src/features//.
3. Preserve visible behavior before changing visuals.
4. Keep page files as composition shells; move reusable surfaces into src/components/casino/.
5. Run pnpm run typecheck and pnpm run build after code or asset path changes.
6. Run pnpm run validate:assets after generated texture changes.

## Current AI-Friendly Improvement Targets

* Move repeated hero-stage placement recipes out of JSX into typed data if the hero roster keeps growing.
* Split large casino primitive files once a primitive family has stable call sites.
* Add Storybook or a lightweight Vite route for visual QA of core casino primitives.
* Add a visual QA route for casino primitives and generated art placement recipes.