@acrobi/design-system

The official design system for Acrobi applications - built with semantic tokens and complete theme management.

Features

• 🎨 Semantic Token Support - Complete CSS variable-based theming system
• 🧩 Component Library - Pre-built React components with TypeScript support
• 🛠️ CLI Tool - Theme management and validation utilities
• 🌗 Theme System - Light/dark mode support with custom themes
• 📱 Responsive Design - Mobile-first approach with Tailwind CSS v4
• 🎯 Accessibility - WCAG compliant components
• 🔄 Tree Shaking - Optimized bundle sizes with ES modules

Installation

# Using npm
npm install @acrobi/design-system

# Using yarn
yarn add @acrobi/design-system

# Using pnpm
pnpm add @acrobi/design-system

Peer Dependencies

Make sure you have these peer dependencies installed:

npm install react react-dom tailwindcss

Quick Start

1. Import CSS

Add the design system CSS to your main entry point:

// In your main CSS file (e.g., globals.css)
@import '@acrobi/design-system/dist/themes/base.css';

2. Setup Tailwind

Configure your tailwind.config.js:

module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@acrobi/design-system/**/*.{js,ts,jsx,tsx}'
  ],
  darkMode: ['class'],
  theme: {
    extend: {
      // Your custom extensions
    },
  },
  plugins: [require('tailwindcss-animate')],
};

3. Use Components

import { Button, Card, ThemeProvider } from '@acrobi/design-system';

function App() {
  return (
    <ThemeProvider>
      <Card className="p-6">
        <h1>Hello Acrobi Design System</h1>
        <Button variant="primary">Get Started</Button>
      </Card>
    </ThemeProvider>
  );
}

Components

Core Components

• Button - Versatile button with multiple variants and sizes
• Card - Flexible container component
• Input - Form input with validation support
• Label - Accessible label component
• Textarea - Multi-line text input

Advanced Components

• ThemeProvider - Context provider for theme management
• ThemeSelector - Interactive theme switcher
• SensoryProvider - Haptic and audio feedback
• Icon - Icon component with Lucide integration
• Spinner - Loading spinner component

Theming

Built-in Themes

• base - Default light theme
• blue - Blue accent theme
• purple - Purple accent theme
• green - Green accent theme
• red - Red accent theme
• orange - Orange accent theme

Using Themes

import { ThemeProvider } from '@acrobi/design-system';

function App() {
  return (
    <ThemeProvider theme="purple" darkMode={true}>
      {/* Your app content */}
    </ThemeProvider>
  );
}

Custom Themes

Create custom themes using the CLI:

# Create a new theme
npx acrobi-design create-theme my-theme --color #ff6b6b

# Create a dark theme
npx acrobi-design create-theme dark-theme --dark --color #1a1a1a

# List available themes
npx acrobi-design list-themes

# Validate theme files
npx acrobi-design validate-all

CLI Usage

The acrobi-design CLI provides powerful theme management utilities:

Commands

# Display help and info
acrobi-design info

# Create a new theme
acrobi-design create-theme <name> [options]
  Options:
    -c, --color <hex>    Base color for the theme
    -d, --dark          Create dark theme variant
    -f, --force         Overwrite existing theme

# List all available themes
acrobi-design list-themes

# Validate a specific theme
acrobi-design validate-theme <name>

# Export a theme
acrobi-design export-theme <name> [options]
  Options:
    -o, --output <path> Output path for exported theme

# Validate all themes
acrobi-design validate-all

Examples

# Create a custom theme with a specific color
acrobi-design create-theme brand --color #6366f1

# Create a dark theme variant
acrobi-design create-theme brand-dark --dark --color #6366f1

# Export a theme for distribution
acrobi-design export-theme brand --output ./brand-theme.css

# Validate all theme files
acrobi-design validate-all

API Reference

Button Component

import { Button } from '@acrobi/design-system';

// Basic usage
<Button>Click me</Button>

// With variants
<Button variant="primary" size="lg">Large Primary Button</Button>

// Custom variants
<Button variant="destructive" size="sm">Delete</Button>

// Loading state
<Button loading={true} loadingText="Processing...">Submit</Button>

// With icons
<Button leftIcon={<Icon name="plus" />}>Add Item</Button>

Button Props:

Prop	Type	Default	Description
variant	'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link'	'primary'	Button style variant
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Button size
loading	boolean	false	Show loading state
loadingText	string	-	Text to show when loading
leftIcon	ReactNode	-	Icon to show on the left
rightIcon	ReactNode	-	Icon to show on the right
disabled	boolean	false	Disable the button
asChild	boolean	false	Render as child component

Card Component

import { Card, CardHeader, CardTitle, CardContent } from '@acrobi/design-system';

<Card>
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Card content goes here.</p>
  </CardContent>
</Card>

ThemeProvider

import { ThemeProvider } from '@acrobi/design-system';

<ThemeProvider
  theme="purple"
  darkMode={false}
  onChange={(theme, darkMode) => console.log({ theme, darkMode })}
>
  {children}
</ThemeProvider>

ThemeProvider Props:

Prop	Type	Default	Description
theme	string	'base'	Theme name
darkMode	boolean	false	Enable dark mode
onChange	(theme: string, darkMode: boolean) => void	-	Theme change callback
storageKey	string	'acrobi-theme'	Local storage key

Semantic Tokens

The design system is built on semantic tokens for complete theming flexibility:

Color System

:root {
  /* Semantic colors */
  --primary: #9333ea;
  --primary-foreground: #fafafa;
  --background: #fafafa;
  --foreground: #0a0a0a;

  /* Surface colors */
  --card: #ffffff;
  --card-foreground: #0a0a0a;
  --border: #e4e4e7;
  --input: #e4e4e7;

  /* Status colors */
  --destructive: #ef4444;
  --success: #22c55e;
  --warning: #f59e0b;
  --info: #3b82f6;
}

Typography Scale

:root {
  /* Font sizes */
  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;

  /* Font weights */
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;
}

Development

Building from Source

# Clone the repository
git clone https://github.com/Acrobi/design-system.git
cd design-system

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Start development server
npm run dev

Project Structure

src/
├── components/          # React components
│   ├── ui/             # Base UI components
│   └── index.build.ts  # Component exports
├── lib/                # Utilities and helpers
│   ├── utils.ts        # Core utilities
│   └── assets.ts       # Asset management
├── styles/             # Global styles
└── index.ts            # Main entry point

cli/
└── index.js            # CLI tool

public/
└── themes/             # Theme CSS files

dist/                   # Built distribution files

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Guidelines

1. No hard-coded styles - All styling uses CSS variables
2. Semantic tokens - Use semantic color, spacing, and typography tokens
3. TypeScript - All components must have proper TypeScript types
4. Accessibility - Ensure WCAG compliance
5. Testing - Write tests for new components and features

License

MIT © Acrobi

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Support

Changelog

See CHANGELOG.md for version history and updates.