sonr/docs/reference/packages/pkl.mdx

---
title: "@sonr.io/ui"
sidebarTitle: "@sonr.io/ui"
description: "A package for Sonr's centralized shadcn/ui component library"
icon: "palette"
---

# @sonr.io/ui

## Overview

The `@sonr.io/ui` package serves as our centralized shadcn/ui component library, providing a consistent and accessible design system across Sonr's ecosystem. Leveraging the power of shadcn/ui, we've created a fully customizable and type-safe component library with a primary color of `#17c2ff`.

<Callout type="info">
  Our UI package is built to provide maximum flexibility while maintaining
  strict design consistency.
</Callout>

## Component Migration Strategy

### Before: Custom Button Component

Previously, our Button component relied on manual variant classes and custom implementations:

```tsx
// Old Implementation
const Button = ({ variant, className, ...props }) => {
  const variantClasses = {
    primary: "bg-blue-500 text-white",
    secondary: "bg-gray-200 text-black",
    // Multiple manual variant definitions
  };

  return (
    <button className={`${variantClasses[variant]} ${className}`} {...props} />
  );
};
```

### After: Shadcn Button Implementation

Our new implementation uses `cva` (class-variance-authority) and the `cn` utility for robust variant management:

```tsx
// New Implementation
import { buttonVariants } from "@sonr.io/ui/components/ui/button";
import { cn } from "@sonr.io/ui/lib/utils";

const Button = ({
  variant = "default",
  size = "default",
  className,
  ...props
}) => {
  return (
    <button
      className={cn(buttonVariants({ variant, size }), className)}
      {...props}
    />
  );
};
```

<Callout type="success">
  Key Improvements: - Type-safe variant management - Enhanced accessibility -
  Consistent theming - Reduced bundle size
</Callout>

## Theme Configuration

### Color System

Our primary theme color is `#17c2ff`, defined in HSL format for maximum flexibility:

```css
:root {
  --primary-h: 200; /* Hue */
  --primary-s: 100%; /* Saturation */
  --primary-l: 59%; /* Lightness */
  --primary: hsl(var(--primary-h), var(--primary-s), var(--primary-l));
}
```

### CSS Variables Structure

```css
:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 3.9%;
  --primary: 200 100% 59%;
  --primary-foreground: 210 40% 98%;
  --secondary: 220 14.3% 95.9%;
  --secondary-foreground: 220.9 39.3% 11%;
  /* Additional theme variables */
}
```

## Usage Guide

### Importing Components

Import components directly from the `@sonr.io/ui` package:

```tsx
import { Button } from "@sonr.io/ui/components/ui/button";
import { Input } from "@sonr.io/ui/components/ui/input";
```

### Adding New Components

Use the shadcn CLI within the `packages/ui` directory:

```bash
# Navigate to packages/ui
cd packages/ui

# Add a new component
npx shadcn-ui@latest add button
```

<Callout type="warning">
  Always add components from the `packages/ui` directory to maintain our
  centralized component management.
</Callout>

## Architecture Patterns

### Monorepo Structure

```
sonr/
├── packages/
│   └── ui/
│       ├── components/
│       │   └── ui/
│       │       ├── button.tsx
│       │       ├── input.tsx
│       │       └── ...
│       ├── lib/
│       │   └── utils.ts
│       └── styles/
│           └── globals.css
```

### Key Principles

- **Single Source of Truth**: All UI components live in `packages/ui`
- **No Local `components.json`**: Centralized configuration
- **Turbo-powered Build Pipeline**: Efficient component compilation

## Global Styles Integration

In your application's main entry point:

```tsx
import "@sonr.io/ui/styles/globals.css";

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}
```

## Best Practices

1. Always use the centralized components from `@sonr.io/ui`
2. Prefer `cn()` utility for dynamic className composition
3. Leverage TypeScript for type-safe component usage
4. Use CSS variables for theming consistency

<Callout type="tip">
  Remember: Our UI library is designed to be both flexible and consistent. When
  in doubt, refer to the components in `@sonr.io/ui`.
</Callout>