Reference guide for the XP App's reusable Vue components, organized following Atomic Design principles.

Components are organized into three tiers following Atomic Design:

1. Atoms - Basic UI primitives that cannot be broken down further
2. Molecules - Combinations of atoms into functional units
3. Organisms - Complex, feature-rich components

Location: src/components/

Basic building blocks that form the foundation of the UI.

Path: components/atoms/AnimatedNumber/

Displays numbers with smooth counting animations. Used for stat displays, counters, and score updates.

<AnimatedNumber :value="currentHP" :duration="500" />

Path: components/atoms/Currency/

Displays currency values (GP, XP, AP) with appropriate icons and formatting.

<CurrencyDisplay type="gp" :amount="100" />
<CurrencyDisplay type="xp" :amount="500" />

Path: components/atoms/Icon/

Wrapper component for FontAwesome and custom icons with consistent styling.

<XpIcon icon="fa-dungeon" size="lg" />
<XpIcon :icon="['fas', 'wind']" class="text-blue-500" />

Path: components/atoms/TypingText/

Typewriter-style text animation for dialog and story sequences.

<TypingText 
  :text="message" 
  :speed="50" 
  @complete="onTextComplete" 
/>

Combinations of atoms into functional units.

Path: components/molecules/Ability/

Displays ability cards with AP cost, MP cost, status, and cooldown information.

Path: components/molecules/AvatarSelect/

Character avatar picker with multiple options. Supports selection callbacks and preview modes.

<AvatarSelect 
  :avatars="availableAvatars"
  v-model="selectedAvatar"
/>

Path: components/molecules/BackgroundSelector/

UI for selecting background themes and parallax layers.

Path: components/molecules/CardMenu/

Card-based menu system for RPG-style action selection.

<XpCardMenu 
  :items="menuItems"
  @select="handleSelection"
/>

Path: components/molecules/Dialog/

Modal dialog component with customizable content and actions.

<XpDialog :open="showDialog" @close="showDialog = false">
  <template #content>
    Dialog content here
  </template>
</XpDialog>

Path: components/molecules/Loading/

Loading indicators and skeleton states.

Path: components/molecules/Modals/

Pre-built modal templates for common actions.

Path: components/molecules/RpgMenu/

RPG-styled menu with hover effects and selection states. Used throughout the app for consistent game-like interactions.

<XpRpgMenu :items="menuOptions" @select="onSelect" />

Path: components/molecules/StatBox/

Displays stat information with labels, values, and optional progress bars. Recently enhanced with premium glassmorphic styling and automated number counting.

• Stat Counting: Automatically animates numbers from 0 to the target value on load using vue3-autocounter.
• Premium Aesthetics: Features a glassmorphic design with backdrop-filter, semi-transparent borders, and deep shadows.
• Interactive States: Smooth hover transitions with lift effects and color shifts.

<XpStatBox 
  :value="1250"
  label="XP Today"
  iconName="fa-calendar-day"
  iconColor="primary"
/>

Complex components that provide full features.

Path: components/organisms/AudioSettings/

Complete audio configuration panel with volume sliders, mute toggles, and sound theme selection.

Path: components/organisms/BattleControls/

Full battle action interface including:

• Attack/Defend/Run buttons
• Ability selection
• Item usage

Path: components/organisms/CardUserStats/

User statistics card displaying:

• Avatar
• Name and level
• HP/MP bars
• XP progress
• GP balance

<CardUserStats :user="currentUser" />

Path: components/organisms/IntroSplash/

Introduction and splash screens for app launch and story sequences.

Path: components/organisms/SwiperGallery/

Image carousel component using Swiper.js for gallery displays.

Path: components/organisms/WeatherFX/

Weather effect overlays including:

• Rain
• Snow
• Lightning
• Fog
• Particles

<WeatherFX type="rain" :intensity="0.5" />
<WeatherFX type="snow" :intensity="0.3" />

// Atoms
import { XpIcon } from '@/components/atoms/Icon';
import { AnimatedNumber } from '@/components/atoms/AnimatedNumber';

// Molecules
import { XpRpgMenu } from '@/components/molecules/RpgMenu';
import { XpDialog } from '@/components/molecules/Dialog';

// Organisms
import { CardUserStats } from '@/components/organisms/CardUserStats';
import { WeatherFX } from '@/components/organisms/WeatherFX';

Follow the atomic hierarchy:

1. Is it a single-purpose element? → Atom
2. Does it combine 2-3 atoms? → Molecule
3. Is it a full feature? → Organism

Each component directory should contain:

ComponentName/
├── ComponentName.vue    # Main component
├── ComponentName.ts     # Logic (if complex)
├── _ComponentName.scss  # Styles
└── index.ts             # Export barrel

The app uses FontAwesome icons with custom coloring via SCSS classes:

// src/styles/icons/_icon-colors.scss
.icon-red { color: var(--ion-color-danger); }
.icon-blue { color: var(--ion-color-primary); }
.icon-gold { color: #ffd700; }

• Architecture - Overall technical structure
• Codebase Structure - File organization