The Magento UI library is a flexible modular Magento frontend library that is designed to assist Magento theme developers. It employs a set of mixins for base elements to ease frontend theme development and customization. The Magento UI library offers the following characteristics for those who develop or customize Magento themes. It is:
Built on LESS preprocessor
Focused on web standards
Customizable
Easy to maintain
Responsive
Accessible
The library provides the ability to customize all of the following user interface elements:
actions-toolbar
breadcrumbs
buttons
components
drop-downs
forms
icons
layout
loaders
messages
pagination
popups
ratings
resets
responsive
sections - tabs and accordions
tables
tooltips
typography
utilities
list of theme variables
Magento UI library file structure
Magento UI library is located under /lib/web/ folder. It and employs:
css/ folder where the library files are placed
fonts/ folder where default and icon fonts are placed
images/ folder where default images are placed
jquery/ folder where jQuery and jQuery widgets are placed
Magento UI library employs a variables and mixins naming convention whereby names of variables and mixins describe their purpose or functions they perform.
A variable or a mixins name may only contain lowercase alphanumeric characters, "-" and "_" characters. A variable name must start with "@" character.
If a variable or mixins name consists of more than one word, they must be concatenated with one hyphen character.
Less variables naming
A *.less file variable can contain lowercase letters, numbers, special characters: "@", "-" and "_". It must start with "@" character and consist of words concatenated with one hyphen. It should not contain capital letters. A variable name should describe its purpose.
A variable name should be formed according to the following rule:
A less mixin name can contain lowercase letters, numbers, "-" and "_" characters. It should not contain capital letters.
A mixin name can consist of one or several words, concatenated with one hyphen. If the mixin is private, its name must start with the "_" character. Mixin should be named after property or action it describes.
//
// First level comment
// _____________________________________________
.nav {
background-color: @nav__background-color;
}
//
// Second level comment
// ---------------------------------------------
.nav {
background-color: @nav__background-color;
}
// Comment
.nav {
// New line comment
background-color: @nav__background-color; // ToDo UI: todo inline comment
color: @nav__color; // inline comment
}
Selectors
Types
According to browser support standards the oldest browser that we support is IE9+, it means that you can feel free to use almost all CSS3 selectors: descendants, attributes, pseudo classes, structural, pseudo elements, etc.
Exeption: Please avoid to use id selector.
All classes should be written in lowercase, starts with letter (exept helpers), words in classes should be separated with dash (minus sign '-')
Not recommended:
.navBar {
...
}
Not recommended: underscore separation
.nav_bar {
...
}
Recommended:
.nav-bar {
...
}
Helper classes
Helper classes should be written in lowercase, starts with underscore ("_")
Example:
._active {
...
}
Size
Use class names that are as short as possible but as long as necessary.
Try to convey what class is about while being as brief as possible.
Using class names this way contributes to acceptable levels of understandability and code efficiency.
Not recommended: too long
.navigation-panel-in-footer {
...
}
Not recommended: too short
.nvpf {
...
}
Recommended:
.nav-bar {
...
}
Writing
Write selector name together in single line, don't use concatenation
Not recommended:
.product {
...
&-list {
...
&-item {
...
}
}
}
Recommended:
.product-list-item {
...
}
Meaning
Use meaningful or generic class names.
Instead of presentational or cryptic names, always use class names that reflect the purpose of the element in question, or that are otherwise generic.
Names that are specific and reflect the purpose of the element should be preferred as these are most understandable and the least likely to change.
Generic names are simply a fallback for elements that have no particular or no meaning different from their siblings. They are typically needed as “helpers.”
Using functional or generic names reduces the probability of unnecessary document or template changes.
Not recommended:
.foo-1901 {
...
}
Not recommended: presentational
.button-green {
...
}
.clear {
...
}
Recommended: specific
.category {
...
}
.category-title {
...
}
Type selectors
Avoid qualifying class names with type selectors.
Unless necessary (for example with helper classes), do not use element names in conjunction with IDs or classes.
Avoiding unnecessary ancestor selectors is useful for performance reasons.
Not recommended:
div.error {
...
}
Recommended:
.error {
...
}
Use type selectors in lowercase
Not recommended:
.nav > LI {
...
}
Recommended:
.nav > li {
...
}
Nesting
Be careful with selectors nesting. In general try to use 3 nested levels as max.
Exception are pseudo elements and states
CSS offers a variety of shorthand properties (like font) that should be used whenever possible, even in cases where only one value is explicitly set.
Using shorthand properties is useful for code efficiency and understandability.
Theme mixins (except extends) should be saved in source/utilities folder
Extends that used in more than one theme should be saved in lib lib/source/utilities.less (will be separated into utilities folder)
Naming
In name creation you can follow the same rules as for the creation of class names.
For mixins grouping use prefix__
Local extends that used only in one file, should be written in this local file.
Extends that used in more than two files should be saved in theme source/_extend.less
Extends that used in more than one theme should be saved in lib lib/source/_abstract.less (will be renamed to _extend.less)
Naming
Extend class names should have prefix .abs- (from abstract)