<!-- BEGIN:nextjs-agent-rules -->
# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
<!-- END:nextjs-agent-rules -->

<!-- ASTRYX:START -->
Astryx v0.2.0 · 154 components
CLI: run every command as `npx astryx <cmd>` (shown below as `astryx ...`).

SETUP (once, in your app entry e.g. main.tsx) — without these, components render unstyled:
  import "@astryxdesign/core/reset.css";
  import "@astryxdesign/core/astryx.css";

WORKFLOW — discover, don't guess. Before writing UI:
1. `astryx build "<idea>"` — START HERE: returns a kit (closest [page] + [block]s + [component]s). No args = full playbook.
2. `astryx template <name> [--skeleton]` — scaffold the [page]/[block]s it named, or study their layout. Templates are reference code.
3. `astryx component <Name>` — props + examples for every component you use.

RULES:
- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.
- Frame first: pick the shell (AppShell / Layout+LayoutPanel) and budget regions in px BEFORE writing content (`astryx docs layout`).
- Dense data = rows (Table, List/Item) edge-to-edge — never Card-wrapped list items. Card = dashboard widgets, galleries, settings groups only.
- Status → StatusDot/Token; Badge only for counts and enumerated states, never decoration.
- Custom styling: component props first; else Tailwind utilities backed by tokens (bg-surface, text-primary, rounded-lg) via tailwind-theme.css. No raw hex/px.
- Tokens for every value (`astryx docs tokens`). Brand/accent via `astryx theme` — never override --color-* in :root.
- SELF-CHECK before you finish: re-read the file and replace any style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded/arbitrary value (e.g. bg-[#fff], p-[13px]) with the component or a token-backed utility. If unsure a component/prop exists, run `astryx component <Name>` / `astryx search "<thing>"`; don't hand-roll CSS.

MORE CLI:
  search "<query>"   find any component / hook / doc / template / block
  component --list   154 components by category
  template --list    page + block recipes
  docs <topic>       color, elevation, icons, illustrations, internationalization, layout, migration, motion, principles, shape, spacing, styling, theme, tokens, typography
  swizzle <Name>     eject component source for deep customization
  upgrade --apply    run after any @astryxdesign/core bump
<!-- ASTRYX:END -->

<!-- LOYALY:START -->
# Loyaly Merchant Dashboard — project rules

## Toolchain
- **Node 22 is required** (`.nvmrc` → 22.23.1). The astryx CLI hard-fails on Node 20.
  `nvm use` before running any `npx astryx` command or `npm run theme:build`.
- Dev server runs on **port 3100** (`lytsup-site` owns 3000).

## Theme
- All design values live in `src/theme/loyalyTheme.ts`. Edit that, then run
  `npm run theme:build`, then **commit the generated** `src/theme/loyaly.{css,js,d.ts,variants.d.ts}`.
- `theme:build` is deliberately NOT wired to `prebuild` — it would break `npm run build` on Node 20.
- Import the theme from **`@/theme`**, never `@/theme/loyaly` directly. `@/theme` re-attaches
  the Lucide icon registry, which `astryx theme build` cannot serialise (icons are React
  components). Skipping it silently degrades every `<Icon>` to Astryx's default glyph set.
- `globals.css` imports `../theme/loyaly.css`, NOT `@astryxdesign/theme-neutral/theme.css`.
  Astryx theme CSS is `@scope`-gated on the theme *name*, so neutral's rules match nothing
  under `[data-astryx-theme="loyaly"]`.

## The monochrome rule
Gray is the accent. The **only** colour permitted is semantic: success, warning, error.
- Astryx's categorical hues (blue/cyan/teal/purple/pink/orange) are aliased to gray in
  `aliasHueToGray()`. green/red/yellow deliberately keep hue — Banner's semantic statuses
  resolve *through* those hue tokens.
- Some neutral-theme component styles hardcode colour instead of reading a token
  (`badge variant:info`, `progressbar variant:accent`). Those need an explicit `components`
  override; `aliasHueToGray()` cannot reach them.
- `/tokens` (dev-only route) is the audit page. After any theme change, load it and run the
  chromatic sweep in the browser console — it should report **0** non-semantic colour nodes.

## Known upstream issues (Astryx 0.2.0)
- **`useEntryAnimation` breaks SSR hydration.** Its source assumes `'use client'` modules never
  run on the server; in the App Router they do. Any `FieldStatus` (i.e. `TextInput`/`TextArea`
  `status={...}`) present at *initial paint* renders without the slide-down class on the server
  and with it on the client → an unpatchable class mismatch. Setting status on blur/submit
  (the normal path) is unaffected. Don't server-render a field that already has a status.
- Component keys in `defineTheme({components})` are inconsistently cased: `text-input` but
  `progressbar`. The CLI warns on unknown keys — **treat any `⚠ Unknown component` from
  `theme:build` as an error**, it means the override silently did nothing.

## Conventions
- Follow the Astryx rules above: no raw `<div>` for layout, no hardcoded hex/px, component
  props first then token-backed Tailwind utilities.
- `src/lib/icons.ts` is the single icon map. Only the 26 semantic names resolve via
  `<Icon icon="search"/>`; everything else is `<Icon icon={ICONS.stores}/>`. Never import a
  lucide icon directly into a feature file.
<!-- LOYALY:END -->