Framework CSS

Principe

Le framework CSS d'OpenOverlay est injecté automatiquement par le dashboard dans toutes les interfaces admin des modules via admin/admin.css. Aucun import CSS n'est nécessaire dans les fichiers des modules : les classes sont disponibles dès que le module est chargé.

Cela garantit la cohérence visuelle entre tous les modules — même provenant d'auteurs différents — et évite les duplications de styles entre modules.

Variables CSS

Les tokens de design sont accessibles via var(--nom) dans les CSS de tes modules. Ils garantissent que ton module s'adapte automatiquement à l'apparence du dashboard.

Composants de base

Les composants du dashboard sont disponibles directement dans les templates JS des modules. Ils constituent la base de toute interface admin.

Cards

.card + .card-header + .card-body — carte avec entête et corps. C'est le conteneur principal de tout panneau d'administration.

Boutons

.btn — bouton de base. Variantes de couleur : .btn-primary, .btn-secondary, .btn-danger (rouge), .btn-ghost (transparent). Tailles : .btn-sm (compact), .btn-xs (encore plus compact).

Champs de formulaire

.field + label + input / select / textarea — structure standard d'un champ de saisie avec son label.

Badge

.badge — étiquette colorée inline. Combinable avec .badge-green, .badge-red, .badge-muted, .badge-purple.

Exemple minimal

<div class="card">
  <div class="card-header">Titre de section</div>
  <div class="card-body">
    <div class="field">
      <label>Nom</label>
      <input type="text" id="cfg-name">
    </div>
    <div class="field">
      <label>Couleur</label>
      <input type="color" id="cfg-color">
    </div>
  </div>
</div>

Modificateurs de card

Ces classes s'ajoutent sur .card ou .card-body pour adapter l'apparence à des contextes spécifiques.

Texte & couleurs

Classes utilitaires de typographie et de couleur. À utiliser directement dans les templates HTML des modules.

Espacement

Classes de marge courtes pour espacer les éléments sans inline style. Préfixes : mb- (margin-bottom), mt- (margin-top), ml- (margin-left).

Exemple combiné : <p class="text-sm text-muted mb-8">...</p> applique simultanément les trois utilitaires.

Flex & visibilité

Composants flex et utilitaires de mise en page pour organiser les éléments sans écrire de CSS ad hoc.

Toggle de visibilité

Pour afficher ou masquer un élément depuis JS, utiliser classList.toggle('hidden', condition) plutôt que de modifier style.display directement.

// Correct
wrap.classList.toggle('hidden', !cfg.showSection);

// Interdit
wrap.style.display = cfg.showSection ? 'flex' : 'none';

Pour les éléments qui ont besoin de display: flex ou display: block quand ils sont affichés, utiliser le pattern .visible dans le CSS du module :

/* Dans mods/{id}/admin.css */
.mon-element { display: none; }
.mon-element.visible { display: flex; }

// Dans admin.js
el.classList.toggle('visible', condition);

Composants de page

Composants spécifiques au dashboard disponibles dans tous les modules pour des besoins courants (URL d'activation, tags, barres de progression, historique…).

Exemple — barre de progression

<div class="row-flex mb-8">
  <span class="text-sm text-muted">Installation…</span>
  <div class="progress-track">
    <div class="progress-fill" style="width: 60%"></div>
  </div>
</div>

Bonnes pratiques

Cinq règles à respecter pour que ton module soit cohérent avec le dashboard et accepté au Store.

1. Pas de style="" dans les templates — Aucune propriété visuelle (couleur, taille, marge, visibilité) ne doit passer par un attribut inline dans le HTML généré dynamiquement. Les rares exceptions légitimes sont documentées explicitement (ex : style="width: X%" sur .progress-fill pour une valeur numérique purement dynamique).
2. Couleurs dynamiques via custom properties — Quand une couleur vient de la config, ne pas l'écrire directement dans style="", et ne pas mettre de fallback dans le var() :

   // Correct — passe la valeur (et la valeur par défaut) via setProperty()
   el.style.setProperty('--dot-color', cfg.color ?? '#888888');
   
   // Dans mods/{id}/admin.css — pas de fallback dans var()
   .ma-classe { background: var(--dot-color); }
   
   // Interdit — fallback CSS
   .ma-classe { background: var(--dot-color, #888); }
   
   // Interdit — inline style direct
   el.style.background = cfg.color;

3. Toggle via classList — Basculer la visibilité par classe, jamais par style.display :

   // Correct
   el.classList.toggle('hidden', !condition);
   
   // Interdit
   el.style.display = condition ? 'flex' : 'none';

4. Préférer les utilitaires aux classes one-shot — Combiner les classes existantes plutôt que d'en créer de nouvelles pour un seul usage :

   <!-- Correct -->
   <p class="text-sm text-muted mb-8">…</p>
   
   <!-- Interdit -->
   <p style="font-size:13px;color:var(--muted);margin-bottom:8px">…</p>

5. Pas de fallback dans var() — Dans les fichiers mods/{id}/admin.css, utiliser var(--x) uniquement, sans valeur de repli. Si une valeur par défaut est nécessaire (notamment pour les CSS custom properties dynamiques), la définir via el.style.setProperty() en JS avant le premier rendu :

   // Avant le premier rendu — définit la valeur par défaut
   el.style.setProperty('--dot-color', cfg.color ?? '#888888');
   
   // Dans mods/{id}/admin.css — sans fallback
   .mon-element { background: var(--dot-color); }
   
   // Interdit dans admin.css
   .mon-element { background: var(--dot-color, #888); }

6. Ne pas redéfinir les classes du framework — Ne pas réécrire .card, .btn, .field ou n'importe quelle classe du dashboard dans mods/{id}/admin.css. Ajouter uniquement des classes spécifiques au module, idéalement préfixées par l'id du module (ex : .ticker-preview).

Téléchargement

Ces fichiers sont générés automatiquement depuis admin/admin.css et mis à jour à chaque release d'OpenOverlay. Utiles pour consulter l'intégralité du framework hors ligne ou pour un éditeur avec autocomplétion.

• oo-mod-framework.css — version complète commentée, lisible. Idéale pour consulter le détail de chaque classe.
• oo-mod-framework.min.css — version minifiée, prête pour production ou pour vérification de taille.