• Open UI Kit
  • ✨ Features
  • 🚀 Quick Start
  • 🔐 Authentication
  • 📦 Installation
    • NPM
    • Yarn
  • 💻 Usage
    • Basic Setup
    • Using Components
    • Theme Customization
    • TypeScript Support
  • 📚 Available Components
  • 📖 Documentation
  • 🧪 Testing
  • 🚢 Releases
    • Beta Releases
  • 🤝 Contributing
  • 📄 License

A comprehensive React component library built on Material-UI for modern applications

✨ Features

• 🎯 50+ Pre-built Components - From basic buttons to complex data tables and interactive charts
• 🌓 Dark/Light Theme Support - Built-in theme switching with seamless transitions
• 📱 Responsive Design - Mobile-first approach with flexible, adaptive layouts
• ♿ Accessibility First - WCAG compliant components with proper ARIA attributes
• 🔧 TypeScript Native - Full TypeScript support with comprehensive type definitions
• 📊 Data Visualization - Rich chart components for analytics and dashboards
• 🎨 Customizable Theming - Extend and customize colors, typography, and spacing
• 📚 Interactive Documentation - Comprehensive Storybook with live examples

🚀 Quick Start

# Install the package and peer dependencies
npm install @open-ui-kit/core @mui/material @emotion/react @emotion/styled

# Import CSS and start using components
import '@open-ui-kit/core/typography.css';
import { ThemeProvider, Button } from '@open-ui-kit/core';

🔐 Installation

Open UI Kit is available as an open source package. You can install it directly from npm.

📦 Installation

Prerequisites: Node.js 18+ and npm 8+ (or Yarn 1.22+)

NPM

npm install @open-ui-kit/core @mui/material @emotion/react @emotion/styled

Yarn

yarn add @open-ui-kit/core @mui/material @emotion/react @emotion/styled

Required Peer Dependencies:

• @mui/material ^5.0.0 - Core Material-UI components
• @emotion/react ^11.0.0 - CSS-in-JS styling engine
• @emotion/styled ^11.0.0 - Styled component utilities
• react ^17.0.0 || ^18.0.0
• react-dom ^17.0.0 || ^18.0.0

💻 Usage

Basic Setup

Wrap your application with the ThemeProvider to enable Open UI Kit theming:

import React, { useState } from 'react';
import { ThemeProvider } from '@open-ui-kit/core';
import '@open-ui-kit/core/typography.css';

function App() {
  const [isDarkMode, setIsDarkMode] = useState(false);

  return (
    <ThemeProvider isDarkMode={isDarkMode}>
      <div className="app">
        <header>
          <button onClick={() => setIsDarkMode(!isDarkMode)}>
            Switch to {isDarkMode ? 'Light' : 'Dark'} Mode
          </button>
        </header>
        {/* Your app content goes here */}
      </div>
    </ThemeProvider>
  );
}

export default App;

Using Components

Import and use components from the library:

import {
  Button,
  Card,
  TextField,
  Badge,
  Avatar,
  Modal,
  Typography
} from '@open-ui-kit/core';

function MyComponent() {
  const [open, setOpen] = useState(false);

  return (
    <Card sx={{ p: 3, maxWidth: 400 }}>
      <div style={{ display: 'flex', alignItems: 'center', mb: 2 }}>
        <Avatar src="/user-avatar.jpg" sx={{ mr: 2 }} />
        <Typography variant="h6">Welcome back!</Typography>
      </div>
      
      <TextField 
        label="Enter your message" 
        variant="outlined" 
        fullWidth 
        sx={{ mb: 2 }}
      />
      
      <Button 
        variant="contained" 
        color="primary" 
        onClick={() => setOpen(true)}
        sx={{ mr: 1 }}
      >
        Open Modal
      </Button>
      
      <Badge badgeContent={4} color="secondary">
        <Button variant="outlined">Notifications</Button>
      </Badge>

      <Modal open={open} onClose={() => setOpen(false)}>
        <div>Modal content here</div>
      </Modal>
    </Card>
  );
}

Theme Customization

Access theme variables for consistent styling across your application:

import { useTheme } from '@open-ui-kit/core';

function StyledComponent() {
  const theme = useTheme();

  return (
    <div
      style={{
        backgroundColor: theme.palette.vars.controlBackgroundDefault,
        color: theme.palette.vars.textPrimary,
        padding: theme.spacing(2),
        borderRadius: theme.shape.borderRadius,
        border: `1px solid ${theme.palette.divider}`
      }}
    >
      <h3 style={{ color: theme.palette.primary.main }}>
        Themed Content
      </h3>
      <p>This component uses theme variables for consistent styling.</p>
    </div>
  );
}

TypeScript Support

The library provides full TypeScript support with augmented Material-UI theme types:

import { useTheme, Theme } from '@open-ui-kit/core';

const MyTypedComponent: React.FC = () => {
  const theme: Theme = useTheme();
  
  // Access custom theme variables with full type safety
  const backgroundColor = theme.palette.vars.controlBackgroundDefault;
  const primaryColor = theme.palette.primary.main;
  const spacing = theme.spacing(2);
  
  return (
    <div 
      style={{ 
        backgroundColor, 
        color: primaryColor,
        padding: spacing
      }}
    >
      Fully typed theme access
    </div>
  );
};

📚 Available Components

The library includes 50+ components organized into the following categories:

🔧 Layout & Structure

• Card, Divider, Drawer, Modal, Tabs, Accordion

📝 Form Controls

• Button, TextField, Checkbox, Radio, Select, Slider, Toggle

🧭 Navigation

• Breadcrumbs, Menu, Pagination, Stepper, Header, Footer

📊 Data Display

• Avatar, Badge, Table, List, Typography, Code Block

💬 Feedback & Status

• Toast, Spinner, Loading States, Empty State, Banner

📈 Data Visualization

• Bar Chart, Line Chart, Donut Chart, Gauge Chart, Chart Widget

🔍 Specialized

• Search Field, Autocomplete Tree, Date Time, Copy Button, Filters

💡 Tip: All components are fully documented with interactive examples in our Storybook.

📖 Documentation

Interactive Documentation

We use Storybook for comprehensive component documentation with live examples:

# Run Storybook locally
yarn storybook

🌐 View Live Documentation

What you'll find in Storybook:

• 📖 Component API docs - Props, types, and usage examples
• 🎮 Interactive playground - Test components with different configurations
• 🎨 Design tokens - Colors, typography, spacing, and theme variables
• 📱 Responsive examples - See how components adapt to different screen sizes
• ♿ Accessibility guidelines - WCAG compliance information and best practices

🧪 Testing

We use Jest and React Testing Library for comprehensive testing coverage.

Writing Tests

• Create test files alongside components: ComponentName.test.tsx
• Test component functionality, accessibility, and user interactions
• Ensure all custom (non-MUI) components have test coverage

Running Tests

# Run all tests
yarn test

# Run tests in watch mode
yarn test --watch

# Run tests with coverage report
yarn test --coverage

Example Test Structure

// src/components/Button/Button.test.tsx
import { render, screen, fireEvent } from '@testing-library/react';
import { ThemeProvider } from '@open-ui-kit/core';
import { Button } from './Button';

const renderWithTheme = (component: React.ReactElement) => {
  return render(
    <ThemeProvider>
      {component}
    </ThemeProvider>
  );
};

describe('Button Component', () => {
  it('renders correctly', () => {
    renderWithTheme(<Button>Click me</Button>);
    expect(screen.getByRole('button')).toBeInTheDocument();
  });

  it('handles click events', () => {
    const handleClick = jest.fn();
    renderWithTheme(<Button onClick={handleClick}>Click me</Button>);
    
    fireEvent.click(screen.getByRole('button'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });
});

🚢 Releases

This repository uses semantic-release for automated version management and package publishing.

🎯 Stable Releases

When a pull request is merged into the main branch, changes are automatically bundled into a stable release.

• Format: vX.Y.Z (e.g., v1.2.3)
• Purpose: Production-ready releases with all new features, improvements, and bug fixes
• Availability: Published to npm with latest tag

🧪 Beta Releases

When a pull request is merged into the beta branch, changes are automatically bundled into a beta release.

• Format: vX.Y.Z-beta.N (e.g., v1.2.3-beta.4)
• Purpose: Pre-release testing and preview of upcoming features
• Availability: Published to npm with beta tag
• ⚠️ Note: Beta releases may be less stable than production releases

📋 Release Notes

Each release includes:

• 📝 Changelog - Detailed list of changes, additions, and fixes
• 🏷️ Git Tags - Semantic versioning tags for easy reference
• 📦 Package Artifacts - Built and tested distribution files

🆘 Support

Need help? Check out our Contributing Guide for support options.

🤝 Contributing

We welcome contributions from the open source community! Please read our Contributing Guidelines and Code of Conduct before getting started.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Run tests: yarn test
5. Submit a pull request

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Built with ❤️ by the Open UI Kit community

📚 Documentation • 🐛 Report Issues • 💬 Discussions