Luaniverse

Lua Design System - A React component library for Lua applications


Installation

``bash
npm install @lua-global/luaniverse


or

yarn add @lua-global/luaniverse

or

pnpm add @lua-global/luaniverse
`

Usage

$3

`tsx
import { Button, IconButton, Badge, Textarea } from '@lua-global/luaniverse';
import { UserIcon, Trash, PDF, PNG, Chat, Clock, Minus, Plus, Tag } from '@lua-global/luaniverse';
`

$3

Import the CSS file in your app's entry point:

`tsx
import '@lua-global/luaniverse/styles';
`

Available Exports:
- @lua-ai-global/luaniverse - Components and utilities
- @lua-ai-global/luaniverse/styles - CSS styles and design tokens
- @lua-ai-global/luaniverse/tailwind - Tailwind preset for utility classes

> 💡 Quick Setup: See INTEGRATION.md for step-by-step consumer app setup instructions.

$3

⚠️ IMPORTANT: Luaniverse requires BOTH the Tailwind preset AND the styles to work correctly. Missing either will cause components to lose their backgrounds and styling.

#### Step 1: Add the Tailwind Preset

Update your tailwind.config.js to use the Luaniverse preset:

`js
// tailwind.config.js
import { luaniversePreset } from '@lua-ai-global/luaniverse/tailwind';

export default {
presets: [luaniversePreset], // 🔥 Required for component styling
content: [
// Your content paths
'./src/*/.{js,jsx,ts,tsx}',
'./app/*/.{js,jsx,ts,tsx}',
// 🔥 Required: Include luaniverse components for class detection
'./node_modules/@lua-ai-global/luaniverse/*/.{js,jsx,ts,tsx}',
],
// Your additional config...
};
`

Or with CommonJS:

`js
// tailwind.config.js
const { luaniversePreset } = require('@lua-ai-global/luaniverse/tailwind');

module.exports = {
presets: [luaniversePreset],
content: [
'./src/*/.{js,jsx,ts,tsx}',
'./node_modules/@lua-ai-global/luaniverse/*/.{js,jsx,ts,tsx}',
],
};
`

#### Step 2: Import the Styles

In your main CSS file, import the Luaniverse styles:

`css
/ app.css or globals.css /
@import '@lua-ai-global/luaniverse/styles'; / 🔥 Required for design tokens /
@import 'tailwindcss';
`

#### Why Both Are Required

- Preset: Enables utility classes like bg-popover, text-card-foreground
- Styles: Provides CSS variables (--primary, --popover) and typography system

❌ Without preset: Components lose backgrounds (transparent dropdowns)
❌ Without styles: Components lose design tokens and typography
✅ With both: Components work perfectly!

$3

Luaniverse comes with built-in dark mode support. The library uses Tailwind's class-based dark mode strategy.

#### Enabling Dark Mode

To enable dark mode in your application:

1. Add the dark class to your HTML:
`html



`

2. Or toggle it programmatically:
`tsx
// Toggle dark mode
document.documentElement.classList.toggle('dark');

// Enable dark mode
document.documentElement.classList.add('dark');

// Disable dark mode
document.documentElement.classList.remove('dark');
`

3. With React state management:
`tsx
function App() {
const [darkMode, setDarkMode] = useState(false);

useEffect(() => {
document.documentElement.classList.toggle('dark', darkMode);
}, [darkMode]);

return (



);
}
`

#### Dark Mode Features

- Automatic Color Adaptation - All components automatically adapt their colors for dark mode
- Maintained Accessibility - Focus indicators and contrast ratios remain WCAG compliant in dark mode
- Brand Consistency - Primary and destructive colors maintain brand identity across themes
- Smooth Transitions - Built-in CSS transitions for theme switching

Troubleshooting

$3

Problem: Dropdown menus, cards, or other components appear transparent or unstyled.

Cause: Missing Tailwind preset or incomplete setup.

Solution: Ensure you have both parts of the setup:

1. ✅ Preset added to tailwind.config.js
2. ✅ Styles imported in your CSS
3. ✅ Content paths include ./node_modules/@lua-ai-global/luaniverse/*/.{js,jsx,ts,tsx}

`js
// ✅ Correct setup
import { luaniversePreset } from '@lua-ai-global/luaniverse/tailwind';

export default {
presets: [luaniversePreset], // Enables bg-popover, bg-card utilities
content: [
'./src/*/.{js,jsx,ts,tsx}',
'./node_modules/@lua-ai-global/luaniverse/*/.{js,jsx,ts,tsx}', // Required!
],
};
`

`css
/ ✅ Required in your CSS /
@import '@lua-ai-global/luaniverse/styles';
@import 'tailwindcss';
`

$3

Problem: Custom typography classes like text-h1, link-primary don't work.

Solution: Make sure you've imported the styles (they contain custom @utility definitions).

$3

Problem: Build fails with Tailwind-related errors.

Solution: Check that your content paths are correct and that you're using a compatible Tailwind version (v3.3+ or v4+).

Components

$3

A versatile button component with multiple variants, sizes, and states.

`tsx
import { Button } from '@lua-global/luaniverse';

function App() {
return (



);
}
`

#### Button Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'default' \| 'primary' \| 'outline-solid' \| 'tertiary' \| 'secondary' \| 'muted' \| 'destructive' | 'default' | The visual style variant |
| size | 'small' \| 'default' \| 'large' | 'default' | The size of the button |
| loading | boolean | false | Shows loading spinner when true |
| disabled | boolean | false | Disables the button |
| asChild | boolean | false | Render as a child element |
| startAdornment | React.ReactNode | - | Icon or element before the text |
| endAdornment | React.ReactNode | - | Icon or element after the text |
| aria-label | string | - | Accessible label for the button |
| aria-describedby | string | - | Additional description for complex actions |

#### Button Variants

- default: Black background with white text (adapts to white background in dark mode)
- primary: Blue background with white text
- outline: White background with blue border and text
- tertiary: White background with gray border (adapts to dark gray in dark mode)
- secondary: Gray background using CSS variables
- muted: Transparent background with hover states
- destructive: Red background with white text

#### Button Examples

`tsx
// With Luaniverse icons
import { UserIcon, Camera } from '@lua-global/luaniverse';

}>
Profile


}>
Take Photo


// Loading state

Processing...


// As a link

Go to Dashboard

`

$3

A button component designed specifically for icons with proper accessibility features and sizing.

`tsx
import { IconButton } from '@lua-global/luaniverse';
import { UserIcon, Trash, XIcon } from '@lua-global/luaniverse';

function App() {
return (



);
}
`

#### IconButton Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'default' \| 'primary' \| 'outline-solid' \| 'tertiary' \| 'secondary' \| 'muted' \| 'destructive' | 'default' | The visual style variant |
| size | 'small' \| 'default' \| 'large' | 'default' | The size of the button |
| loading | boolean | false | Shows loading spinner when true |
| disabled | boolean | false | Disables the button |
| asChild | boolean | false | Render as a child element |
| aria-label | string | Required | Accessible label describing the action |
| aria-describedby | string | - | Additional description for complex actions |

#### IconButton Sizes

- small: 28px × 28px button with 16px recommended icon size
- default: 40px × 40px button with 20px recommended icon size
- large: 48px × 48px button with 24px recommended icon size

#### IconButton Examples

`tsx
import { IconButton } from '@lua-global/luaniverse';
import { UserIcon, Trash, Camera, ArrowLeft } from '@lua-global/luaniverse';

// Navigation




// Actions




// Destructive actions




// Loading state




// Different sizes



`

$3

A flexible badge component for displaying status, counts, and labels with multiple variants and color options.

`tsx
import { Badge } from '@lua-global/luaniverse';

function App() {
return (



);
}
`

#### Badge Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'default' \| 'secondary' \| 'destructive' \| 'outline-solid' \| 'success' \| 'warning' | 'default' | The visual style variant |
| asChild | boolean | false | Render as a child element |
| aria-label | string | - | Accessible label for the badge |

#### Badge Variants

- default: Primary color background with white text
- secondary: Gray background using CSS variables
- destructive: Red background for errors and warnings
- outline: Transparent background with border
- success: Green background for positive status
- warning: Yellow background for cautionary information

#### Badge Examples

`tsx
// Status badges
Active
Error
Pending

// Count badges
3
New

// As a link

5 unread

`

$3

A multi-line text input component with built-in label, description, error states, and accessibility features.

`tsx
import { Textarea } from '@lua-global/luaniverse';

function App() {
return (