---
name: kor-ui
description: Complete guide for using the Kor UI library (@korsolutions/ui) in React Native and Expo applications. Use this skill when building user interfaces with Universal UI, customizing themes, setting up the library, working with any of the 24+ components (Button, Input, Select, Alert, Card, Tabs, Menu, Popover, Calendar, Toast, etc.), styling and theming, implementing compound components, debugging component issues, or when the user mentions "@korsolutions/ui", "Universal UI", "UIProvider", or asks about unstyled primitives, theme customization, or React Native UI components. This skill covers installation, provider setup, component usage patterns, theme customization, variant system, hooks, responsive design, and troubleshooting.
---

# Universal UI Library

Universal UI (@korsolutions/ui) is a library of unstyled UI primitives for React Native and Expo applications. It provides production-ready components with a focus on minimal dependencies, compound component patterns, and comprehensive theming support.

## Core Principles

- **Unstyled Primitives**: Components are unstyled by default with variant-based styling
- **Compound Components**: All components follow Root + sub-component pattern
- **Variant System**: Each component offers multiple style variants
- **Minimal Dependencies**: Only React Native and Expo core dependencies
- **Full TypeScript Support**: Complete type definitions for all components
- **Cross-Platform**: iOS, Android, and Web support

## Quick Start

### Installation

```bash
npm install @korsolutions/ui
# or
yarn add @korsolutions/ui
# or
bun add @korsolutions/ui
```

### Provider Setup

Wrap your application with `UIProvider` in your root layout:

```tsx
import { UIProvider } from "@korsolutions/ui";
import { useSafeAreaInsets } from "react-native-safe-area-context";

export default function RootLayout() {
  const safeAreaInsets = useSafeAreaInsets();

  return (
    <UIProvider safeAreaInsets={safeAreaInsets}>
      <YourApp />
    </UIProvider>
  );
}
```

### Basic Import Pattern

```tsx
import { Button, Input, Card } from "@korsolutions/ui";

function MyComponent() {
  return (
    <Card.Root>
      <Card.Body>
        <Button.Root onPress={() => console.log("Pressed")}>
          <Button.Label>Click Me</Button.Label>
        </Button.Root>
      </Card.Body>
    </Card.Root>
  );
}
```

### Your First Component

```tsx
import { useState } from "react";
import { Button } from "@korsolutions/ui";

function SubmitButton() {
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    setLoading(true);
    await submitForm();
    setLoading(false);
  };

  return (
    <Button.Root variant="default" isLoading={loading} onPress={handleSubmit}>
      <Button.Label>Submit</Button.Label>
    </Button.Root>
  );
}
```

## Component Overview

### Layout & Structure

| Component     | Description                                     | Variants | Reference                                                        |
| ------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------- |
| **Card**      | Content container with header, body, and footer | default  | [Layout Components](./references/components-layout.md#card)      |
| **ScrollBar** | Custom scrollbar styling                        | default  | [Layout Components](./references/components-layout.md#scrollbar) |
| **Portal**    | Render components outside hierarchy             | -        | [Layout Components](./references/components-layout.md#portal)    |
| **List**      | Performance-optimized list rendering            | -        | [Layout Components](./references/components-layout.md#list)      |

### Form Inputs

| Component        | Description                                          | Variants | Reference                                                          |
| ---------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------ |
| **Input**        | Text input field                                     | default  | [Input Components](./references/components-inputs.md#input)        |
| **NumericInput** | Formatted numeric input (currency, percentage, etc.) | default  | [Input Components](./references/components-inputs.md#numericinput) |
| **Textarea**     | Multi-line text input                                | default  | [Input Components](./references/components-inputs.md#textarea)     |
| **Checkbox**     | Toggle selection with label                          | default  | [Input Components](./references/components-inputs.md#checkbox)     |
| **Select**       | Dropdown selection with search                       | default  | [Input Components](./references/components-inputs.md#select)       |
| **Field**        | Form field wrapper with label and validation         | -        | [Input Components](./references/components-inputs.md#field)        |

### Display Components

| Component      | Description                             | Variants                                               | Reference                                                           |
| -------------- | --------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| **Typography** | Text with semantic variants             | heading-xs to 3xl, body-xs to lg, label, code, caption | [Display Components](./references/components-display.md#typography) |
| **Avatar**     | User avatar with image and fallback     | default                                                | [Display Components](./references/components-display.md#avatar)     |
| **Badge**      | Status indicators and labels            | default, secondary, success, warning, danger, info     | [Display Components](./references/components-display.md#badge)      |
| **Icon**       | Icon rendering with render prop pattern | -                                                      | [Display Components](./references/components-display.md#icon)       |
| **Empty**      | Empty state placeholders                | default                                                | [Display Components](./references/components-display.md#empty)      |
| **Progress**   | Linear progress indicators              | default                                                | [Display Components](./references/components-display.md#progress)   |

### Interactive Components

| Component    | Description                        | Variants           | Reference                                                                 |
| ------------ | ---------------------------------- | ------------------ | ------------------------------------------------------------------------- |
| **Button**   | Action buttons with loading states | default, secondary | [Interactive Components](./references/components-interactive.md#button)   |
| **Tabs**     | Tabbed navigation                  | default, line      | [Interactive Components](./references/components-interactive.md#tabs)     |
| **Menu**     | Dropdown menus                     | default            | [Interactive Components](./references/components-interactive.md#menu)     |
| **Popover**  | Positioned overlay content         | default            | [Interactive Components](./references/components-interactive.md#popover)  |
| **Calendar** | Date picker with range selection   | default            | [Interactive Components](./references/components-interactive.md#calendar) |

### Feedback Components

| Component       | Description                     | Variants                 | Reference                                                              |
| --------------- | ------------------------------- | ------------------------ | ---------------------------------------------------------------------- |
| **Alert**       | Inline notifications with icons | default, destructive     | [Feedback Components](./references/components-feedback.md#alert)       |
| **AlertDialog** | Modal confirmation dialogs      | default                  | [Feedback Components](./references/components-feedback.md#alertdialog) |
| **Toast**       | Transient notifications         | default, success, danger | [Feedback Components](./references/components-feedback.md#toast)       |

## Compound Component Pattern

All Universal UI components follow a compound component pattern where a parent component (usually `Root`) provides context to child sub-components.

### Structure

```tsx
<Component.Root {...rootProps}>
  <Component.SubComponent1 {...props} />
  <Component.SubComponent2 {...props} />
</Component.Root>
```

### Common Sub-Components

Most components share similar sub-component naming:

- **Root** - Parent container that provides context
- **Label** - Text label for the component
- **Icon** - Icon display with render prop pattern
- **Description** - Secondary descriptive text
- **Title** - Primary heading text
- **Body** - Main content area
- **Header** - Top section
- **Footer** - Bottom section

### Example: Button

```tsx
<Button.Root variant="default" onPress={handlePress} isLoading={loading}>
  <Button.Label>Submit Form</Button.Label>
</Button.Root>
```

### Example: Alert with Icon

```tsx
import { AlertCircle } from "lucide-react-native";

<Alert.Root variant="destructive">
  <Alert.Icon render={AlertCircle} />
  <Alert.Body>
    <Alert.Title>Error</Alert.Title>
    <Alert.Description>Something went wrong</Alert.Description>
  </Alert.Body>
</Alert.Root>;
```

### Example: Field with Input

```tsx
<Field.Root>
  <Field.Label for="email">Email Address</Field.Label>
  <Input id="email" value={email} onChange={setEmail} placeholder="you@example.com" />
  <Field.Description>We'll never share your email.</Field.Description>
  {error && <Field.Error>{error}</Field.Error>}
</Field.Root>
```

### Style Composition

Component styles are always composed with variant styles first, allowing user styles to override:

```tsx
// Variant styles are applied first
<Button.Root style={{ marginTop: 16 }}>
  <Button.Label style={{ fontWeight: "bold" }}>Custom Button</Button.Label>
</Button.Root>
```

This ensures your custom styles always take precedence over variant defaults.

## Theme System Basics

Universal UI includes a comprehensive theming system with light/dark mode support.

### Theme Tokens

The theme provides these customizable tokens:

- **colors** - Color palette with light/dark schemes
- **radius** - Border radius (default: 10)
- **fontSize** - Base font size (default: 16)
- **fontFamily** - Font family (default: "System")
- **letterSpacing** - Letter spacing (default: 0)

### Color Tokens

Each color scheme (light/dark) includes:

- **background** - Main background color
- **foreground** - Main text color
- **primary** - Primary brand color
- **primaryForeground** - Text on primary color
- **secondary** - Secondary brand color
- **secondaryForeground** - Text on secondary color
- **muted** - Muted background color
- **mutedForeground** - Muted text color
- **border** - Border color
- **surface** - Surface/card background
- **success**, **warning**, **danger**, **info** - Semantic colors

### Using the Theme

Access the theme in your components:

```tsx
import { useTheme } from "@korsolutions/ui";

function MyComponent() {
  const theme = useTheme();

  return (
    <View
      style={{
        backgroundColor: theme.colors.background,
        borderRadius: theme.radius,
        padding: 16,
      }}
    >
      <Text
        style={{
          color: theme.colors.foreground,
          fontSize: theme.fontSize,
          fontFamily: theme.fontFamily,
        }}
      >
        Themed Content
      </Text>
    </View>
  );
}
```

### Color Scheme

Toggle between light and dark mode:

```tsx
const theme = useTheme();

// Get current scheme
console.log(theme.colorScheme); // "light" | "dark"

// Set color scheme
theme.setColorScheme("dark");
```

### Quick Customization

Customize the theme via UIProvider:

```tsx
<UIProvider
  theme={{
    radius: 12,
    fontSize: 18,
    colors: {
      light: {
        primary: "hsla(220, 90%, 56%, 1)",
        primaryForeground: "hsla(0, 0%, 100%, 1)",
      },
      dark: {
        primary: "hsla(220, 90%, 70%, 1)",
        primaryForeground: "hsla(0, 0%, 100%, 1)",
      },
    },
  }}
  safeAreaInsets={safeAreaInsets}
>
  <App />
</UIProvider>
```

For detailed theming documentation, see [Theme Customization](./references/theme-customization.md).

## Common Patterns

### Form Field with Validation

```tsx
import { Field, Input } from "@korsolutions/ui";

<Field.Root>
  <Field.Label for="email">Email</Field.Label>
  <Input id="email" value={email} onChange={setEmail} placeholder="you@example.com" />
  <Field.Description>Enter your email address</Field.Description>
  {error && <Field.Error>{error}</Field.Error>}
</Field.Root>;
```

### Icons with Render Prop

Universal UI uses a render prop pattern for icons, supporting any icon library:

```tsx
import { AlertCircle, CheckCircle } from "lucide-react-native";
import { Alert } from "@korsolutions/ui";

// With lucide-react-native
<Alert.Icon render={AlertCircle} />

// With custom function
<Alert.Icon render={(props) => <CheckCircle {...props} size={20} />} />

// With @expo/vector-icons
import { MaterialCommunityIcons } from "@expo/vector-icons";
<Alert.Icon render={(props) => (
  <MaterialCommunityIcons {...props} name="alert-circle" />
)} />
```

### Controlled State Management

Most input components use controlled state:

```tsx
import { useState } from "react";
import { Input, Checkbox } from "@korsolutions/ui";

function Form() {
  const [text, setText] = useState("");
  const [checked, setChecked] = useState(false);

  return (
    <>
      <Input value={text} onChange={setText} />
      <Checkbox.Root checked={checked} onChange={setChecked}>
        <Checkbox.Indicator />
        <Checkbox.Content>
          <Checkbox.Title>Accept terms</Checkbox.Title>
        </Checkbox.Content>
      </Checkbox.Root>
    </>
  );
}
```

### Loading States

Buttons support loading states with built-in spinner:

```tsx
<Button.Root isLoading={isSubmitting} onPress={handleSubmit}>
  <Button.Label>Submit</Button.Label>
</Button.Root>
```

When `isLoading` is true, the button displays `Button.Spinner` and disables interaction.

### Disabled States

Most components support disabled states:

```tsx
<Button.Root isDisabled={!formValid} onPress={handleSubmit}>
  <Button.Label>Submit</Button.Label>
</Button.Root>

<Input isDisabled value={email} onChange={setEmail} />

<Checkbox.Root disabled checked={value} onChange={setValue}>
  <Checkbox.Indicator />
  <Checkbox.Content>
    <Checkbox.Title>Disabled option</Checkbox.Title>
  </Checkbox.Content>
</Checkbox.Root>
```

### Selecting Variants

Most components offer multiple variants:

```tsx
// Button variants
<Button.Root variant="default">
  <Button.Label>Default Button</Button.Label>
</Button.Root>

<Button.Root variant="secondary">
  <Button.Label>Secondary Button</Button.Label>
</Button.Root>

// Alert variants
<Alert.Root variant="default">
  <Alert.Body>
    <Alert.Title>Info</Alert.Title>
  </Alert.Body>
</Alert.Root>

<Alert.Root variant="destructive">
  <Alert.Body>
    <Alert.Title>Error</Alert.Title>
  </Alert.Body>
</Alert.Root>

// Badge variants
<Badge variant="success">Active</Badge>
<Badge variant="danger">Inactive</Badge>
<Badge variant="warning">Pending</Badge>
```

### Style Overrides

Override component styles using the `style` prop:

```tsx
<Button.Root
  style={{
    marginTop: 20,
    backgroundColor: "blue",
  }}
>
  <Button.Label style={{ color: "white", fontSize: 18 }}>Custom Styled</Button.Label>
</Button.Root>
```

## Import Reference

### Component Imports

```tsx
// Import individual components
import { Button, Input, Card, Alert } from "@korsolutions/ui";

// Import all components
import * as UI from "@korsolutions/ui";
```

### Hook Imports

```tsx
// Theme hook
import { useTheme } from "@korsolutions/ui";

// Responsive design hook
import { useScreenSize } from "@korsolutions/ui";

// React Navigation theme integration
import { useReactNavigationTheme } from "@korsolutions/ui";
```

### Provider Import

```tsx
import { UIProvider } from "@korsolutions/ui";
```

### Type Imports

```tsx
// Component prop types
import type { ButtonRootProps } from "@korsolutions/ui";
import type { InputProps } from "@korsolutions/ui";

// Theme types
import type { ThemeAssets, Colors } from "@korsolutions/ui";
```

## Quick Troubleshooting

### Provider Not Wrapping App

**Issue**: Components don't render or theme doesn't apply

**Solution**: Ensure `UIProvider` wraps your app in the root layout:

```tsx
// app/_layout.tsx
import { UIProvider } from "@korsolutions/ui";

export default function RootLayout() {
  return (
    <UIProvider>
      <Stack />
    </UIProvider>
  );
}
```

### Import Errors

**Issue**: Cannot resolve `@korsolutions/ui`

**Solution**: Install the package and restart your bundler:

```bash
npm install @korsolutions/ui
# Restart Metro bundler
```

### Theme Not Updating

**Issue**: Theme changes don't reflect in components

**Solution**: Ensure theme customization is passed to UIProvider before app renders:

```tsx
const customTheme = {
  colors: { light: { primary: "hsla(220, 90%, 56%, 1)" } },
};

<UIProvider theme={customTheme}>
  <App />
</UIProvider>;
```

### Styles Not Applying

**Issue**: Custom styles don't override component styles

**Solution**: Remember style composition order - user styles always override variant styles:

```tsx
// This works - style prop overrides variant
<Button.Root style={{ backgroundColor: "red" }}>
  <Button.Label>Red Button</Button.Label>
</Button.Root>
```

For comprehensive troubleshooting, see [Troubleshooting Guide](./references/troubleshooting.md).

## Reference Documentation

Consult these detailed references as needed:

### Component References

- [Layout Components](./references/components-layout.md) - Card, ScrollBar, Portal, List
- [Input Components](./references/components-inputs.md) - Input, NumericInput, Textarea, Checkbox, Select, Field
- [Display Components](./references/components-display.md) - Typography, Avatar, Badge, Icon, Empty, Progress
- [Interactive Components](./references/components-interactive.md) - Button, Tabs, Menu, Popover, Calendar
- [Feedback Components](./references/components-feedback.md) - Alert, AlertDialog, Toast

### System References

- [Theme Customization](./references/theme-customization.md) - Complete theming guide with color schemes, typography, and responsive design
- [Patterns & Recipes](./references/patterns-recipes.md) - Common implementation patterns for forms, modals, navigation, and feedback
- [Troubleshooting](./references/troubleshooting.md) - Solutions for setup, component, type, and platform-specific issues