acemyjob-ui/README.md

A React component library for job search and career management applications

# AceMyJob UI

A modern React component library built for job search and career management applications. Built with TypeScript, Tailwind CSS, and Headless UI.

[![npm version](https://badge.fury.io/js/acemyjob-ui.svg)](https://badge.fury.io/js/acemyjob-ui)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🎨 **Modern Design System** - Beautiful, accessible components with dark/light theme support
- 🔧 **TypeScript First** - Full TypeScript support with comprehensive type definitions
- 📱 **Responsive** - Mobile-first design that works on all screen sizes
- ♿ **Accessible** - Built with accessibility in mind using Headless UI primitives
- 🎭 **Themeable** - Customizable color system with CSS variables
- 📦 **Tree Shakable** - Import only what you need

## 📦 Installation

```bash
npm install acemyjob-ui
# or
yarn add acemyjob-ui
# or
pnpm add acemyjob-ui
```

### Peer Dependencies

Make sure you have the required peer dependencies installed:

```bash
npm install react react-dom @headlessui/react @heroicons/react
```

## 🚀 Quick Start

1. **Import the CSS** in your app's entry point:

```tsx
// In your main.tsx or App.tsx
import 'acemyjob-ui/styles';
```

2. **Wrap your app with ThemeProvider**:

```tsx
import { ThemeProvider } from 'acemyjob-ui';

function App() {
  return (
    <ThemeProvider defaultTheme="system" storageKey="app-theme">
      <YourApp />
    </ThemeProvider>
  );
}
```

3. **Use components**:

```tsx
import { Sidebar, ThemeToggle } from 'acemyjob-ui';
import { HomeIcon, BriefcaseIcon } from '@heroicons/react/24/outline';

const navigation = [
  { name: 'Dashboard', href: '/', icon: HomeIcon, current: true },
  { name: 'Jobs', href: '/jobs', icon: BriefcaseIcon, current: false },
];

const company = {
  name: "Your Company",
  logo: "/logo.svg"
};

const profile = {
  name: "John Doe",
  image: "/avatar.jpg"
};

function Dashboard() {
  return (
    <>
      <ThemeToggle />
      <Sidebar 
        company={company} 
        profile={profile} 
        navigation={navigation} 
      />
    </>
  );
}
```

## 📖 Components

### ThemeProvider

Provides theme context to your application.

```tsx
<ThemeProvider defaultTheme="light" storageKey="my-app-theme">
  <App />
</ThemeProvider>
```

**Props:**
- `defaultTheme` - `"light" | "dark" | "system"` (default: "system")
- `storageKey` - String for localStorage key (default: "acemyjob-ui-theme")

### ThemeToggle

A button to toggle between light, dark, and system themes.

```tsx
<ThemeToggle />
```

### Sidebar

A responsive navigation sidebar with mobile support.

```tsx
<Sidebar 
  company={company} 
  profile={profile} 
  navigation={navigation} 
/>
```

**Props:**
- `company` - `{ name: string; logo: string }`
- `profile` - `{ name: string; image: string }`
- `navigation` - Array of navigation items

### ColorPalette

Displays the complete color system (useful for design systems documentation).

```tsx
<ColorPalette />
```

## 🎨 Styling

### CSS Variables

The library uses CSS variables for theming. You can customize colors by overriding these variables:

```css
:root {
  --color-background: oklch(1.0 0.0 0);
  --color-surface: oklch(0.98 0.002 247.83);
  --color-text-primary: oklch(0.15 0.007 265.75);
  /* ... more variables */
}

.dark {
  --color-background: oklch(0.1 0.007 265.75);
  --color-surface: oklch(0.13 0.008 265.75);
  --color-text-primary: oklch(0.95 0.002 247.83);
  /* ... more variables */
}
```

### Tailwind CSS

If you're using Tailwind CSS, extend your config to include the library's color system:

```js
module.exports = {
  darkMode: 'class',
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/acemyjob-ui/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      colors: {
        background: 'var(--color-background)',
        surface: 'var(--color-surface)',
        'text-primary': 'var(--color-text-primary)',
        // ... more semantic colors
      },
    },
  },
  plugins: [],
}
```

## 📚 TypeScript

All components come with TypeScript definitions. Import types as needed:

```tsx
import type { NavigationItem, Company, Profile, Theme } from 'acemyjob-ui';
```

## 🛠 Development

To contribute to this library:

```bash
# Clone the repository
git clone https://github.com/yourusername/acemyjob-ui.git

# Install dependencies
npm install

# Start development server
npm run dev

# Build the library
npm run build

# Run Storybook
npm run storybook
```

## 📄 License

MIT © [Your Name](https://github.com/yourusername)

## 🤝 Contributing

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