unionflow-server-api/unionflow-mobile-apps/lib/shared/design_system/DESIGN_SYSTEM_GUIDE.md

Guide du Design System UnionFlow

📋 Table des matières

1. Introduction
2. Tokens
3. Composants
4. 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

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

---

Tokens

🎨 Couleurs (ColorTokens)

// 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)

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)

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)

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)

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é

// 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é

// 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

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

ℹ️ UFInfoCard - Card d'information

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

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

📱 UFAppBar - AppBar standardisé

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

🔘 Boutons

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

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

---

Bonnes pratiques

✅ À FAIRE

// ✅ 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

// ❌ 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 :

// 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