gui/LLM.md

LLM context — @luxfi/gui

This file (CLAUDE.md) is the canonical agent-facing readme; LLM.md is a symlink to it. Update either name and both stay in sync.

Lux-branded UI chrome composed on top of hanzogui (a Tamagui distribution). Ships header, footer, hero, feature grid, stat card, CTA, nav, chat, design tokens, and a Lux Tamagui config extension. Every Lux web property (lux.network, lux.finance, lux.exchange, and the rest of the portfolio) consumes this package so brand chrome stays identical across apps.

What lives here

• src/index.ts — flat barrel that re-exports every surface package.
• src/gui.config.ts — extends @hanzogui/config/v5 defaults with lux_dark / lux_light themes via createGui; exposed at @luxfi/gui/config for <GuiProvider config={...}>.
• src/header/, src/footer/, src/hero/, src/feature-grid/, src/stat-card/, src/cta/, src/nav/, src/chat/ — one surface per directory; each has an index.ts and a single TSX file.
• src/tokens/ — colors.ts (luxLight / luxDark), typography.ts, spacing.ts, re-exported via tokens/index.ts.
• package.json — canonical peer-dep ranges and the exports map.

Package structure

The exports map in package.json exposes one entry per surface so consumers can import the barrel or a single component bundle:

import { LuxHeader, LuxFooter, LuxHero, LUX_PRODUCTS } from '@luxfi/gui'
import { LuxHeader } from '@luxfi/gui/header'   // smallest slice
import { luxColors } from '@luxfi/gui/tokens'
import luxConfig from '@luxfi/gui/config'

"type": "module" and "sideEffects": false let bundlers tree-shake any unused surface.

Tamagui composition pattern

Each component is a Tamagui primitive composition — YStack, XStack, H1..H6, Paragraph, Button, Popover, Sheet, etc. — re-shaped into a Lux-branded surface. Responsive behaviour uses Tamagui media queries ($gtSm, $gtMd, $gtLg); no Tailwind, no runtime CSS.

Components must render inside a <GuiProvider> from hanzogui:

import { GuiProvider } from 'hanzogui'
import luxConfig from '@luxfi/gui/config'

<GuiProvider config={luxConfig} defaultTheme="lux_dark">{children}</GuiProvider>

gui.config.ts augments @hanzogui/web's GuiCustomConfig interface via declare module, so consumers get Lux theme types automatically.

Peer dependencies

From package.json (canonical):

Peer	Range
hanzogui	>=7.3.0
react	>=19
react-dom	>=19

pnpm add @luxfi/gui hanzogui react react-dom

Note: the top-level README.md references @hanzo/gui in install / code samples, but the actual source and package.json use the hanzogui package name. Trust package.json and src/gui.config.ts for the real import path.

Variant system + render-prop links

LuxHeader accepts a variant prop that highlights the active product and brands the wordmark: network, finance, financial, exchange, credit, fund, invest, safe, market, cloud, id, industries, docs, default. Nav structure lives in LUX_PRODUCTS and LUX_PRIMARY_LINKS (src/nav/).

Every component takes renderLink={({ href, children }) => ReactNode} so the host app owns its router (Next, TanStack Router, Expo Router). The default renderer is a plain <a>.

Consumer projects

The Lux portfolio per README.md: lux.network, lux.finance, lux.exchange, lux.financial, lux.cloud, lux.industries, lux.id, plus the variant list above. Each property imports the same barrel, picks a variant, and supplies its own renderLink.

Build

pnpm install
pnpm build       # tsc -p tsconfig.build.json → dist/
pnpm typecheck

Cross-refs

• README.md — canonical export table, usage example, variant list.
• package.json — authoritative peer-dep ranges and exports map.
• src/gui.config.ts — theme augmentation on @hanzogui/config/v5.
• hanzoai/gui (hanzogui) — upstream Tamagui distribution.
• Org inventory: /Users/a/work/lux/luxfi/LLM.md (sibling repos, inter-repo deps).