(this is a living, breathing document)
This is a style guide for my self-imposed rules for how I write code in projects. Follow these rules makes it easier for me to debug code, especially CSS.
I would probably need to change these rules when working in a team environment. But for projects where I'm only the client side person, following this style guide works for me.
When the kdz app command is run, it scaffolds out my standard file and folder structure for a project. The structure looks like this:
├── build
| └── css
| └── js
| └── libs
├── coffee
| └── main.coffee
├── css-build
| └── imports
├── image-min
├── bower.json
└── package.json
If either the -l flag or -s flag is passed to kdz app, then specific .less or .scss files will be created in css-build/imports, respectively. Afterwards, commands are run that download Bootstrap's core CSS file via Bower and creates a core stylesheet that imports in all the preprocessor files.
For example, if .less files were built out, the structure would look like this:
├── project-folder
...
└── css-build
├── style.less
└── imports
├── all-transform-3d-webkit-transform-3d.less
├── bootstrap-override.less
├── for.less
├── globals.less
├── max-device-width-480-orientation-landscape.less
├── max-width-767.less
├── min-width-1200.less
├── min-width-768-max-width-991.less
├── min-width-768.less
├── min-width-992-max-width-1199.less
├── min-width-992.less
├── mixins.less
├── mobile_first.less
├── retina-media-queries.less
├── screen-and-max-width-767.less
├── screen-and-min-width-768.less
├── screen-webkit-min-device-pixel-ratio-0.less
├── screen-webkit-min-device-pixel-ratio-0
└── variables.less
...and style.less would look like this
// style.less
@import "imports/variables";
@import "imports/mixins";
@import "imports/for";
@import "imports/bootstrap-override";
@import "imports/retina-media-queries";
@import "imports/globals";
@import "imports/mobile_first";
@import "imports/min-width-768";
@import "imports/min-width-992";
@import "imports/min-width-992-max-width-1199";
@import "imports/min-width-1200";
@import "imports/screen-and-max-width-767";
@import "imports/screen-webkit-min-device-pixel-ratio-0";
@import "imports/max-device-width-480-orientation-landscape";
@import "imports/max-width-767";
@import "imports/screen-and-min-width-768";
@import "imports/all-transform-3d-webkit-transform-3d";
@import "imports/min-width-768-max-width-991";
-
All preprocessor variables would go in
variables.less -
All preprocessor mixins would go in
mixins.less -
for.lessis a LESS-specific file that outputs a set of CSS selectors using a LESS function. The.scssfile buildout doesn't have a similar file. -
bootstrap-overide.lesswould contain classes needed to override classes already insidebootstrap.css. -
retina-media-querieswould contain classes that define any settings for retina and non-retina images. -
mobile-first.lesswould contain classes that appear on handheld views only. -
Media query files are listed in the order that the queries appear in the current version of
bootstrap.css.
In the example above, style.less compiles out to style.css in css-build. style.css gets concatenated with bootstrap.css to wherever I specify.
Clearly define selector names
Right
.article-header {
color: red;
font-weight: bold;
}
Wrong
.red-bold-text {
color: red;
font-weight: bold;
}
Create classes instead of IDs (when possible...some plugins make you style IDs)
Right
.article-header
Wrong
#article-header
Dashes between selector names
Right
.article-header
Wrong
.articleHeader
Selectors that appear on all views should be listed in `globals.less` and should start with `gl-`
Right
// In globals.less
.gl-article-element {
font-size: 18px;
}
Wrong
// In globals.less
.article-element {
font-size: 18px;
}
Selectors should not overlap in the various views
Right
// Mobile First
.article-header {
font-size: 10px;
color: red;
}
@media (max-width: 767px) {
.article-header {
color: blue;
}
}
Wrong // Overrides the Mobile First font size unnecessarily @media (max-width: 767px) { .article-header { font-size: 10px; color: blue; } }
// Mobile First
.article-header {
font-size: 10px;
color: red;
}
Consider placing selectors like this globals.less
Avoid overly-specific selectors (this may be unavoidable with WordPress)
Right
.menu-list-item {
font-size: 12px;
font-weight: bold;
}
Wrong
ul .menu-list-item {
font-size: 12px;
font-weight: bold;
}
Wrong
ul > .menu-list-item {
font-size: 12px;
font-weight: bold;
}
Wrong
#container ul > .menu-list-item {
font-size: 12px;
font-weight: bold;
}
Really REALLY Wrong
div ul > .menu-list-item {
font-size: 12px;
font-weight: bold;
}
If using LESS mixins inside CSS selectors, end the mixin with ()
Right
// Parentheses are optional, but make it easier to tell it's a mixin
.menu-list-item {
.font-styles();
}
Wrong
// Legal but not as verbose than if parentheses were added
.menu-list-item {
.font-styles;
}
If you HAVE to use any sort of CSS descendant selectors, nest them if your pre processor allows for it. Even if you only have one. It makes it easier to add more if needed.
Right
// Done with LESS
.menu-list-item {
.header-copy {
font-size: 16px;
}
}
Wrong
.menu-list-item .header-copy {
font-size: 16px;
}
Avoid CSS descendant selectors because they're inefficient.
Right
.menu-list-item {
font-size: 16px;
}
Wrong
ul .menu list-item {
font-size: 16px;
}
Use as little `z-index` levels as possible: there should never be a need for more than five levels (unless plugins force there to be more.)
Right
.about-textbox {
z-index: 3;
}
Wrong
.about-textbox {
z-index: 10000;
}
## General Notes
Whenever possible, plugin-specific styles should go in their own pre-process file and start with PLUGIN_. So if I'm using jQuery Cycle, create a pre-process files called PLUGIN_cycle.
ALWAYS try to avoid using `!important`, but there are times when you have no choice, such as overriding a plugin.
Comments should clearly say what CSS selectors do.