UI Library Overview

@elcto/ui is a shared React component library for Heimdall applications. It provides a consistent design system with reusable components, design tokens, and utilities.

Installation

The UI library is part of the monorepo workspace. It's automatically available to all platform apps.

For Platform Apps

Add the dependency to your package.json:

{
  "dependencies": {
    "@elcto/ui": "workspace:*"
  }
}

Then run:

pnpm install

Next.js Configuration

Add the package to transpilePackages in your next.config.ts:

const nextConfig: NextConfig = {
  transpilePackages: ["@elcto/ui"],
  // ... other config
};

Import Styles

Import the design tokens and component styles in your globals.css:

@import "tailwindcss";
@import "@elcto/ui/styles/tokens.css";
@import "@elcto/ui/styles/components.css";

/* Tell Tailwind to scan the shared UI library for classes */
@source "../../../../shared/ui/src/**/*.tsx";

Usage

Importing Components

// Import from components
import { Button, Modal, Alert } from "@elcto/ui/components";

// Import utilities
import { cn } from "@elcto/ui/utils";

Re-exporting in Your App

Create a local components/ui/index.ts to re-export shared components:

// Re-export from shared UI library
export {
  Button,
  Modal,
  Alert,
  // ... other components
} from "@elcto/ui/components";

// Re-export cn utility
export { cn } from "@elcto/ui/utils";

Then import from your local module:

import { Button, Alert } from "@/components/ui";

Package Structure

shared/ui/
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts              # Main barrel export
    ├── components/           # React components
    │   ├── Alert/
    │   ├── AnimatedBackground/
    │   ├── ApiHealthBanner/
    │   ├── AppSwitcher/
    │   ├── AuditIcons/
    │   ├── Avatar/
    │   ├── Badge/
    │   ├── Banner/
    │   ├── BlurredText/
    │   ├── Button/
    │   ├── Card/
    │   ├── Checkbox/
    │   ├── CodeInput/
    │   ├── DateTimePicker/
    │   ├── Dropdown/
    │   ├── FloatingInput/
    │   ├── Icons/
    │   ├── Input/
    │   ├── LanguageSwitcher/
    │   ├── LoadingSpinner/
    │   ├── Logo/
    │   ├── Modal/
    │   ├── Select/
    │   ├── SubMenuBar/
    │   ├── SubNav/
    │   ├── Table/
    │   ├── Toast/
    │   ├── Tooltip/
    │   └── Turnstile/
    ├── hooks/
    │   └── index.ts          # Custom hooks
    ├── styles/
    │   ├── tokens.css        # CSS design tokens
    │   └── components.css    # Component utility classes
    ├── utils/
    │   └── cn.ts             # Class name utility
    └── types/
        └── index.ts          # Shared types

Features

• Dark Theme - Optimized for dark mode interfaces
• TypeScript - Full type safety with exported types
• Tailwind CSS - Built with Tailwind for consistency
• Accessible - ARIA attributes and keyboard navigation
• Composable - Flexible component APIs

Available Components

Component	Description
Alert	Status messages with variants
AnimatedBackground	Animated gradient background with particles
ApiHealthBanner	Real-time API health monitoring
AppSwitcher	App navigation dropdown
AuditIcon	Icons for audit events
Avatar	User avatar with fallback
Badge	Status badges and labels
Banner	Full-width notification banners
BlurredText	Privacy-aware text display
Button	Interactive buttons with variants
Card	Content containers
Checkbox	Styled checkbox input
CodeInput	OTP/verification code input
DateTimePicker	Date, time, datetime picker
Dropdown	Dropdown menus
FloatingInput	Inputs with floating labels
Input	Basic text input
LanguageSwitcher	Locale selection dropdown
LoadingSpinner & Spinner	Loading indicators
Logo	Brand logo components
Modal	Dialog windows
Platform Icons	SVG icons for platforms
Select	Custom dropdown select
SubMenuBar	Horizontal sub-navigation bar below header
SubNav	Nested navigation tabs
Table	Data tables with pagination
Toast	Toast notifications
Tooltip	Hover tooltips
Turnstile	Cloudflare bot protection

Next Steps

• Design Tokens - Colors, spacing, and theming
• Components - Component API reference
• Icons - Platform icons