npm package: @haykal/ui
Description: Haykal Design System — Tailwind CSS + shadcn/ui component library
Latest version: 1.0.0

# @haykal/ui — Haykal Design System

A comprehensive design system built on **Tailwind CSS v4** and **shadcn/ui**, providing components, tokens, hooks, providers, and utilities for building consistent UIs across Haykal applications.

## Features

- **36+ shadcn/ui Components** — Button, Card, Dialog, Table, Form, Sidebar, and more
- **Design Tokens** — Colors (OKLCH), spacing, typography, animation, breakpoints, elevation
- **Theme System** — Light/dark mode with system preference detection via `next-themes`
- **Hooks** — `useTheme`, `useBreakpoint`, `useMediaQuery`, `useMounted`, `useToggle`
- **Providers** — `HaykalUIProvider` composites all providers into a single root
- **Utilities** — `cn()` (class merging), `cva` (variants), composable refs
- **Publishable** — Proper `exports` map for ESM, tree-shakeable

## Usage

### 1. Install

```bash
pnpm add @haykal/ui
```

### 2. Import Styles

In your app's root CSS (or layout):

```css
/* app/globals.css */
@import '@haykal/ui/styles/globals.css';
```

### 3. Add the Provider

```tsx
// app/layout.tsx
import { HaykalUIProvider } from '@haykal/ui/providers';
import './globals.css';

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <HaykalUIProvider theme={{ defaultMode: 'system' }}>
          {children}
        </HaykalUIProvider>
      </body>
    </html>
  );
}
```

### 4. Use Components

```tsx
import { Button, Card, CardContent, Badge } from '@haykal/ui';
import { useTheme } from '@haykal/ui/providers';

export function MyComponent() {
  const { toggle, isDark } = useTheme();

  return (
    <Card>
      <CardContent>
        <Badge>Status</Badge>
        <Button onClick={toggle}>{isDark ? 'Light Mode' : 'Dark Mode'}</Button>
      </CardContent>
    </Card>
  );
}
```

## Import Paths

| Path                   | Contents                                                    |
| ---------------------- | ----------------------------------------------------------- |
| `@haykal/ui`           | All components + core exports                               |
| `@haykal/ui/providers` | `HaykalUIProvider`, `ThemeProvider`, `useTheme`             |
| `@haykal/ui/hooks`     | `useMediaQuery`, `useBreakpoint`, `useMounted`, `useToggle` |
| `@haykal/ui/tokens`    | Design tokens (colors, spacing, typography, etc.)           |
| `@haykal/ui/theme`     | Theme config types                                          |
| `@haykal/ui/utils`     | `cn()`, `cva`, helpers                                      |
| `@haykal/ui/styles`    | Global CSS with Tailwind + theme tokens                     |

## Adding New Components

```bash
# From the packages/ui directory:
cd packages/ui

# Add a component via shadcn CLI
pnpm ui:add <component-name>

# Fix imports for monorepo compatibility
pnpm ui:fix

# Then re-export in src/lib/components/index.ts:
# export * from './ui/<component-name>';
```

## Customizing Theme Per-App

Override CSS variables in your app's CSS:

```css
/* app/globals.css */
@import '@haykal/ui/styles/globals.css';

:root {
  /* Override primary color for this app */
  --primary: oklch(0.55 0.22 250);
  --primary-foreground: oklch(0.98 0 0);
}
```

## Next.js Configuration

For Next.js apps consuming this package, add to `next.config.ts`:

```ts
const nextConfig = {
  transpilePackages: ['@haykal/ui'],
};
```

And in `postcss.config.mjs`:

```js
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
```

## Design Tokens

Tokens are available both as CSS custom properties and as JS/TS exports:

```typescript
import { LIGHT_COLORS, oklch, BREAKPOINTS } from '@haykal/ui/tokens';

// Get a color as CSS string
const primary = oklch(LIGHT_COLORS.primary); // "oklch(0.205 0 0)"

// Use breakpoints programmatically
import { useBreakpoint } from '@haykal/ui/hooks';

const { isMobile, isDesktop, current } = useBreakpoint();
```

## Components (36)

### Layout & Structure

Accordion, AspectRatio, Card, Collapsible, Separator, ScrollArea, Table, Tabs

### Navigation

Breadcrumb, NavigationMenu, Sidebar

### Forms & Inputs

Button, Checkbox, Form, Input, Label, RadioGroup, Select, Slider, Switch, Textarea, Toggle, ToggleGroup

### Feedback & Display

Alert, Avatar, Badge, Progress, Skeleton, Sonner (Toast), Tooltip

### Overlays & Dialogs

AlertDialog, Command, Dialog, DropdownMenu, Popover, Sheet