The Obvious Corporation uses LESS as its CSS preprocessor. It's helpful to become familiar with its dynamic behavior before reading these guidelines.
Classes and IDs are lowercase with words separated by a dash:
Right:
.user-profile {}
.post-header {}
#top-navigation {}Wrong:
.userProfile {}
.postheader {}
#top_navigation {}Image file names are lowercase with words separated by a dash:
Right:
icon-home.png
Wrong:
iconHome.png
icon_home.png
iconhome.png
Image file names are prefixed with their usage.
Right:
icon-home.png
bg-container.jpg
bg-home.jpg
sprite-top-navigation.png
Wrong:
home-icon.png
container-background.jpg
bg.jpg
top-navigation.png
You should almost never need to use IDs. Broken behavior due to ID collisions are hard to track down and annoying.
When implementing feature styles, you should only be using color variables provided by colors.less.
When adding a color variable to colors.less, using RGB and RGBA color units are preferred over hex, named, HSL, or HSLA values.
Right:
rgb(50, 50, 50);
rgba(50, 50, 50, 0.2);Wrong:
#FFF;
#FFFFFF;
white;
hsl(120, 100%, 50%);
hsla(120, 100%, 50%, 1);Please use the z-index scale defined in z-index.less. @z-index-1 - @z-index-9 are provided. @z-index-9 is the kill -9 of our z-index scale and really should never be used.
With the additional support of web fonts font-weight plays a more important role than it once did. Different font weights will render typefaces specifically created for that weight, unlike the old days where bold could be just an algorithm to fatten a typeface. Obvious uses the numerical value of font-weight to enable the best representation of a typeface. The following table is a guide:
Raw font weights should not be specified. Instead, use the appropriate font mixin: .wf-sans-i7, .wf-sans-n7, etc.
The suffix defines the weight and style:
n = normal
i = italic
4 = normal font-weight
7 = bold font-weightRefer to type.less for type size, letter-spacing, and line height. Raw sizes, spaces, and line heights should be avoided outside of type.less.
ex:
@type-micro
@type-smallest
@type-smaller
@type-small
@type-base
@type-large
@type-larger
@type-largest
@type-jumboSee Mozilla Developer Network — font-weight for further reading.
Always look to abstract components. Medium has a very strong, very consistent style and the reuse of components across designs helps to improve this consistency at an implementation level.
A name like .homepage-nav limits its use. Instead think about writing styles in such a way that they can be reused in other parts of the app. Instead of .homepage-nav, try instead .nav or .nav-bar. Ask yourself if this component could be reused in another context (chances are it could!).
Components should belong to their own less file. For example, all general button definitions should belong in buttons.less.
Name-spacing is great! But it should be done at a component level – never at a page level.
Also, namespacing should be made at a descriptive, functional level. Not at a page location level. For example, .profile-header could become .header-hero-unit.
Wrong:
.nav,
.home-nav,
.profile-nav,Right:
.nav,
.nav-bar,
.nav-listMedium pages should largely be reusing the general component level styles defined above. Page level name-spaces however can be helpful for overriding generic components in very specific contexts.
Page level overrides should be minimal and under a single page level class nest.
.home-page {
.nav {
margin-top: 10px;
}
}Don't nest. Ever.
Nesting makes it harder to tell at a glance where css selector optimizations can be made.
Wrong:
.list-btn {
.list-btn-inner {
.btn {
background: red;
}
.btn:hover {
.opacity(.4);
}
}
}Right:
.list-btn .btn-inner {
background: red;
}
.list-btn .btn-inner:hover {
.opacity(.4);
}CSS rules should be comma seperated but live on new lines:
Right:
.content,
.content-edit {
…
}Wrong:
.content, .content-edit {
…
}CSS blocks should be seperated by a single new line. not two. not 0.
Right:
.content {
…
}
.content-edit {
…
}Wrong:
.content {
…
}
.content-edit {
…
}Use Less style comments to annotate styles because they are compiled out. Use them to seperate logical groups of styles within a document. Always use the following style comment:
Right:
// Title of section // --------------------------------------------------
**Wrong:**
```css
/* Title of section
**********************/
Quotes are optional in CSS and LESS. Obvious chooses to use quotes as it is visually clearer that the string is not a selector or a style property.
Right:
background-image: url("/img/you.jpg");
font-family: "Helvetica Neue Light", "Helvetica Neue", Helvetica, Arial;Wrong:
background-image: url(/img/you.jpg);
font-family: Helvetica Neue Light, Helvetica Neue, Helvetica, Arial;Although in the name (cascading style sheets) cascading can introduce unnecessary performance overhead for applying styles. Take the following example:
ul.user-list li span a:hover { color: red; }Styles are resolved during the renderer's layout pass. The selectors are resolved right to left, exiting when it has been detected the selector does not match. Therefore, in this example every a tag has to be inspected to see if it resides inside a span and a list. As you can imagine this requires a lot of DOM walking and and for large documents can cause a significant increase in the layout time. For further reading checkout: https://developers.google.com/speed/docs/best-practices/rendering#UseEfficientCSSSelectors
If we know we want to give all a elements inside the .user-list red on hover we can simplify this style to:
.user-list a:hover { color: red; }If we want to only style specific a elements inside .user-list we can give them a specific class:
.user-list .link-primary:hover { color: red; }Make sure to take into consideration the output of using LESS' powerful mixins. They are best used for grouping browser-specific code or as powerful ways to contain functionality. They are not a good way to add additional styles to an element as you will be sending duplicate styles across the wire.
Wrong:
<button class="btn-secondary">Click me</button>.btn-primary {
color: red;
background: black;
width: 120px;
height: 60px
border-radius: 6px
}
.btn-secondary {
.btn-primary;
color: green;
}
.btn-disabled {
.btn-primary;
color: gray;
background: darkgray;
}Generated Output:
.btn-primary {
color: red;
background: black;
width: 120px;
height: 60px
border-radius: 6px
}
.btn-secondary {
color: red;
background: black;
width: 120px;
height: 60px
border-radius: 6px
color: green;
}
.btn-disabled {
color: red;
background: black;
width: 120px;
height: 60px
border-radius: 6px
color: gray;
background: darkgray;
}Right:
<button class="btn btn-secondary">Click me</button>.btn {
width: 120px;
height: 60px
border-radius: 6px
}
.btn-primary {
color: red;
background: black;
}
.btn-disabled {
color: gray;
background: darkgray;
}Generated Output:
.btn {
width: 120px;
height: 60px
border-radius: 6px
}
.btn-primary {
color: red;
background: black;
}
.btn-disabled {
color: gray;
background: darkgray;
}Encapsulate vendor-prefixes into reusable parameterized LESS mixins:
Right:
.user-page-avatar {
.transition(width .2s ease-in);
}
.transition(@transition) {
-webkit-transition: @transition;
-moz-transition: @transition;
-ms-transition: @transition;
-o-transition: @transition;
transition: @transition;
}Wrong:
.user-page-avatar {
-webkit-transition: width .2s ease-in;
-moz-transition: width .2s ease-in;
-ms-transition: width .2s ease-in;
-o-transition: width .2s ease-in;
transition: width .2s ease-in;
}
There is a small formatting error in the
Commentsection ;)Great conventions by the way! 👍