npm package: @osmoz-ui/osmoz-ui
Description: <div align="center">   <img src="assets/osmoz-ui-logo.png" alt="Osmoz UI Logo" width="180" height="180" style="border-radius: 20px;">   <h1>Osmoz UI</h1>   <p><strong>Un système de design élégant, performant et accessible pour les applications React moder
Author: Théo Beaurain
Latest version: 0.1.0

<div align="center">
  <img src="assets/osmoz-ui-logo.png" alt="Osmoz UI Logo" width="180" height="180" style="border-radius: 20px;">
  <h1>Osmoz UI</h1>
  <p><strong>Un système de design élégant, performant et accessible pour les applications React modernes</strong></p>
  <p>
    <a href="#installation"><strong>Installation</strong></a> •
    <a href="#utilisation"><strong>Utilisation</strong></a> •
    <a href="#documentation"><strong>Documentation</strong></a> •
    <a href="#composants"><strong>Composants</strong></a> •
    <a href="#architecture"><strong>Architecture</strong></a>
  </p>
  <p>
    <a href="https://www.npmjs.com/package/@osmoz-ui/osmoz-ui"><img src="https://img.shields.io/npm/v/@osmoz-ui/osmoz-ui.svg?style=flat" alt="npm version"></a>
    <a href="https://github.com/Osmoz-UI/osmoz-ui/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
    <a href="#"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
    <a href="#"><img src="https://img.shields.io/badge/TypeScript-4.9+-blue" alt="TypeScript"></a>
    <a href="#"><img src="https://img.shields.io/badge/React-19+-61DAFB" alt="React"></a>
  </p>
</div>

---

## 🌟 Présentation

**Osmoz UI** est une bibliothèque d'interface utilisateur moderne, accessible et personnalisable conçue pour accélérer le développement d'applications web React. Elle propose un ensemble de composants réutilisables, des modèles de conception cohérents et des options de thématisation flexibles.

### Fonctionnalités principales

- **Composants réutilisables et accessibles**: Collection complète d'éléments UI conformes aux normes WCAG.
- **Système de thèmes avancé**: Architecture CSS en couches permettant une personnalisation simple et profonde.
- **Support TypeScript complet**: Types solides et autocomplétion intelligente pour une expérience de développement optimale.
- **Optimisé pour la performance**: Léger, rapide et compatible avec le tree shaking pour des bundles minimisés.
- **Design system cohérent**: Tokens CSS structurés avec primitives, sémantiques et variantes par thème.

## 📦 Installation

```bash
# Via npm
npm install @osmoz-ui/osmoz-ui

# Via yarn
yarn add @osmoz-ui/osmoz-ui

# Via pnpm
pnpm add @osmoz-ui/osmoz-ui
```

## 🚀 Utilisation

### 1. Importer les styles globaux

À la racine de votre projet, importez la feuille de style principale :

```js
// Dans votre fichier principal (ex: main.js, index.js, App.js)
import "@osmoz-ui/osmoz-ui/index.css";
```

### 2. Utiliser les composants

```jsx
import { Text } from '@osmoz-ui/osmoz-ui';

const App = () => {
  return (
    <Text 
      size="xl" 
      weight="bold" 
      font={{ origin: "google", name: "Roboto" }}
    >
      Bonjour avec Osmoz UI !
    </Text>
  );
}
```

## 📚 Documentation

- **Explorer les composants**: Découvrez tous les composants disponibles et leurs exemples d'utilisation dans notre Storybook.
- **Guides d'utilisation**: Apprenez à utiliser efficacement Osmoz UI dans vos projets.
- **Références API**: Consultez les props, les états et les options de personnalisation pour chaque composant.

## 🏗️ Architecture

Osmoz UI est structuré selon une architecture modulaire et évolutive :

### Structure du projet

```
osmoz-ui/
├── src/                     # Code source
│   ├── index.ts             # Point d'entrée principal
│   ├── styles/              # Styles globaux
│   │   ├── index.css        # Import central des styles
│   │   ├── reset.css        # Normalisation CSS
│   │   └── variables/       # Variables CSS
│   │       ├── primitives.css   # Tokens primitifs (couleurs, tailles, etc.)
│   │       └── themes/          # Thèmes
│   │           ├── light.css    # Thème clair
│   │           └── dark.css     # Thème sombre
│   ├── lib/                 # Bibliothèque de composants
│   │   └── components/      # Composants React
│   │       └── Text/        # Exemple: Composant Text
│   │           ├── Text.tsx          # Implémentation du composant
│   │           ├── Text.css          # Styles spécifiques au composant
│   │           ├── Text.types.ts     # Types TypeScript
│   │           ├── Text.utils.ts     # Utilitaires du composant
│   │           ├── Text.test.tsx     # Tests du composant
│   │           ├── Text.stories.tsx  # Documentation Storybook
│   │           └── index.ts          # Export du composant
│   ├── utils/               # Utilitaires partagés
│   └── types/               # Types globaux
└── .storybook/             # Configuration Storybook
```

### Architecture CSS

Osmoz UI utilise une architecture en couches pour les styles CSS :

1. **Primitives** (`primitives.css`) : Tokens fondamentaux comme les couleurs, espacements et typographie
2. **Sémantiques** (`light.css`, `dark.css`) : Variables sémantiques pour chaque thème
3. **Composants** (`Text.css`, etc.) : Styles spécifiques aux composants utilisant les tokens sémantiques

Cette approche permet une grande flexibilité dans la personnalisation tout en maintenant une cohérence visuelle.

### Fonctionnalités de style

- **Variables CSS natives** pour une personnalisation simplifiée
- **Support de polices Google** intégré directement dans les composants
- **Thèmes clairs/sombres** avec transition fluide
- **Structure modulaire** permettant d'importer uniquement les styles nécessaires

## 🧪 Tests et qualité

Osmoz UI est développé avec une attention particulière à la qualité :

- **Tests unitaires** avec Vitest
- **Tests d'accessibilité** automatisés
- **Tests visuels** avec Chromatic
- **Documentation interactive** avec Storybook

## 🤝 Contribuer

Les contributions sont les bienvenues ! Voici comment vous pouvez participer :

1. **Forker le dépôt** et créer une branche pour votre fonctionnalité
2. **Installer les dépendances** : `npm install`
3. **Lancer le serveur de développement** : `npm run dev`
4. **Soumettre une Pull Request** avec une description détaillée

## 📄 Licence

Ce projet est sous licence MIT - voir le fichier [LICENSE](LICENSE) pour plus de détails.