@altahq/design-system

A modern React component library built with Tailwind CSS v4, Radix UI primitives, and class-variance-authority for variant management.

Installation

yarn add @altahq/design-system

Peer Dependencies

Ensure you have these peer dependencies installed:

yarn add react react-dom tailwindcss@^4.1.17 class-variance-authority clsx tailwind-merge radix-ui @carbon/icons-react

Setup

1. Import Styles

Import the design system styles in your application's entry point:

import '@altahq/design-system/styles/styles.css';

2. Configure Tailwind (if using custom Tailwind config)

The design system uses Tailwind CSS v4 with CSS variables for theming. The styles are self-contained, but if you need to extend or customize, reference the included CSS variables.

Usage

Importing Components

Components are exported individually for optimal tree-shaking:

import { Button } from '@altahq/design-system/components/ui/button';
import { Input } from '@altahq/design-system/components/ui/input';
import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@altahq/design-system/components/ui/dialog';

Importing Icons

Icons are re-exported from @carbon/icons-react along with custom Alta icons:

import { Add, Close, Email, Settings } from '@altahq/design-system/icons';

Importing Utilities

import { cn } from '@altahq/design-system/lib/utils';

Components

Form Controls

| Component | Description | | ------------- | ----------------------------------------- | | Button | Primary interactive element with variants | | Input | Text input field | | Textarea | Multi-line text input | | Checkbox | Toggle selection control | | Radio Group | Single selection from options | | Switch | Toggle switch control | | Slider | Range selection control | | Field | Form field wrapper with label support | | Label | Accessible form label |

Layout & Structure

| Component | Description | | -------------- | ------------------------------------ | | Card | Container with elevation and padding | | Separator | Visual divider | | Resizable | Resizable panel layouts | | Scroll Area | Custom scrollable container | | Aspect Ratio | Maintain aspect ratio for content | | Sidebar | Application sidebar navigation |

Overlay & Dialogs

| Component | Description | | --------------- | ------------------------------- | | Dialog | Modal dialog | | Alert Dialog | Confirmation dialog | | Sheet | Slide-out panel | | Popover | Floating content container | | Tooltip | Contextual information on hover | | Hover Card | Rich content on hover | | Dropdown Menu | Menu triggered by button | | Context Menu | Right-click menu |

Navigation

| Component | Description | | ------------ | ------------------------ | | Tabs | Tabbed navigation | | Breadcrumb | Navigation breadcrumbs | | Command | Command palette / search |

Feedback & Status

| Component | Description | | ---------- | -------------------- | | Alert | Inline alert message | | Badge | Status indicator | | Progress | Progress indicator | | Spinner | Loading indicator | | Skeleton | Loading placeholder | | Sonner | Toast notifications |

Data Display

| Component | Description | | ------------- | ---------------------------- | | Avatar | User avatar display | | Accordion | Collapsible content sections | | Collapsible | Single collapsible section | | Carousel | Image/content carousel | | Text | Typography component | | Kbd | Keyboard shortcut display |

Grouping

| Component | Description | | -------------- | ------------------------ | | Button Group | Group of related buttons | | Input Group | Input with addons | | Toggle | Single toggle button | | Toggle Group | Group of toggle buttons | | Item | Generic item component |

Button Variants

The Button component supports multiple variants and sizes:

import { Button } from '@altahq/design-system/components/ui/button';

// Variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="tertiary">Tertiary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="link">Link</Button>

// Sizes
<Button size="xs">Extra Small</Button>
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="icon">Icon Only</Button>
<Button size="icon-md">Medium Icon</Button>
<Button size="icon-lg">Large Icon</Button>

With Icons

import { Button } from '@altahq/design-system/components/ui/button';
import { Email } from '@altahq/design-system/icons';

<Button>
  <Email /> Send Email
</Button>;

Theming

The design system uses CSS custom properties for theming with built-in light and dark mode support.

CSS Variables

Key color tokens available:

| Variable | Description | | ------------------------ | ------------------- | | --background | Page background | | --foreground | Primary text color | | --primary | Primary brand color | | --primary-foreground | Text on primary | | --secondary | Secondary color | | --secondary-foreground | Text on secondary | | --muted | Muted backgrounds | | --muted-foreground | Muted text | | --accent | Accent color | | --destructive | Error/danger color | | --border | Border color | | --input | Input border color | | --ring | Focus ring color |

Dark Mode

Dark mode is automatically applied when the .dark class is present on a parent element:

<html className="dark">{/* Dark mode active */}</html>

Or use a theme provider like next-themes:

import { ThemeProvider } from 'next-themes';

<ThemeProvider attribute="class" defaultTheme="system">
  <App />
</ThemeProvider>;

Utility Functions

cn() - Class Name Merger

Combines class names with Tailwind merge support:

import { cn } from '@altahq/design-system/lib/utils';

const className = cn(
  'base-class',
  isActive && 'active-class',
  variant === 'primary' && 'bg-primary text-primary-foreground'
);

Architecture

src/
├── components/
│   └── ui/                    # UI components
│       ├── button/
│       │   ├── button.tsx     # Component implementation
│       │   ├── button.stories.tsx  # Storybook stories
│       │   └── index.ts       # Public exports
│       └── ...
├── hooks/
│   └── use-mobile.ts          # Custom hooks
├── icons/
│   ├── custom/                # Custom Alta icons
│   └── index.ts               # Re-exports Carbon icons
├── lib/
│   └── utils.ts               # Utility functions
└── styles/
    └── styles.css             # Global styles & CSS variables

Technology Stack

• React 19 - UI framework
• Tailwind CSS v4 - Utility-first CSS
• Radix UI - Accessible primitives
• class-variance-authority - Variant management
• Carbon Icons - Icon library
• Storybook - Component documentation

License

MIT © Alta