Manuel:Règles de codage/CSS

This page is a translated version of the page Manual:Coding conventions/CSS and the translation is 100% complete.

Nommage

Nommer les classes et les identifiants de la même manière : tout en minuscules avec des tirets de séparation. Utiliser le préfixe mw- pour éviter les conflits avec les identifiants générés par l'analyseur syntaxique de wikicode pour marquer l'entête des sections.

Quelques exemples :

/* Eléments valides sur tout le site */
.mw-body,
.mw-headline,
.mw-label,
.mw-input {
}

/* Pages spéciales */
.mw-body-content,
/* - Special:AllPages */
.mw-allpages-table-form,
.mw-allpages-nav {
}

Caractère espace

Un sélecteur ou propriété par ligne
Ouvrir les accolades pour le bloc de déclarations CSS sur la même ligne que le (dernier) sélecteur.
indenter chaque déclaration de propriété à l'aide de la tabulation.
Pas d'espace avant les deux-points (:).
Un espace après les deux-points et avant la valeur.
Un espace après chaque virgule (, ) dans les propriétés à valeurs multiples.
Un point virgule (;) après chaque déclaration (y compris la dernière).
Les accolades fermantes se réindentent vers la gauche.
Les annotations pour CSSJanus et CSSMin doivent être sur leur propre ligne, au-dessus de la déclaration du CSS auquel elles se rapportent.
Une ligne de séparation entre chaque ensemble de règles CSS et le suivant.

.mw-selector,
#mw-some-element {
	background-color: #fff;
	color: #252525;
	float: right;
	font-family: Arial, Helvetica, sans-serif;
	text-align: left;
}

/* exemple d'annotations CSSMin/CSSJanus */
.mw-look-at-the-left {
	/* @embed */
	background-image: url( images/foobar.png );
	/* @noflip */
	float: left;
}

Guillemets

Dans la déclaration background-image, il est préférable d'utiliser la syntaxe url() sans guillemets. Ils ne sont pas nécessaires. Le seul cas qui pourrait poser problème est celui d'une parenthèse fermante non échappée et présente dans le chemin fourni, mais celle-ci devrait être protégée par le format URL.

Valeurs des propriétés de couleur

Avec CSS3 les développeurs ont a leur disposition une pléthore de valeurs de couleurs reconnues pour les propriétés telles que background-color, color, border-color et autres. Pour faciliter la maintenance et la taille du fichier^[1], utiliser les minuscules :

Valeurs hexadécimales de couleur comme #fff (notation raccourcie si possible) ou #fefefe
valeurs de rgba() si une transparence alpha supérieure à 0 est nécessaire
mot clé de couleur transparent (attention à certaines mises en garde pour les navigateurs Internet Explorer <= IE9).

Eviter les autres valeurs des mots-clé de couleur, les notations rgb(), hsl(), et hsla(). Assurez-vous également que votre rapport de contraste entre les couleurs de premier plan et d'arrière-plan (même chose que pour les gradients de fond) est conforme au niveau AA (ou idéalement AAA) de WCAG 2.0 .^[2]

D'autres informations sont disponibles sur MDN.

Préfixes des vendeurs

Placez toujours les nouvelles versions après les anciennes dans le cas des préfixes CSS de vendeurs, en mettant les déclarations standard à la fin. Voir aussi https://css-tricks.com/ordering-css3-properties/.

/* Mauvais */
.bar {
	border-radius: 30px 10px;
	-webkit-border-radius: 30px 10px;
}

/* Correct */
.bar {
	-webkit-border-radius: 30px 10px;
	/* Il est important de placer la version -webkit avant la version standardisée.
	 * Sinon elle l'annulera (comme prévu dans le CSS), y compris en déclenchant les
	 * bogues de l'ancienne version -webkit- mais que WebKit a corrigé depuis (en CSS3)
	 * mais qu'il garde de l'ancienne implémentation (compatibilité arrière).
	 */
	border-radius: 30px 10px;
}

/* Mauvais */
.foo {
	background-image: linear-gradient(top, #444444, #999999);
	background-image: -o-linear-gradient(top, #444444, #999999);
	background-image: -moz-linear-gradient(top, #444444, #999999);
	background-image: -webkit-linear-gradient(top, #444444, #999999);
	background-image: -webkit-gradient(linear, left top, left bottom, from(#444444), to(#999999));
}

/* Correct */
.foo {
	background-color: #444;
	background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999));
	background-image: -webkit-linear-gradient(      top, #444, #999);
	background-image:    -moz-linear-gradient(      top, #444, #999);
	background-image:      -o-linear-gradient(      top, #444, #999);
	background-image:         linear-gradient(to bottom, #444, #999);
}

/* Correct (commenté) */
.foo {
	/* couleur de repli dans le cas où le gradient n'est pas supporté pour l'image de fond */
	background-color: #444;
	/* Safari 4+, Chrome 2, iOS 2 */
	background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999));
	/* Safari 5.1+, Chrome 10+, iOS 5 */
	background-image: -webkit-linear-gradient(      top, #444, #999);
	/* Firefox 3.6 - 15 */
	background-image:    -moz-linear-gradient(      top, #444, #999);
	/* Opera 11.10 - 12.5 */
	background-image:      -o-linear-gradient(      top, #444, #999);
	/* Standard (Firefox 16+, Opera 12.5+, IE10) */
	background-image:         linear-gradient(to bottom, #444, #999);
}

.client-js et .client-nojs

MediaWiki génère la classe client-nojs en sortie sur l'élément ‎<html> à chaque page. Au moment de l'exécution, le code JavaScript le remplace par la classe client-js. Vous pouvez donc utiliser cette classe dans votre sélecteur pour afficher conditionnellement, masquer ou personnaliser certains éléments selon que JavaScript est activé sur le navigateur et qu'il est pris en charge par le ResourceLoader . Notez que pour que cela soit utile, la feuille de style en question doit être chargée avec mw.loader (voir Développer avec ResourceLoader )

Anti-modèles

z-index

Eviter l'utilisation de z-index autant que possible. Au lieu de cela, essayez d'utiliser l'ordre d'empilage naturel du DOM. Les exceptions connues comprennent :

Compact Personal Bar sur 100
Aperçus des pages commençant à 110
Fenêtres instantanées de navigation commençant à 1000.

!important

Évitez d'utiliser !important (sauf pour travailler sur le code upstream exécuté sur la même page qui utilise également !important, car seulement !important peut redéfinir !important).

Dans la plupart des cas, vous n'en n'avez pas besoin (paranoïa). Dans d'autres cas, il peut être le résultat d'un bogue ailleurs dans le programme. En général, pour redéfinir une règle on utilise le même sélecteur que celui de la règle de style originale. Depuis les CSS en cascades, cela fonctionne naturellement (les styles appliqués ultérieurement remplacent les styles appliqués antérieurement, les sélecteurs n'ont pas besoin de spécificité supérieure).^[3]

Si les styles redéfinis sont appliqués avant les styles originaux, c'est que les styles ont été chargés dans le mauvais ordre. Cela devrait être abordé, mais vous pouvez recourir à des solutions de contournement pour augmenter artificiellement la spécificité :

Répéter le même sélecteur pour augmenter le poids, comme .foo.foo.foo.foo.^[4]
Ajouter ou répéter les sélecteurs d'attributs, comme [class].
Utiliser les éléments par défaut comme le sélecteur parent (par exemple body .foo, html body .foo).

Ajoutez autant de points que vous en avez besoin. Il permettra encore à plusieurs feuilles de style d'utiliser la même technique et chacune exprimera sa spécificité. C'est mieux que d'ajouter dans les classes parents non liées à votre code. (Et c'est plus maintenable car elles ne changent pas.)

LESS

À partir de MediaWiki 1.22 , il existe un support natif dans ResourceLoader pour utiliser LESS de manière transparente (avec l'extension de fichier .less) à la place du CSS. La plupart de la syntaxe LESS peut être formatée en utilisant les conventions CSS :

Indenter les blocs imbriqués avec une tabulation (même chose que les règles CSS sur l'indentation des déclarations).
Ne pas aligner les déclarations des valeurs à l'aide d'espaces à l'intérieur des mixins (même chose que ppour les règles CSS).
Aucun espace à l'extérieur des listes de paramètres dans les invocations de fonction, les utilisations de mixin et les définitions de mixin (même chose que pour url( image.png ) dans CSS).
Pas de guillemets autour de la valeur des paramètres (même chose que pour url( image.png ) en CSS).

Exemple :

/*
	Vous n'avez pas besoin de copier '.background-image' dans votre code.
	Il est fourni par le noyau MediaWiki (en mediawiki.less).
	Il est ici comme exemple de syntaxe de garde.
*/
.background-image(@url) when (embeddable(@url)) {
	background-image: embed(@url);
	background-image: url(@url)!ie;
}

.background-image(@url) when not (embeddable(@url)) {
	background-image: url(@url);
}

.mw-example {
	padding: 0.2em 0.5em;
	border: 1px solid #aaa;
	.background-image(images/example.png);
	font-size: 1em;

	.mw-example-thing {
		display: inline-block;
		/* @noflip */
		float: left;
		border: 1px solid #ddd;
		padding: 1px 4px;
		border-radius: 2px;
	}
}

Il y a quelques nouveaux concepts qui ne correspondent pas aux conventions CSS décrits ci-dessous.

Structure

Séparer les déclarations du parent et les règles CSS imbriquées à l'aide d'une ligne vide.
Les balises @noflip doivent être sur la ligne juste au-dessus de la déclaration, comme indiqué dans l'exemple ci-dessus.

Importer

Le nom de fichier d'une déclaration d'import ne doit pas comporter l'extension de fichier .less.
Utiliser @import pour charger les mixins et les variables afin qu'ils puissent être utilisés par la feuille de style LESS actuelle; ceux-ci sont traités en synchronisation par phpless et ne seront pas présents dans la sortie CSS générée.
N'utilisez pas @import pour regrouper des feuilles de style qui sont liées entre elles uniquement conceptuellement; au lieu de cela, faites référence à l'ensemble de fichiers dans le tableau styles d'un module ResourceLoader.

Résoudre les problèmes

Si votre import LESS ne fonctionne pas, veuillez vérifier :

Votre code contient-il @font-face ? Voir cette question sur Stack Overflow à propos de l'utilisation de @font-face avec LESS.

Bibliothèque LESS de MediaWiki

resources/src/mediawiki.less/mediawiki.mixins.less est une bibliothèque commune LESS pour MediaWiki. Le répertoire se trouve dans $wgResourceLoaderLESSImportPaths, vous n'avez donc pas à fournir son chemin complet. Par exemple :

@import "mediawiki.mixins";

.my-create-link {
    .background-image-svg('images/create_normal.svg', 'images/create_normal.png');
}

Les mixins

Les noms de mixin doivent utiliser la casse et les tirets, tout comme le nom des propriétés CSS.

Ils doivent être préfixés par mixin- pour éviter de perturber les développeurs qui connaissent bien CSS, mais pas LESS et les distinguer des classes, dont la syntaxe est similaire.

Comme indiqué ci-dessus, il n'y a pas d'espace à l'extérieur de la liste des paramètres et ni de guillemets autour des valeurs.

Si vous devez appeler un mixin avec un ou plusieurs arguments contenant une virgule, utilisez un point virgule ; en LESS pour séparer les arguments. Cela vous permet d'utiliser des virgules dans la valeur littérale.

.mixin-example(@function, @properties) {
	transition-timing-function: @function;
	transition-property: @properties;
}

/* Correct */
.mw-example {
	.mixin-example(easy-in-out; opacity, color);

	/* Se développe en : */
	transition-timing-function: easy-in-out;
	transition-property: opacity, color;
}

/* Mauvais */
.mw-example {
	.mixin-example('easy-in-out', 'opacity, color');

	/* Se développe en : */
	transition-timing-function: 'easy-in-out';
	transition-property: 'opacity, color';

	/* Les valeurs contiennent des guillemets, le CSS n'est pas valide
	 * et le navigateur ignore alors ces propriétés
	 */
}

/* Mauvais */
.mw-example {
	.mixin-example(~'easy-in-out', ~'opacity, color');

	/* Se développe en : */
	transition-timing-function: easy-in-out;
	transition-property: opacity, color;

	/* L'operator '~' indique à LESS de supprimer les guillemets des valeurs.
	 * Cela produit un CSS valide mais nous évitons ce modèle
	 * en faveur de l'utilisation de ';' par mesure de cohérence.
	 */
}

Références

↑ Le balisage en minuscules génère des archives gzip de taille plus petite, HTML5 Boilerplate 2015 (modèle d'interface utilisateur professionnel pour construire des applications web ou des sites, rapides, robustes et adaptables)
↑ WCAG 2.0 Understanding Contrast
↑ Spécifications des spécificités de CSS
↑ 3.14 choses que je ne savais pas sur CSS, jour de conférence CSS 2014

[1] Le balisage en minuscules génère des archives gzip de taille plus petite, HTML5 Boilerplate 2015 (modèle d'interface utilisateur professionnel pour construire des applications web ou des sites, rapides, robustes et adaptables)

[2] WCAG 2.0 Understanding Contrast

[3] Spécifications des spécificités de CSS

[4] 3.14 choses que je ne savais pas sur CSS, jour de conférence CSS 2014

[1]

[2]

[3]

[4]