@aircall/ds

v0.2.4

Published

2 days ago

Aircall Design System - Modern UI Component Library

Downloads

235

0High
0Medium
0Low

aircall-ci

@aircall/ds - Aircall Design System

Modern React component library built with TailwindCSS 4, Radix UI primitives, and TypeScript.

Tech Stack

React 19 - Latest React with compiler optimizations
TailwindCSS 4 - Utility-first CSS with OKLch color space
Radix UI - Unstyled, accessible component primitives
TypeScript 5.7 - Type-safe development
Class Variance Authority (CVA) - Variant-based component styling
Storybook 10 - Interactive component documentation

Installation

For Monorepo Apps (Hydra Workspace)

If you're developing within the Hydra monorepo (e.g., apps/aw-web, apps/hubspot-cti):

# In your app's package.json
{
  "dependencies": {
    "@aircall/ds": "workspace:*"
  }
}

For External Apps

If you're using the design system in an external project or consuming the published NPM package:

pnpm add @aircall/ds

Required peer dependencies:

pnpm add react react-dom @aircall/icons @aircall/numbers

Usage

Import Components

Components work the same way in both monorepo and external apps:

import { Button } from '@aircall/ds';

function App() {
  return (
    <Button variant="default" color="primary" size="default">
      Click me
    </Button>
  );
}

Import CSS Styles

The CSS import differs depending on your environment:

Monorepo Apps

In monorepo apps, import the source CSS for optimal build integration:

 /* In your app's entry point or globals.css */
import '@aircall/ds/globals.css';

/* Scan your own source files for Tailwind classes */
@source "your_own_source_file";

Benefits:

Source-level integration with your app's Tailwind build
Shared Tailwind context for better optimization
Access to theme variables and utilities

External Apps

In external apps, use the pre-compiled CSS bundle:

@import 'tailwindcss';
@import '@aircall/ds/globals.css';

/* Scan your own source files for Tailwind classes */
@source "your_own_source_file";

Or in TypeScript/JavaScript entry point:

// main.tsx
import '@aircall/ds/styles.css';

Benefits:

No need to configure Tailwind to scan node_modules
Smaller bundle size (pre-compiled and minified)
Faster build times
Simpler setup

Dark Mode

Dark mode is controlled via the data-theme attribute:

// Light mode (default)
<html>

// Dark mode
<html data-theme="dark">

The design system uses CSS variables that automatically adjust based on this attribute.

Components

Button

Versatile button component with multiple variants, colors, sizes, and shapes.

Props:

variant: 'default' | 'outline' | 'ghost' | 'link'
color: 'primary' | 'secondary' | 'brand-primary' | 'brand-secondary' | 'brand-destructive' | 'info' | 'success' | 'warning' | 'destructive'
size: 'xs' | 'sm' | 'default' | 'lg'
shape: 'default' | 'square' | 'circle'
readOnly: boolean
block: boolean (full width)
asChild: boolean (use with Slot for polymorphic rendering)

Examples:

// Primary button
<Button variant="default" color="primary">Primary</Button>

// Outline button
<Button variant="outline" color="secondary">Outline</Button>

// Icon button
<Button shape="circle" size="sm">
  <Phone className="size-4" />
</Button>

// Button with icon
<Button>
  <Mail className="size-4" />
  Send Email
</Button>

// Full width button
<Button block>Full Width</Button>

// Destructive button
<Button color="destructive">Delete</Button>

// Link as button (using asChild with Slot)
<Button asChild>
  <a href="/profile">Go to Profile</a>
</Button>

Storybook

Interactive component documentation with live examples, controls, and accessibility testing.

Quick Start

cd packages/ds
pnpm sb:dev

View at: http://localhost:6008

Features

🎨 Interactive component playground with live editing
🌓 Light/dark mode testing via toolbar switcher
♿ Accessibility testing with a11y addon
📱 Responsive viewport testing
🎭 Pseudo-state simulation (hover, focus, active)
📐 Figma design integration
📚 Auto-generated documentation from TypeScript types

Building Storybook

pnpm sb:build

Static site output: storybook-static/

Development

Adding Components

This package uses shadcn/ui patterns for component development:

# Add a new component from shadcn
pnpm add <component-name>

File Structure

src/
├── components/        # React components
│   └── button/
│       ├── __stories__/
│       │   └── Button.stories.tsx
│       └── button.tsx
├── styles/           # Global styles
│   ├── globals.css   # TailwindCSS + theme variables
│   └── brand.css     # Aircall brand colors
├── lib/              # Utilities
│   └── utils.ts      # cn() helper for class merging
├── hooks/            # Custom React hooks
└── fonts/            # Fellix Aircall font files

Styling System

Components use Class Variance Authority (CVA) for variant-based styling:

const buttonVariants = cva('base-classes', {
  variants: {
    variant: {
      default: 'variant-specific-classes',
      outline: 'outline-specific-classes'
    }
  },
  defaultVariants: {
    variant: 'default'
  }
});

This provides:

Type-safe variant props
Automatic TypeScript inference
Composable class generation
TailwindCSS class merging via tailwind-merge

Theme System

The design system uses CSS variables with OKLch color space for better color perception:

/* Light mode (default) */
:root {
  --primary: oklch(52.42% 0.201 192.01);
}

/* Dark mode */
[data-theme='dark'] {
  --primary: oklch(78.09% 0.128 192.01);
}

Colors automatically adapt when data-theme="dark" is set on the root element.

Scripts

# Development
pnpm sb:dev              # Start Storybook development server
pnpm lint                # Run ESLint

# Building for Distribution
pnpm build:package       # Build both JS and CSS for publishing
pnpm build:js            # Build JavaScript bundle only
pnpm build:css           # Build pre-compiled CSS only

# Testing Package Locally
pnpm pack                # Create tarball for local testing

# Storybook
pnpm sb:build            # Build static Storybook site

# Component Management
pnpm add <component>     # Add new shadcn component

# Maintenance
pnpm clean               # Remove build artifacts