Less coding standard | Adobe Commerce Developer Guide

This standard defines Magento internal requirements for code formatting and style for teams that develop Less and CSS code. TableofContents CodingStandards CodingStandardsCodedemarcationstandardPHPcodingstandardDocBlockstandardJavaScriptcodingstandardJavaScriptDocBlockstandardjQuerywidgetcodingstandardLESScodingstandardHTMLstyleguideContributingTechnicalguidelinesTechnicalvisionWebApi ThisstandarddefinesMagentointernalrequirementsforcodeformattingandstyleforteamsthatdevelopLessandCSScode. SomepartsofMagentocodemightnotcomplywiththiscodingstandardyet,butweareworkingtograduallyimprovethis. Thiscodingstandardisoptionalforthird-partyMagentodevelopers. Generalrules Indentation Useonlyspacesforindentation: Tabsize:4spaces Indentsize:4spaces Continuationindent:4spaces Correct: 1 2 3 4 5 .nav{ .nav-item{ ... } } Formatting Braces Addonespacebeforeopeningbracesandalinebreakafter.Addalinebreakbeforeclosingbraces. Correct: 1 2 3 .nav{ color:@nav__color; } Incorrect: 1 .nav{color:@nav__color;} Selectordelimiters Addalinebreakaftereachselectordelimiter.Donotaddspacesbeforeorafterdelimiters. Correct: 1 2 3 4 .nav, .bar{ color:@color__base; } Incorrect: 1 2 3 .nav,.bar{ color:@color__base; } Quotes Usesinglequotes. Correct: 1 2 3 .nav{ content:'loremipsum'; } Incorrect: 1 2 3 .nav{ content:"loremipsum"; } Combinatorindents Addspacesbeforeandaftercombinators. Correct: 1 2 3 .nav+.bar{ color:@bar__color; } Incorrect: 1 2 3 4 5 6 7 8 9 10 11 .nav+.bar{ color:@bar__color; } .nav+.bar{ color:@bar__color; } .nav+.bar{ color:@bar__color; } Propertieslinebreak Starteachpropertydeclarationinanewline. Correct: 1 2 3 4 .nav{ background-color:@nav__background-color; color:@nav__color; } Incorrect: 1 2 3 .nav{ color:@nav__color;background-color:@nav__background-color; } Propertiescolonindents Addspaceafterbutnotbeforethecolonthatseparatespropertynamesfromvalues. Correct: 1 2 3 .nav{ color:@nav__color; } Incorrect: 1 2 3 4 5 6 7 8 9 10 11 .nav{ color:@nav__color; } .bar{ color:@bar__color; } .item{ color:@item__color; } Endoffile Addablanklineattheendoffile. Endofselector Addablanklineafteraselector. Correct: 1 2 3 4 5 6 7 .nav{ background-color:@nav__background-color; } .bar{ background-color:@bar__background-color; } Incorrect: 1 2 3 4 5 6 .nav{ background-color:@nav__background-color; } .bar{ background-color:@bar__background-color; } Endofthepropertyline Addasemicolonafterproperty. Correct: 1 2 3 .nav{ background-color:@nav__background-color; } Incorrect: 1 2 3 .nav{ background-color:@nav__background-color } !importantproperty Avoidusingthe!importantpropertyifpossible.Ifitisrequired,addaspacebeforetheproperty. Correct: 1 2 3 .jquery-ui-calendar-item{ background-color:@nav__background-color!important; } Incorrect: 1 2 3 .jquery-ui-calendar-item{ background-color:@nav__background-color!important; } Comments Firstandsecondlevelcommentsmustbesurroundedbyemptylines. First,secondandthirdlevelcommentsshouldhavetwospacesafter“//”.Inlinecommentsshouldhaveonespaceafter“//”. Correct: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 // //Firstlevelcomment //_____________________________________________ .nav{ background-color:@nav__background-color; } // //Secondlevelcomment //--------------------------------------------- .nav{ background-color:@nav__background-color; } //Comment .nav{ //Newlinecomment background-color:@nav__background-color;//ToDoUI:todoinlinecomment color:@nav__color;//inlinecomment } Selectors Types Magentosupportsthetwomostrecentversionsofallmajorbrowsers.InternetExplorerissupportedfromversion9andlater. YoucanusealmostallCSS3selectors:descendants,attributes,pseudoclasses,structural,pseudoelements,andsoon. Exception:Avoidtheidselector. Correct: 1 2 3 4 5 6 7 8 9 10 11 .nav{ ... } .nav+bar{ ... } .nav:not(.bar){ ... } Incorrect: 1 2 3 #foo{ ... } ClassesNaming Standardclasses Classnamesshouldbelowercase,startwithaletter(excepthelperclasses),wordsshouldbeseparatedwithdash‘-‘. Correct: 1 2 3 .nav-bar{ ... } Incorrect: 1 2 3 .navBar{ ... } Incorrect:underscoreseparation 1 2 3 .nav_bar{ ... } Helperclasses Helperclassnamesshouldbelowercaseandstartwithunderscore(“_”). SomepartsofMagentocodemightnotcomplywiththisstandardyet.Youmightstillfindhelpernameswithnounderscores.Weareworkingtograduallyremovetheinconsistency. Example: 1 2 3 ._active{ ... } Size Useclassnamesthatareasshortaspossible,butaslongasnecessary. Trytoconveywhatclassisaboutwhilebeingasbriefaspossible. Correct: 1 2 3 .nav-bar{ ... } Incorrect:toolong 1 2 3 .navigation-panel-in-footer{ ... } Incorrect:tooshort 1 2 3 .nvpf{ ... } Meaning Usemeaningful,specificclassnamesthatreflectthepurposeoftheelement.Classnamesshouldnotbepresentationalorcryptic. Correct:specific 1 2 3 4 5 6 .category{ ... } .category-title{ ... } Incorrect:cryptic 1 2 3 .foo-1901{ ... } Incorrect:presentational 1 2 3 4 5 6 7 .button-green{ ... } .clear{ ... } Selectorsnaming Typeselectors Avoidqualifyingclassnameswithtypeselectors. Unlessnecessary(forexamplewithhelperclasses),donotuseelementnamesinconjunctionwithIDsorclasses. Correct: 1 2 3 .error{ ... } Incorrect: 1 2 3 div.error{ ... } Typeselectorsmustbelowercase. Correct: 1 2 3 .nav>li{ ... } Incorrect: 1 2 3 .nav>LI{ ... } Formatting Writeselectorinoneline,donotuseconcatenation. Correct: 1 2 3 .product-list-item{ ... } Incorrect: 1 2 3 4 5 6 7 8 9 .product{ ... &-list{ ... &-item{ ... } } } Nesting Avoidusingmorethanthreelevelsofnesting. Exceptionsarepseudoelementsandstates. Correct: 1 2 3 4 5 6 7 8 9 10 11 12 .footer{ ... .nav{ ... } .nav-list{ ... .nav-list-item{ ... } } } Incorrect: 1 2 3 4 5 6 7 8 9 10 11 12 .footer{ ... .nav{ ... .nav-list{ ... .nav-list-item{ ... } } } } Properties Sorting Sortallpropertiesinthealphabeticalorder.Mixins,variables,andsoonshouldgofirst. Correct: 1 2 3 4 5 .nav{ background-color:@nav__background-color; color:@nav__color; text-align:center; } Incorrect: 1 2 3 4 5 .nav{ color:@nav__color; text-align:center; background-color:@nav__background-color; } Shorthand Useshorthandpropertieswherepossible. CSSoffersavarietyofshorthandpropertiesthatshouldbeusedwheneverpossible,evenincaseswhereonlyonevalueisexplicitlyset. Correct: 1 2 border-top:0; padding:01em2em; Incorrect: 1 2 3 4 5 border-top-style:none; padding-bottom:2rem; padding-left:1rem; padding-right:1rem; padding-top:0; 0andunits Donotspecifyunits“0”value. Correct: 1 2 border-width:0; margin:0; Incorrect: 1 2 border-width:0px; margin:0rem; Floatingvalues Omitleading“0”sinvalues,usedotinstead. Correct: 1 margin-left:.5rem; Incorrect: 1 margin-left:0.5rem; Hexadecimalnotation Uselowercaseonly. Usethree-characterhexadecimalnotationwherepossible. Avoidusinghexadecimalvaluesforcolorinproperties,useonlyvariablesinstead. Correct: 1 2 3 4 @nav__color:#fafafa; @nav-item__color:#f00; ... color:@nav-item__color; Incorrect: 1 2 3 color:#ff0000; @nav__color:#FAFAFA; @nav-item__color:red; Variables Location Localvariables Ifvariablesarelocalandusedonlyinamodulescope,theyshouldbelocatedinthemodulefile,inthebeginningofthegeneralcomment. Example:_module.less: 1 2 3 4 5 6 7 8 9 10 11 ... // //Variables //_____________________________________________ //Colors @btn__color:@color-brownie; @btn-primary__color:@color-white; @btn-secondary__color:@color-white; ... Themevariables Ifvariablesarecommonforseveralmodulestheyshouldbespecifiedinthe_theme.lessfile. Naming Allvariablenamesmustbelowercase. Valuevariables Generalmodelisthefollowing: 1 @property-name Examples: 1 2 3 @primary__color:@color-phoenix; @indent__base:2rem; @border-radius-round:100%; Parametervariables Generalmodelisthefollowing: 1 @component-element__state__property__modifier Componentnamemustmeaningful.Itcancontaintheprimary,secondary,tertiarynames. baseisamodifier. Examples: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 @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 Thememixins(exceptextends)shouldbelocatedintheweb/css/sourcedirectory.Formoredetails,refertoCssTheme. Naming Formixinnamingapplytheclassnamingrules. Formixinsgroupingusethedoubleunderscore“__”prefix. TherearecommonsituationswhendifferentelementsuseasimilarsetofCSSproperties. Ina.cssfile,propertiesareduplicatedforeachelement.Ina.lessfile,itisdonebyreusingtheCSSrule-usingmixins. Forexample,manyelementsonthepageusethesameanimation.Forthis,createan.animation-1classwithasetofanimationproperties: Example: 1 2 3 4 5 6 7 .extend__clearfix(...){ ... } .vendor-prefix__flex-direction(...){ ... } 1 2 3 4 5 6 .animation-1{ transition:300msease-in-out; -moz-transition:300msease-in-out; -webkit-transition:300msease-in-out; -o-transition:300msease-in-out; } Andthenapplythismixinwherenecessary: 1 2 3 4 .example-1{ .animation-1(); width:100%; } Aftercompilingthe.lessfileintoa.cssfile,the.example-1elementhasthefollowing: 1 2 3 4 5 6 7 8 9 10 11 12 13 .animation-1{ transition:300msease-in-out; -moz-transition:300msease-in-out; -webkit-transition:300msease-in-out; -o-transition:300msease-in-out; } .example-1{ transition:300msease-in-out; -moz-transition:300msease-in-out; -webkit-transition:300msease-in-out; -o-transition:300msease-in-out; width:100%; } Mixinswithparameters Mixinsalsoacceptparameters.Whencallingthesemixins,theseparametervaluesarepassedin.Whencreatingthistypeofmixin,alwayssetdefaultvalues,sinceissuesmayoccurwhencallingthemixinwithoutspecifyingtheparametervalue.Theexamplebelowshowshowtocreateamixinwithparametersbasedontheexampleaboveandshowshowtocallit: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 .animation-1( @animation-speed:300ms, @animation-type:ease-in-out ){ transition:@animation-speed@animation-type; -moz-transition:@animation-speed@animation-type; -webkit-transition:@animation-speed@animation-type; -o-transition:@animation-speed@animation-type; } .example-1{ .animation-1( @animation-speed:1500ms ); } Mixinparametersaresetinparentheseswithdefaultvalues. Whencallingamixininparentheses,settherequiredvalueofthemixinparameters,iftheydifferfromthedefaultvalues. Aftercompilingthe.lessfileintoa.cssfile,the.example-1elementwillhavethefollowing: 1 2 3 4 5 6 .example-1{ transition:1500msease-in-out; -moz-transition:1500msease-in-out; -webkit-transition:1500msease-in-out; -o-transition:1500msease-in-out; } Extends Location Localextendsusedonlyinonefile,shouldbespecifiedinthisfile. Extendsthatareusedinseveralfilesshouldbespecifiedinthetheme’ssource/_extend.lessfile. Naming Extendnamesshouldstartwiththe.abs-prefix. @importdirective Alwaysaddthefileextensionoftheimportedresource. Correct: 1 2 @import'source/lib/_lib.less'; @import(css)'styles.css'; Incorrect: 1 2 @import'source/lib/_lib'; @import(css)'styles'; Usesinglequotes. Correct: 1 @import'source/lib/_lib.less'; Incorrect: 1 @import"source/lib/_lib.less"; BecomeaContributor Glossary PrivacyPolicy TermsofService License/TrademarkFAQ ReleaseNotes Third-PartyLicenses ©2022Adobe.Allrightsreserved.