Less Guideline

1 Guideline

Less is a CSS pre-processor, meaning that it extends the CSS language, adding features that allow variables, mixins, functions and many other techniques that allow you to make CSS that is more maintainable, themable and extendabl (see: less.org).

Since ILIAS 5.0 Bootstrap 3 is used. With the Design Revision 5.1 the JF decided that Bootstrap Concepts SHOULD be used where possible. One important element of Bootstrap 3 is the usage of less.

1.1 General

• All new CSS-Styles of Modules or Services in ILIAS MUST be written in less.
• You SHOULD consult less.org to make use of the advantages of less.
• Delos.less MUST only contain imports and no other less logic at all.

1.2 Variables

1.2.1 Naming

• All less variables MUST be stored in the variables.less file.
• Less variables MUST be named [il-component-they-are-primarely-used-in-descriptive-functionality-name]. Example: il-modal-body-bg-color. Note the il-prefix, distinguishing this variable from a bootstrap standard variable.
• In the variables.less file, the variables MUST be structured into categories. 
• Variables and Sections MUST use the following template as structure:

//== Name of Category (e.g. Colors)
//
//## Description of Category
 
//** Variable 1 Description
@variable-1-name:   variable-1-value;
//** Breadcrumb background color
@variable-2-name:   variable-2-value;

1.2.2 Colors

• All colors MUST be defined by using variables. In any less file other than variables.less there are therefore only color assignments by directly using a variables allowed. E.g. color: darken(@other-variable, 10%), or color: #564 is not allowed outside variables less.
• In the variables.less file, all new color values MUST be defined in the "Colors" section. Later those values can be reassigned to other variables, but the values MUST NOT be changed anymore. E.g. @il-modal-bg can be defined outside the colors section, but should be assigned directly to a variable from the colors section. E.g. il-modal-bg: @il-primary-container-bg, and not il-modal-bg: darken(@il-primary-container-bg, 15%) or similar.
• Shortforms MUST be used in less and CSS. E.g. #efe, instead of #eeffee.
• Only use lowercase for color codes in less and CSS. E.g. #efe, instead of #EFE.

1.2.3 Customize

• Note that custom variables in a custom variables.less file have the be included after the delos.less file. 
• Also note that in delos, the ilias custom variables are included after all the bootstrap includes. This as to do with the way less assignes values from variables to less content by compiling the less to css. See Lessc.

1.3 Classes

• You SHOULD use Bootstrap classes if possible (see http://getbootstrap.com/ for a documentation of all bootstrap components, classes can be found in the code snippets).
• If new less classes are needed they MUST be named according the following pattern: [il-component-descriptive-name]. Example: il-modal-title. Note the il- prefix distinguishing this class from a standard bootstrap class.

1.4 Attributes

• You SHOULD aim to write as little less as possible. Use existing bootstrap logic if possible.
• If you need to add custom styling, you SHOULD the following ordering for your attributes (see Concentric CSS):

#Concentric-CSS-Overview {
        display: ;    /* Directions about where and how the box is placed */
        position: ;
        float: ;
        clear: ;
 
        visibility: ; /* Next: can the box be seen? */
        opacity: ;
        z-index: ;
 
        margin: ;     /* Layers of the box model, from outside to inside */
        outline: ;
        border: ;
        background: ; /* (padding and content BOTH get the background color) */
        padding: ;
 
        width: ;      /* Content dimensions and scrollbars */
        height: ;
        overflow: ;
 
        color: ;      /* Textual content */
        text: ;
        font: ;
    }

#Concentric-CSS-Complete {
        /* All CSS properties, in roughly the order I use when being careful */
 
        display: ;
        position: ;
        top: ;
        right: ;
        bottom: ;
        left: ;
 
        float: ;
        clear: ;
 
        visibility: ;
        opacity: ;
        z-index: ;
 
        margin: ;
        margin-top: ;
        margin-right: ;
        margin-bottom: ;
        margin-left: ;
 
        outline: ;
 
        border: ;
        border-top: ;
        border-right: ;
        border-bottom: ;
        border-left: ;
 
        border-width: ;
        border-top-width: ;
        border-right-width: ;
        border-bottom-width: ;
        border-left-width: ;
 
        border-style: ;
        border-top-style: ;
        border-right-style: ;
        border-bottom-style: ;
        border-left-style: ;
 
        border-color: ;
        border-top-color: ;
        border-right-color: ;
        border-bottom-color: ;
        border-left-color: ;
 
        background: ;
        background-color: ;
        background-image: ;
        background-repeat: ;
        background-position: ;
        cursor: ;
 
        padding: ;
        padding-top: ;
        padding-right: ;
        padding-bottom: ;
        padding-left: ;
 
        width: ;
        min-width: ;
        max-width: ;
 
        height: ;
        min-height: ;
        max-height: ;
 
        overflow: ;
 
        list-style: ;
        caption-side: ;
 
        table-layout: ;
        border-collapse: ;
        border-spacing: ;
        empty-cells: ;
 
        vertical-align: ;
 
        text-align: ;
        text-indent: ;
        text-transform: ;
        text-decoration: ;
 
        line-height: ;
        word-spacing: ;
        letter-spacing: ;
        white-space: ;
        color: ;
 
        font: ;
        font-family: ;
        font-size: ;
        font-weight: ;
 
        content: ;
        quotes: ;
    }

1.5 Structure

• The less variables file is place in templates/default/less/variables.less
• Less files for centralized UI-Components MUST be placed in src/UI/templates/ComponentName/ComponentName.less
• Less files for existing UI for Modules or Services are stored in templates/default/less/Modules/... (or templates/default/less/Services/...).

1.6 Media

• Media queries SHOULD directly added into the less structure. Delos_sm files are deprecated and MUST NOT be created anymore.
• We currently follow a desktop first approach on the less level. This means, that we handle all mobile cases as special cases and the desktop as the default.
  • You should use: max-width: @grid-float-breakpoint-max instead of min-width: @grid-float-breakpoint (or min-width: @screen-sm-min). With max-width, the mobile version is declared as the special case version (desktop first). 

2 Status

• Effective from release: Release 5.3
  
• Approved by Jour Fixe at: JourFixe-2017-01-16
• Implementation status: { implemented completely | partly implemented | needs implementation }
• Funding for streamlining existing features: { name of organisation }
• Implementation of guideline: { all developers | name of responsible developer }

3 Components that are not compliant with the Guideline

• …

4 Discussion

2016-12-12 Erkens, Jochen [j.erkens]: Since bootstrap 4 changes from LESS to SASS, it could be smart to carry out the change to SASS already now. Bootstrap 3 also works with SASS. The differences are small, but the developers would be spared a new habituation time.

http://blog.getbootstrap.com/2015/08/19/bootstrap-4-alpha/

2016-12-14 Klees, Richard [rklees]: Thanks a lot for this guideline proposal! I discussed it with our Art Director Christoph, this is our feedback and some questions (mostly for curiosity) as well:

• Is the system for structuring the comments some common system? Are there existing tools or documentation for that system out there?
• It would be nice to hint the reader of this guideline to some location where she could find the mentioned bootstrap-classes.
• Although we very much like the Concentric CSS/Less style, we want to at least mention the fact, that Firebug sorts the css-props alphabetically when inspecting elements, which might make it harder to figure out what's going on when debugging or skinning.
• We (Timon and me, this time) already talked about moving the complete skin to one directory in the repo to make it possible at some point to turn the skin into some separate sub-repo which could accept PRs etc. Maybe we should start this move now by moving the less from src/UI/templates to templates. Didn't think about this much, but this came to my mind when reading this guideline proposal.
• Must variables.less be included after bootstrap stuff in delos.less to make it possible to override and use bootstrap vars? If yes, should we mention that in this guideline?
• Please mention the required il-prefix for ILIAS classes and variables more clearly.  This would make it possible to clearly distinguishg between bootstrap and ILIAS stuff.
• We would propose to use a guideline similar to the colors for font-sizes and maybe for spacings as well. We are quite sure that it would be very beneficial for font-sizes, but not so much for spacings. In general, there seems to be a problem on how to present a matrix with the dimensions variables and components in a linear style.
• We think, that only RGB should be used as color system. Is this already implied by the requirement of shortforms for colors?
• Do you see some feasible guideline rule that would allow us to move to relative sizes (em/rem instead of px) completely, gradually or at all? Christoph mentioned this as a painpoint when creating skins for ILIAS that work on different screen sizes. This might start with a rule akin to the color rule which would force all uses of px-sizes to reference some (small) set of variables.

2016-12-19 Amstutz, Timon [amstutz]: Thanks for your feedbacks.

@Jochen: 

• You are right in regard of the change from LESS to SASS. However I think this is easier to communicate and perform if done along with the change to the new bootstrap version. As you point out, the changes will probably doable. 
• Bootstrap4 is in alpha since august 2015. I not sure on how fast they are progresssing. I expect after this alpha phasis a longer beta phasis. I would not decide to shift to Bootstrap4 untill there is a very concrete release date. Especially since there are no immediate issue with bootstrap 3 (except for the awkward handling of navlist and some JS anomalities).
• The work we do now, by ordering our variables will not be lost when we change to SASS.

• Is the system for structuring the comments some common system? <-- Bootstrap uses it as it's ways to document their variables.less file. Other than that, not that I know of. If you know of one, I more than open for it. If not, I recommand to pick one (e.g. the one proposed) and stick with it. If we do that consistently, a later change will be a breeze (e.g. can be performed automatically).
• It would be nice to hint the reader of this guideline to some location where she could find the mentioned bootstrap-classes. <-- Done
• Although we very much like the Concentric CSS/Less style, we want to at least mention the fact, that Firebug sorts the css-props alphabetically when inspecting elements, which might make it harder to figure out what's going on when debugging or skinning. <-- Again, I recommend to pick one, stick with it. Are there better proposals?

2016-12-19 Amstutz, Timon [amstutz]: Continuation.

• We (Timon and me, this time) already talked about moving the complete skin to one directory in the repo to make it possible at some point to turn the skin into some separate sub-repo which could accept PRs etc. Maybe we should start this move now by moving the less from src/UI/templates to templates. Didn't think about this much, but this came to my mind when reading this guideline proposal. <-- I still thin this to be a good proposal. However this would be a proper FR and should not be discussed at this point. Obviously if we decide to change the location, we should update this guideline.
• Must variables.less be included after bootstrap stuff in delos.less to make it possible to override and use bootstrap vars? If yes, should we mention that in this guideline? <-- Done
• Please mention the required il-prefix for ILIAS classes and variables more clearly.  This would make it possible to clearly distinguishg between bootstrap and ILIAS stuff? <-- Done
• We would propose to use a guideline similar to the colors for font-sizes and maybe for spacings as well. We are quite sure that it would be very beneficial for font-sizes, but not so much for spacings. In general, there seems to be a problem on how to present a matrix with the dimensions variables and components in a linear style. <-- Correct. Although we would like to start with the colors first and see, how well our proposals work out and how they are accepted. If this proves to be successfull we extend it the other dimension variables, such as font, spacing, borders etc...
• We think, that only RGB should be used as color system. Is this already implied by the requirement of shortforms for colors? <-- Why? Personally I do not have a strong preference. Hex is slighty shorter to write though. Again, pick one stick with it.
• Do you see some feasible guideline rule that would allow us to move to relative sizes (em/rem instead of px) completely, gradually or at all? Christoph mentioned this as a painpoint when creating skins for ILIAS that work on different screen sizes. This might start with a rule akin to the color rule which would force all uses of px-sizes to reference some (small) set of variables. <-- I am personally afraid of opening to many battle field at one. Bootstrap uses px, but there are ways around that (see: https://gist.github.com/jasny/9731895). Is there a strong prefrence for either em or rem?

Kunkel, Matthias [mkunkel], 16 Jan 2017: We highly appreciate this guideline and schedule it for 5.3. We see today's version as a first version that should be extended step by step. We prefer

• to move to SASS when Bootstrap 4 has been released as stable
• to follow the Concentric CSS pattern
• to have all media queries close to the default rule and not to place them in separate files
• to have this guideline as md file in the delos directory