sokko-g/DESIGN_SYSTEM.md

Design System - Sokko G

Ce document est la reference visuelle du projet Sokko G. Toute nouvelle interface doit rester coherente avec le theme Nebula Command actuel.

1. Vision

Sokko G est une webapp gaming locale, pensee pour rester ouverte sur un second ecran pendant une session. L'interface doit etre sombre, lisible, dense sans etre surchargee, et suffisamment immersive pour evoquer une ambiance nebuleuse premium.

Principes directeurs :

• priorite a la lisibilite pendant de longues sessions ;
• pas de style RGB agressif ;
• violet et indigo pour la profondeur et les interactions ;
• dore pour les accents de hierarchie, les eyebrows, les focus et certaines bordures ;
• cyan conserve comme token secondaire, mais non dominant ;
• les effets lumineux doivent rester contenus.

2. Tokens

Les tokens source sont dans website/src/styles/_tokens.scss. Ne pas dupliquer les couleurs dans les composants.

Couleurs principales :

--color-bg-page: #070913;
--color-bg-deep: #050711;
--color-bg-sidebar: #0b0e1b;
--color-bg-surface: #101426;
--color-bg-surface-alt: #151a30;
--color-bg-elevated: #1a2038;
--color-bg-hover: #202745;

--color-primary: #8b5cf6;
--color-primary-hover: #9f7aea;
--color-primary-active: #7347dc;
--color-primary-soft: rgba(139, 92, 246, 0.14);
--color-primary-border: rgba(139, 92, 246, 0.45);

--color-accent-gold: #f6c453;
--color-accent-cyan: #22d3ee;
--color-accent-pink: #d946ef;
--color-accent-indigo: #6366f1;

--color-text-primary: #f5f7ff;
--color-text-secondary: #b4bdd3;
--color-text-muted: #7d879f;

--color-border: rgba(150, 165, 205, 0.14);
--color-border-hover: rgba(150, 165, 205, 0.28);

Rayons :

• --radius-sm: 6px
• --radius-md: 10px
• --radius-lg: 14px
• --radius-xl: 18px
• --radius-pill: 999px

Animations :

• --duration-fast: 120ms
• --duration-normal: 180ms
• --ease-standard: cubic-bezier(0.2, 0.8, 0.2, 1)

3. Fond Nebula

Le fond global est defini dans website/src/styles/_nebula.scss.

Regles :

• fond de page tres sombre avec nebuleuses violettes, indigo, rose et leger accent dore ;
• etoiles statiques, reparties de facon non alignee ;
• pas d'animation permanente de fond ;
• le contenu reste prioritaire sur l'ambiance.

Ne pas ajouter d'orbes decoratifs supplementaires. Si une section a besoin de profondeur, utiliser les fonds semi-transparents et les bordures existantes.

4. Typographie

Police principale :

font-family: Inter, "Segoe UI", system-ui, -apple-system, BlinkMacSystemFont, sans-serif;

Regles :

• pas de letter-spacing negatif ;
• corps de texte entre 14 et 16 px ;
• titres de cartes/modules entre 15 et 18 px ;
• titres de page avec clamp deja defini dans _home.scss ;
• paragraphs limites visuellement, pas de longs blocs sans respiration ;
• les <i> doivent etre en italique, pas utilises comme gris decoratif.

5. Heroes

Les heroes de la page d'accueil et des pages jeux utilisent le meme style via .hero et .game-hero.

Caracteristiques :

• fond commun nebula sombre ;
• overlay sombre pour garder le texte lisible ;
• bordure gradient subtile dore/violet clair ;
• border-radius: var(--radius-xl) ;
• box-shadow: var(--shadow-md) ;
• pas de background inline sur les heroes de jeux.

Les pages jeux doivent heriter du hero commun. Si un jeu a une image, elle doit etre utilisee dans les cards ou les covers, pas comme remplacement complet du hero commun sauf decision explicite.

6. Cards

Les cards representent les elements repetes : toolboxes, jeux, categories, monstres, faune.

Style courant :

• fond sombre rgba(16, 20, 38, 0.88) ;
• bordure gradient fine, majoritairement doree avec une petite presence cyan ;
• support optionnel de corner-shape: scoop quand le navigateur le supporte ;
• pas de translation au hover pour les cards principales ;
• hover en violet/violet clair avec glow contenu.

La bordure haute/basse interne d'une cover doit rester doree quand elle separe une image du contenu.

Eviter les cards dans des cards. Les sections de page doivent rester des layouts ou panneaux, pas des empilements de cartes decoratives.

7. Modules Toolbox

Les modules sont des panneaux de travail, pas des cards classiques.

Style courant :

• fond semi-transparent rgba(16, 20, 38, 0.42) ;
• bordure neutre tres discrete ;
• accent dore leger en bas/droite ;
• hover violet/violet clair moins intense que les cards ;
• pas de mouvement au hover ;
• contenu interne au-dessus des pseudo-bordures via z-index.

Le mot visible cote utilisateur est outil, pas module. Le terme module reste acceptable uniquement dans le code.

Outils En Deux Colonnes

Les outils avec controles a gauche et resultats a droite doivent reutiliser les classes generiques tool-split-*.

Exemples actuels :

• calculateur ;
• timer.

Regles :

• ratio de base 35 / 65 entre controles et resultats ;
• panneau gauche compact, sans hauteur artificielle inutile ;
• panneau droit scrollable uniquement quand l'utilisateur active le switch dedie ;
• hauteur scrollable cible : environ 450 px ;
• boutons reset, copie, scroll et tri alignes en haut a droite du panneau de resultats ;
• edition inline des libelles plutot que boutons ou alertes navigateur ;
• styles specifiques autorises uniquement pour la logique propre a l'outil.

Timer

Le timer combine chronometre a etapes et comptes a rebours multiples.

Regles UI :

• tabs compactes avec icones uniquement et tooltips ;
• chronometre avec centiemes visibles en plus petit dans le timer principal ;
• les temps sauvegardes gardent une taille uniforme ;
• compte a rebours sans centiemes ;
• types visibles : Duree, Heure precise, Pattern horaire, Intervalle ;
• les libelles au-dessus des champs hh:mm:ss restent accessibles en sr-only, mais ne sont pas visibles ;
• les boutons de controle utilisent les icones play-circle, pause-circle, record-circle, stop-circle, refresh, sort-time, scrollable.

Alertes timer :

• switch a 3 etats par compte a rebours : aucune alerte, alerte si la toolbox est visible, alerte globale site ;
• le garde-fou ne se base pas sur le temps restant, mais sur la frequence configuree ;
• le garde-fou bloque uniquement les comptes a rebours recurrents (Pattern horaire, Intervalle) si la repetition est inferieure a 5 minutes ;
• un Pattern horaire comme X:24:X cible hh:24:00 et se repete toutes les heures.

Bloc Notes Riche

Le bloc notes utilise une edition directe en contentEditable, sans mode preview separe.

Regles UI :

• toolbar compacte en haut de l'outil ;
• boutons courts pour gras, italique, souligne, barre, titre et listes ;
• le paragraphe est le style par defaut et n'a pas de bouton dedie ;
• les types de listes sont regroupes dans un dropdown compact ;
• couleurs texte et surlignage regroupees dans un dropdown unique avec icone arc-en-ciel et libelles de categories ;
• date de derniere modification affichee en pied d'outil, sans prendre le dessus sur le contenu ;
• switch de stockage des dessins en pied d'outil, avec icone sauvegarde et etat actif ;
• placeholder integre dans la surface d'edition quand la note est vide ;
• le HTML persiste doit rester nettoye via allowlist, jamais via HTML libre.

Calque De Dessin

Les annotations dessinees utilisent un canvas transparent superpose au contenu annote.

Regles UI :

• le calque est inactif par defaut pour laisser le contenu editable ;
• en mode dessin, les interactions pointer sont capturees par le canvas ;
• les controles de dessin sont regroupes dans un panneau reutilisable vertical, colle a droite de la surface annotee ;
• seuls les controles directement lies au dessin sont affiches quand le mode dessin est actif ;
• les controles restent compacts : gommer, annuler, effacer, couleur et epaisseur via dropdowns ;
• le mode temporaire privilegie le griffonnage de session et utilise sessionStorage ;
• le mode permanent suit le stockage IndexedDB de l'outil ;
• pour les surfaces scrollables, le canvas suit le contenu complet plutot que le viewport visible.
• sur les annotations d'images, les traits utilisent des coordonnees en pourcentage et restent visibles dans l'aperçu reduit ; l'edition se fait uniquement en plein ecran et le switch de sauvegarde reste disponible dans la barre de dessin.

8. Tabs Et Switchs

Dropdowns Compacts

Les menus flottants compacts d'icones, couleurs, epaisseurs ou actions rapides doivent reutiliser CompactDropdown.

Regles :

• conserver un trigger compact, idealement icone seule avec tooltip ;
• fermer au clic exterieur, a Escape, a la selection et quand le focus sort du menu ;
• garder le contenu interne libre pour supporter grilles d'icones, swatches, libelles de categories ou choix d'epaisseur ;
• reutiliser les classes visuelles existantes du contexte quand le menu appartient a un outil precis.

Tabs :

• utiliser le composant commun quand un outil doit alterner entre plusieurs modes ;
• icones seules quand les labels sont evidents ou fournis en tooltip ;
• etat actif sobre : bordure doree, fond legerement dore/violet, pas de gros glow.

Switchs :

• les switchs binaires utilisent l'icone a gauche et le rail a droite quand ils controlent un mode technique comme scrollable ;
• les switchs a plusieurs etats doivent rester compacts, avec icones et tooltips ;
• les etats desactives doivent etre clairement attenues et sans etat actif dore.

9. Panneaux De Section

Les grandes sections non repetitives, comme le dialogue d'origine et les sections de presentation, utilisent .nebula-panel.

Style courant :

• fond semi-transparent rgba(16, 20, 38, 0.42) ;
• bordure statique identique aux outils en etat normal ;
• accent dore leger en bas/droite ;
• pas de hover sur les panneaux de lecture ;
• implementation via le mixin gold-panel-frame dans website/src/styles/_mixins.scss.

10. Boutons

Primary

Les boutons primary sont plus contrastes que les boutons standards.

Style :

• fond violet/indigo sombre ;
• bordure doree ;
• hover plus lumineux avec bordure doree plus nette ;
• glow violet/dore contenu ;
• pas de brightness() global ;
• pas de translation verticale.

Boutons standards

Hover :

• fond nebula plus lumineux ;
• bordure violet clair ;
• glow violet tres discret ;
• pas d'accent dore systematique.

Boutons Toggle Temporaires

Les boutons qui ouvrent temporairement un panneau, un menu ou un mode local ne doivent pas utiliser le style switch.

Etat actif :

• bordure gradient dore/violet plus visible que le hover ;
• fond sombre avec degrade transparent/dore tres leger et touche violette en bas a droite, sans remplissage primary ;
• texte ou icone clair pour préserver la lisibilite ;
• trait interne dore discret pour distinguer l'etat actif des badges et actions primary ;
• bordure dore/dore clair statique, sans effet toast ;
• pas de glow externe fort ni animation permanente ;
• utiliser le mixin temporary-toggle-active pour garder les variantes coherentes.

Ghost

Hover minimal :

• leger fond violet transparent ;
• texte plus clair ;
• pas de glow.

Danger

Reserve aux actions destructrices.

• couleur rouge au repos ;
• hover rouge sombre, bordure rouge, texte/icones blancs ;
• confirmation en modale pour les actions irreversibles.

Boutons icones

Les icones utilisent currentColor via .ui-icon.

• taille habituelle : 20 px ;
• bouton : 40 x 40 px ;
• hover neutre : icone violet clair #c4b5fd + leger glow ;
• hover danger : icone blanche + glow rouge discret ;
• utiliser les SVG de website/public/static/icons.

11. Formulaires Et Checkbox

Inputs et textareas :

• fond sombre ;
• bordure fine ;
• focus dore via :focus-visible ;
• placeholders en --color-text-muted.

Checkbox :

• style custom global ;
• format carre strict ;
• fond non coche legerement eclaire ;
• bordure dore/violet ;
• etat coche avec gradient dore/violet et coche blanche ;
• spacing adapte dans les filtres.

Accessibilite :

• utiliser .sr-only pour conserver un label utile sans l'afficher ;
• ne pas retirer les labels accessibles au profit du visuel uniquement.

12. Navigation

Sidebar :

• fond sombre, stable ;
• icones SVG pour Accueil, Toolboxes et Jeux ;
• navigation active en violet soft ;
• le logo controller garde le gradient de l'ancien badge et une rotation au hover.

Le nom de marque affiche Sokko en blanc et G en dore. Au hover, Sokko anime vers le dore de droite a gauche puis revient au hover out.

13. Filtres Et Tableaux

Filtres :

• chips compactes ;
• checkbox, icone puis texte ;
• spacing lisible : checkbox pas collee au bord, icone proche du texte ;
• reset avec bouton icone rubber.

Tableaux :

• pas de scroll horizontal pour les tableaux de degats MHWilds ;
• cellules compactes ;
• bordures fines ;
• lisibilite prioritaire sur la decoration.

Outil Tableau :

• scroll horizontal autorise uniquement dans la surface de grille editable ;
• entetes de lignes/colonnes compacts et stables ;
• intitulés de lignes/colonnes éditables sans modifier les références de formule ;
• cellules en inputs directs, avec focus dore et erreurs de formule discrètes ;
• sélection multiple visible par fond cyan/violet discret et destinée aux actions de plage comme la copie TSV ;
• actions de lignes/colonnes en boutons icones.

14. Toolboxes

Les toolboxes sont locales et stockees dans le navigateur.

Regles UI :

• pas de champ description ;
• image de jeu si associee a un jeu ;
• icone editable si toolbox libre ;
• action importer/exporter clairement identifiee ;
• budget IndexedDB recommande visible en bas de page/panneau, avec quota navigateur reel seulement informatif ;
• import/export global disponibles.

Les cards toolbox doivent garder une taille compacte. L'image/icone de cover est cliquable.

15. Donnees Jeux

Le contenu editorial editable doit rester dans :

• website/public/data/site.json pour les textes generaux ;
• website/public/data/games.json pour la liste des jeux ;
• website/public/data/mhwilds/*.json pour les donnees MHWilds.

Les retours a la ligne \n du JSON doivent etre rendus correctement. Le JSX ne doit pas contenir de contenu editorial long si une entree JSON existe deja.

16. Modales, Drawer Et Notifications

Modales :

• fond floute mais pas trop opaque ;
• panneau centre ;
• fermeture au clic exterieur quand l'action le permet ;
• boutons icones pour fermer/zoomer quand approprie.

Drawer toolbox :

• panneau lateral redimensionnable ;
• overlay floute leger ;
• les actions internes ne doivent pas fermer le drawer sauf action explicite.

Notifications internes :

• pas d'alerte navigateur ;
• utiliser les toasts internes globaux ;
• position configurable gauche/droite via le switch de la page toolboxes ;
• une nouvelle alerte s'empile au-dessus des precedentes ;
• limite visible : 5 toasts ;
• a la 6e alerte, fermer la plus ancienne ;
• duree d'affichage cible : 2 minutes, fermeture manuelle possible ;
• style plus visible que les confirmations simples : bordure conique animee, pulse leger, arrivee depuis le cote configure.

17. Scrollbars

Les scrollbars reprennent l'ancien rendu :

::-webkit-scrollbar {
  width: 6px;
  height: 6px;
  background-color: transparent;
}

::-webkit-scrollbar-track {
  background-color: transparent;
  box-shadow: none;
}

::-webkit-scrollbar-thumb {
  background-image: -webkit-gradient(
    linear,
    left bottom,
    left top,
    color-stop(0.5, rgb(79, 26, 114)),
    color-stop(1, rgb(44, 1, 135))
  );
  border-radius: 10px;
}

Ne pas ajouter de rail noir visible ni de double bordure pres des panneaux.

18. Images Et Assets

Regles :

• les pages jeux et toolboxes associees utilisent les images de jeu en cover ;
• les images de jeu doivent etre rangees par jeu dans website/public/static/img/games/<game-id>/ ;
• utiliser card-cover.png pour les cards et hero-bg.png pour le futur fond de hero ;
• declarer ces images dans games.json via images.cardCover et images.heroBg ;
• les toolboxes libres utilisent une icone de website/public/static/img/toolbox-icons ;
• toolbox.png est l'icone par defaut ;
• les categories de jeu utilisent des images representatives, entieres et bien cadrees ;
• eviter les images trop grandes dans les cards.

19. Accessibilite

Minimum attendu :

• focus visible dore ;
• boutons reels pour les actions ;
• liens reels pour la navigation ;
• labels explicites ou aria-label pour les boutons icones ;
• contraste suffisant ;
• modales avec role="dialog" et aria-modal="true" ;
• ne pas transmettre une information uniquement par couleur.

20. A Eviter

• accents dores partout ;
• hover trop lumineux sur tous les elements ;
• mouvements verticaux sur les cards/modules principaux ;
• background inline qui remplace le theme commun ;
• descriptions de toolbox ;
• alertes navigateur pour confirmations ou creation ;
• gros blocs explicatifs visibles dans l'app ;
• scroll horizontal sur les tableaux de donnees critiques.