Manual talk:Coding conventions/CSS/Archive 1

Comments about colors
Does it make sense to anybody but me to demand writing comments about numbered color values in CSS? --Amir E. Aharoni (talk) 19:35, 25 July 2012 (UTC)


 * Everyone who writes CSS probably knows what #000 and #FFF stand for, but I for one don't know that #C71585 stands for "MediumVioletRed" without looking it up on the English Wikipedia (or some other CSS resource). So yes, I wholeheartedly support using comments to write out the color name in plain English. After all, comments are cheap, just like space. --Jack Phoenix (Contact) 13:55, 26 July 2012 (UTC)

LESS
The LESS section is more a guide about LESS than a coding conventions set of guidelines.

Someone has an objection to move most of the section to a Manual:LESS page? --Dereckson (talk) 21:32, 30 October 2013 (UTC)

Prefix mixins with `mixin-` ?
It's hard to distinguish .foo { } with .foo { .foo; } especially if you are new to LESS. I think it would be in everyones interest to prefix all mixins with mixin- to help with readability and to place mixins at the top of a file. e.g. .mixin-foo { } .foo { .mixin-foo; }

Thoughts? Jdlrobson (talk) 22:25, 7 August 2014 (UTC)
 * +1. You've convinced me this is a good idea. I don't have a strong preference on the prefix, or whether mixins have to go in the top of the file.  But it seems like a useful convention overall. Superm401 - Talk 00:03, 9 September 2014 (UTC)

Add spaces around mixin parameters ?
I'm not sure about one of the existing code conventions. I think it is useful to be able to more clearly distinguish between and In the second case we are dealing with a mixin and I would recommend that using spaces would make it clearer. e.g.

Just a suggestion. Jdlrobson (talk) 15:57, 9 April 2014 (UTC)


 * I think that's a very good idea and that, because ResourceLoader is minifying the files anyways, we should also discuss about applying whitespace for CSS property values with brackets like URIs to align CSS brackets notation with PHP and JS Coding Conventions.
 * Citing from W3C – "The format of a URI value is 'url(' followed by optional whitespace followed by an optional single quote (') or double quote (") character followed by the URI itself, followed by an optional single quote (') or double quote (") character followed by optional whitespace followed by ')'. The two quote characters must be the same." Resulting in:
 * --VEckl (WMF) (talk) 14:53, 21 July 2015 (UTC)
 * Agreed, let's update. ESanders (WMF) (talk) 18:19, 2 October 2015 (UTC)
 * --VEckl (WMF) (talk) 14:53, 21 July 2015 (UTC)
 * Agreed, let's update. ESanders (WMF) (talk) 18:19, 2 October 2015 (UTC)

Less and future CSS variable naming convention
We are currently missing a naming convention for Less and somewhen future CSS variables (custom properties). We already have conventions for PHP variables or JavaScript variables. It's time to agree on and implement a CSS/Less variable naming convention.

Throughout projects there's currently a pretty wild mix, for example in Vector:

or mediawiki.ui:

or Minerva:

A new proposal
The duplication of property name and property as variable name in applied property values is IMHO verbose and redundant. I'd propose to take popular and widely-used Emmet (section CSS) as base for shortening of property into consideration. Variables are (with the very exception of calculations and size values) almost always belonging to a certain CSS property, therefore the property doesn't need to be repeated. Even when the variable's value change, it will always be connected to a certain property!

When it comes to the variable names, I'd suggest to follow the same formatting regimen like CSS' built-in and the CSS vars standards document draft and use  as separators. Although camelCase is used across PHP and JS coding conventions, it's not common in CSS. Here's some more food for thought. To the structure of the variable naming, I think it's a good idea, to follow the HTML5 classification, so no, but   and.
 * My opinion, as someone who's written mountains of CSS, is that abbreviations in any but the most limited form (like mw) are cognitive affordances that I personally can't afford. I would rather write and read a fully formed word hundreds of times than abbreviate it.  My text editor helps me with autocompletion and we have no reason to conserve characters since the early days of CSS.  I admit, my aversion to this may be because I'm slightly dyslexic, and it's hard enough for me to read words as it is, without doing the extra translation step in my head.  Just wanted to add this point as a counter to abbreviations being friendly for experienced developers.  I personally prefer the naming philosophy behind semantic ui, and regardless of what people think of the library overall, it's pretty clear that the beautiful naming conventions have drawn people to it.  I like the way they use fully named camelCase for their less variable names, it separates them from the CSS and makes a cognitively easy to follow documentMilimetric (WMF) (talk) 12:25, 2 February 2016 (UTC)


 * -The thing we should remember about naming is that code is written once and read thousands of times. I don't have a strong preference for abbreviations or not, but I will say that I think abbreviations optimize for writing code, and full names optimize for reading it. As an author, I prefer abbreviated variable names, because it's easier to remember and recall shorter variable names than longer ones, especially if the abbreviations follow a standard convention. I do have to load that convention into (my) memory, but once I do it become as Milimetric mentions, a cognitive affordance.


 * As someone reading the code on the other hand, I would have a hard time deciphering what something like @bdrs-base means. I would have to find the variables file, learn and load the abbreviation system into my brain, and then go back to the file I was interested in. Something like @border-radius-base on the other hand, is basically self-documenting. I do think "border-radius: @border-radius-base;" is verbose and repetitive, but for the sake of those who have to read the code after I write it, I think full variable names provide a clearer path to understanding.  --JDrewniak (WMF) (talk) 10:53, 15 March 2016 (UTC)

CSS namespaces useful?
Naming is hard and designing CSS for scalability is even harder. CSS namespaces (example) have in my experience a great potential to gain speed working with disperse people and projects on front-end. — Preceding unsigned comment added by VEckl (WMF) (talk • contribs) 04:43, 12 September 2015 (UTC)
 * Would "Hungarian notation for CSS" be an appropriate TL;DR summary of that link? Anomie (talk) 13:24, 14 September 2015 (UTC)
 * Unlike in the CSS-/Less variable naming proposal, I would actually not advocate for abbreviations like in the csswizardry example. Because MW is for the broadest range of developers often with very minimal CSS/Less experience. And abbreviations make development for the inexperienced harder. See f.e. current side-navigation in Vector:
 * Looking into  I see ID  . At that point I can just widely guess what p stands for. The next sibling   has   and   applied. So is p an abbreviation for portal then? But wait,   is outside of it, so maybe it's something else…   probably?
 * But, I would wanna see clearer naming patterns in CSS handlers (predominantly classes) to speed up development for front-end devs. As an example instead of
 * better:
 * Might look verbose/not too inviting in the beginning, but speeds up orientation and clarification code-wise in CSS modules impactfully from my experience.
 * Be cautious, that this is result of a very short code review process, I haven't looked into the JS connected with #centralNotice, nor at which places it is used. As it's an ID this might be the only place of it being in use.
 * To explain in a few words, I'm following BEM (Block Element Modifier) notation here, a  signifies a child (an Element) of the Block. And   signifies a Modified state of the Element.
 * With that I can easily separate CSS styles for elements and denote in another rule very few modifier specifics. In JS I can easily care about getting/setting modified states only.
 * I'm aware that this is a big conversation with lots of dependecies and problems. And it will not help to come up with another standard -- ahem, approach besides the historically grown and therefore understandable, but still horrifying mix of ID/class naming variations out there. --VEckl (WMF) (talk) 19:03, 6 November 2015 (UTC)
 * With that I can easily separate CSS styles for elements and denote in another rule very few modifier specifics. In JS I can easily care about getting/setting modified states only.
 * I'm aware that this is a big conversation with lots of dependecies and problems. And it will not help to come up with another standard -- ahem, approach besides the historically grown and therefore understandable, but still horrifying mix of ID/class naming variations out there. --VEckl (WMF) (talk) 19:03, 6 November 2015 (UTC)

Gzip heatmap of lowercase color values
Out of curiosity I wanted to see for myself how lowercased, shorthand notated color values of 2015-08's Vector CSS would look like in gzthermal heatmap, mentioned on color property section on the guidelines article:

Gathering ideas of what base unit values to use where/when?
Copy from IRC for now. Will work on some ideas soon. 01:05  we're talking about the content's font-size? 01:05  in which case, it's already compatible. it works on Vector and MonoBook, which have different font-size 01:05  if we're talking about the font-size for VE's own UI, then no one has tried yet, it's still using 0.8em (=12.8px) on both Vector and MonoBook, afaik [...] 01:06  (MonoBook uses 0.8em for content, Vector uses 0.875em=14px for content) 01:09  MatmaRex: trying to experiment with ideas getting out of the for me not-satisfying pixel rounding of applied 'em's 01:10  Volker_E: oh, hmm 01:10  Volker_E: i'm not sure if you realize, but thesituation there is far more interesting 01:10  :D 01:11  MatmaRex: in which way? :} 01:11  Volker_E: the MediaWiki theme of OOjs UI is currently developed with font-size of 0.8em (12.8px) in mind 01:11  since that was the font-size of Vector when it started to be developed 01:11  then font-size of Vector was changed, but the theme did not get updated. 01:12  so right now, in the demo, we still have 0.8em, but in the actual MediaWiki, we have 0.875em. this is easily noticeable as blurry icons (unless you have an absurdly retina screen) 01:12  MatmaRex: yeah, great scheme of hard-to-maintain dependency failures 01:12 — Volker_E shudders 01:13  but not in VisualEditor! it has some custom CSS to make the font-size inside its UI 0.8em, because no one wanted to update the theme itself to 0.875em 01:13  this was not a problem, until we started using the theme outside of VE [...] 01:13 <MatmaRex> but if we try to fix the theme now, VE will look weird, so we have to update it simultaneously 01:13 <James_F> Ideally we should make everything use a font-size of 1em and just change what the base font size is. 01:14 <James_F> (Heresy!) 01:14 <MatmaRex> and then other things will no doubt break. Flow also uses OOUI, and also has font-size hacks, but only in some places, because it was done inconsistently [...] 01:14 <Volker_E> Ideally would be relying on `rem` but as we have no superpowers people come up with weirdest default settings 01:14 <Volker_E> *we would 01:15 <MatmaRex> the only real problem with the font-size changing under us is that icons become blurry, evertything else should scale fine 01:15 <MatmaRex> but the nested hacks upon hacks are a problem, the last time we touched it, in VE, inspectors inside dialogs balooned to twice the usual size for some reason 01:15 <Volker_E> MatmaRex: I disagree, there are (due to shortcomings in browser rendering engines) several issues around pixel rounding errors 01:16 <Volker_E> MatmaRex: like box-shadows, or border-radius weird effects 01:16 <MatmaRex> oh yeah, that's true, but i personally think that is just hopeless. :) 01:17 <Volker_E> MatmaRex: what hacks upon hacks are you referring to? 01:18 <Volker_E> MatmaRex: hacks to get inherited em in balance again? 01:18 <MatmaRex> yes 01:18 <MatmaRex> in VE, modules/ve-mw/init/styles/ve.init.mw.DesktopArticleTarget-vector.css and similar 01:19 <MatmaRex> Volker_E: there is at least one bug in VE caused by that, if you look closely, the page heading/title is smaller in edit mode. 01:20 <Volker_E> MatmaRex: for a UI (here a theme) where I have full control about root elements `rem` is my best bet from current perspective 01:21 <Volker_E> MatmaRex: for an extension it's much more difficult 01:21 <Volker_E> MatmaRex: did anyone ever look into using px for all browsers aside from IE 01:22 <MatmaRex> Volker_E: no idea. 01:22 <Volker_E> MatmaRex: which would mean that modern zoom applies in modern browsers 01:22 <Volker_E> MatmaRex: but in text-zoom only mode you're targeting size adaption with em... 01:24 <MatmaRex> Volker_E: i don't know. the decision to use ems predates me, it looked reasonable to me and i never questioned it. if anyone knows more about this, it's Trevor 01:26 <Volker_E> MatmaRex: ok, hopefully I've got enough time to prepare some historical anecdotes, code examples and pro&con summaries. ;) That should prob get on the next FE std group list. 01:26 <Volker_E> MatmaRex: Thanks for the insights!

How much of this is actually true?
Looking at core and what seem to be best practices in current extensions and skins, a lot of this just doesn't apply, and sometimes for very good reason. So how much of these conventions are, er, actually correct? -— Isarra ༆ 17:42, 30 October 2015 (UTC)
 * What are "sometimes very good reasons" for not applying on which of the topics? Knowledge and best-practices have to be shared before being applied. And even if they are shared, on best-practices like color name guidelines, there's currently no strict enforcement of those conventions. If you find problems within the current conventions, here on the talk page seems to be a good place to raise them. --VEckl (WMF) (talk) 04:39, 5 November 2015 (UTC)
 * So... this page is supposed to be real? -— Isarra ༆ 07:38, 5 November 2015 (UTC)
 * Well, you know how it is with reality and its perception… it's a wide field. But yes, that's IMHO the place to raise general issues/ideas on best approaches/guidelines around CSS/Less outside of Phabricator. --VEckl (WMF) (talk) 01:28, 6 November 2015 (UTC)

Okay, some things:


 * ''"One space after a starting and before an ending parentheses (( and )) in selectors (ex. :not) and properties (ex. rgba)."
 * This does not apply to any core or extension code I have seen. Why does core not follow this/does this differ here?
 * Yeah it seems like an extension of our 'liberal use of whitespace' convention in JS, but this specifically it's not a current practice anywhere. But I don't mind making it one really. (DJ)
 * So far, there has been mixed notations all around, including whitespace after starting and before ending parentheses. This is a pretty new CSS guideline and it comes from the PHP&JS coding conventions, where we ask and partly enforce the same style and therefore we've targeted at making it easier for MediaWiki PHP developers to dive into CSS. But it's just a guideline and not enforced anywhere yet. Which is very important for the following points as well: In contrast to JavaScript or PHP we allow a lot of freedom by not enforcing developers to write in a certain way. There are voices pro and against stricter (and enforced) rules around CSS/Less – we'll have to weigh in how much those stricter rules might gain us and how much work is needed to make our software environment enforcing those rules. (VE)


 * ''"Quotes are unnecessary in the url parameter"
 * They may be unnecessary in most contexts, but they are simpler to do and a more consistent solution to strange characters, and are also useful for syntax highlighters. Is there any reason to use quotes?
 * In my experience, single quotes are most commonly used.
 * This is a pre-existing practice and followed reasonably well. (DJ)
 * They are superfluous in the context and should (for file size & gzipping purposes be avoided). In my experience, double quotes have been more widely used. But as there are trillions of websites out there and millions of developers, we should agree on one way. The argument for syntax highlighters can be misleading, because for every good syntax highlighter there are ways to customize. This guidelines follows two logical argumentations, size reduction and unification across projects. In a perfect world, we would agree on one way to write  parameters and the best minifier to our needs would make sure, that no quotes land in the output. But that's complicated and given the low importance of this particular issue, it's hard to find resources for it. When there are a big number of developers unhappy with the guideline, we are definitely revisiting the pros and cons. (VE)


 * ''"Repeat the same selector to increase weight, like .foo.foo.foo.foo"
 * ''"Add or repeat attribute selectors, like [class]."
 * Don't do this. This is bad. Even worse than having generally unnecessarily specific selectors in the first place. Which is also bad. (Every subsequent level needs to override it in an even worse fashion than the previous. Don't start something horrible that will then need to be continued... say, on-wiki.)
 * No fan of [class] either, doubling up classnames, I sort of can appreciate as an elegant hack if you want to avoid having to refer to ancestors. (DJ)
 * Good point! Although I don't know the history of that guideline, the major problem must have been that people used  everywhere. And because they have urgent needs, where they are not going to learn CSS in-depth, you won't be able to stop this, therefore the authors came up with so-called better alternatives. What would be your proposal on improving that guideline? (VE)
 * If people need to override something horrible that's already there, it's generally pretty clear how to do that. We don't need to advocate any of these. -— Isarra ༆
 * Well, the reason that the advice is in here might come from the background, that people were not clear how to do that and used  all over the place. Making it harder to override later on. Also, the headline is "Anti-patterns", so it's pretty well-stated first-hand thinking of using those. As I've stated above, I agree that it should be less promoting and changed the selector and the description in the article. --VEckl (WMF) (talk) 19:15, 11 January 2016 (UTC)


 * ''"No quotes around parameter values (same as for url( image.png ) in CSS)"
 * This is important in order to avoid breaking the parameters, not because it is unnecessary.
 * Haven't looked into this myself (DJ)
 * To my knowledge there's just one place, where it is necessary to put parameters in quotes, which is the example directly below. (VE)


 * ''"Mixin names ... should be prefixed with mixin-"
 * No. We do not prefix function names with 'function' in any language; this is inappropriate with mixins too. The syntax is similar for classes, but not the same.
 * I have no objections to this. It's too much praise to call the less syntax a function call here in my opinion. I'd appreciate them standing out more.
 * The Less syntax is weak when looking at mixins. I don't understand why they have to start with a, that makes reading Less code unnecessarily harder. Sass'   or PostCSS'   (the latest and syntactically greatest IMHO) syntax are superior. In different code bases we don't widely use mixin- prefix currently, what would be your idea to standardize and clarify it for new developers? (VE)
 * Why do they need anything special? The fact that it's randomly inline without css inside it (like an actual class would have) should be plenty to distinguish these unless the less is particularly poorly written. -— Isarra ༆


 * ''"If you need to call a mixin with one or more arguments that contain a comma use a semicolon to separate the arguments"
 * This is inconsistent and also partially incorrect: it arbitrarily differs from normal practice (using a comma), and also requires a semicolon at the end as well to actually work when only using a single parameter. Either we should be using semicolons everywhere, or not recommending this at all. Optional parameters are a thing.
 * YUCK YUCK YUCK, this really is the best that less has to offer ? (DJ)
 * I agree, this is not very inviting and not easily graspable. As far as I understand (not being the original author, neither having come across this syntax in daily usage more than once), this is a necessity of Less. So we can't really get around it here?! (VE)

-— Isarra ༆ 03:01, 10 November 2015 (UTC)
 * Original points and opinions by Isarra, 2nd level opinions by —Th e DJ (Not WMF) (talk • contribs) 13:35, 20 November 2015 (UTC)
 * 3rd level opinions by --VEckl (WMF) (talk) 16:14, 5 January 2016 (UTC)
 * Yes. -— Isarra ༆ 20:08, 5 January 2016 (UTC)

Order of declarations
It would be useful to have a coding convention for the order of the declarations in a declaration block. A consisted order improves the gzip compression and makes it easier to find or insert declarations.

The intuitive order is the alphabetical order. A alphabetical order has the disadvantage that it may disrupt declarations that belongs together, especially when there are blocks of comments.

An other possibility would be the order in the CSS specification. But CSS 2 is the last complete specification.

Is it desired to have an order for declarations? --Fomafix (talk) 11:46, 21 December 2015 (UTC)


 * https://css-tricks.com/poll-results-how-do-you-order-your-css-properties/ -— Isarra ༆ 20:22, 5 January 2016 (UTC)
 * I'm in favor of adding a CSS guideline for property order, especially when looking at the growing number of possible CSS properties. Here's one example where missing property order has caused unnecessary property duplication ( : https://phabricator.wikimedia.org/diffusion/MW/browse/wmf%252F1.27.0-wmf.9/resources/src/mediawiki.ui/components/checkbox.less;2cb36350c88ca6cd214ccdf996bdcba33eac94f9$90
 * This is an outcome we definitely don't want to see.


 * The outcomes of the poll results at css-tricks above (45% in favor of grouped by type) are interesting and also the summaries by the author:

<blockquote style="background-color:#eee; padding: .5em 1em;"> I think this is a bigger deal in teams. There has to be a standard otherwise the CSS project-wide looks sloppy. I know that inconsistent styles would wear on my conscience and I'd spend time fixing trivial formatting stuff rather than doing actual work.

Cognitive load factors into this. If you can always count on certain properties being in the same place, you can understand the CSS a bit faster (less scanning). Again, a bigger deal when on a team and you are looking at code you are slightly less familiar with because you didn't write it.
 * I couldn't agree more with those thoughts (emphasizing done by myself).
 * Therefore I'd like to come up with a new proposal for a guideline on CSS property order:

CSS/Less property order proposal
--VEckl (WMF) (talk) 03:48, 10 January 2016 (UTC)
 * 1) Generated content comes first, as content gets priority,
 * 2) Backgrounds (in alphabetical order of sub properties), colors, list-styles as similar to background-images, filter and opacity properties are next, as they are together with box sizing the most used and most altered properties and therefore should be on top of the list
 * 3) Display is next, as it is also a often used and strong property
 * 4) Box Model in order of outside in, so outline > margin > padding > border and min- & max- values before the fixed property value.
 * 5) Typographic values in alphabetical sub order
 * 6) Animations and transitions are last, as they are extending the scope of the styles applied to the element

CSS Property Value Section
I propose to extend the current guidelines by a section "CSS Property Values", where we are recommending specific values, like already done about colors, but also for unit sizes in,   or   or setting shorthand properties   and   always to   when nulling. Example: Time values: --VEckl (WMF) (talk) 19:51, 9 February 2016 (UTC)
 * Use fractional numbers for <time-values> like 0.1s and not 100ms.