Components Overview

The UI Kit provides four categories of functionality:

UI Primitives

Low-level, accessible components from shadcn-vue. These are unstyled by default and themed via CSS variables.

Available Components

Component	Description
Accordion	Collapsible sections
Alert	Alert messages
AlertDialog	Confirmation dialog
AspectRatio	Aspect ratio container
Avatar	User avatar
Badge	Status badge
Button	Clickable button with variants and sizes
Calendar	Date picker
Card	Content container
Checkbox	Checkbox input
Collapsible	Collapsible content
Command	Command palette
ContextMenu	Right-click menu
Dialog	Modal dialog with overlay
DropdownMenu	Context menu
Form	Form wrapper with validation
HoverCard	Hover preview
Input	Text input with v-model support
Label	Form label
Menubar	Top menubar
NavigationMenu	Site navigation
Pagination	Page navigation
Popover	Floating content
Progress	Progress indicator
RadioGroup	Radio button group
ScrollArea	Custom scrollbar
Select	Dropdown select input
Separator	Visual divider
Sheet	Side panel
Skeleton	Loading placeholder
Slider	Range slider
Switch	Toggle switch
Table	Data table
Tabs	Tabbed navigation
Textarea	Multiline text input
Toaster (Sonner)	Toast notifications
Tooltip	Hover tooltip

Domain Components

Platform-specific components designed for GXP platform use cases.

Available Components

Component	Description
ActivityNotifications	Toast notification system for activity events
AudioVisualizer	Frequency bars and waveform timeline via Web Audio API
AwardIcon	SVG award/medal icon
BarcodeScanner	QR/barcode scanning using Quagga2 with dynamic import
Countdown	Idle timeout countdown with user interaction detection
FileUploader	File upload with image processing and multi-file support
Header	Page header with background image, logo, and video support
Leaderboard	Ranked list with placeholders, top-3 styling, and animations
Spinner	Loading spinner with sm/md/lg sizes
VideoPlayer	HTML5 video player with TypeScript props and events

Composables

Reusable composition functions for common platform functionality.

Available Composables

Composable	Description
useAnimations	Page transition animations with animate.css
useErrors	Shared error message state management
useMedia	Video/audio recording, device management, canvas processing
useNfcListener	NFC scan event handler via window.postMessage
useScanning	Barcode/QR scan state management
useExperience	State-machine orchestrator for multi-stage flows
useExperienceApi	Adapter that maps callApi to named experience actions

Experience Flow

A state-machine orchestrator with 20 prebuilt page components for building multi-stage interactive apps (kiosks, photo booths, AI experiences). Pages are pure (emit data only); the optional useExperienceApi adapter wires API calls between pages so a typical flow is ~5 lines of config.

See the Experience Flow overview for the full guide.

Orchestration

Export	Description
useExperience(config)	Owns navigation, reactive context, busy/error state, action dispatch
<ExperienceFlow :flow />	Renderer with transitions and loading/error slots
useExperienceApi({ callApi })	Optional adapter that turns callApi into typed named operations
withExperienceDefaults(component, defaults)	Attach a default action / result key to a page component

Prebuilt Pages

All pages emit next / back (and where relevant exit), expose customization slots, and ship with sensible defaults. See Pages reference for full per-page details.

Intro & legal

Page	Description
WelcomePage	Splash / landing screen with title, subtitle, CTA
TermsPage	Legal consent with optional accept checkbox
InstructionsPage	How-to guide with optional image/video

Capture

Page	Description
CameraPage	Photo capture with countdown, mirroring, border/silhouette overlays
CameraReviewPage	Preview captured photo with accept/retake + optional caption
VideoCapturePage	Video recording with max-duration timer
VideoReviewPage	Playback + accept/retake for captured video
AudioCapturePage	Audio recording with frequency visualizer
AudioReviewPage	Playback + accept/retake for captured audio
DrawingPage	Canvas drawing with pen, eraser, undo, clear, color picker
NotepadPage	Typed-text note on coloured paper, rendered to PNG blob
TextPage	Multiline text input with character limit
PromptPage	Freeform or Mad-Libs-style prompt entry
OptionsPage	Choice-button grid for branching flows
FormPage	Dynamic schema-driven form with conditional fields

Outcome

Page	Description
ResultsGalleryPage	Grid of AI-generated results with selection + regenerate
PhotoEditPage	Subject + backdrop canvas compositor with optional border
SharePage	Final media display with native navigator.share + fallback
FinalPage	Outcome screen with QR code and configurable action buttons

Utility

Page	Description
LoadingPage	Standalone loading screen for long-running async work between steps

Component Architecture

File Structure

Each component follows this structure:

src/components/ui/<component-name>/
├── ComponentName.vue      # Main component
├── index.ts               # Exports
├── ComponentName.test.ts  # Unit tests
└── ComponentName.stories.ts  # Storybook stories

For domain components:

src/components/domain/<component-name>/
├── ComponentName.vue      # Main component
├── index.ts               # Exports
├── ComponentName.test.ts  # Unit tests
└── ComponentName.stories.ts  # Storybook stories

For experience pages:

src/experience/pages/<page-name>/
├── PageName.vue           # Main page component
├── index.ts               # Exports + withExperienceDefaults wrapping
├── PageName.test.ts       # Unit tests (logic-bearing pages)
└── PageName.stories.ts    # Storybook stories

Naming Conventions

• PascalCase for component names: Button.vue, VideoPlayer.vue
• kebab-case for directories: video-player/, barcode-scanner/
• Type exports suffixed with type: ButtonVariants, InputProps

Props Pattern

Components use TypeScript interfaces for props:

interface Props {
  variant?: 'default' | 'secondary' | 'destructive'
  size?: 'default' | 'sm' | 'lg'
  disabled?: boolean
  class?: string
}

Event Pattern

Components emit typed events:

const emit = defineEmits<{
  (e: 'click', event: MouseEvent): void
  (e: 'update:modelValue', value: string): void
}>()

Using Components

Basic Import

import { Button, Input, VideoPlayer } from '@gxp-dev/uikit'

With Types

import { Button, type ButtonVariants } from '@gxp-dev/uikit'

Using Composables

import { useMedia, useScanning } from '@gxp-dev/uikit'

const { startRecording, stopRecording } = useMedia()
const { startScanning, stopScanning } = useScanning()

Accessing Variant Functions

Some components export variant functions for advanced styling:

import { buttonVariants } from '@gxp-dev/uikit'

// Use in custom component
const classes = buttonVariants({ variant: 'secondary', size: 'lg' })

Customizing Components

Via Props

<Button variant="secondary" size="lg" class="custom-class">
  Custom Button
</Button>

Via CSS Variables

Override the theme CSS variables:

:root {
  --primary: #your-color;
  --primary-foreground: #your-text-color;
}

Via Tailwind

Add custom classes that merge with defaults:

<Button class="rounded-full shadow-lg">
  Rounded Shadow Button
</Button>

Accessibility

All UI primitives from shadcn-vue are built on Reka UI, which provides:

• Keyboard navigation - Full keyboard support
• Focus management - Proper focus handling
• ARIA attributes - Semantic accessibility
• Screen reader support - Announced correctly

Storybook

Explore components interactively:

pnpm storybook

Each component has stories demonstrating:

• All variants and sizes
• Interactive controls
• Edge cases
• Accessibility features