# Design MD — Keros / AMCO Avancé > Référence design exploitable par les agents IA (Claude, Codex, ChatGPT Agent), les développeurs front et les designers. > **Source de vérité** : ce fichier + `03_design_system_html/css/tokens.css`. Toute évolution graphique passe par une mise à jour conjointe de ces deux ressources et une entrée de changelog. - **Version** : 0.2.0 (V0 — fondations + Keros AI + alignement charte TEEO 2025) - **Statut** : projet, en cours de validation TEEO - **Date** : 2026-05-21 - **Auteur** : Reynholds Reinette + assistance Claude (Cowork) - **Conformité** : Charte TEEO — *Identité Visuelle de Référence* (Document maître, Version 2025) --- ## 1. Vision produit ### 1.1 Rôle de Keros Keros est la **couche d'évolution progressive** de la plateforme AMCO. Son rôle est de moderniser l'expérience utilisateur, d'unifier l'identité visuelle, de préparer l'intégration de micro-services et d'introduire les briques Data & IA — à commencer par le micro-service **Détection d'anomalies** d'AMCO Avancé. Keros n'est **pas** une refonte radicale d'AMCO. C'est une montée en gamme module par module, écran par écran, en cohabitation avec l'existant. ### 1.2 Positionnement AMCO Avancé AMCO Avancé désigne la **gamme** d'AMCO qui intègre les briques Data & IA. Le premier livrable phare est la détection d'anomalies, réutilisant les acquis de Keros AI. Les modules AMCO Avancé sont délivrés comme **micro-services** intégrés progressivement dans le portail AMCO (via micro-frontend ou iFrame), avec un filtrage multi-tenant strictement backend. ### 1.3 Philosophie design - **Progressivité** : pas de rupture brutale ; chaque module migré doit cohabiter avec les écrans AMCO existants. - **Sobriété industrielle** : esthétique professionnelle, dense mais lisible, pas startup, pas marketing. - **Clarté opérationnelle** : prioriser ce qui appelle une action (anomalies, alertes, KPI critiques). - **Réutilisabilité** : composants framework-agnostiques (HTML/CSS portable vers React/Vite ou Vue). - **Continuité métier** : vocabulaire AMCO conservé (compteur, secteur, anomalie, requalification). --- ## 2. Principes UX | Principe | Pourquoi | Application concrète | |---|---|---| | **Progressivité** | Préserver les habitudes utilisateurs AMCO | Cohabitation visuelle, migration écran par écran | | **Continuité avec AMCO** | Pas de désorientation | Navigation top/side conservée, mêmes mots métier | | **Clarté opérationnelle** | Aller à l'action | KPI en haut, anomalies critiques en évidence | | **Densité maîtrisée** | Outil métier, pas grand public | Tableaux denses (32-40 px) mais respiration entre groupes | | **Hiérarchie visuelle** | Lire vite ce qui compte | Taille / poids / couleur servent la lecture, pas la déco | | **Explicabilité des anomalies** | Confiance dans l'IA | Score affiché, modèle nommé, contexte (compteur, période) | | **Priorité aux actions métier** | Productivité | Boutons d'action à portée directe sur chaque anomalie | | **États explicites** | Pas de magie silencieuse | Toasts, timeline, log d'activité visibles | --- ## 3. Identité visuelle ### 3.1 Couleurs — strictement conformes à la charte TEEO 2025 - **Bleu TEEO** `#157AB3` : couleur primaire, structurante (titres, éléments de navigation, primary buttons, logos). - **Indigo Profond** `#485194` : sous-titres, contrastes forts, texte secondaire. - **Orange Vif** `#E9A547` : attention, notifications, points chauds — usage parcimonieux. - **Rouge Alerte** `#E14929` : alertes et anomalies uniquement — jamais décoratif. - **Gris Clair** `#DEDFDF` : fonds, bordures, lignes de séparation. - **Blanc** `#FFFFFF` : fond dominant. - **Sévérités d'anomalie** : faible (gris), moyenne (orange), élevée (orange foncé), critique (rouge alerte). - **Data viz** : palette restreinte — Bleu (Donnée A), Indigo (Donnée B), Orange (accent / comparaison), Vert sobre (référence), Rouge (anomalie). > **Ratio recommandé charte TEEO** : 70 % blanc/neutre, 20 % bleu, 10 % accents. Contrastes WCAG AA respectés sur tous les textes. ### 3.2 Typographie — charte TEEO - **Famille** : `Inter Tight, Inter, Roboto, "Segoe UI", system-ui, sans-serif` (Sans-Serif moderne). - **Style** : net, lisible, professionnel. - **Échelle** : 11 / 12 / 14 / 16 / 18 / 20 / 24 / 30 px. - **Poids** : 400 / 500 / 600 / 700. - **Niveau 1 — Titres** : grand, graisse Bold, couleur Bleu Principal `#157AB3`. - **Niveau 2 — Sous-titres / chapeaux** : moyen, Regular, Indigo `#485194`. - **Niveau 3 — Corps** : petit, Regular, Noir/Gris foncé. - **Niveau 4 — Mise en exergue** : usage parcimonieux du **Bold** ou de l'orange TEEO `#E9A547` pour les mots-clés. - **Numériques** : `font-variant-numeric: tabular-nums` sur valeurs chiffrées. - **Mono** : `JetBrains Mono` ou pile mono système pour IDs, scores, payloads. - **Règle impérative TEEO** : jamais plus de 2 niveaux de titres par écran / par slide. ### 3.3 Icônes — charte TEEO - **Style** : linéaire (outline), simple, **bicolore Bleu Principal + Touche d'Orange**. - Pack recommandé : **Lucide** ou **Phosphor** ; les icônes sont retouchées si besoin pour intégrer l'accent orange TEEO sur les éléments porteurs de sens. - Stroke épais et lisible (1.8 à 2 px) ; tailles 16 / 20 / 24 px. - Couleur via `currentColor` (héritage CSS) ; l'accent orange est appliqué au pinceau (path spécifique). - **Règles TEEO** : une icône = un concept ; fonctionnelle, pas décorative ; trait épais. - Toujours associer une icône à un libellé sauf si la signification est universelle (loupe = recherche, × = fermer). ### 3.3.bis Logo TEEO & monogramme - **Logo complet** : sur fond blanc, couleurs officielles. Réservé aux en-têtes officiels, page d'accueil, footer. - **Monogramme** (plaque arrondie + boucle bicolore) : pour avatars et puces graphiques — utilisé notamment dans l'icône **Keros** (voir §5.23). - **Zone de protection** : espace minimum autour du logo = hauteur du 'e'. - **Interdits TEEO** : ne pas déformer, ne pas changer les couleurs du dégradé, ne pas placer sur fond bruyant, ne pas écrire TEEO différemment des versions autorisées. ### 3.4 Grilles & espacements - Échelle 4 px : `--space-1` (4) à `--space-12` (48). - Marges externes de page : 24-32 px. - Marges internes de carte : 16-24 px. - Gouttière entre cards (grid gap) : 16 px par défaut. ### 3.5 Rayons - `--radius-sm` : 4 px (badges, sparkline, micro-éléments). - `--radius-md` : 8 px (boutons, inputs, cartes, modale). - `--radius-lg` : 12 px (cartes principales, sections). - `--radius-pill` : 999 px (chips, badges arrondis). ### 3.6 Ombres - `--shadow-sm` : élévation discrète (cartes). - `--shadow-md` : drawers, dropdowns. - `--shadow-lg` : modales centrées. ### 3.7 Règles de contraste - Texte normal : contraste ≥ 4.5:1 (WCAG AA). - Texte large (≥ 18 px ou 14 px bold) : contraste ≥ 3:1. - Icônes informatives : contraste ≥ 3:1. - Bordures non décoratives : contraste ≥ 3:1 avec leur fond. --- ## 4. Design tokens Source : `03_design_system_html/css/tokens.css`. À recopier tel quel dans tout projet Keros (React/Vite, Vue ou autre). ```css :root { /* Brand TEEO (Charte 2025) */ --color-primary: #157AB3; /* Bleu TEEO */ --color-primary-hover: #0F5F8C; --color-primary-active: #0B4D72; --color-primary-soft: #E1F0F8; --color-secondary: #485194; /* Indigo Profond */ --color-secondary-soft: #E6E8F2; --color-accent: #E9A547; /* Orange Vif */ --color-accent-soft: #FBEFD8; /* Surfaces & neutres */ --color-bg: #FFFFFF; --color-surface: #FFFFFF; --color-surface-alt: #F5F7FA; --color-border: #DEDFDF; /* Gris Clair TEEO */ --color-border-strong: #C1C4C7; --color-text: #1A1F2E; --color-text-muted: #485194; --color-text-soft: #8A909C; /* Fonctionnelles */ --color-success: #2E8B57; --color-success-bg: #E1F2E8; --color-warning: #E9A547; --color-warning-bg: #FBEFD8; --color-danger: #E14929; /* Rouge Alerte TEEO */ --color-danger-bg: #FDE3DC; --color-info: #157AB3; --color-info-bg: #E1F0F8; /* Sévérités */ --color-sev-low: #8A909C; --color-sev-medium: #E9A547; --color-sev-high: #D87826; --color-sev-critical: #E14929; /* Data viz */ --chart-1: #157AB3; --chart-2: #485194; --chart-3: #E9A547; --chart-4: #2E8B57; --chart-5: #E14929; --chart-6: #5C8DB8; --chart-grid: #DEDFDF; /* Espacements (4px scale) */ --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-5: 20px; --space-6: 24px; --space-8: 32px; --space-10: 40px; --space-12: 48px; /* Rayons */ --radius-sm: 4px; --radius-md: 8px; --radius-lg: 12px; --radius-pill: 999px; /* Ombres */ --shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.04); --shadow-md: 0 4px 12px rgba(15, 23, 42, 0.08); --shadow-lg: 0 12px 24px rgba(15, 23, 42, 0.12); /* Typo (charte TEEO) */ --font-sans: "Inter Tight", "Inter", "Roboto", "Segoe UI", system-ui, -apple-system, sans-serif; --font-mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace; --fs-11: 11px; --fs-12: 12px; --fs-14: 14px; --fs-16: 16px; --fs-18: 18px; --fs-20: 20px; --fs-24: 24px; --fs-30: 30px; } ``` **Règle absolue** : aucun composant Keros ne doit utiliser de valeur en dur. Toujours `var(--token-name)`. --- ## 5. Composants Convention : nom du composant + classe CSS principale (préfixe `.k-`). Pour chaque composant : rôle, variantes, états, règles d'usage, erreurs à éviter, exemple HTML minimal. ### 5.1 Button — `.k-btn` - **Rôle** : déclencher une action. - **Variantes** : `primary` (par défaut), `secondary`, `ghost`, `danger`. - **Tailles** : `sm` (28 px), `md` (36 px, défaut), `lg` (44 px). - **États** : default, hover, active, focus, disabled, loading. - **Règles** : 1 seul bouton primaire par groupe d'actions. `danger` réservé aux actions destructives. `ghost` pour les actions secondaires dans les listes. - **Erreurs à éviter** : 3 boutons primaires côte à côte ; bouton primaire pour une action destructive ; pas de focus visible. ```html ``` ### 5.2 Input — `.k-input` / `.k-field` - **Rôle** : capturer une valeur texte / numérique / email. - **Variantes** : standard, avec icône (`.k-input-icon`), en erreur (`.k-input--error`). - **États** : default, focus, disabled, error. - **Règles** : toujours un label visible OU `aria-label`. Hint optionnel sous le champ. Erreur en rouge avec texte explicite. - **Erreurs à éviter** : placeholder utilisé comme label ; champ requis sans indication ; message d'erreur uniquement en couleur. ```html
Format PREFIX-NNNNN
``` ### 5.3 Select — `.k-select` - **Rôle** : choisir une valeur dans une liste fermée. - **Règles** : préférer un Select natif pour la simplicité ; passer à un combobox custom uniquement si recherche / multi-sélection requise. ### 5.4 DateRangePicker — `.k-daterange` - **Rôle** : sélectionner une plage de dates. - **Variantes** : avec presets (24h / 7j / 30j / 90j) ou personnalisée. - **Règles** : la plage par défaut dépend de l'écran ; toujours présent sur les pages d'analyse temporelle. ### 5.5 SearchBar & FilterBar — `.k-filterbar` - **Rôle** : restreindre l'ensemble visible (tableau, liste). - **Composition** : champ recherche + chips de filtres + bouton "Réinitialiser". - **Règles** : la `FilterBar` est sticky en haut du tableau lors du scroll ; "filtres actifs" mis en évidence (classe `.is-active`). - **Erreurs à éviter** : filtres éparpillés dans plusieurs zones ; pas de feedback "X filtres actifs" ; reset caché. ### 5.6 MetricCard / KPIGrid — `.k-metric` - **Rôle** : afficher un chiffre clé avec contexte. - **Composition** : label + valeur + delta (avec direction) + sparkline optionnelle. - **Variantes** : avec / sans sparkline, avec / sans delta. - **Règles** : 3-4 KPI maximum par ligne. Toujours indiquer la période de comparaison. Delta = couleur + flèche (jamais couleur seule). - **Erreurs à éviter** : 7 KPI alignés (illisible) ; valeur sans unité ; variation sans baseline. ### 5.7 AnomalyCard — `.k-anomaly` - **Rôle** : présenter une anomalie de manière dense et actionnable. - **Variantes** : par sévérité (`--low`, `--medium`, `--high`, `--critical`) — change la couleur de la bordure gauche. - **Composition** : titre + métadonnées + badges + actions + mini-chart optionnel. - **Règles** : la sévérité change la bordure gauche (4 px) ; les actions sont à portée directe. - **Erreurs à éviter** : changement de fond entier selon la sévérité (trop bruyant) ; sévérité indiquée uniquement par la couleur. ### 5.8 DataTable — `.k-table` - **Rôle** : afficher des collections d'objets métier (compteurs, anomalies, commentaires). - **Variantes** : default (40 px de ligne), `.k-table--compact` (32 px). - **Capacités** : tri colonne (`data-sortable`), filtre temps réel (`data-table-filter`), sélection de ligne. - **Règles** : entêtes 12 px / 600 / uppercase ; séparateur 1 px ; hover surface-alt ; valeurs numériques en `tabular-nums`. - **Erreurs à éviter** : actions cachées sans indication ; pas de tri visible sur colonnes triables ; rayé alterné qui réduit la lisibilité. ### 5.9 ChartCard — `.k-card` + charts SVG - **Rôle** : afficher un graphique avec son titre et son contexte. - **Composition** : header (titre + hint période/unité) + zone SVG + légende. - **Règles** : axe Y commence à 0 sauf cas justifié ; grille horizontale légère ; tooltip au survol ; couleurs catégorielles stables (`--chart-1` à `--chart-6`). ### 5.10 Histogram, LineChart, DonutChart - Voir section 7 (Data visualization) pour les règles détaillées. ### 5.11 StatusBadge — `.k-badge` - **Rôle** : indiquer le statut d'un objet (anomalie, service). - **Variantes** : `--success`, `--warning`, `--danger`, `--info`, `--neutral`. - **Sémantique fixe** : - `nouvelle` → `--danger` - `en cours` → `--warning` - `confirmée` → `--success` - `requalifiée` → `--info` - `ignorée` → `--neutral` - `résolue` → `--neutral` ### 5.12 SeverityBadge — `.k-sev` - **Rôle** : indiquer la sévérité d'une anomalie. - **Variantes** : `--low`, `--medium`, `--high`, `--critical`. - **Règle** : à utiliser systématiquement à côté du statut, jamais en remplacement. ### 5.13 Toast — `.k-toast` - **Rôle** : feedback éphémère après une action. - **Variantes** : success / warning / danger / neutre. - **Durée** : 2,4 s (configurable). - **Position** : bas-droite, empilement vertical. - **Règles** : message court et clair (action passée, pas instruction future). Pas plus de 3 toasts visibles simultanément. ### 5.14 Modal — `.k-modal` - **Rôle** : confirmer une action critique ou collecter une saisie courte. - **Composition** : head (titre + close) + body + foot (annuler / confirmer). - **Largeur** : 480 px par défaut, 640 px si formulaire. - **Fermeture** : bouton fermer + clic backdrop + touche Échap. - **Erreurs à éviter** : modal en cascade (modal dans modal) ; formulaire long (utiliser une page). ### 5.15 Drawer — `.k-drawer` - **Rôle** : afficher le détail d'un objet (anomalie, compteur, événement) sans quitter le contexte. - **Largeur** : 480 px (`md`) ou 640 px (`lg`). - **Position** : droite ; animation slide. - **Composition** : head + body scrollable + foot d'actions. - **Règles** : préférer un drawer à une nouvelle page quand l'objet est consulté brièvement ; utiliser une page dédiée si l'utilisateur travaille longtemps dessus. ### 5.16 CommentPanel — `.k-comment-list` - **Rôle** : fil chronologique de commentaires métier rattachés à un objet (anomalie, compteur). - **Composition** : avatar + nom + horodatage + texte ; champ d'ajout en bas. - **Règles** : tri chronologique antéchronologique par défaut ; mentions @user en V2 ; pas de markdown lourd. ### 5.17 Timeline — `.k-timeline` - **Rôle** : historique d'événements d'un objet. - **Composition** : dot coloré selon le type + horodatage + titre + détail. - **Règles** : types prédéfinis (détection, commentaire, changement de statut) → couleur cohérente. ### 5.18 EmptyState — `.k-state` - **Rôle** : informer qu'aucune donnée n'est disponible avec une action de sortie. - **Composition** : icône neutre + titre + message + bouton "Réinitialiser les filtres" ou équivalent. - **Erreurs à éviter** : "Aucun résultat" sans action ; texte technique ("0 rows returned"). ### 5.19 ErrorState — `.k-state` (variante danger) - **Rôle** : signaler un échec sans bloquer l'utilisateur. - **Composition** : icône erreur + titre métier ("Impossible de charger") + message + "Réessayer" + détail technique replié. - **Règles** : pas de stack trace visible directement ; lien "Voir le détail technique" optionnel. ### 5.20 LoadingState — `.k-state` (variante loading) - **Rôle** : occuper l'écran pendant un chargement. - **Composition** : skeleton lignes pour les tableaux, skeleton card pour les KPI, spinner ponctuel pour les actions courtes. - **Règles** : skeleton préférable au spinner global ; durée minimale visible 300 ms (éviter le clignotement). ### 5.21 AppShell — `.k-app` - **Rôle** : conteneur global de l'application Keros. - **Composition** : topbar (logo, tenant, env, user) + sidenav (groupes de modules) + content. - **Règles** : largeur sidenav 240 px ; topbar 56 px sticky ; sidenav peut se collapser en V2. ### 5.22 MicroFrontendFrame — `.k-mfframe` - **Rôle** : enveloppe pour embarquer un micro-frontend Keros dans AMCO (ou inversement). - **Composition** : head (nom du module + version + contexte) + content (iFrame). - **Capacités** : injection du JWT, du `tenant_id`, du thème via `postMessage` ; hauteur dynamique. - **Règles** : header visuel léger pour permettre l'identification du module embarqué ; préfixe CSS `.k-` strict pour éviter les collisions. ### 5.23 KerosAIPanel — `.k-keros-panel` (volet IA d'AMCO) > **Concept clé** : Keros est **l'IA d'AMCO**. Elle ne remplace aucun module ; elle s'ajoute en surcouche permanente, accessible depuis n'importe quelle page via le badge flottant. Le volet conserve l'utilisateur dans son contexte métier en cours. - **Rôle** : permettre à un utilisateur de poser une question en langage naturel à l'IA de la plateforme, lire un statut temps réel et voir les analyses en cours. - **Dimensions** : 380 px de large × hauteur fluide (max 100vh − 120 px). Position : `fixed bottom: 96px ; right: 24px`. - **Composition (5 zones verticales)** : 1. **Header** dégradé Bleu TEEO `#157AB3` → Indigo Profond `#485194` : monogramme TEEO + titre "KEROS" en lettres capitales + sous-titre "L'IA d'AMCO" + actions réduire/fermer. 2. **Scénarios d'exemple** : 4 boutons de raccourcis contextuels (Alerte énergie, Maintenance, Audit, Incident). Premier scénario actif par défaut selon le contexte d'ouverture. 3. **Statut temps réel** : carte grise claire avec 3 indicateurs ligne par ligne (consommation actuelle, anomalies actives, équipements). Les compteurs d'anomalies utilisent un pill coloré (rouge alerte si > 0). 4. **Analyse temps réel** : pile de cartes d'alertes (orange = vigilance, rouge = anomalie). Texte court (1-2 lignes), action implicite. 5. **Footer** : input pill "Posez une question…" + bouton envoyer rond Bleu TEEO. - **Variantes** : ouvert / réduit (header seul, 56 px) / fermé. - **États** : default, loading (skeleton dans le body), offline (bandeau d'erreur sobre). - **Ouverture** : clic sur le badge flottant ; raccourci clavier `K` ou `Ctrl+K` (V1). - **Fermeture** : croix dans le header ; clic backdrop ; touche Échap. - **Règles d'usage** : - Le volet ne masque jamais tout le contenu : il s'ouvre en flotteur à droite. - Il **conserve le contexte** : la page courante (compteur, secteur, période) est passée à Keros à l'ouverture. - Maximum 4 scénarios visibles ; les autres sont accessibles via "Plus de scénarios" en V2. - Les alertes affichées sont **les plus récentes** sur le périmètre actuel (5 max). - **Erreurs à éviter** : - Volet plein écran (perd l'avantage du contexte). - Conversation infinie sans actions (Keros est un copilote action-orienté). - Couleurs hors charte TEEO ; effets 3D ou flottants marketing. ```html ``` ### 5.24 KerosFloatingBadge — `.k-keros-launcher` (lanceur) - **Rôle** : point d'entrée unique et permanent vers Keros, présent sur toutes les pages AMCO / Keros (sauf authentification). - **Apparence** : cercle 60×60 px, fond blanc, monogramme Keros centré (inspiré du logo TEEO — voir `assets/keros-icon.svg`), ombre douce, pulse subtile pour signaler que l'IA est active. - **Position** : `fixed bottom: 24px ; right: 24px` (16 px en mobile). - **Pastille de notification** : point orange `#E9A547` en haut-droite si Keros a une recommandation ou une alerte à signaler. - **États** : default, hover (légère surélévation), focus (anneau primary 4 px), notification (avec pastille), inactif (grisé si service IA down). - **Accessibilité** : `aria-label="Ouvrir Keros — l'IA d'AMCO"` ; focusable Tab. - **Erreurs à éviter** : - Badge "promotionnel" trop saillant qui détourne l'attention. - Plusieurs badges flottants concurrents. - Remplacer le monogramme par une autre icône — c'est le marqueur d'identité Keros / TEEO. ```html ``` ### 5.25 Icône Keros — `assets/keros-icon.svg` - **Rôle** : marqueur visuel d'identité de l'IA d'AMCO. C'est une **déclinaison sobre du monogramme TEEO** (plaque arrondie + boucle bicolore Bleu + Orange), augmentée d'un petit point bleu rappelant "IA active". - **Format** : SVG 64×64, scalable. - **Couleurs strictement TEEO** : plaque gris clair `#DEDFDF`, boucle dégradé `#E14929 → #E9A547 → #157AB3`, accent `#157AB3`. - **Règles** : - Ne jamais déformer. - Ne pas appliquer d'ombre portée. - Sur fond coloré, conserver une zone blanche de protection (au minimum la hauteur de l'élément 'e' du logo TEEO). - Ne pas remplacer par un robot 3D, un chatbot stéréotypé, ni une émoji. --- ## 6. Patterns métier ### 6.1 Listing compteurs - **Layout** : breadcrumb + titre + actions + FilterBar + DataTable. - **Colonnes recommandées** : ID, Type (Eau/Énergie), Secteur, Statut, Dernière relève, Anomalies ouvertes, actions. - **Filtres** : recherche texte, type, secteur, statut. ### 6.2 Synthèse compteur - **Layout** : breadcrumb + en-tête compteur (ID, type, statut, secteur) + Tabs (Vue d'ensemble / Mesures / Anomalies / Commentaires). - **Vue d'ensemble** : 3 MetricCard (conso 7j, moyenne mobile, anomalies 30j) + LineChart. - **Anomalies** : tableau dense ou cartes. ### 6.3 Synthèse secteur - **Layout** : breadcrumb + en-tête secteur + Tabs. - **Indicateurs** : nombre de compteurs, conso totale, anomalies ouvertes. ### 6.4 Dashboard anomalies - **Layout** : titre + actions (Exporter, DateRange) + KPIGrid (4 KPI) + 2 colonnes (Tableau anomalies récentes / Donut par sévérité). - **KPI clés** : Ouvertes, Critiques, Faux positifs (30j), Délai qualification. ### 6.5 Détail d'anomalie - **Layout 2 colonnes** : - colonne principale : LineChart avec overlay + CommentPanel ; - colonne latérale : contexte (compteur, secteur, score, modèle) + Timeline. - **Actions** : Ignorer / Requalifier / Confirmer en haut à droite. ### 6.6 Qualification / requalification - **Mécanique** : Modal avec motif obligatoire, action journalisée, statut mis à jour, Toast de confirmation. ### 6.7 Commentaires (sur anomalie ou compteur) - **Composition** : CommentPanel + champ d'ajout. ### 6.8 Statut API - **Composition** : 3 MetricCard (ingestion, latence p95, erreurs 24h) + DataTable services. - **Colonnes** : Service, Statut (badge), Version, Dernière ingestion, Erreurs 24h. ### 6.9 Intégration iFrame AMCO - **Composition** : MicroFrontendFrame avec header identifiant le module Keros + zone iFrame. - **Communication** : `postMessage` typé (handshake d'authentification, hauteur dynamique, thème). ### 6.10 Conversation Keros (IA d'AMCO) - **Point d'entrée** : badge flottant en bas à droite (`.k-keros-launcher`) présent sur toutes les pages. - **Ouverture** : volet 380 px qui apparaît en bas à droite avec animation `transform/opacity` (220 ms). - **Contexte transmis** : page d'origine, compteur / secteur courant, période active, tenant. - **Scénarios par défaut** : - *Alerte énergie* — détection / qualification d'une dérive. - *Maintenance* — préparation d'intervention. - *Audit* — synthèse pour un comité ou un client. - *Incident* — gestion d'événement en cours. - **Statut temps réel** affiché dès l'ouverture : 3 indicateurs (consommation, anomalies, équipements). - **Cycle de vie** : conversation persistée par utilisateur + tenant ; historique consultable en V2. - **Sortie** : actions concrètes proposées en fin de conversation (créer un commentaire, requalifier une anomalie, exporter une synthèse). ### 6.11 Navigation portail AMCO ↔ micro-service Keros - **Principe** : depuis AMCO, lien vers le module Keros ouvre dans le même contexte (iFrame ou page dédiée). - **Breadcrumb** : reflète le double-niveau (AMCO > Anomalies > ANO-00478). --- ## 7. Data visualization ### 7.1 Histogrammes - Barres pleines, espacement 30 %. - Couleur unique par série (`--chart-1` par défaut). - Axe Y commence à 0. - Étiquettes courtes (initiales jours, dates compactes). ### 7.2 Courbes temporelles - Trait 1.8-2 px, couleur `--chart-1`. - Pas de marqueurs systématiques (sauf points d'intérêt). - Grille horizontale légère (`--chart-grid`). - Périodes d'anomalies en overlay (fond rouge léger + markers). ### 7.3 Camemberts / Donuts - Donut préféré au camembert plein (centre permet d'afficher le total). - Maximum 6 segments visibles ; au-delà, agréger en "Autres". - Légende à droite avec valeurs et pourcentages. ### 7.4 Jauges - Forme demi-cercle (160°-200° d'arc). - Couleur fonctionnelle adaptée (vert / orange / rouge selon seuil métier). - Valeur centrale + unité. ### 7.5 Heatmaps - Échelle de couleur monochromatique (par exemple opacité d'un même rouge). - Toujours associer une légende d'échelle. - Préférer 7×24 (semaine × heures) pour les profils journaliers. ### 7.6 Sparklines - Hauteur 30-40 px. - Sans axe ni grille. - Couleur cohérente avec le KPI (vert si tendance positive, rouge si négative). ### 7.7 Couleurs des anomalies - Marker / overlay : `--color-danger` (`#DC2626`). - Overlay opacité : 0.6 sur fond `--color-danger-bg`. ### 7.8 Couleurs des périodes normales - Trait : `--chart-1` (bleu). - Aucun overlay. ### 7.9 Tooltips - Fond `--color-text` (sombre), texte blanc. - Format : valeur + unité + date. - Apparition au survol, suit le curseur. ### 7.10 Légendes - Position : sous le graphique ou à droite selon la place. - Carrés colorés 10×10 px + libellé + valeur optionnelle. ### 7.11 Axes & unités - Toujours indiquer l'unité (m³, kWh, °C, %, j). - Format date local FR : `JJ/MM` ou `JJ/MM hh:mm`. - Arrondis raisonnables : valeurs > 1 000 → entiers ; entre 1 et 1 000 → 1 décimale ; < 1 → 2 décimales. ### 7.12 Données manquantes - Pas d'interpolation silencieuse. - Trou visible dans la courbe (pas de point relié). - Mention "données manquantes" dans le tooltip / légende si pertinent. --- ## 8. Accessibilité - **Contrastes** : WCAG AA (4.5:1 sur texte normal, 3:1 sur texte large et icônes informatives). - **Focus visible** : tous les éléments interactifs exposent `--focus-ring`. Jamais désactivé sans alternative équivalente. - **Navigation clavier** : Tab cycle dans l'ordre logique ; Échap ferme drawer et modal ; flèches pour les menus. - **Cibles cliquables** : hauteur minimum 28 px (sm), recommandée 36 px+ ; sur mobile, viser 44 px. - **Labels** : tout champ a un `label` visible ou un `aria-label`. - **Aria** : `aria-modal="true"` sur modales et drawers ; `role="dialog"` ; `aria-sort` sur colonnes triées. - **Tableaux** : usage de `` pour les entêtes ; `scope="col"` recommandé. - **Couleur seule** : tout état est exprimé en couleur + libellé + (idéalement) icône. - **Skip link** : "Aller au contenu principal" à prévoir en V1. - **Reduced motion** : respecter `prefers-reduced-motion` (désactiver les transitions au-delà de 100 ms). --- ## 9. Responsive | Breakpoint | Comportement | |---|---| | ≥ 1280 px | Layout cible : sidenav 240 px + content fluide | | 1024-1280 px | Layout maintenu ; grilles passent de 4 col à 3 col | | 768-1024 px | Tablette ; sidenav collapsable ; grilles 2 col | | < 768 px | Sidenav cachée derrière un menu ; tableaux passent en mode "cards stack" ; drawer plein écran | - **Desktop prioritaire** : AMCO est essentiellement utilisé sur poste. - **Tablette** : usage terrain ; à supporter en V1 sans optimisation poussée. - **Mobile** : marginal ; cible V2/V3. - **Tableaux** : sur mobile, transformation en cartes verticales (1 ligne = 1 carte). - **Graphiques** : largeur fluide, hauteur 180-220 px ; sur mobile, simplification de la légende. - **Drawer** : plein écran sous 768 px. - **Filtres** : sur mobile, regroupés dans un drawer "Filtres". --- ## 10. Intégration technique ### 10.1 Micro-frontend & iFrame - Composants Keros encapsulables ; préfixe CSS `.k-` strict. - Communication parent-iFrame via `postMessage` typés. - Handshake initial : JWT, `tenant_id`, locale, thème. - Hauteur dynamique reportée au parent. ### 10.2 Authentification & tenant - JWT centralisé (Keycloak ou propriétaire). - Multi-tenant **filtré backend systématiquement**. Le front ne décide jamais seul du périmètre. - Le sélecteur de tenant est affiché en topbar quand l'utilisateur a plusieurs périmètres. ### 10.3 API REST & OpenAPI - Routes versionnées (`/api/v1/...`). - Documentation OpenAPI maintenue à jour, accessible par les développeurs front. - Erreurs structurées (`code`, `message`, `details`) pour permettre un rendu propre dans `ErrorState`. ### 10.4 Stack front - Cible long terme : **React/Vite** ou **Vue** (à arbitrer projet par projet). - Tokens et composants HTML/CSS du design system restent **framework-agnostiques**. - Recommandation : packager le design system en library partagée (`@keros/ui`). ### 10.5 Séparation front/back - Pas de logique métier dans le front au-delà de la présentation. - Pas de duplication du filtrage multi-tenant côté front. - Le front consomme les API et expose un rendu cohérent. ### 10.6 Compatibilité progressive avec AMCO - Les modules Keros doivent pouvoir cohabiter avec AMCO sans casser de styles globaux. - Préfixage CSS strict, scope JavaScript (pas de variables globales hors `window.KEROS_*`). - Charte couleur compatible avec AMCO existant (pas de rupture visuelle). --- ## 11. Règles pour agents IA Cette section s'adresse à Claude, Codex, ChatGPT Agent et tout agent IA travaillant sur Keros. 1. **Toujours lire `design.md` avant toute modification UI.** Ne pas faire d'hypothèse sur les tokens ou composants sans relire la référence. 2. **Ne pas inventer une nouvelle charte.** Toute nouvelle couleur, taille ou composant non documenté doit faire l'objet d'une proposition explicite et d'une demande de validation. 3. **Réutiliser les tokens.** Aucun composant Keros ne doit utiliser de valeur hex ou pixel en dur. Toujours `var(--token-name)`. 4. **Réutiliser les composants existants.** Avant d'écrire un nouveau composant, vérifier qu'aucun composant existant ne couvre le besoin (même partiellement). 5. **Documenter toute nouvelle variante.** Une nouvelle variante de composant doit être ajoutée dans `design.md` + `components.css` + une démo dans `components.html` + une entrée changelog. 6. **Garder la cohérence AMCO/Keros.** Ne pas dériver vers une esthétique étrangère au contexte métier énergie/eau. 7. **Préserver la progressivité.** Ne pas proposer de refonte radicale d'un écran AMCO existant sans validation explicite. 8. **Créer un changelog en cas d'évolution.** Toute évolution structurante du design system fait l'objet d'une entrée datée (voir section 12 et `CHANGELOG.md` à créer). 9. **Signaler les écarts au design system.** Si une contrainte oblige à dévier du design system (cas particulier, dépendance externe), le mentionner explicitement et proposer une régularisation à terme. 10. **Respecter le multi-tenant.** Le filtrage par `tenant_id` ne se fait jamais côté front uniquement. 11. **Respecter la confidentialité.** Aucune donnée client réelle dans les exemples / démos / commentaires de code. 12. **Vérifier l'accessibilité.** Tout nouveau composant doit passer les règles de la section 8 (contraste, focus, labels, navigation clavier). --- ## 12. Roadmap design system ### V0 — Artboard + tokens (présente livraison, mai 2026) - Audit AMCO (`01_audit_amco/`). - Artboard HTML "façon Figma" (`02_artboard_keros/`). - Design system HTML interactif (`03_design_system_html/`). - Tokens CSS centralisés. - `design.md` exhaustif. ### V1 — Composants essentiels (T3 2026, en parallèle du module Détection d'anomalies) - Portage en bibliothèque React/Vite ou Vue (selon choix d'AMCO Avancé). - Tests d'accessibilité automatisés. - Documentation Storybook ou équivalent. - Composants couverts : tous ceux de la V0. ### V2 — Patterns métier (T4 2026) - Templates de page complets (dashboard, listing, détail, synthèse). - Composants enrichis : CommentPanel avancé (mentions), Drawer multi-step, Toast en file, DateRangePicker complet. - Variantes thème (préparation mode sombre). ### V3 — Intégration front réelle (T1 2027) - Premier module Keros intégré dans AMCO en production. - Boucles de feedback utilisateurs en place (mesure d'adoption, retours). - Optimisation perf (lazy load, virtualisation tableaux). ### V4 — Documentation complète et gouvernance (T2 2027) - Process de contribution au design system (RFC + revue design + tests). - Versioning SemVer du package `@keros/ui`. - Synchronisation officielle avec la roadmap AMCO. - Mode sombre stable. - Responsive mobile traité. --- ## 13. Changelog | Version | Date | Auteur | Changements | |---|---|---|---| | 0.2.0 | 2026-05-21 | Reynholds + Claude | Alignement charte TEEO 2025 (Bleu `#157AB3`, Indigo `#485194`, Orange `#E9A547`, Rouge alerte `#E14929`, Gris clair `#DEDFDF`). Ajout des composants `KerosAIPanel` (§5.23), `KerosFloatingBadge` (§5.24), icône Keros (§5.25). Ajout du pattern métier "Conversation Keros" (§6.10). Nouvelle page de démo `03_design_system_html/keros-ai.html`. | | 0.1.0 | 2026-05-21 | Reynholds + Claude | Initialisation du design system Keros V0 : audit, artboard, design system HTML, design.md. | > Toute évolution structurante (nouveau composant, nouveau token, changement de règle) doit faire l'objet d'une ligne ici. --- ## 14. Références - `01_audit_amco/audit_amco.md` — contexte AMCO, Keros, AMCO Avancé. - `01_audit_amco/visual_inventory.md` — inventaire visuel existant → recommandation. - `01_audit_amco/ux_observations.md` — observations UX et risques. - `01_audit_amco/functional_map.md` — carte fonctionnelle orientée design. - `02_artboard_keros/artboard.html` — artboard visuel autonome. - `03_design_system_html/index.html` — design system HTML interactif. - `03_design_system_html/css/tokens.css` — tokens CSS (source de vérité).