UI Architecture

UI Architecture

React/TypeScript frontend in client/src/ using Tailwind CSS, Radix UI, CVA (class-variance-authority), and Storybook.

Component Hierarchy

client/src/components/
├── icons/          # SVG icon components (see ui-architecture-icon skill)
├── ui/             # Radix UI primitives (Button, Select, Tabs, etc.)
├── elements/       # Game-specific UI elements (Stat, Balance, PowerUp, etc.)
├── containers/     # Page-level compositions (Header, Games, Leaderboard, etc.)
├── animations/     # Motion components (Countup, Countdown)
└── layouts/        # Layout wrappers

Shared Utilities

• cn() from @/lib/utils — merges Tailwind classes safely (clsx + tailwind-merge)
• iconVariants() from @/components/icons — CVA variants for icon sizing
• useAudio() from @/context/audio — sound effects for interactive components

Git Hygiene (MANDATORY)

Always pull before branching

Before creating a new feature branch, always pull and rebase the base branch to ensure you start from the latest state. Stale branches cause merge conflicts and wasted effort.

# CORRECT: Always do this before creating a feature branch
git checkout main && git pull --rebase origin main && git checkout -b feat/my-feature

# WRONG: Creating a branch from a stale main
git checkout -b feat/my-feature  # main might be behind origin

Barrel Export Rule (MANDATORY)

Every new component MUST be exported from its directory's index.ts

Every component directory has a barrel index.ts file that re-exports all components. When creating a new component, always add an export line to the directory's index.ts. A component that isn't exported is invisible to the rest of the app.

Export pattern

// client/src/components/elements/index.ts
export * from "./my-new-component";

Where to export

Checklist (BLOCKING — component is NOT done without these)

• Component file created (my-component.tsx)
• Export added to directory index.ts (export * from "./my-component")
• Storybook file created (my-component.stories.tsx)
• pnpm format and pnpm lint:check pass (see Validation section)

Validation Rules (MANDATORY)

Always format and lint after every change

After every modification to client/ files, run:

pnpm format
pnpm lint:check

• pnpm format — auto-fixes formatting (Prettier). Run first.
• pnpm lint:check — reports lint errors (ESLint). Fix any errors before moving on.

This applies to ALL client changes: new components, prop updates, import changes, storybook files — everything. No exceptions. Do NOT batch these to the end; run them after each logical change.

Storybook Rules (MANDATORY)

Every component MUST have a storybook

When creating a new component, always create a .stories.tsx file alongside it. When modifying a component (new props, new variants, changed behavior), always update its storybook to cover the changes.

Match existing storybook style

Before writing a storybook, read 2-3 existing .stories.tsx files in the same directory to match the exact code style. The patterns vary by component tier:

Element storybook pattern

File: client/src/components/elements/<component>.stories.tsx

import type { Meta, StoryObj } from "@storybook/react-vite";
import { MyComponent } from "./my-component";

const meta = {
  title: "Elements/My Component",
  component: MyComponent,
  parameters: {
    layout: "centered",
  },
  globals: {
    backgrounds: {
      value: "dark",
    },
  },
  argTypes: {
    myProp: {
      control: "text",
      description: "Description of the prop",
    },
    variant: {
      control: "select",
      options: ["default", "secondary"],
      description: "The visual variant",
    },
  },
} satisfies Meta<typeof MyComponent>;

export default meta;
type Story = StoryObj<typeof meta>;

// Keep it minimal — one Default story with representative data is enough
export const Default: Story = {
  args: {
    myProp: "value",
  },
};

Container storybook pattern

Containers often need mock data or providers. Follow existing container stories for the wrapping pattern.

Key conventions

• satisfies Meta<typeof Component> — always use satisfies, not as
• globals.backgrounds.value: "dark" — always dark background
• parameters.layout: "centered" — always centered layout
• argTypes — document every controllable prop with control and description
• Keep stories minimal — one Default story with representative mixed data is usually sufficient. Storybook controls (argTypes) let users explore other states interactively. Only add extra stories for distinct CVA variants (e.g. variant: "secondary"), not for different data permutations.
• Use fn() from storybook/test for callback props (onClick, onChange, etc.)
• Title format: "Tier/Component Name" — use spaces for compound names (e.g., "Elements/Game Icon", "Containers/Game Over", "Elements/Staking Reward")

When to update storybooks

Component Patterns

Universal CVA Pattern (MANDATORY for all tiers)

Every component across elements, containers, animations, and covers MUST use cva + VariantProps + cn(). This is the universal pattern — no exceptions, even with a single default variant. Consistency and extensibility are non-negotiable.

Standard pattern (elements, containers)

import { cn } from "@/lib/utils";
import { cva, type VariantProps } from "class-variance-authority";

export interface MyComponentProps
  extends
    React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof myComponentVariants> {
  // custom props
}

const myComponentVariants = cva("base-classes", {
  variants: {
    variant: {
      default: "default-classes",
    },
  },
  defaultVariants: {
    variant: "default",
  },
});

export const MyComponent = ({
  variant,
  className,
  ...props
}: MyComponentProps) => {
  return (
    <div className={cn(myComponentVariants({ variant, className }))} {...props}>
      {/* content */}
    </div>
  );
};

ForwardRef pattern (ui primitives only)

ui/ components additionally use forwardRef and named exports:

import * as React from "react";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

const myComponentVariants = cva("base-classes", {
  variants: {
    variant: {
      default: "default-classes",
      secondary: "secondary-classes",
    },
    size: {
      md: "size-md-classes",
      lg: "size-lg-classes",
    },
  },
  defaultVariants: {
    variant: "default",
    size: "md",
  },
});

export interface MyComponentProps
  extends
    React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof myComponentVariants> {}

const MyComponent = React.forwardRef<HTMLDivElement, MyComponentProps>(
  ({ className, variant, size, ...props }, ref) => (
    <div
      className={cn(myComponentVariants({ variant, size, className }))}
      ref={ref}
      {...props}
    />
  ),
);
MyComponent.displayName = "MyComponent";

export { MyComponent, myComponentVariants };

Exceptions (do NOT use as precedent)

These components intentionally skip CVA because they are not styled components:

Audio Integration

Interactive components integrate sound via useAudio():

import { useAudio } from "@/context/audio";

const MyButton = () => {
  const { playClick } = useAudio();
  return (
    <button
      => {
        playClick(); /* action */
      }}
    >
      Click
    </button>
  );
};

Theming

Design Tokens

CSS variables in client/src/themes/default.css — 30+ color families with 9-level opacity scales (100-900).

Game-specific colors: purple, mauve, yellow, red, green, pink, blue, brown, black, gray, white. Power colors: double, down, reroll, wildcard, swap, halve, up, low, foresight, high. Trap colors: ribbon, gem, magnet, windy, lucky, slots, bomb, ufo, glitchbomb.

All mapped to Tailwind utilities via client/src/themes/preset.ts:

bg-purple-100, text-yellow-200, border-red-500, etc.

Fonts

Custom Animations

Defined in client/src/index.css:

• reward-diff — floating text (2s)
• shimmer-reflect — shiny text effect (6s)
• multiplier-fire — fire effect (1.75s)
• pulse-border — pulsing outline (3s)
• toast-progress — progress bar (4s)

UI Primitives (Radix)

All in client/src/components/ui/. Use CVA for variants, forwardRef pattern, and integrate useAudio() for click sounds.

Dependencies