# Guide du Design System UnionFlow

## 📋 Table des matières
1. [Introduction](#introduction)
2. [Tokens](#tokens)
3. [Composants](#composants)
4. [Bonnes pratiques](#bonnes-pratiques)

---

## Introduction

Le Design System UnionFlow garantit la cohérence visuelle et l'expérience utilisateur dans toute l'application.

**Palette de couleurs** : Bleu Roi (#4169E1) + Bleu Pétrole (#2C5F6F)  
**Basé sur** : Material Design 3 et tendances UI/UX 2024-2025

### Import

```dart
import 'package:unionflow_mobile_apps/shared/design_system/unionflow_design_system.dart';
```

---

## Tokens

### 🎨 Couleurs (ColorTokens)

```dart
// Primaire
ColorTokens.primary          // Bleu Roi #4169E1
ColorTokens.onPrimary        // Blanc #FFFFFF
ColorTokens.primaryContainer // Container bleu roi

// Sémantiques
ColorTokens.success          // Vert #10B981
ColorTokens.error            // Rouge #DC2626
ColorTokens.warning          // Orange #F59E0B
ColorTokens.info             // Bleu #0EA5E9

// Surfaces
ColorTokens.surface          // Blanc #FFFFFF
ColorTokens.background       // Gris clair #F8F9FA
ColorTokens.onSurface        // Texte principal #1F2937
ColorTokens.onSurfaceVariant // Texte secondaire #6B7280

// Gradients
ColorTokens.primaryGradient  // [Bleu Roi, Bleu Roi clair]
```

### 📏 Espacements (SpacingTokens)

```dart
SpacingTokens.xs    // 2px
SpacingTokens.sm    // 4px
SpacingTokens.md    // 8px
SpacingTokens.lg    // 12px
SpacingTokens.xl    // 16px
SpacingTokens.xxl   // 20px
SpacingTokens.xxxl  // 24px
SpacingTokens.huge  // 32px
SpacingTokens.giant // 48px
```

### 🔘 Rayons (SpacingTokens)

```dart
SpacingTokens.radiusXs       // 2px
SpacingTokens.radiusSm       // 4px
SpacingTokens.radiusMd       // 8px
SpacingTokens.radiusLg       // 12px - Standard pour cards
SpacingTokens.radiusXl       // 16px
SpacingTokens.radiusXxl      // 20px
SpacingTokens.radiusCircular // 999px - Boutons ronds
```

### 🌑 Ombres (ShadowTokens)

```dart
ShadowTokens.xs      // Ombre minimale
ShadowTokens.sm      // Ombre petite (cards, boutons)
ShadowTokens.md      // Ombre moyenne (cards importantes)
ShadowTokens.lg      // Ombre large (modals, dialogs)
ShadowTokens.xl      // Ombre très large (éléments flottants)

// Ombres colorées
ShadowTokens.primary  // Ombre avec couleur primaire
ShadowTokens.success  // Ombre verte
ShadowTokens.error    // Ombre rouge
```

### ✍️ Typographie (TypographyTokens)

```dart
TypographyTokens.displayLarge    // 57px - Titres héroïques
TypographyTokens.headlineLarge   // 32px - Titres de page
TypographyTokens.headlineMedium  // 28px - Sous-titres
TypographyTokens.titleLarge      // 22px - Titres de section
TypographyTokens.titleMedium     // 16px - Titres de card
TypographyTokens.bodyLarge       // 16px - Corps de texte
TypographyTokens.bodyMedium      // 14px - Corps standard
TypographyTokens.labelLarge      // 14px - Labels
TypographyTokens.labelSmall      // 11px - Petits labels
```

---

## Composants

### 📦 UFCard - Card standardisé

```dart
// Card avec ombre (par défaut)
UFCard(
  child: Text('Contenu'),
)

// Card avec bordure
UFCard.outlined(
  borderColor: ColorTokens.primary,
  child: Text('Contenu'),
)

// Card avec fond coloré
UFCard.filled(
  color: ColorTokens.primaryContainer,
  child: Text('Contenu'),
)

// Card cliquable
UFCard(
  onTap: () => print('Cliqué'),
  child: Text('Contenu'),
)
```

### 📦 UFContainer - Container standardisé

```dart
// Container standard
UFContainer(
  child: Text('Contenu'),
)

// Container arrondi
UFContainer.rounded(
  color: ColorTokens.primary,
  padding: EdgeInsets.all(SpacingTokens.lg),
  child: Text('Contenu'),
)

// Container avec ombre
UFContainer.elevated(
  child: Text('Contenu'),
)

// Container circulaire
UFContainer.circular(
  width: 48,
  height: 48,
  color: ColorTokens.primary,
  child: Icon(Icons.person),
)
```

### 📊 UFStatCard - Card de statistiques

```dart
UFStatCard(
  title: 'Membres',
  value: '142',
  icon: Icons.people,
  iconColor: ColorTokens.primary,
  subtitle: '+5 ce mois',
  onTap: () => navigateToMembers(),
)
```

### ℹ️ UFInfoCard - Card d'information

```dart
UFInfoCard(
  title: 'État du système',
  icon: Icons.health_and_safety,
  iconColor: ColorTokens.success,
  trailing: Badge(label: Text('OK')),
  child: Column(
    children: [
      Text('Tous les systèmes fonctionnent normalement'),
    ],
  ),
)
```

### 🎯 UFHeader - Header de page

```dart
UFHeader(
  title: 'Tableau de bord',
  subtitle: 'Vue d\'ensemble de votre activité',
  icon: Icons.dashboard,
  onNotificationTap: () => showNotifications(),
  onSettingsTap: () => showSettings(),
)
```

### 📱 UFAppBar - AppBar standardisé

```dart
UFAppBar(
  title: 'Détails du membre',
  actions: [
    IconButton(
      icon: Icon(Icons.edit),
      onPressed: () => edit(),
    ),
  ],
)
```

### 🔘 Boutons

```dart
// Bouton primaire
UFPrimaryButton(
  text: 'Enregistrer',
  onPressed: () => save(),
  icon: Icons.save,
)

// Bouton secondaire
UFSecondaryButton(
  text: 'Annuler',
  onPressed: () => cancel(),
)
```

---

## Bonnes pratiques

### ✅ À FAIRE

```dart
// ✅ Utiliser les tokens
Container(
  padding: EdgeInsets.all(SpacingTokens.xl),
  decoration: BoxDecoration(
    color: ColorTokens.surface,
    borderRadius: BorderRadius.circular(SpacingTokens.radiusLg),
    boxShadow: ShadowTokens.sm,
  ),
)

// ✅ Utiliser les composants
UFCard(
  child: Text('Contenu'),
)
```

### ❌ À ÉVITER

```dart
// ❌ Valeurs hardcodées
Container(
  padding: EdgeInsets.all(16),
  decoration: BoxDecoration(
    color: Color(0xFFFFFFFF),
    borderRadius: BorderRadius.circular(12),
    boxShadow: [
      BoxShadow(
        color: Colors.black.withOpacity(0.05),
        blurRadius: 10,
        offset: Offset(0, 2),
      ),
    ],
  ),
)

// ❌ Card Flutter standard
Card(
  elevation: 2,
  shape: RoundedRectangleBorder(
    borderRadius: BorderRadius.circular(12),
  ),
  child: Text('Contenu'),
)
```

### 📐 Hiérarchie des espacements

- **xs/sm** : Éléments très proches (icône + texte)
- **md/lg** : Espacement interne standard
- **xl/xxl** : Espacement entre sections
- **xxxl+** : Grandes séparations

### 🎨 Hiérarchie des couleurs

1. **primary** : Actions principales, navigation active
2. **secondary** : Actions secondaires
3. **success/error/warning** : États et feedbacks
4. **surface/background** : Fonds et containers

### 🌑 Hiérarchie des ombres

- **xs/sm** : Cards et boutons standards
- **md** : Cards importantes
- **lg/xl** : Modals, dialogs, éléments flottants
- **Colorées** : Éléments avec accent visuel

---

## 🔄 Migration

Pour migrer du code existant :

1. Remplacer `Card` par `UFCard`
2. Remplacer `Container` personnalisés par `UFContainer`
3. Remplacer couleurs hardcodées par `ColorTokens`
4. Remplacer espacements hardcodés par `SpacingTokens`
5. Remplacer ombres personnalisées par `ShadowTokens`

**Exemple** :

```dart
// Avant
Card(
  elevation: 2,
  shape: RoundedRectangleBorder(
    borderRadius: BorderRadius.circular(12),
  ),
  child: Padding(
    padding: EdgeInsets.all(16),
    child: Text('Contenu'),
  ),
)

// Après
UFCard(
  child: Text('Contenu'),
)
```

---

**Version** : 1.0.0  
**Dernière mise à jour** : 2025-10-05