npm package: @limurse/design-system
Description: A comprehensive design system for the Limurse Web platform
Author: Limurse Team
Latest version: 1.0.14

# Limurse Design System

A comprehensive design system for the Limurse Business Web platform, built with React, TypeScript, and Tailwind CSS.

## 🎨 Overview

The Limurse Design System provides a consistent, accessible, and scalable foundation for building user interfaces. It includes:

- **Design Tokens**: Colors, typography, spacing, and other design values
- **Component Library**: Reusable UI components built with React and TypeScript
- **Documentation**: Comprehensive guides and examples
- **Design Guidelines**: Best practices for implementation

## 📦 Installation

```bash
npm install @limurse/design-system
# or
yarn add @limurse/design-system
```

## 🚀 Quick Start

```tsx
import { Button, Card, Typography } from '@limurse/design-system';

function App() {
  return (
    <div className="p-4">
      <Typography variant="h1">Welcome to Limurse</Typography>
      <Card>
        <Typography variant="body">This is a card component</Typography>
        <Button variant="primary">Get Started</Button>
      </Card>
    </div>
  );
}
```

## 🎯 Core Principles

- **Consistency**: Unified design language across all interfaces
- **Accessibility**: WCAG 2.1 AA compliance
- **Performance**: Optimized components with minimal bundle size
- **Flexibility**: Customizable while maintaining design integrity
- **Developer Experience**: TypeScript support and comprehensive documentation

## 📚 Documentation

- [Getting Started](./docs/getting-started.md)
- [Design Tokens](./docs/design-tokens.md)
- [Components](./docs/components.md)
- [Theming](./docs/theming.md)
- [Accessibility](./docs/accessibility.md)
- [Contributing](./docs/contributing.md)

## 🛠️ Tech Stack

- **React 18+** - UI library
- **TypeScript** - Type safety
- **Tailwind CSS** - Utility-first CSS framework
- **Radix UI** - Accessible component primitives
- **Framer Motion** - Animation library
- **Storybook** - Component documentation and testing

## 📋 Table of Contents

- [Design Tokens](#design-tokens)
- [Components](#components)
- [Theming](#theming)
- [Accessibility](#accessibility)
- [Contributing](#contributing)

## 🎨 Design Tokens

### Colors

Our color system is built around semantic color tokens that adapt to light and dark modes:

```tsx
// Primary colors
primary: {
  DEFAULT: 'hsl(var(--primary))',
  foreground: 'hsl(var(--primary-foreground))'
}

// Secondary colors
secondary: {
  DEFAULT: 'hsl(var(--secondary))',
  foreground: 'hsl(var(--secondary-foreground))'
}

// Semantic colors
destructive: {
  DEFAULT: 'hsl(var(--destructive))',
  foreground: 'hsl(var(--destructive-foreground))'
}
```

### Typography

```tsx
// Font families
fontFamily: {
  sans: ['Rubik', 'system-ui', 'sans-serif'],
  serif: ['Rubik', 'Geist', 'system-ui', 'sans-serif'],
  display: ['Rubik', 'Geist', 'system-ui', 'sans-serif'],
  body: ['Rubik', 'Geist', 'system-ui', 'sans-serif'],
  jakarta: ['"Plus Jakarta Sans"', 'sans-serif']
}
```

### Spacing

```tsx
// Consistent spacing scale
spacing: {
  0: '0px',
  1: '4px',
  2: '8px',
  3: '12px',
  4: '16px',
  5: '20px',
  6: '24px',
  8: '32px',
  10: '40px',
  12: '48px',
  16: '64px',
  20: '80px',
  24: '96px',
  32: '128px',
  40: '160px',
  48: '192px',
  56: '224px',
  64: '256px',
}
```

## 🧩 Components

### Available Components

- **Layout**: Container, Grid, Stack, Divider
- **Navigation**: Button, Link, Breadcrumb, Pagination
- **Forms**: Input, Select, Checkbox, Radio, Textarea
- **Feedback**: Alert, Toast, Progress, Spinner
- **Data Display**: Card, Table, List, Badge
- **Overlay**: Modal, Drawer, Popover, Tooltip
- **Media**: Avatar, Image, Icon

### Component Usage

```tsx
import { Button, Card, Typography } from '@limurse/design-system';

// Basic usage
<Button variant="primary" size="md">
  Click me
</Button>

// With icons
<Button variant="secondary" size="sm" icon={<Icon />}>
  With Icon
</Button>

// Cards
<Card>
  <Card.Header>
    <Typography variant="h3">Card Title</Typography>
  </Card.Header>
  <Card.Content>
    <Typography variant="body">Card content goes here</Typography>
  </Card.Content>
  <Card.Footer>
    <Button variant="outline">Action</Button>
  </Card.Footer>
</Card>
```

## 🎨 Theming

### Light Mode (Default)

```css
:root {
  --background: 0 0% 100%;
  --foreground: 224 71.4% 4.1%;
  --primary: 220.9 39.3% 11%;
  --primary-foreground: 210 20% 98%;
  /* ... more tokens */
}
```

### Dark Mode

```css
.dark {
  --background: 224 71.4% 4.1%;
  --foreground: 210 20% 98%;
  --primary: 210 20% 98%;
  --primary-foreground: 220.9 39.3% 11%;
  /* ... more tokens */
}
```

### Custom Theming

```tsx
import { ThemeProvider } from '@limurse/design-system';

const customTheme = {
  colors: {
    primary: {
      DEFAULT: '#your-primary-color',
      foreground: '#your-primary-foreground'
    }
  }
};

<ThemeProvider theme={customTheme}>
  <App />
</ThemeProvider>
```

## ♿ Accessibility

All components are built with accessibility in mind:

- **WCAG 2.1 AA** compliance
- **Keyboard navigation** support
- **Screen reader** compatibility
- **Focus management** and indicators
- **ARIA attributes** and roles
- **Color contrast** ratios

### Accessibility Guidelines

```tsx
// Proper labeling
<Button aria-label="Close dialog">
  <Icon />
</Button>

// Focus management
<Modal onOpenChange={handleOpenChange}>
  <Modal.Content>
    <Modal.Title>Dialog Title</Modal.Title>
    <Modal.Description>Dialog description</Modal.Description>
  </Modal.Content>
</Modal>
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./docs/contributing.md) for details.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/limurse/design-system.git

# Install dependencies
npm install

# Start Storybook
npm run storybook

# Run tests
npm test

# Build the library
npm run build
```

### Component Development

1. Create your component in `src/components/`
2. Add TypeScript types in `src/types/`
3. Write stories in `src/stories/`
4. Add tests in `src/__tests__/`
5. Update documentation

## 📄 License

MIT License - see [LICENSE](./LICENSE) for details.

## 🆘 Support

- **Documentation**: [docs.limurse.com/design-system](https://docs.limurse.com/design-system)
- **Issues**: [GitHub Issues](https://github.com/limurse/design-system/issues)
- **Discussions**: [GitHub Discussions](https://github.com/limurse/design-system/discussions)
- **Email**: design-system@limurse.com

---

Built with ❤️ by the Limurse Team