@haykal/ui

v1.0.0

Published

4 days ago

Haykal Design System — Tailwind CSS + shadcn/ui component library

Downloads

0High
0Medium
0Low

ahmadaltomy

@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

pnpm add @haykal/ui

2. Import Styles

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

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

3. Add the Provider

// 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

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

# 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:

/* 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:

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

And in postcss.config.mjs:

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

Design Tokens

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

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