Base UI Kit

A modern, accessible, and customizable React component library built on top of Base UI. This design system provides a set of beautifully designed, production-ready components that you can use across your React projects.

✨ Features

• 🎨 Beautifully Designed - Modern components with a clean, professional design
• ♿ Accessible - Built on Base UI with ARIA compliance and keyboard navigation
• 🎯 TypeScript First - Full TypeScript support with comprehensive types
• 🎭 Customizable - CSS variables for easy theming and customization
• 📦 Tree Shakeable - Only import what you need
• 🌗 Dark Mode - Built-in dark mode support
• ⚡ React 19 Ready - Compatible with the latest React
• 🎨 Tailwind CSS v4 - Latest Tailwind CSS with built-in optimizations
• 🔒 CSS Modules - Scoped styles with CSS Modules support

📦 Installation

npm install base-ui-kit-dga

Or using yarn:

yarn add base-ui-kit-dga

Or using pnpm:

pnpm add base-ui-kit-dga

⚠️ Important: You also need to install peer dependencies:

npm install @base-ui/react react react-dom

🚀 Quick Start

Step 1: Import the CSS in your app entry point (main.tsx, App.tsx, or _app.tsx):

// This import is REQUIRED for styles to work
import 'base-ui-kit-dga/styles.css';

Step 2: Use the components:

import { Button } from 'base-ui-kit-dga';

function App() {
  return (
    <div>
      <Button variant="primary" size="md">
        Click me
      </Button>
      
      <Button variant="secondary" size="lg">
        Secondary Button
      </Button>
      
      <Button variant="success">
        Success Button
      </Button>
    </div>
  );
}

🎨 Using with Tailwind CSS

You can enhance components with Tailwind utility classes:

import { Button } from 'base-ui-kit-dga';
import 'base-ui-kit-dga/styles.css';

<div className="flex gap-4 p-8">
  <Button variant="primary" className="shadow-lg hover:scale-105">
    Enhanced Button
  </Button>
  
  <div className="bg-surface rounded-lg p-md">
    <h2 className="text-xl font-bold">Card with Tailwind</h2>
  </div>
</div>

See Tailwind CSS Guide for more information.

## 📚 Components

### Button

A versatile button component with multiple variants and sizes, built on your comprehensive design token system.

```tsx
import { Button } from 'base-ui-kit-dga';

{/* Color Variants */}
<Button variant="primary">Primary (SA Flag Green)</Button>
<Button variant="secondary">Secondary (Dark)</Button>
<Button variant="success">Success (Green)</Button>
<Button variant="danger">Danger (Red)</Button>
<Button variant="warning">Warning (Orange)</Button>
<Button variant="info">Info (Blue)</Button>
<Button variant="neutral">Neutral (Light Gray)</Button>
<Button variant="ghost">Ghost (Transparent)</Button>
<Button variant="outline">Outline (Border)</Button>

{/* Sizes */}
<Button size="sm">Small Button</Button>
<Button size="md">Medium Button</Button>
<Button size="lg">Large Button</Button>

{/* Full Width */}
<Button fullWidth>Full Width Button</Button>

{/* Disabled */}
<Button disabled>Disabled Button</Button>

Props:

• variant: 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'neutral' | 'ghost' | 'outline'
  • primary: SA Flag green color (default)
  • secondary: Dark neutral color
  • success: Green semantic color
  • danger: Red error color
  • warning: Orange warning color
  • info: Blue information color
  • neutral: Light gray neutral color
  • ghost: Transparent with hover effect
  • outline: Bordered transparent button
• size: 'sm' | 'md' | 'lg' (default: 'md')
• fullWidth: boolean (default: false)
• Plus all standard HTML button props

Input

A form input with label and helper text support.

import { Input } from '@your-org/base-ui-kit';

<Input 
  label="Username"
  placeholder="Enter username"
  helperText="Choose a unique username"
  size="md"
/>

<Input 
  label="Password"
  type="password"
  error
  helperText="Password is required"
/>

Props:

• size: 'sm' | 'md' | 'lg'
• error: boolean
• label: string
• helperText: string
• fullWidth: boolean

Select

A dropdown select component.

import { Select } from '@your-org/base-ui-kit';

const [value, setValue] = useState('');

<Select
  label="Country"
  placeholder="Select a country"
  options={[
    { value: 'us', label: 'United States' },
    { value: 'uk', label: 'United Kingdom' },
    { value: 'ca', label: 'Canada' }
  ]}
  value={value}
  onValueChange={setValue}
/>

Props:

• options: SelectOption[]
• value: string
• onValueChange: (value: string) => void
• label: string
• placeholder: string
• size: 'sm' | 'md' | 'lg'

Switch

A toggle switch component.

import { Switch } from '@your-org/base-ui-kit';

const [checked, setChecked] = useState(false);

<Switch
  label="Enable notifications"
  checked={checked}
  onCheckedChange={setChecked}
  size="md"
/>

Props:

• label: string
• size: 'sm' | 'md' | 'lg'
• checked: boolean
• onCheckedChange: (checked: boolean) => void

Checkbox

A checkbox component with label support.

import { Checkbox } from '@your-org/base-ui-kit';

const [checked, setChecked] = useState(false);

<Checkbox
  label="Accept terms and conditions"
  checked={checked}
  onCheckedChange={setChecked}
  size="md"
/>

Props:

• label: string
• size: 'sm' | 'md' | 'lg'
• checked: boolean
• indeterminate: boolean
• onCheckedChange: (checked: boolean) => void

Dialog

A modal dialog component.

import { Dialog, Button } from '@your-org/base-ui-kit';

<Dialog
  trigger={<Button>Open Dialog</Button>}
  title="Dialog Title"
  description="Dialog description text"
  size="md"
>
  <p>Your dialog content goes here</p>
  <Button>Action</Button>
</Dialog>

Props:

• open: boolean
• onOpenChange: (open: boolean) => void
• title: string
• description: string
• trigger: React.ReactNode
• size: 'sm' | 'md' | 'lg' | 'xl'

Tooltip

A tooltip component for displaying helpful information.

import { Tooltip, Button } from '@your-org/base-ui-kit';

<Tooltip content="This is helpful information" side="top">
  <Button>Hover me</Button>
</Tooltip>

Props:

• content: React.ReactNode
• side: 'top' | 'right' | 'bottom' | 'left'
• align: 'start' | 'center' | 'end'
• delay: number

🎨 Theming

The component library uses CSS variables for theming. You can customize the look by overriding these variables:

:root {
  /* Colors */
  --color-primary: #3b82f6;
  --color-primary-hover: #2563eb;
  --color-secondary: #64748b;
  --color-success: #10b981;
  --color-danger: #ef4444;
  --color-warning: #f59e0b;
  
  /* Spacing */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  
  /* Typography */
  --font-size-xs: 0.75rem;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  
  /* Border Radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  
  /* And more... */
}

🌗 Dark Mode

Dark mode is automatically applied based on user preferences. The library respects the prefers-color-scheme media query.

📖 Development

Setup

# Install dependencies
npm install

# Build the library
npm run build

# Watch for changes
npm run dev

# Type checking
npm run type-check

# Linting
npm run lint

Project Structure

base-ui-kit/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   ├── Input/
│   │   ├── Select/
│   │   ├── Switch/
│   │   ├── Checkbox/
│   │   ├── Dialog/
│   │   └── Tooltip/
│   ├── utils/
│   │   └── cn.ts
│   ├── styles/
│   │   └── tokens.css
│   ├── index.ts
│   └── styles.css
├── dist/           # Build output
└── package.json

📦 Publishing to npm

Want to publish your component library to npm? See the Publishing Guide for detailed instructions.

Quick start:

# 1. Update package name in package.json
# 2. Login to npm
npm login

# 3. Build and publish
npm run build
npm publish --access public

See docs/QUICK-PUBLISH.md for a quick reference.

📖 Additional Documentation

• Tailwind CSS Guide - Using Tailwind CSS with the component library
• CSS Modules Guide - Working with CSS Modules
• Publishing Guide - How to publish to npm
• Contributing Guide - Development guidelines

🔧 Troubleshooting

Styles not appearing

If components render but have no styling:

1. Make sure you imported the CSS file:

// Add this to your main entry file (main.tsx, App.tsx, or _app.tsx)
import 'base-ui-kit-dga/styles.css';

2. Check that your bundler supports CSS imports from node_modules:

• Most modern bundlers (Vite, Next.js, Create React App) support this by default
• For custom webpack configs, ensure css-loader is configured

3. Verify peer dependencies are installed:

npm list react react-dom @base-ui/react

4. Clear your build cache:

# For Vite
rm -rf node_modules/.vite

# For Next.js
rm -rf .next

# Then reinstall
npm install

TypeScript errors

If you see type errors, ensure you have the required type definitions:

npm install -D @types/react @types/react-dom

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

🙏 Acknowledgments

Built with ❤️ using Base UI by MUI.