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

Thème Espresso

Le thème Espresso est le nouveau système de design unifié de Dokos, conçu pour harmoniser l'apparence de toutes les applications (Dokos, HRMS, Payments, etc.) tout en offrant une expérience utilisateur moderne et cohérente.

Personnalisation du thème

Les administrateurs peuvent personnaliser le thème Espresso depuis Paramètres > Personnalisation > Thème Espresso. Voici les principales options disponibles :

Espacements et radius

Les espacements (marges, paddings) et les coins arrondis (radius) sont également standardisés :

Variable	Rôle	Valeur par défaut
`--radius-sm`	Coins légèrement arrondis	`4px`
`--radius-md`	Coins modérément arrondis	`6px`
`--radius-lg`	Coins très arrondis	`8px`
`--spacing-xs`	Espacement extra-small	`4px`
`--spacing-sm`	Espacement small	`8px`
`--spacing-md`	Espacement medium	`12px`
`--spacing-lg`	Espacement large	`16px`
`--spacing-xl`	Espacement extra-large	`24px`

Exemple — Bureau Moderne Pour une interface plus moderne, l'administrateur de Bureau Moderne augmente --radius-md à 12px et --spacing-lg à 20px pour des espacements plus aérés.

Badges

Les badges Espresso remplacent les anciennes "pilules d'indicateur" (indicator-pill). Ils sont plus flexibles et accessibles, avec des styles prédéfinis pour chaque type de message :

<span class="badge badge-primary">Primaire</span>
<span class="badge badge-success">Succès</span>
<span class="badge badge-danger">Danger</span>
<span class="badge badge-warning">Avertissement</span>
<span class="badge badge-info">Information</span>

      
flowchart LR
    A[Ancien style] -->|Remplacé par| B[Badges Espresso]
    B --> C[Couleurs standardisées]
    B --> D[Espacements optimisés]
    B --> E[Accessibilité améliorée]

Migration des personnalisations

Si vous avez personnalisé l'apparence de Dokos via des fichiers CSS ou des scripts, certaines modifications peuvent nécessiter des ajustements pour rester compatibles avec Espresso.

Variables dépréciées

Les anciennes variables CSS sont dépréciées et remplacées par leurs équivalents Espresso :

Ancienne variable	Nouvelle variable
`--border-radius`	`--radius-md`
`--primary-color`	`--primary`
`--success-color`	`--success`
`--danger-color`	`--danger`

Bon à savoir : Les anciennes variables restent fonctionnelles pour l'instant, mais il est recommandé de les remplacer progressivement pour garantir la compatibilité avec les futures mises à jour.

Exemple de migration

Avant (ancien thème) :

.custom-button {
    background-color: var(--primary-color);
    border-radius: var(--border-radius);
}

Après (thème Espresso) :

.custom-button {
    background-color: var(--primary);
    border-radius: var(--radius-md);
}

Spécificités Dokos

Le thème Espresso intègre des spécificités Dokos pour garantir une expérience utilisateur optimale, notamment dans le bundle website (site web public).

Variables CSS spécifiques

Le fichier frappe/public/scss/website/index.scss charge quatre imports spécifiques à Dokos, essentiels pour le bon fonctionnement du thème :

@import "../common/inter.css"; // @dokos
@import "../common/css_variables.scss"; // @dokos
@import "../desk/calendar-base.scss"; // @dokos
@import "../website/web_sidebar.scss"; // @dokos

Ces imports fournissent :

inter.css : La police Inter, optimisée pour le web.
css_variables.scss : Les variables CSS spécifiques à Dokos, comme $input-height et --padding-*.
calendar-base.scss : Les styles de base pour le calendrier.
web_sidebar.scss : Les styles pour la barre latérale du site web.

⚠️ Attention : Ces imports sont critiques pour le bon fonctionnement du thème Espresso sur le site web. Toute modification ou suppression de ces lignes peut entraîner des régressions visuelles ou fonctionnelles.

Test de validation

Un test automatisé (TestDokosWebsiteBundleScss) vérifie la présence de ces quatre imports dans le bundle website. Ce test garantit que les spécificités Dokos sont bien intégrées et protégées contre les régressions lors des mises à jour.

Pour exécuter le test :

bench --site test run-tests --module frappe.tests.test_dokos_specificities

Ressources utiles

Pour les développeurs — Personnalisation avancée

Si vous souhaitez personnaliser davantage le thème Espresso, vous pouvez :

Surcharger les variables CSS : Créez un fichier apps/your_app/your_app/public/scss/theme.scss et redéfinissez les variables Espresso.
```
:root {
    --primary: #2563EB;
    --radius-md: 12px;
}
```

Ajouter des styles personnalisés : Utilisez le même fichier pour ajouter des styles spécifiques à votre application.

.custom-card {
    background-color: white;
    border-radius: var(--radius-md);
    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

Intégrer vos styles dans le bundle : Ajoutez votre fichier SCSS dans le hooks.py de votre application pour qu'il soit compilé avec le thème Espresso.
```
app_include_css = [
    "public/css/your_app.css",
]
```

⚠️ Attention : Évitez de modifier directement les fichiers SCSS du thème Espresso dans frappe/public/scss, car ces modifications seront écrasées lors des mises à jour.