Topic on Manual talk:Coding conventions/CSS

CSS/LESS variable naming guidelines request for comments

9
Volker E. (WMF) (talkcontribs)

We're still in need of documenting variable naming guidelines similar to PHP variables or JavaScript variables. Following up archived discussion at https://www.mediawiki.org/wiki/Manual_talk:Coding_conventions/CSS/Archive_1#Less_and_future_CSS_variable_naming_convention it's now time to settle on a guiding convention. The full property name variant has seen the most supportive feedback due to reduced cognitive load and is therefore the selected proposal.

LESS exampleː

/* Colors */
@background-color-base: #fff;
@background-color-error: #fff36f;
@color-base: #000;
@color-error: #c00;
@color-progressive: #347bff;

/* Sizes & Boxes */
@size-selector: 42rem;
@size-small: 0.1rem;
@border-error: @size-small solid @color-error;

/* Fonts */
@font-family-heading: "Linux Libertine", Georgia, Times, serif;
@font-family-flow: "Helvetica Neue", Helvetica, Arial, sans-serif;

/* Transitions */
@transition-base: 0.2s ease-in;

/* CSS Variables example */
--background-color-error: #fff36f;
--color-error: #c00;


/* Applied (Less): */
.mw-selector {
	background-image: url( selector.svg );
	background-repeat: no-repeat;
	color: @color-error;
	display: block;
	position: absolute;
	top: 0;
	left: 0;
	width: @size-selector;
	height: @size-selector;
	font-family: @font-family-flow;
}
/* Applied (mixed): */
.mw-error {
	background-color: @background-color-error;
	background-color: var( --background-color-error );
	margin: @size-small 0;
	border: @border-error;
	transition: opacity @transition-base;
}

Variables are (with the very exception of calculations and size values) almost always belonging to a certain CSS property, therefore starting with repeating the property clarifies and emphasizes the content of the variable.

ESanders (WMF) (talkcontribs)

This seems like a good first step. +1

JDrewniak (WMF) (talkcontribs)

I think the full variable names aid in comprehension and readability, and are thus more maintainable. +1

EGardner (WMF) (talkcontribs)

+1, having well-thought-out and documented conventions here would be an improvement.

Volker E. (WMF) (talkcontribs)

Going ahead after today's Front-end Standards Developer Group Meeting with general support and agreement on the proposal. Adding the guidelines to the main article. Additionally, enforcing such guidelines with help of a stylelint plugin might be possible, but time-consuming to build. Only close project is part of a SonarQube plugin. Propose to keep it a soft guideline, with explanation on the article and main Product projects supporting it, a.o. WikimediaUI Base, OOUI, Vector, MobileFrontend/Minerva Neue.

Volker E. (WMF) (talkcontribs)
Aron Manning (talkcontribs)

The convetion has an example with "font-family-sans-serif":
@font-family-sans-serif: "Helvetica Neue", Helvetica, Arial, sans-serif;
WikimediaUI Base has "font-family-sans":
@font-family-sans: 'Helvetica Neue', 'Helvetica', 'Nimbus Sans L', 'Arial', 'Liberation Sans', sans-serif;

Which one is normative?

Aron Manning (talkcontribs)
Volker E. (WMF) (talkcontribs)
Reply to "CSS/LESS variable naming guidelines request for comments"