{"id":22235620,"url":"https://github.com/rafaelstz/magento-2-ui-library","last_synced_at":"2025-04-11T13:14:08.948Z","repository":{"id":138552903,"uuid":"79822816","full_name":"rafaelstz/Magento-2-UI-library","owner":"rafaelstz","description":"⚡ Magento 2 UI library is a flexible modular Magento frontend library that is designed to assist Magento theme developers.","archived":false,"fork":false,"pushed_at":"2025-02-10T18:58:56.000Z","size":1029,"stargazers_count":9,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-05T09:38:36.666Z","etag":null,"topics":["frontend","magento2","magento2-theme","theme-development"],"latest_commit_sha":null,"homepage":"http://magento2-ui-library.rafaelcg.com/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rafaelstz.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-23T16:26:50.000Z","updated_at":"2025-03-23T09:29:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"e4007dd8-df56-420b-b64a-f0e870d58719","html_url":"https://github.com/rafaelstz/Magento-2-UI-library","commit_stats":null,"previous_names":["rafaelstz/magento-2-ui-library"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafaelstz%2FMagento-2-UI-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafaelstz%2FMagento-2-UI-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafaelstz%2FMagento-2-UI-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafaelstz%2FMagento-2-UI-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rafaelstz","download_url":"https://codeload.github.com/rafaelstz/Magento-2-UI-library/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248406391,"owners_count":21098208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["frontend","magento2","magento2-theme","theme-development"],"created_at":"2024-12-03T02:14:19.671Z","updated_at":"2025-04-11T13:14:08.925Z","avatar_url":"https://github.com/rafaelstz.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Magento UI library\n\nThe 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:\n\n* Built on LESS preprocessor\n* Focused on web standards\n* Customizable\n* Easy to maintain\n* Responsive\n* Accessible\n\nThe library provides the ability to customize all of the following user interface elements:\n\n* actions-toolbar\n* breadcrumbs\n* buttons\n* components\n* drop-downs\n* forms\n* icons\n* layout\n* loaders\n* messages\n* pagination\n* popups\n* ratings\n* resets\n* responsive\n* sections -  tabs and accordions\n* tables\n* tooltips\n* typography\n* utilities\n* list of theme variables\n\n# Magento UI library file structure\nMagento UI library is located under `/lib/web/` folder. It and employs:\n* `css/` folder where the library files are placed\n* `fonts/` folder where default and icon fonts are placed\n* `images/` folder where default images are placed\n* `jquery/` folder where jQuery and jQuery widgets are placed\n\n### Magento UI library structure\n\n```css\n/lib/web/\n    ├── css/\n    │    ├── docs/ (Library documentation)\n    │    │    ├── source/\n    │    │    │    ├── _actions-toolbar.less\n    │    │    │    ├── _breadcrumbs.less\n    │    │    │    ├── _buttons.less\n    │    │    │    ├── _dropdowns.less\n    │    │    │    ├── _forms.less\n    │    │    │    ├── _icons.less\n    │    │    │    ├── _layout.less\n    │    │    │    ├── _lib.less\n    │    │    │    ├── _loaders.less\n    │    │    │    ├── _messages.less\n    │    │    │    ├── _pages.less\n    │    │    │    ├── _popups.less\n    │    │    │    ├── _rating.less\n    │    │    │    ├── _resets.less\n    │    │    │    ├── _responsive.less\n    │    │    │    ├── _sections.less\n    │    │    │    ├── _tables.less\n    │    │    │    ├── _tooltips.less\n    │    │    │    ├── _typography.less\n    │    │    │    ├── _utilities.less\n    │    │    │    ├── _variables.less\n    │    │    │    ├── _components.less\n    │    │    │    ├── docs.less\n    │    │    │    └── README.md\n    │    │    ├─── extends.html\n    │    │    ├─── actions-toolbar.html\n    │    │    ├─── breadcrumbs.html\n    │    │    ├─── buttons.html\n    │    │    ├─── components.html\n    │    │    ├─── docs.css\n    │    │    ├─── docs.html\n    │    │    ├─── dropdowns.html\n    │    │    ├─── forms.html\n    │    │    ├─── icons.html\n    │    │    ├─── index.html\n    │    │    ├─── layout.html\n    │    │    ├─── lib.html\n    │    │    ├─── loaders.html\n    │    │    ├─── messages.html\n    │    │    ├─── pages.html\n    │    │    ├─── popups.html\n    │    │    ├─── rating.html\n    │    │    ├─── resets.html\n    │    │    ├─── responsive.html\n    │    │    ├─── sections.html\n    │    │    ├─── tables.html\n    │    │    ├─── tooltips.html\n    │    │    ├─── typography.html\n    │    │    ├─── utilities.html\n    │    │    └─── variables.html\n    │    └── source/\n    │          ├── components/ (Reusable components files)\n    │          │    └── _modals.less\n    │          ├── lib/ (Library source files)\n    │          │    └── variables/ (Decoupled variables)\n    │          │          └── ...\n    │          │    ├── _extends.less\n    │          │    ├── _actions-toolbar.less\n    │          │    ├── _breadcrumbs.less\n    │          │    ├── _buttons.less\n    │          │    ├── _dropdowns.less\n    │          │    ├── _forms.less\n    │          │    ├── _icons.less\n    │          │    ├── _layout.less\n    │          │    ├── _lib.less\n    │          │    ├── _loaders.less\n    │          │    ├── _messages.less\n    │          │    ├── _navigation.less\n    │          │    ├── _pages.less\n    │          │    ├── _popups.less\n    │          │    ├── _rating.less\n    │          │    ├── _resets.less\n    │          │    ├── _responsive.less\n    │          │    ├── _sections.less\n    │          │    ├── _tables.less\n    │          │    ├── _tooltips.less\n    │          │    ├── _typography.less\n    │          │    ├── _utilities.less\n    │          │    └── _variables.less\n    │          ├── _extend.less\n    │          └── _theme.less\n    ├── fonts/\n    │    └── Blank-Theme-Icons/ (Library custom icons font)\n    ├── images/\n    │    └── blank-theme-icons.png (Library icons sprite)\n    └── jquery/ (Library javascript files)\n\n```\n\u0026nbsp;\n\n# Magento UI library naming convention\n\nMagento UI library employs a variables and mixins naming convention whereby names of variables and mixins describe their purpose or functions they perform.\n\nA variable or a mixins name may only contain lowercase alphanumeric characters, \"-\" and \"_\" characters. A variable name must start with \"@\" character.\n\nIf a variable or mixins name consists of more than one word, they must be concatenated with one hyphen character.\n\n# Less variables naming\n\nA *.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.\n\nA variable name should be formed according to the following rule:\n\n`'@' + 'object' + '-' + 'property' + '-' + 'state' = @object-property-state`\n\nIf it is a private variable (is used only in a mixin), it must start with \"_\" character after \"@\":\n\n`'@' + '_' + 'object' + '-' + 'property' + '-' + 'state' = @_object-property-state`\n\n#### Examples:\n\n##### Acceptable:\n\n```css\n    @link-color-hover;\n    @color-primary;\n    @color-2;\n```\n\nPrivate variables:\n\n```css\n    @_padding-left;\n    @_font-size;\n```\n\n##### Unacceptable:\n\n```css\n    @Link-Color-Hover;\n    @colorPrimary;\n    @color--primary;\n    @paddingleft;\n    @__font-size;\n```\n\u0026nbsp;\n\n# Less mixins naming\n\nA less mixin name can contain lowercase letters, numbers, \"-\" and \"_\" characters. It should not contain capital letters.\n\nA 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.\n\n#### Examples:\n\n##### Acceptable:\n```css\n    .mixin-name() {}\n    .transition() {}\n    .mixin() {}\n    ._button-gradient() {}\n```\n##### Unacceptable:\n```css\n    .mixinName() {}\n    .__transition() {}\n    .MiXiN() {}\n    ._button--gradient() {}\n```\n\u0026nbsp;\n\n# Less Code Standards\n\n## General rules\n\n### Indentation\n\nPlease verified that you use spaces instead tabs:\n\n* Tab size: 4 spaces\n* Indent size: 4 spaces\n* Continuation indent: 4 spaces\n\n```css\n    .nav {\n        .nav-item {\n            ...\n        }\n    }\n```\n\n### Format\n\n#### Braces\n\nAdd space before opening brace and line break after. And line break before closing brace.\n\n##### Not recommended:\n```css\n    .nav{color: @nav__color;}\n```\n\n##### Recommended:\n\n```css\n    .nav {\n        color: @nav__color;\n    }\n```\n\n#### Selector delimiters\n\nAdd line break after each selector delimiter. Delimeter shouldn't have spaces before and after.\n\n##### Not recommended:\n\n```css\n    .nav, .bar {\n        color: @color__base;\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav,\n    .bar {\n        color: @color__base;\n    }\n```\n\n#### Quotes\n\nUse single quotes\n\n##### Not recommended:\n\n```css\n    .nav {\n        content: \"lorem ipsum\";\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav {\n        content: 'lorem ipsum';\n    }\n```\n\n#### Combinator indents\n\nUse spaces before and after combinators\n\n##### Not recommended:\n\n```css\n    .nav+.bar {\n        color: @bar__color;\n    }\n\n    .nav +.bar {\n        color: @bar__color;\n    }\n\n    .nav+ .bar {\n        color: @bar__color;\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav + .bar {\n        color: @bar__color;\n    }\n```\n\n#### Properties line break\n\nUse line break for each property declaration\n\n##### Not recommended:\n\n```css\n    .nav {\n        color: @nav__color; background-color: @nav__background-color;\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav {\n        background-color: @nav__background-color;\n        color: @nav__color;\n    }\n```\n\n#### Properties colon indents\n\nUse no space before property colon, and space after\n\n##### Not recommended:\n\n```css\n    .nav {\n        color : @nav__color;\n    }\n\n    .bar {\n        color:@bar__color;\n    }\n\n    .item {\n        color :@item__color;\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav {\n        color: @nav__color;\n    }\n```\n\n#### End of file\n\nEach less file should be finished with new line\n\n#### End of the selector\n\nEach selector should be finished with new line\n\n##### Not recommended:\n\n```css\n    .nav {\n        background-color: @nav__background-color;\n    }\n    .bar {\n        background-color: @bar__background-color;\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav {\n        background-color: @nav__background-color;\n    }\n\n    .bar {\n        background-color: @bar__background-color;\n    }\n```\n\n#### End of the property line\n\nEach property should be finished with semicolon\n\n##### Not recommended:\n\n```css\n    .nav {\n        background-color: @nav__background-color\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav {\n        background-color: @nav__background-color;\n    }\n```\n\n#### !Important property\n\nBasically avoid use this property at all, but if you really really need it use the following format:\n\n##### Not recommended:\n\n```css\n    .jquery-ui-calendar-item {\n        background-color: @nav__background-color!important;\n    }\n```\n\n##### Recommended:\n\n```css\n    .jquery-ui-calendar-item {\n        background-color: @nav__background-color !important;\n    }\n```\n\n### Comments\n\nPlease follow the next format of comments\n\n```css\n    //\n    //  First level comment\n    //  _____________________________________________\n\n    .nav {\n        background-color: @nav__background-color;\n    }\n\n    //\n    //  Second level comment\n    //  ---------------------------------------------\n\n    .nav {\n        background-color: @nav__background-color;\n    }\n\n    //  Comment\n    .nav {\n        //  New line comment\n        background-color: @nav__background-color; // ToDo UI: todo inline comment\n        color: @nav__color; // inline comment\n    }\n```\n\n### Selectors\n\n#### Types\n\nAccording 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.\nExeption: Please avoid to use id selector.\n\n##### Not recommended:\n\n```css\n    #foo {\n        ...\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav {\n        ...\n    }\n\n    .nav + bar {\n        ...\n    }\n\n    .nav:not(.bar) {\n        ...\n    }\n```\n\n### Naming\n\n#### Standard classes\n\nAll classes should be written in lowercase, starts with letter (exept helpers), words in classes should be separated with dash (minus sign '-')\n\n##### Not recommended:\n\n```css\n    .navBar {\n       ...\n    }\n```\n\n##### Not recommended: underscore separation\n\n```css\n    .nav_bar {\n       ...\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav-bar {\n        ...\n    }\n```\n\n#### Helper classes\n\nHelper classes should be written in lowercase, starts with underscore (\"_\")\n\n##### Example:\n\n```css\n    ._active {\n        ...\n    }\n```\n\n### Size\n\nUse class names that are as short as possible but as long as necessary.\nTry to convey what class is about while being as brief as possible.\nUsing class names this way contributes to acceptable levels of understandability and code efficiency.\n\n##### Not recommended: too long\n\n```css\n\n    .navigation-panel-in-footer {\n       ...\n    }\n```\n\n##### Not recommended: too short\n\n```css\n    .nvpf {\n       ...\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav-bar {\n        ...\n    }\n```\n\n### Writing\n\nWrite selector name together in single line, don't use concatenation\n\n##### Not recommended:\n```css\n    .product {\n        ...\n        \u0026-list {\n            ...\n            \u0026-item {\n                ...\n            }\n        }\n    }\n```\n\n##### Recommended:\n\n```css\n    .product-list-item {\n        ...\n    }\n```\n\n### Meaning\n\n**Use meaningful or generic class names.**\n\nInstead of presentational or cryptic names, always use class names that reflect the purpose of the element in question, or that are otherwise generic.\nNames that are specific and reflect the purpose of the element should be preferred as these are most understandable and the least likely to change.\nGeneric names are simply a fallback for elements that have no particular or no meaning different from their siblings. They are typically needed as “helpers.”\nUsing functional or generic names reduces the probability of unnecessary document or template changes.\n\n##### Not recommended:\n```css\n    .foo-1901 {\n        ...\n    }\n```\n\n##### Not recommended: presentational\n\n```css\n    .button-green {\n       ...\n    }\n\n    .clear {\n       ...\n    }\n```\n\n##### Recommended: specific\n\n```css\n    .category {\n        ...\n    }\n    .category-title {\n        ...\n    }\n```\n\n### Type selectors\n\n**Avoid qualifying class names with type selectors.**\n\nUnless necessary (for example with helper classes), do not use element names in conjunction with IDs or classes.\nAvoiding unnecessary ancestor selectors is useful for performance reasons.\n\n##### Not recommended:\n\n```css\n    div.error {\n       ...\n    }\n```\n\n##### Recommended:\n\n```css\n    .error {\n        ...\n    }\n```\n\nUse type selectors in lowercase\n\n##### Not recommended:\n\n```css\n    .nav \u003e LI {\n       ...\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav \u003e li {\n        ...\n    }\n```\n\n### Nesting\n\nBe careful with selectors nesting. In general try to use 3 nested levels as max.\nException are pseudo elements and states\n\n##### Not recommended:\n\n```css\n    .footer {\n        ...\n        .nav {\n            ...\n            .nav-list {\n                ...\n                .nav-list-item {\n                    ...\n                }\n            }\n        }\n    }\n```\n\n##### Recommended:\n\n```css\n    .footer {\n        ...\n        .nav {\n            ...\n        }\n        .nav-list {\n            ...\n        }\n        .nav-list-item {\n            ...\n         }\n    }\n```\n\n## Properties\n\n### Sort\n\nSort all properties alphabetical. Mixins, variables etc. should go first\n\n##### Not recommended:\n\n```css\n    .nav {\n        color: @nav__color;\n        text-align: center;\n        background-color: @nav__background-color;\n    }\n```\n\n##### Recommended:\n\n```css\n    .nav {\n        background-color: @nav__background-color;\n        color: @nav__color;\n        text-align: center;\n    }\n```\n\n### Shorthand\n\nUse shortland properties where possible.\n\nCSS offers a variety of shorthand properties (like font) that should be used whenever possible, even in cases where only one value is explicitly set.\nUsing shorthand properties is useful for code efficiency and understandability.\n\n##### Not recommended:\n\n```css\n    border-top-style: none;\n    padding-bottom: 2rem;\n    padding-left: 1rem;\n    padding-right: 1rem;\n    padding-top: 0;\n```\n\n ##### Recommended:\n\n```css\n    border-top: 0;\n    padding: 0 1em 2em;\n```\n\n### 0 and units\n\nOmit unit specification after \"0\" values.\n\n##### Not recommended:\n\n```css\n    border-width: 0px;\n    margin: 0rem;\n```\n\n##### Recommended:\n\n```css\n    border-width: 0;\n    margin: 0;\n```\n\n### Floating values\n\nOmit leading \"0\"s in values, use dot instead\n\n##### Not recommended:\n\n```css\n    margin-left: 0.5rem;\n```\n\n##### Recommended:\n\n```css\n    margin-left: .5rem;\n```\n\n### Hexadecimal notation\n\n* Use lowercase only\n* Use 3 character hexadecimal notation where possible.\n* For color values that permit it, 3 character hexadecimal notation is shorter and more succinct.\n* Also please avoid hex color in properties, use only variables instead.\n\n##### Not recommended:\n\n```css\n    color: #ff0000;\n    @nav__color: #FAFAFA;\n    @nav-item__color: red;\n```\n\n##### Recommended:\n\n```css\n    @nav__color: #fafafa;\n    @nav-item__color: #f00;\n    ...\n    color: @nav-item__color;\n```\n\n## Variables\n\n### Location\n\n#### Local variables\n\nIf 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\n\nExample **_module.less**:\n```css\n    ...\n\n    //\n    //  Variables\n    //  _____________________________________________\n\n    //  Colors\n    @btn__color: @color-brownie;\n    @btn-primary__color: @color-white;\n    @btn-secondary__color: @color-white;\n    ...\n```\n\n#### Theme variables\n\nIf variables are common for couple modules it should be located in **_theme.less** file\n\n#### Global variables\n\nIf variables are common for couple themes it should be located in global lib in **_variables.less** file\n\n### Naming\n\nAll variables should be written in lowercase.\n\n#### Value variables\n\n##### General model is:\n\n```css\n    @property-name\n```\n\n##### Examples:\n\n```css\n    @primary__color: @color-phoenix;\n    @indent__base: 2rem;\n    @border-radius-round: 100%;\n```\n\n#### Parameter variables\n\n##### General model is:\n\n```css\n    @component-element__state__property__modifier\n```\n\nPlease mention that component can be not only element name, it also can be primary, secondary, tertiary\nBase is a modifier\n\n##### Examples:\n\n```css\n    @color-orange: '';\n    @link__hover__color: '';\n    @nav-element__background-color: '';\n    @secondary__color: '';\n    @side-nav__indent__s: '';\n    @side-nav-el__background-color: '';\n    @side-nav-el__active__background-color: '';\n    @side-nav-el__active-focus__background-color: '';\n    @side-nav-el__active-focus__font-size__xl: '';\n    @text__color__base: '';\n```\n\n## Mixins\n\n### Location\n\nTheme mixins (except extends) should be saved in **source/utilities** folder\nExtends that used in more than one theme should be saved in lib **lib/source/utilities.less** (will be separated into utilities folder)\n\n### Naming\n\nIn name creation you can follow the same rules as for the creation of class names.\nFor mixins grouping use prefix__\n\n##### Example:\n\n```css\n    .extend__clearfix (...) {\n        ...\n    }\n\n    .vendor-prefix__flex-direction (...) {\n        ...\n    }\n```\n\n## Extends\n\n### Location\n\nLocal extends that used only in one file, should be written in this **local file**.\nExtends that used in more than two files should be saved in theme **source/_extend.less**\nExtends that used in more than one theme should be saved in lib **lib/source/_abstract.less** (will be renamed to _extend.less)\n\n### Naming\n\nExtend class names should have prefix **.abs-** (from abstract)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafaelstz%2Fmagento-2-ui-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frafaelstz%2Fmagento-2-ui-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafaelstz%2Fmagento-2-ui-library/lists"}