Version de développement

Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.

Personnalisation

Personnalisation du thème Espresso

Le thème Espresso est le nouveau système de design unifié de Dokos, conçu pour offrir une expérience utilisateur moderne, cohérente et accessible. Cette migration centralise la gestion des styles dans le framework Dodock, garantissant une harmonisation visuelle entre toutes les applications (Dokos, HRMS, Payments, etc.).

Thème Espresso — Personnalisation de l'interface

Le thème Espresso est le nouveau système de design unifié de Dokos, conçu pour offrir une expérience utilisateur moderne, cohérente et accessible. Cette migration centralise la gestion des styles dans le framework Dodock, garantissant une harmonisation visuelle entre toutes les applications (Dokos, HRMS, Payments, etc.).

Principes clés

Source unique de vérité : Les tokens de design (couleurs, typographie, espacements, ombres) sont définis dans Dodock et importés par les autres applications.
Composants standardisés : Chaque élément d'interface (badges, boutons, cartes) suit une spécification stricte, réduisant les incohérences.
Personnalisation contrôlée : Les administrateurs peuvent adapter l'apparence via des variables CSS sans altérer la structure des composants.

Composants migrés

Badges (Pilules d'indicateur)

Les badges remplacent les anciennes "pilules d'indicateur" (indicator-pill) avec une implémentation plus flexible et conforme au design system Espresso.

Utilisation de base

<span class="es-badge">Nouveau</span>

Variantes et options

Attribut	Valeurs possibles	Description
`data-variant`	`solid`, `subtle`, `outline`	Style du badge
`data-size`	`sm`, `md`, `lg`	Taille du badge
`data-theme`	`gray`, `red`, `amber`, `green`, `blue`, `violet`	Couleur du badge

Exemple avec icône :

<span class="es-badge" data-variant="solid" data-size="lg" data-theme="amber">
  <i class="i-mdi-alert-circle"></i> Urgent
</span>

Les couleurs personnalisées non conformes à la palette Espresso (ex. : purple, pink) sont dépréciées. Utilisez les thèmes prédéfinis ou définissez des variables CSS personnalisées (voir section Personnalisation avancée).

Tokens de design

Les variables CSS suivantes sont disponibles pour personnaliser l'interface. Elles remplacent les anciennes variables (ex. : --border-radius → --radius).

Couleurs

Variable	Description	Valeur par défaut
`--fg-color`	Couleur de premier plan	`#1f2937`
`--bg-color`	Couleur de fond	`#ffffff`
`--primary`	Couleur primaire	`#3b82f6`
`--success`	Couleur de succès	`#10b981`
`--warning`	Couleur d'avertissement	`#f59e0b`
`--danger`	Couleur de danger	`#ef4444`

Typographie

Variable	Description	Valeur par défaut
`--font-family`	Police principale	`Inter, sans-serif`
`--text-base`	Taille de texte de base	`1rem`
`--text-sm`	Texte petit	`0.875rem`
`--text-lg`	Texte grand	`1.125rem`

Espacement

Variable	Description	Valeur par défaut
`--space-1`	Espacement unitaire	`0.25rem`
`--space-2`	Espacement double	`0.5rem`
`--space-3`	Espacement triple	`0.75rem`
`--space-4`	Espacement quadruple	`1rem`

Radius (coins arrondis)

Variable	Description	Valeur par défaut
`--radius-sm`	Petit radius	`0.125rem`
`--radius-md`	Radius moyen	`0.25rem`
`--radius-lg`	Grand radius	`0.375rem`
`--radius-full`	Radius complet (cercle)	`9999px`

Personnalisation via l'interface

Modifier les couleurs du thème

Allez dans Paramètres > Personnalisation > Thème Espresso (ou recherchez "Thème Espresso" dans la barre Awesome).
Sélectionnez une couleur primaire, secondaire, ou une couleur de danger/succès.
Les changements sont appliqués en temps réel.
Cliquez sur Enregistrer pour valider.

      
flowchart TD
    A[Accéder aux paramètres du thème] --> B[Modifier les couleurs]
    B --> C[Prévisualiser]
    C --> D{Appliquer ?}
    D -->|Oui| E[Enregistrer]
    D -->|Non| B

Réinitialiser le thème

Pour revenir aux valeurs par défaut d'Espresso :

Allez dans Paramètres > Personnalisation > Thème Espresso.
Cliquez sur Réinitialiser en bas du formulaire.
Confirmez la réinitialisation.

Personnalisation avancée (développeurs)

Surcharger les variables CSS

Pour adapter le thème à votre charte graphique, créez un fichier CSS personnalisé (ex. : apps/your_app/your_app/public/css/custom_theme.css) et surchargez les variables Espresso :

:root {
  --primary: #6366f1; /* Violet personnalisé */
  --radius-md: 0.5rem; /* Coins plus arrondis */
  --space-3: 1rem; /* Espacement plus large */
}

Puis chargez ce fichier dans votre application via le hooks.py :

app_include_css = [
  "/assets/your_app/css/custom_theme.css"
]

Créer des thèmes dérivés

Pour proposer plusieurs thèmes (ex. : clair/sombre) :

Définissez un sélecteur de thème dans votre application :

<body class="theme-light">
  <!-- Contenu -->
</body>

Adaptez les variables CSS en fonction du thème :

.theme-light {
  --bg-color: #ffffff;
  --fg-color: #1f2937;
}

.theme-dark {
  --bg-color: #1f2937;
  --fg-color: #f9fafb;
}

Ajoutez un sélecteur de thème dans les paramètres utilisateur.

Migration des anciennes personnalisations

Badges (anciennes pilules d'indicateur)

Les anciennes classes indicator-pill et indicator-pill-{color} sont toujours supportées pour des raisons de compatibilité, mais leur utilisation est déconseillée. Voici comment migrer :

Ancienne classe	Équivalent Espresso
`indicator-pill`	`es-badge`
`indicator-pill-green`	`es-badge data-theme="green"`
`indicator-pill-red`	`es-badge data-theme="red"`

Exemple de migration :

- <span class="indicator-pill indicator-pill-green">Actif</span>
+ <span class="es-badge" data-theme="green">Actif</span>

Variables CSS dépréciées

Ancienne variable	Nouvelle variable
`--border-radius`	`--radius-md`
`--shadow-sm`	`--shadow-1`
`--text-muted`	`--gray-500`

Bonnes pratiques

Consistance : Utilisez les composants Espresso (es-badge, es-button, etc.) plutôt que de créer des styles personnalisés.
Accessibilité : Vérifiez les contrastes de couleurs avec des outils comme WebAIM Contrast Checker.
Performance : Évitez de surcharger les variables CSS dans des sélecteurs spécifiques (privilégiez les surcharges globales).
Documentation : Documentez les personnalisations dans un fichier THEME.md à la racine de votre application.

Dépannage

Problème : Les badges n'affichent pas les icônes

Vérifiez que l'icône est bien chargée (utilisez des icônes de Material Design Icons ou Frappe Icons).
Assurez-vous que la classe CSS de l'icône est correcte (ex. : i-mdi-alert-circle).

Problème : Les couleurs personnalisées ne s'appliquent pas

Vérifiez que votre fichier CSS est bien chargé (inspectez le réseau dans les outils de développement).
Assurez-vous que les variables sont surchargées dans le bon sélecteur (ex. : :root pour une portée globale).

Problème : L'interface semble "cassée" après la migration

Videz le cache du navigateur.
Vérifiez que toutes les applications utilisent bien les dernières versions des dépendances (ex. : frappe-ui).
Consultez les logs du serveur pour détecter d'éventuelles erreurs de compilation CSS.

Ressources

Voir les paramètres du thème Espresso dans la démo