Skip to content

Latest commit

 

History

History
936 lines (700 loc) · 19 KB

README.md

File metadata and controls

936 lines (700 loc) · 19 KB
Raw

Magento UI library

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 structure

/lib/web/
    ├── css/
    │    ├── docs/ (Library documentation)
    │    │    ├── source/
    │    │    │    ├── _actions-toolbar.less
    │    │    │    ├── _breadcrumbs.less
    │    │    │    ├── _buttons.less
    │    │    │    ├── _dropdowns.less
    │    │    │    ├── _forms.less
    │    │    │    ├── _icons.less
    │    │    │    ├── _layout.less
    │    │    │    ├── _lib.less
    │    │    │    ├── _loaders.less
    │    │    │    ├── _messages.less
    │    │    │    ├── _pages.less
    │    │    │    ├── _popups.less
    │    │    │    ├── _rating.less
    │    │    │    ├── _resets.less
    │    │    │    ├── _responsive.less
    │    │    │    ├── _sections.less
    │    │    │    ├── _tables.less
    │    │    │    ├── _tooltips.less
    │    │    │    ├── _typography.less
    │    │    │    ├── _utilities.less
    │    │    │    ├── _variables.less
    │    │    │    ├── _components.less
    │    │    │    ├── docs.less
    │    │    │    └── README.md
    │    │    ├─── extends.html
    │    │    ├─── actions-toolbar.html
    │    │    ├─── breadcrumbs.html
    │    │    ├─── buttons.html
    │    │    ├─── components.html
    │    │    ├─── docs.css
    │    │    ├─── docs.html
    │    │    ├─── dropdowns.html
    │    │    ├─── forms.html
    │    │    ├─── icons.html
    │    │    ├─── index.html
    │    │    ├─── layout.html
    │    │    ├─── lib.html
    │    │    ├─── loaders.html
    │    │    ├─── messages.html
    │    │    ├─── pages.html
    │    │    ├─── popups.html
    │    │    ├─── rating.html
    │    │    ├─── resets.html
    │    │    ├─── responsive.html
    │    │    ├─── sections.html
    │    │    ├─── tables.html
    │    │    ├─── tooltips.html
    │    │    ├─── typography.html
    │    │    ├─── utilities.html
    │    │    └─── variables.html
    │    └── source/
    │          ├── components/ (Reusable components files)
    │          │    └── _modals.less
    │          ├── lib/ (Library source files)
    │          │    └── variables/ (Decoupled variables)
    │          │          └── ...
    │          │    ├── _extends.less
    │          │    ├── _actions-toolbar.less
    │          │    ├── _breadcrumbs.less
    │          │    ├── _buttons.less
    │          │    ├── _dropdowns.less
    │          │    ├── _forms.less
    │          │    ├── _icons.less
    │          │    ├── _layout.less
    │          │    ├── _lib.less
    │          │    ├── _loaders.less
    │          │    ├── _messages.less
    │          │    ├── _navigation.less
    │          │    ├── _pages.less
    │          │    ├── _popups.less
    │          │    ├── _rating.less
    │          │    ├── _resets.less
    │          │    ├── _responsive.less
    │          │    ├── _sections.less
    │          │    ├── _tables.less
    │          │    ├── _tooltips.less
    │          │    ├── _typography.less
    │          │    ├── _utilities.less
    │          │    └── _variables.less
    │          ├── _extend.less
    │          └── _theme.less
    ├── fonts/
    │    └── Blank-Theme-Icons/ (Library custom icons font)
    ├── images/
    │    └── blank-theme-icons.png (Library icons sprite)
    └── jquery/ (Library javascript files)

 

Magento UI library naming convention

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:

'@' + 'object' + '-' + 'property' + '-' + 'state' = @object-property-state

If it is a private variable (is used only in a mixin), it must start with "_" character after "@":

'@' + '_' + 'object' + '-' + 'property' + '-' + 'state' = @_object-property-state

Examples:

Acceptable:
    @link-color-hover;
    @color-primary;
    @color-2;

Private variables:

    @_padding-left;
    @_font-size;
Unacceptable:
    @Link-Color-Hover;
    @colorPrimary;
    @color--primary;
    @paddingleft;
    @__font-size;

 

Less mixins naming

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.

Examples:

Acceptable:
    .mixin-name() {}
    .transition() {}
    .mixin() {}
    ._button-gradient() {}
Unacceptable:
    .mixinName() {}
    .__transition() {}
    .MiXiN() {}
    ._button--gradient() {}

 

Less Code Standards

General rules

Indentation

Please verified that you use spaces instead tabs:

  • Tab size: 4 spaces
  • Indent size: 4 spaces
  • Continuation indent: 4 spaces
    .nav {
        .nav-item {
            ...
        }
    }

Format

Braces

Add space before opening brace and line break after. And line break before closing brace.

Not recommended:
    .nav{color: @nav__color;}
Recommended:
    .nav {
        color: @nav__color;
    }

Selector delimiters

Add line break after each selector delimiter. Delimeter shouldn't have spaces before and after.

Not recommended:
    .nav, .bar {
        color: @color__base;
    }
Recommended:
    .nav,
    .bar {
        color: @color__base;
    }

Quotes

Use single quotes

Not recommended:
    .nav {
        content: "lorem ipsum";
    }
Recommended:
    .nav {
        content: 'lorem ipsum';
    }

Combinator indents

Use spaces before and after combinators

Not recommended:
    .nav+.bar {
        color: @bar__color;
    }

    .nav +.bar {
        color: @bar__color;
    }

    .nav+ .bar {
        color: @bar__color;
    }
Recommended:
    .nav + .bar {
        color: @bar__color;
    }

Properties line break

Use line break for each property declaration

Not recommended:
    .nav {
        color: @nav__color; background-color: @nav__background-color;
    }
Recommended:
    .nav {
        background-color: @nav__background-color;
        color: @nav__color;
    }

Properties colon indents

Use no space before property colon, and space after

Not recommended:
    .nav {
        color : @nav__color;
    }

    .bar {
        color:@bar__color;
    }

    .item {
        color :@item__color;
    }
Recommended:
    .nav {
        color: @nav__color;
    }

End of file

Each less file should be finished with new line

End of the selector

Each selector should be finished with new line

Not recommended:
    .nav {
        background-color: @nav__background-color;
    }
    .bar {
        background-color: @bar__background-color;
    }
Recommended:
    .nav {
        background-color: @nav__background-color;
    }

    .bar {
        background-color: @bar__background-color;
    }

End of the property line

Each property should be finished with semicolon

Not recommended:
    .nav {
        background-color: @nav__background-color
    }
Recommended:
    .nav {
        background-color: @nav__background-color;
    }

!Important property

Basically avoid use this property at all, but if you really really need it use the following format:

Not recommended:
    .jquery-ui-calendar-item {
        background-color: @nav__background-color!important;
    }
Recommended:
    .jquery-ui-calendar-item {
        background-color: @nav__background-color !important;
    }

Comments

Please follow the next format of comments

    //
    //  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.

Not recommended:
    #foo {
        ...
    }
Recommended:
    .nav {
        ...
    }

    .nav + bar {
        ...
    }

    .nav:not(.bar) {
        ...
    }

Naming

Standard classes

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

Not recommended:
    .footer {
        ...
        .nav {
            ...
            .nav-list {
                ...
                .nav-list-item {
                    ...
                }
            }
        }
    }
Recommended:
    .footer {
        ...
        .nav {
            ...
        }
        .nav-list {
            ...
        }
        .nav-list-item {
            ...
         }
    }

Properties

Sort

Sort all properties alphabetical. Mixins, variables etc. should go first

Not recommended:
    .nav {
        color: @nav__color;
        text-align: center;
        background-color: @nav__background-color;
    }
Recommended:
    .nav {
        background-color: @nav__background-color;
        color: @nav__color;
        text-align: center;
    }

Shorthand

Use shortland properties where possible.

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.

Not recommended:
    border-top-style: none;
    padding-bottom: 2rem;
    padding-left: 1rem;
    padding-right: 1rem;
    padding-top: 0;
Recommended:
    border-top: 0;
    padding: 0 1em 2em;

0 and units

Omit unit specification after "0" values.

Not recommended:
    border-width: 0px;
    margin: 0rem;
Recommended:
    border-width: 0;
    margin: 0;

Floating values

Omit leading "0"s in values, use dot instead

Not recommended:
    margin-left: 0.5rem;
Recommended:
    margin-left: .5rem;

Hexadecimal notation

  • Use lowercase only
  • Use 3 character hexadecimal notation where possible.
  • For color values that permit it, 3 character hexadecimal notation is shorter and more succinct.
  • Also please avoid hex color in properties, use only variables instead.
Not recommended:
    color: #ff0000;
    @nav__color: #FAFAFA;
    @nav-item__color: red;
Recommended:
    @nav__color: #fafafa;
    @nav-item__color: #f00;
    ...
    color: @nav-item__color;

Variables

Location

Local variables

If variables are local and used only in module scope it should be located in module file, on the top of the file with general comment

Example _module.less:

    ...

    //
    //  Variables
    //  _____________________________________________

    //  Colors
    @btn__color: @color-brownie;
    @btn-primary__color: @color-white;
    @btn-secondary__color: @color-white;
    ...

Theme variables

If variables are common for couple modules it should be located in _theme.less file

Global variables

If variables are common for couple themes it should be located in global lib in _variables.less file

Naming

All variables should be written in lowercase.

Value variables

General model is:
    @property-name
Examples:
    @primary__color: @color-phoenix;
    @indent__base: 2rem;
    @border-radius-round: 100%;

Parameter variables

General model is:
    @component-element__state__property__modifier

Please mention that component can be not only element name, it also can be primary, secondary, tertiary Base is a modifier

Examples:
    @color-orange: '';
    @link__hover__color: '';
    @nav-element__background-color: '';
    @secondary__color: '';
    @side-nav__indent__s: '';
    @side-nav-el__background-color: '';
    @side-nav-el__active__background-color: '';
    @side-nav-el__active-focus__background-color: '';
    @side-nav-el__active-focus__font-size__xl: '';
    @text__color__base: '';

Mixins

Location

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__

Example:
    .extend__clearfix (...) {
        ...
    }

    .vendor-prefix__flex-direction (...) {
        ...
    }

Extends

Location

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)