Guide d'amélioration des styles

Ce guide documente les tokens du système de design et les classes de composants implémentés dans styles/custom.css. Il sert de référence pour les tokens de bordure, de surface, d’ombre, de rayon, de bouton, de dégradé, de transition, de focus et de typographie utilisés dans l’ensemble du thème.

Statut : Tous les tokens de design et classes de composants décrits ci-dessous sont implémentés et disponibles à l’utilisation.

Comment lire ce guide

Chaque section documente une catégorie de tokens :

1. Définitions des tokens — propriétés CSS personnalisées avec valeurs en mode clair/sombre
2. Correspondance avec les composants — quels composants du thème utilisent chaque token
3. Notes d’implémentation — conseils d’utilisation et considérations d’accessibilité

Les tableaux de tokens sont séparés par mode clair et mode sombre lorsque les valeurs diffèrent.

---

1. Système de couleurs

Bordures alpha-transparentes

Le thème utilise des bordures alpha-transparentes plutôt que des couleurs grises solides. Cela permet aux bordures de s’adapter naturellement à n’importe quel arrière-plan.

/* Modèle de bordure alpha-transparente */
border: 1px solid var(--f5-border-default);  /* neutre à 20% d'opacité */

Tokens de bordure

/* Mode clair */
:root[data-theme='light'] {
  --f5-border-faint: #3434341a;    /* --f5-black-3 à 10% */
  --f5-border-default: #34343433;  /* --f5-black-3 à 20% */
  --f5-border-strong: #22222266;   /* --f5-black-4 à 40% */
}

/* Mode sombre */
:root {
  --f5-border-faint: #f5f5f51a;    /* --f5-white-2 à 10% */
  --f5-border-default: #f5f5f533;  /* --f5-white-2 à 20% */
  --f5-border-strong: #cccccc66;   /* --f5-white-4 à 40% */
}

Cas d’utilisation des bordures

Token	Opacité	Cas d’utilisation
--f5-border-faint	10%	Séparateurs discrets, lignes de tableau
--f5-border-default	20%	Bordures par défaut, contours de carte
--f5-border-strong	40%	Bordures accentuées, états actifs

Statut : Complet — implémenté dans styles/custom.css.

Couleurs de surface interactives

Tokens de surface sémantiques pour les états de survol et d’activation.

Surfaces en mode clair

Token	Valeur	Rôle
--f5-white	#ffffff	Arrière-plans principaux
--f5-white-1	#faf9f7	Barre latérale, zones discrètes
--f5-white-2	#f5f5f5	Surfaces élevées
--f5-surface-hover	var(--f5-white-2)	Remplissage au survol
--f5-surface-active	var(--f5-white-3)	Remplissage pressé/actif

Surfaces en mode sombre

Token	Valeur	Rôle
--f5-black	#000000	Arrière-plans principaux
--f5-black-4	#222222	Barre latérale, zones discrètes
--f5-surface-hover	var(--f5-black-3)	Remplissage au survol
--f5-surface-active	var(--f5-black-2)	Remplissage pressé/actif

Définitions des tokens de surface

:root[data-theme='light'] {
  --f5-surface-hover: var(--f5-white-2);     /* #f5f5f5 */
  --f5-surface-active: var(--f5-white-3);    /* #e6e6e6 */
}

:root {
  --f5-surface-hover: var(--f5-black-3);     /* #343434 */
  --f5-surface-active: var(--f5-black-2);    /* #666666 */
}

Statut : Complet — implémenté dans styles/custom.css.

---

2. Système d’élévation et d’ombre

Échelle d’ombres

Le thème utilise des ombres alpha à teinte neutre avec des valeurs en double couche pour un rendu de profondeur naturel. Le mode clair utilise --f5-black-3 (#343434) comme base de teinte ; le mode sombre utilise #cccccc.

Ombres en mode clair

:root[data-theme='light'] {
  --f5-shadow-inset: inset 0px 1px 2px 1px #3434341a;
  --f5-shadow-low:
    0px 1px 1px 0px #3434340d,
    0px 2px 2px 0px #3434340d;
  --f5-shadow-mid:
    0px 2px 3px 0px #3434341a,
    0px 8px 16px -10px #34343433;
  --f5-shadow-high:
    0px 2px 3px 0px #34343426,
    0px 16px 16px -10px #34343433;
  --f5-shadow-higher:
    0px 2px 3px 0px #3434341a,
    0px 12px 28px 0px #34343440;
}

Ombres en mode sombre

:root {
  --f5-shadow-inset: inset 0px 1px 2px 1px #cccccc0d;
  --f5-shadow-low:
    0px 1px 1px 0px #cccccc0a,
    0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid:
    0px 2px 3px 0px #cccccc0d,
    0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high:
    0px 2px 3px 0px #cccccc1a,
    0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher:
    0px 2px 3px 0px #cccccc0d,
    0px 12px 28px 0px #cccccc26;
}

Correspondance des ombres par composant

Composant	Niveau d’ombre
.swatch, .icon-card	--f5-shadow-low (au repos)
.starlight-aside	--f5-shadow-low
.expressive-code .frame	--f5-shadow-mid
.mermaid-container	--f5-shadow-mid
Cartes au survol	--f5-shadow-mid
Menus déroulants, popovers	--f5-shadow-high
Modales	--f5-shadow-higher

Statut : Complet — tous les niveaux d’ombre (inset, low, mid, high, higher) implémentés dans styles/custom.css.

---

3. Échelle des rayons de bordure

Tokens de rayon

:root {
  --f5-radius-xs: 0.1875rem;   /* 3px — badges, étiquettes */
  --f5-radius-sm: 0.3125rem;   /* 5px — éléments de navigation, petits contrôles */
  --f5-radius-md: 0.375rem;    /* 6px — cartes, blocs de code */
  --f5-radius-lg: 0.5rem;      /* 8px — modales, grands conteneurs */
  --f5-radius-full: 999px;     /* pilules, entièrement arrondis */
}

Correspondance des rayons par composant

Composant	Token de rayon
.swatch	--f5-radius-md (6px)
.icon-card	--f5-radius-md (6px)
.starlight-aside	--f5-radius-md (6px)
.expressive-code .frame	--f5-radius-md (6px)
.mermaid-container	--f5-radius-lg (8px)
.edit-link	--f5-radius-full (pilule)
Éléments de navigation de la barre latérale	--f5-radius-sm (5px)
Badges	--f5-radius-xs (3px)

Statut : Complet — échelle de rayon (xs, sm, md, lg, full) implémentée dans styles/custom.css.

---

4. Style de navigation de la barre latérale

Styles des éléments de la barre latérale

/* Éléments de navigation de la barre latérale */
nav.sidebar a {
  border-radius: var(--f5-radius-sm);    /* 5px */
  padding: 0.25rem 0.5rem;               /* 4px 8px */
  min-height: 2.25rem;                    /* 36px */
  display: flex;
  align-items: center;
  transition: background-color 0.15s ease, color 0.15s ease;
}

/* Survol en mode clair */
:root[data-theme='light'] nav.sidebar a:hover {
  background-color: var(--f5-white-2);   /* #f5f5f5 */
}

/* Survol en mode sombre */
:root nav.sidebar a:hover {
  background-color: var(--f5-black-3);   /* #343434 */
}

/* Indicateur de page active */
nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-white-3);   /* #e6e6e6 clair */
  font-weight: 600;
}

:root:not([data-theme='light']) nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-black-2);   /* #666666 → ajuster pour la lisibilité */
}

Indicateur d’accent gauche

nav.sidebar a[aria-current="page"] {
  border-left: 3px solid var(--sl-color-accent);
  padding-left: calc(0.5rem - 3px);  /* compensation pour la bordure */
}

Statut : Complet — survol de la barre latérale, état actif et indicateur d’accent implémentés dans styles/custom.css.

---

5. Système de boutons

Variantes de boutons

/* Principal — utilisant le rouge F5 comme action de marque */
.btn-primary {
  background: var(--f5-red);
  color: var(--f5-white);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, box-shadow 0.15s ease;
}
.btn-primary:hover {
  background: var(--f5-red-3);
  box-shadow: var(--f5-shadow-low);
}

/* Secondaire — style avec contour */
.btn-secondary {
  background: transparent;
  color: var(--sl-color-gray-2);
  border: 1px solid var(--f5-border-default);
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, border-color 0.15s ease;
}
.btn-secondary:hover {
  background: var(--f5-surface-hover);
  border-color: var(--f5-border-strong);
}

/* Tertiaire — fantôme/texte uniquement */
.btn-tertiary {
  background: transparent;
  color: var(--sl-color-accent);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease;
}
.btn-tertiary:hover {
  background: var(--f5-surface-hover);
}

Échelle de tailles de boutons

Taille	Rembourrage	Taille de police	Hauteur minimale
Petit	0.375rem 0.75rem	0.8125rem (13px)	32px
Moyen (par défaut)	0.625rem 1rem	0.875rem (14px)	40px
Grand	0.75rem 1.5rem	1rem (16px)	48px

Statut : Complet — toutes les variantes de boutons (primary, secondary, tertiary, critical) et l’échelle de tailles (sm, par défaut, lg) implémentées dans styles/custom.css.

---

6. Arrière-plans de la section hero et de l’en-tête

Dégradés hero

Utilisant la palette de marque F5 :

/* Dégradé hero principal — bleu River */
.hero-gradient-primary {
  background: linear-gradient(135deg, var(--f5-river-2) 0%, var(--f5-river) 100%);
  /* #6e8dcc → #0e41aa */
}

/* Légère teinte de page — ton chaud subtil */
:root[data-theme='light'] .hero-gradient-faint {
  background: linear-gradient(180deg, #faf9f7 0%, #f5f5f5 100%);
}
:root .hero-gradient-faint {
  background: linear-gradient(180deg, #222222 0%, #000000 100%);
}

/* Variante aubergine pour les pages de fonctionnalités */
.hero-gradient-eggplant {
  background: linear-gradient(135deg, var(--f5-eggplant-2) 0%, var(--f5-eggplant) 100%);
  /* #9c59c9 → #62228b */
}

/* Variante rouge de marque pour les annonces */
.hero-gradient-red {
  background: linear-gradient(135deg, var(--f5-red-2) 0%, var(--f5-red) 100%);
  /* #f06680 → #e4002b */
}

Techniques de superposition de dégradés

/* Vignette radiale pour la profondeur */
.hero-vignette::after {
  content: '';
  position: absolute;
  inset: 0;
  background: radial-gradient(ellipse at center, transparent 40%, rgba(0, 0, 0, 0.15) 100%);
  pointer-events: none;
}

/* Fondu bas vers l'arrière-plan de la page */
.hero-fade::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  height: 30%;
  background: linear-gradient(to bottom, transparent, var(--sl-color-black));
  pointer-events: none;
}

Statut : Complet — dégradés hero (primary, eggplant, red, faint) et superpositions (hero-fade, hero-vignette) implémentés dans styles/custom.css.

---

7. Effets de survol et transitions

Tokens de transition

:root {
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);
}

Token	Durée	Accélération	Cas d’utilisation
--f5-transition-fast	0.15s	ease	La plupart des états de survol, changements de couleur
--f5-transition-base	0.2s	ease	Remplissages d’arrière-plan, changements de bordure
--f5-transition-bounce	0.2s	cubic-bezier(0.68, -0.2, 0.265, 1.15)	Commutateurs, bascules
--f5-transition-decelerate	0.6s	cubic-bezier(0.5, 1, 0.89, 1)	Indicateurs d’onglet, panneaux coulissants
--f5-transition-spring	0.2s	cubic-bezier(0.54, 1.5, 0.38, 1.11)	Infobulles, entrée de popover

Ce qu’il convient d’animer

Propriété	Sûr à animer	Notes
background-color	Oui	Standard pour les remplissages au survol
color	Oui	Changements de couleur du texte
border-color	Oui	Accentuation de la bordure au survol
box-shadow	Oui	Changements d’élévation (utiliser will-change en cas de saccade)
transform	Oui	Mise à l’échelle, translation pour le retour visuel
opacity	Oui	Fondu entrant/sortant
width, height	À éviter	Provoque un recalcul de la mise en page
padding, margin	À éviter	Provoque un recalcul de la mise en page

Correspondance des transitions par composant

/* Éléments de navigation de la barre latérale */
nav.sidebar a {
  transition: background-color var(--f5-transition-fast),
              color var(--f5-transition-fast);
}

/* Cartes — élévation d'ombre au survol */
.swatch, .icon-card {
  transition: box-shadow var(--f5-transition-base),
              transform var(--f5-transition-base);
}
.swatch:hover, .icon-card:hover {
  box-shadow: var(--f5-shadow-mid);
  transform: translateY(-1px);
}

/* Boutons */
.btn-primary, .btn-secondary, .btn-tertiary {
  transition: background-color var(--f5-transition-fast),
              border-color var(--f5-transition-fast),
              box-shadow var(--f5-transition-fast);
}

/* Liens */
a {
  transition: color var(--f5-transition-fast);
}

Statut : Complet — les cinq tokens de transition (fast, base, bounce, decelerate, spring) et les transitions de composants implémentés dans styles/custom.css.

---

8. Système d’anneaux de focus

Tokens d’anneau de focus

Le thème utilise un modèle à double anneau avec un anneau intérieur en incrustation et une lueur extérieure :

/* Focus d'action — utilisant le bleu River F5 */
:root {
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  /* inset 0 0 0 1px #0e41aa, 0 0 0 3px #6e8dcc */

  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);
  /* inset 0 0 0 1px #a70020, 0 0 0 3px #f06680 */
}

/* Appliquer aux éléments interactifs */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: none;
  box-shadow: var(--f5-focus-action);
}

/* Variante critique pour les boutons destructifs */
.btn-critical:focus-visible {
  box-shadow: var(--f5-focus-critical);
}

Notes d’accessibilité

• Le modèle à double anneau satisfait aux exigences WCAG 2.2 Focus Appearance (contour contrasté d’au moins 2px)
• L’utilisation de box-shadow plutôt que outline permet de respecter le rayon de bordure
• :focus-visible garantit que l’anneau n’apparaît que lors de la navigation au clavier, et non au clic de souris

Statut : Complet — modèle de focus à double anneau (action, critical) et styles :focus-visible implémentés dans styles/custom.css.

---

9. Typographie

Pile de polices

:root {
  --sl-font: "proximaNova", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-font-heading: "neusaNextProWide", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-line-height-headings: 1.1;
}

Échelle typographique

Échelle	Taille	Hauteur de ligne	Utilisation
Display 500	1.875rem (30px)	1,267	--sl-text-h1
Display 400	1.5rem (24px)	1,333	--sl-text-h2
Display 300	1.125rem (18px)	1,333	--sl-text-h3
Display 200	1rem (16px)	1,5	--sl-text-h4
Display 100	0.8125rem (13px)	1,385	Texte de surtitre
Body 300	1rem (16px)	1,5	Corps principal
Body 200	0.875rem (14px)	1,429	Texte de barre latérale, légendes
Body 100	0.8125rem (13px)	1,385	Petits caractères

Caractéristiques principales

Aspect	Valeur	Notes
Hauteur de ligne des titres	1.1	Titres serrés pour l’impact de marque ; envisager 1.2 pour la lisibilité
Hauteur de ligne du corps	1.5 (valeur par défaut Starlight)	Bien adaptée à la lecture
Famille de polices	Polices de marque personnalisées	proximaNova (corps), neusaNextProWide (titres)
Graisses des titres	h1-h2 : 700, h3 : 500, h4-h6 : 700 majuscules	Opiniatre pour la cohérence de la marque

Priorité : Aucune modification nécessaire. La typographie actuelle est bien définie et adaptée à la marque. Un ajustement mineur de la hauteur de ligne des titres (1.1 à 1.2) est optionnel.

---

10. Journal des modifications d’implémentation

Tous les tokens de design ont été implémentés en cinq sprints :

Sprint	Périmètre	Tokens ajoutés
1. Fondations	Ombres + rayons de bordure	--f5-shadow-* (5 niveaux), --f5-radius-* (5 niveaux)
2. Barre latérale + Surfaces	Navigation + tokens interactifs	--f5-surface-hover, --f5-surface-active, --f5-border-* (3 niveaux), --f5-transition-fast
3. Boutons	Système de composants	.btn-primary, .btn-secondary, .btn-tertiary, .btn-critical, variantes de taille
4. Dégradés hero	Utilitaires d’arrière-plan	.hero-gradient-primary, -eggplant, -red, -faint, .hero-vignette, .hero-fade
5. Focus + Transitions	Accessibilité + finition	--f5-focus-action, --f5-focus-critical, --f5-transition-* (5 tokens), effets de survol des cartes

---

Référence rapide : récapitulatif des tokens

Toutes les propriétés personnalisées

:root {
  /* Échelle de rayon de bordure */
  --f5-radius-xs: 0.1875rem;     /* 3px */
  --f5-radius-sm: 0.3125rem;     /* 5px */
  --f5-radius-md: 0.375rem;      /* 6px */
  --f5-radius-lg: 0.5rem;        /* 8px */
  --f5-radius-full: 999px;

  /* Temporisation des transitions */
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);

  /* Anneaux de focus */
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);

  /* Ombres en mode sombre (par défaut) */
  --f5-shadow-low: 0px 1px 1px 0px #cccccc0a, 0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid: 0px 2px 3px 0px #cccccc0d, 0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high: 0px 2px 3px 0px #cccccc1a, 0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher: 0px 2px 3px 0px #cccccc0d, 0px 12px 28px 0px #cccccc26;

  /* Bordures en mode sombre */
  --f5-border-faint: #f5f5f51a;
  --f5-border-default: #f5f5f533;
  --f5-border-strong: #cccccc66;

  /* Surfaces en mode sombre */
  --f5-surface-hover: var(--f5-black-3);
  --f5-surface-active: var(--f5-black-2);
}

:root[data-theme='light'] {
  /* Ombres en mode clair */
  --f5-shadow-low: 0px 1px 1px 0px #3434340d, 0px 2px 2px 0px #3434340d;
  --f5-shadow-mid: 0px 2px 3px 0px #3434341a, 0px 8px 16px -10px #34343433;
  --f5-shadow-high: 0px 2px 3px 0px #34343426, 0px 16px 16px -10px #34343433;
  --f5-shadow-higher: 0px 2px 3px 0px #3434341a, 0px 12px 28px 0px #34343440;

  /* Bordures en mode clair */
  --f5-border-faint: #3434341a;
  --f5-border-default: #34343433;
  --f5-border-strong: #22222266;

  /* Surfaces en mode clair */
  --f5-surface-hover: var(--f5-white-2);
  --f5-surface-active: var(--f5-white-3);
}