• Stars
    star
    992
  • Rank 46,173 (Top 1.0 %)
  • Language
  • License
    MIT License
  • Created over 10 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🎨 CSS: The Good Parts

.bc-style-guide {

The so-called "nico-style" brought to markdown. Because Style Guide.

This style guide is a jab at solving collisions between CSS class names, and issues that ultimately lead to confusion, having to use !important rules, copying and pasting style declarations, and similarly awful aspects of CSS development.

Goal

These suggestions aren't set in stone, they aim to provide a baseline you can use in order to write more consistent codebases. To maximize effectiveness, share the styleguide among your co-workers and attempt to enforce it. Don't become obsessed about code style, as it'd be fruitless and counterproductive. Try and find the sweet spot that makes everyone in the team comfortable developing for your codebase, while not feeling frustrated that their code always fails automated style checking because they added a single space where they weren't supposed to. It's a thin line, but since it's a very personal line I'll leave it to you to do the drawing.

Astonishingly, this style guide won't do anything for you that you're not able to figure out for yourself. That means you won't see the benefits unless you try and follow most of the conventions laid out next.

Use together with bevacqua/js for great good!

Feel free to fork this style guide, or better yet, send Pull Requests this way!

Table of Contents

  1. Namespaces
  2. Classes
  3. Attributes
  4. id attribute
  5. Tag Names
  6. Selectors and Nesting
  7. Organization
  8. Presentation-Specific vs Layout-Specific Styles
  9. Styles
  10. Media Queries
  11. Frameworks and Vendor Styles
  12. Languages
  1. License

Namespaces

Components should always be assigned a unique namespace prefix.

  • The namespace can be as short as a single character, or as long as 5 characters
  • Where possible, the namespace should be a meaningful shorthand
  • In class names, the namespace must be followed by a single dash
  • Views should be treated as individual components

Consider the following example, where we assigned ddl to a drop down list component. Take note of the class names.

Good
.ddl-container {
  // ...
}

.ddl-item-list {
  // ...
}

.ddl-item {
  // ...
}
Bad
.item-list {
  // ...
}

.dropdown-item-list {
  // ...
}

.xyz-item-list {
  // ...
}

Classes that are meant to be shared among a large set of elements, or provide reusable styles, should be grouped under a universal namespace, such as uv.

Good
.uv-clearfix {
  // ...
}
Bad
.clearfix {
  // ...
}

See Selectors and Nesting for information in regard to how styles should be overridden

Classes

Class names must follow a few rules.

  • Must be all-lowercase
  • Words must be separated by single dashes
  • As short as possible, but as long as necessary
    • Don't abbreviate words carelessly
  • Name things consistently
  • Meaningful description of the elements that should use it
  • Keep your non-prefix word count below 4
Good
.ddl-item {
  // ...
}

.ddl-selected {
  // ...
}

.ddl-item-selected {
  // ...
}
Bad
.ddlItem {
  // ...
}

.ddl-item-container-text {
  // ...
}

.ddl-foo-bar-baz {
  // ...
}

Attributes

Attributes make decent selectors from time to time. Some ground rules apply.

  • If the "exists" check suffices, use that
  • Don't overqualify using a tag name
Good
[href] {
  // ...
}
Bad
a[href] {
  // ...
}

[href^='http'] {
  // ...
}

id attribute

While the id attribute might be fine in HTML and JavaScript, it should be avoided entirely inside stylesheets. Few reasons.

Good
.ur-name {
  // ...
}
Bad
#ur-name {
  // ...
}

Just assign a class name to the element.

Tag Names

Tag names in selectors follow a few rules.

  • Application level styles that are only overridden in a few places are okay to use tag name selectors
  • Not semantic. Avoid where possible, use class names instead
  • Fine to use when there's a ton of elements under the same namespace that need a small tweak
  • Don't overqualify (a.foo)
Good
button {
  padding: 5px;
  margin-right: 3px;
}

.ddl-button {
  background-color: #f00;
}
Bad
.ddl-container button {
  background-color: #f00;
}

Selectors and Nesting

Styles shouldn't need to be nested more than three (four at worst) levels deep. This includes pseudo-selectors. If you find yourself going further, think about re-organizing your rules (either the specificity needed, or the layout of the nesting).

Good
.sg-title-icon:before {
  // ...
}

.dg-container .sg-title {
  font-size: 1.1em; // larger segment title inside dialogs
}
Bad
.dg-container .sg-container .sg-title {
  font-size: 1.1em;
}

.dg-container .sg-title span:before {
  // ...
}

If a component needs to be different within another component, these rules apply.

  • Where possible, give a class name using the parent namespace to the child component
  • If that's not possible, then use a nested selector

Suppose you have a User List component .ul-* and a User Card component .uc-*.

Good
<div class='ul-container'>
  <div class='uc-container'>
    <span class='uc-name ul-card-name'>John Doe</span>
  </div>
</div>
.ul-card-name {
  // ...
}
Okay
<div class='ul-container'>
  <div class='uc-container'>
    <span class='uc-name'>John Doe</span>
  </div>
</div>
.ul-container .uc-name {
  // ...
}
Bad
<div class='ul-container'>
  <div class='uc-container'>
    <span class='uc-name uc-name-in-ul'>John Doe</span>
  </div>
</div>
.uc-name-in-ul {
  // ...
}

Organization

Ideally, you should keep your stylesheets separated in different files. Either of the approaches below is fine. The former is prefered.

  • Use a single all.{styl,less,scss} file and have it @import every other file
  • Use a build tool to glob the styles directory

A few rules apply.

  • Each component should take up its own file
  • Styles applied globally to tag names, see Tag Names, should be kept in a single file
  • Where possible split presentation-specific styles from layout-specific styles. See below

Presentation-Specific vs Layout-Specific Styles

Presentation-Specific styles are those that only alter the visual design of the element, but don't change its dimensions or position in a meaningful way. The examples below are presentation-specific.

  • Rules such as color, font-weight, or font-variant
  • Rules that animate other properties
  • font-size is not considered a meaningful dimension change
  • padding may fit this category (loosely), but only if box-sizing: border-box; is in effect
  • max-width and max-height may fit either category, but it's generally reasonable to consider them presentation-specific

Layout-Specific Styles are those that change the dimensions or positioning of DOM elements. These are mostly layout-specific.

  • Rules such as margin or padding
  • width, and height
  • The element's position
  • z-index, definitely

Where possible, it's suggested to explicitly split styles into these two categories. The explicit differentiation could be made in a few different ways.

  • (bad) No differentiation
  • (decent) Layout-specific first, presentation-specific later
  • (good) A line-break between both categories
  • (better) Split in subsequent style declarations using the same selector
  • (best) Declaring the rules in different files altogether
Good
.foo {
  position: fixed;
  top: 8px;
  right: 8px;
  padding: 2px;
  font-weight: bold;
  background-color: #333;
  color: #f00;
}
.foo {
  position: fixed;
  top: 8px;
  right: 8px;
  padding: 2px;

  font-weight: bold;
  background-color: #333;
  color: #f00;
}
.foo {
  position: fixed;
  top: 8px;
  right: 8px;
  padding: 2px;
}

.foo {
  font-weight: bold;
  background-color: #333;
  color: #f00;
}
Bad
.foo {
  font-weight: bold;
  background-color: #333;
  color: #f00;
  position: fixed;
  top: 8px;
  right: 8px;
  padding: 2px;
}

.foo {
  right: 8px;
  color: #f00;
  padding: 2px;
  top: 8px;
  background-color: #333;
  font-weight: bold;
  position: fixed;
}

Styles

These rules apply to your CSS property values

  • If the value of a property is 0, do not specify units
  • The !important rule should be aggressively avoided.
    • Keep style rules in a sensible order
    • Compose styles to dissipate the need for an !important rule
    • Fine to use in limited cases
      • Overlays
      • Declarations of the display: none !important; type
  • Keep z-index levels in variables in a single file. Avoids confusion about what level should be given to an element, and arbitrarily-high 999-style values
  • Use hex color codes #000 unless there's an explicit need for an rgba declaration
  • Dislike magic numbers
  • Avoid mixing units
  • Unit-less line-height is preferred because it does not inherit a percentage value of its parent element, but instead is based on a multiplier of the font-size.
Good
.btn {
  color: #222;
}

.btn-error {
  color: #f00;
}
Bad
.btn-red {
  color: #f00 !important;
}

.btn {
  color: #222;
}

Media Queries

If you are reading this, I salute you. You're almost as boring as I am. I'm more boring because I actually wrote the damn thing. It's not a contest, though.

A few rules apply to media queries.

  • Settle for a few (2-3) breakpoints and use those only
  • Don't wrap entire stylesheets in media queries
  • Instead, modularize media queries wherever possible, keep them relevant to the components
  • Approach your styles in a Mobile First manner. Generally you add more things as you get more real estate. Mobile First logically follows
Good
.co-field {
  width: 120px;
}

@media only screen and (min-width: 768px) {
  .co-field {
    width: 400px;
    color: #f00;
  }
}
Bad
.co-field {
  width: 400px;
  color: #f00;
}

@media only screen and (max-width: 768px) {
  .co-field {
    width: 120px;
    color: initial;
  }
}

Frameworks and Vendor Styles

You should shy away from all of these. A few rules apply.

  • Stay away from frameworks
  • Use normalize.css if you want
  • Vendor styles, such as those required by external components are okay, and they should come before you define any of your own styles

Languages

Some rules apply to stylesheet, regardless of language.

  • Use a pre-processor language where possible
  • Use soft-tabs with a two space indent
  • One line per selector
  • One (or more) line(s) per property declaration
    • Long, comma-separated property values (such as collections of gradients or shadows) can be arranged across multiple lines in an effort to improve readability and produce more useful diffs.
  • Comments that refer to selector blocks should be on a separate line immediately before the block to which they refer
  • Use a plugin such as TrailingSpaces in Sublime Text to get rid of trailing spaces
Good
.foo {
  color: #f00;
}

.foo,
.bar,
.baz {
  color: #f00;
}
Bad
.foo {
    color: #f00;
}

.foo, .bar, .baz {
  color: #f00;
}

.foo {
  color: red;
}

Not Stylus

These rules apply to every language except Stylus.

  • Always end property declarations with a semicolon
  • Put a single space after : in property declarations
  • Put spaces before { in rule declarations
Good
.foo {
  color: #f00;
}
Bad
.foo{
  color: #f00;
}

.foo {
  color:#f00;
}

.foo {
  color: #f00
}

Not CSS

Rules applicable to most pre-processor languages.

  • Put comments in // statements
  • Prefer nested selectors .foo { .bar {} } vs .foo .bar {}
    • Only if both .foo and .foo .bar need styling
  • Use &{selector} to concatenate selectors
  • Don't blindly over-nest
  • Keep z-index levels in a single file, using variables
Good
// foo
.bar {
  // ...

  .baz {
    ///...
  }
}
Bad
/* foo */
.bar {
  // ...
}

.bar .baz {
  // ...
}

Stylus

Rules specific to Stylus.

  • Omit brackets {} in rule declarations
  • Omit : and ; in property declarations
  • Use transparent mix-ins
  • Use nib
Good (Stylus)
// foo
.foo
  color #f00
.foo
  color #f00

  .bar
    padding 2px
Bad (Stylus)
/* foo */
.foo {
  color: #f00;
}
.foo {
  color: #f00;
}

.foo .bar {
  padding: 2px;
}

License

MIT

Fork away!

}

More Repositories

1

dragula

👌 Drag and drop so simple it hurts
JavaScript
21,936
star
2

es6

🌟 ES6 Overview in 350 Bullet Points
4,328
star
3

rome

📆 Customizable date (and time) picker. Opt-in UI, no jQuery!
JavaScript
2,913
star
4

js

🎨 A JavaScript Quality Guide
2,874
star
5

fuzzysearch

🔮 Tiny and blazing-fast fuzzy search in JavaScript
JavaScript
2,711
star
6

woofmark

🐕 Barking up the DOM tree. A modular, progressive, and beautiful Markdown and HTML editor
JavaScript
1,624
star
7

promisees

📨 Promise visualization playground for the adventurous
JavaScript
1,199
star
8

horsey

🐴 Progressive and customizable autocomplete component
JavaScript
1,167
star
9

react-dragula

👌 Drag and drop so simple it hurts
JavaScript
992
star
10

contra

🏄 Asynchronous flow control with a functional taste to it
JavaScript
771
star
11

shots

🔫 pull down the entire Internet into a single animated gif.
JavaScript
728
star
12

insignia

🔖 Customizable tag input. Progressive. No non-sense!
JavaScript
674
star
13

campaign

💌 Compose responsive email templates easily, fill them with models, and send them out.
JavaScript
641
star
14

perfschool

🌊 Navigate the #perfmatters salt marsh waters in this NodeSchool workshopper
CSS
630
star
15

local-storage

🛅 A simplified localStorage API that just works
JavaScript
523
star
16

angularjs-dragula

👌 Drag and drop so simple it hurts
HTML
509
star
17

reads

📚 A list of physical books I own and read
486
star
18

insane

😾 Lean and configurable whitelist-oriented HTML sanitizer
JavaScript
449
star
19

hget

👏 Render websites in plain text from your terminal
HTML
334
star
20

hit-that

✊ Render beautiful pixel perfect representations of websites in your terminal
JavaScript
332
star
21

hash-sum

🎊 Blazing fast unique hash generator
JavaScript
301
star
22

swivel

Message passing between ServiceWorker and pages made simple
JavaScript
294
star
23

dominus

💉 Lean DOM Manipulation
JavaScript
277
star
24

trunc-html

📐 truncate html by text length
JavaScript
220
star
25

grunt-ec2

📦 Create, deploy to, and shutdown Amazon EC2 instances
JavaScript
190
star
26

beautify-text

✒️ Automated typographic quotation and punctuation marks
JavaScript
186
star
27

sixflix

🎬 Detects whether a host environment supports ES6. Algorithm by Netflix.
JavaScript
175
star
28

twitter-for-github

🐥 Twitter handles for GitHub
JavaScript
146
star
29

awesome-badges

🏆 Awesome, badges!
JavaScript
124
star
30

prop-tc39

Scraping microservice for TC39 proposals 😸
JavaScript
108
star
31

megamark

😻 Markdown with easy tokenization, a fast highlighter, and a lean HTML sanitizer
JavaScript
104
star
32

diferente

User-friendly virtual DOM diffing
JavaScript
95
star
33

domador

😼 Dependency-free and lean DOM parser that outputs Markdown
JavaScript
86
star
34

proposal-undefined-coalescing-operator

Undefined Coalescing Operator proposal for ECMAScript
77
star
35

dotfiles

💠 Yay! @bevacqua does dotfiles \o/
Shell
75
star
36

assignment

😿 Assign property objects onto other objects, recursively
JavaScript
73
star
37

sektor

📍 A slim alternative to jQuery's Sizzle
JavaScript
65
star
38

map-tag

🏷 Map template literal expression interpolations with ease.
JavaScript
65
star
39

unbox

Unbox a node application with a well-designed build-oriented approach in minutes
JavaScript
61
star
40

hint

Awesome tooltips at your fingertips
JavaScript
60
star
41

but

🛰 But expands your functional horizons to the edge of the universe
JavaScript
59
star
42

kanye

Smash your keyboards with ease
JavaScript
55
star
43

correcthorse

See XKCD for reference
JavaScript
52
star
44

easymap

🗺 simplified use of Google Maps API to render a bunch of markers.
JavaScript
52
star
45

flickr-cats

A demo page using the Flickr API, ServiceWorker, and plain JavaScript
HTML
49
star
46

hubby

👨 Hubby is a lowly attempt to describe public GitHub activity in natural language
JavaScript
46
star
47

ruta3

Route matcher devised for shared rendering JavaScript applications
JavaScript
45
star
48

poser

📯 Create clean arrays, or anything else, which you can safely extend
JavaScript
45
star
49

baal

🐳 Automated, autoscaled, zero-downtime, immutable deployments using plain old bash, Packer, nginx, Node.js, and AWS. Made easy.
Shell
44
star
50

lipstick

💄 sticky sessions for Node.js clustering done responsibly
JavaScript
43
star
51

crossvent

🌏 Cross-platform browser event handling
JavaScript
41
star
52

lazyjs

The minimalist JavaScript loader
JavaScript
39
star
53

spritesmith-cli

😳 Adds a CLI to the spritesmith module
JavaScript
38
star
54

gulp-jsfuck

Fuck JavaScript and obfuscate it using only 6 characters ()+[]!
JavaScript
37
star
55

measly

A measly wrapper around XHR to help you contain your requests
JavaScript
36
star
56

keynote-extractor

🎁 Extract Keynote presentations to JSON and Markdown using a simple script.
AppleScript
35
star
57

hyperterm-working-directory

🖥👷📂 Adds a default working directory setting. Opens new tabs using that working directory.
JavaScript
34
star
58

gitcanvas

🏛 Use your GitHub account's commit history as a canvas. Express the artist in you!
JavaScript
34
star
59

cave

Remove critical CSS from your stylesheet after inlining it in your pages
JavaScript
33
star
60

scrape-metadata

📜 HTML metadata scraper
JavaScript
31
star
61

feeds

🍎 RSS feeds I follow and maintain
31
star
62

suchjs

Provides essential jQuery-like methods for your evergreen browser, in under 200 lines of code. Such small.
JavaScript
30
star
63

ponyedit

An interface between contentEditable and your UI
JavaScript
29
star
64

grunt-grunt

Spawn Grunt tasks in other Gruntfiles easily from a Grunt task
JavaScript
29
star
65

ultramarked

Marked with built-in syntax highlighting and input sanitizing that doesn't encode all HTML.
JavaScript
28
star
66

sell

💰 Cross-browser text input selection made simple
JavaScript
28
star
67

icons

Free icon sets gathered around the open web
27
star
68

insert-rule

Insert rules into a stylesheet programatically with a simple API
JavaScript
26
star
69

hose

Redirect any domain to localhost for convenience or productivity!
JavaScript
26
star
70

ponymark

Next-generation PageDown fork
JavaScript
25
star
71

omnibox

Fast url parsing with a tiny footprint and extensive browser support
JavaScript
25
star
72

estimate

Calculate remaining reading time estimates in real-time
JavaScript
24
star
73

node-emoji-random

Creates a random emoji string. This is as useless as it gets.
JavaScript
24
star
74

sluggish

🐍 Sluggish slug generator that works universally
JavaScript
24
star
75

seleccion

💵 A getSelection polyfill and a setSelection ranch dressing
JavaScript
24
star
76

bullseye

🎯 Attach elements onto their target
JavaScript
23
star
77

vectorcam

🎥 Record gifs out of <svg> elements painlessly
JavaScript
22
star
78

paqui

Dead simple, packager-agnostic package management solution for front-end component developers
JavaScript
22
star
79

grunt-ngdoc

Grunt task for generating documentation using AngularJS' @ngdoc comments
JavaScript
20
star
80

ftco

⚡ Browser extension that unshortens t.co links in TweetDeck and Twitter
JavaScript
19
star
81

jadum

💍 A lean Jade compiler that understands Browserify and reuses partials
JavaScript
19
star
82

trunc-text

📏 truncate text by length, doesn't cut words
JavaScript
16
star
83

flexarea

Pretty flexible areas!
JavaScript
16
star
84

music-manager

📻 Manages a list of favorite artists and opens playlists on youtube.
JavaScript
16
star
85

grunt-integration

Run Integration Tests using Selenium, Mocha, a Server, and a Browser
JavaScript
15
star
86

apartment

🏡 Remove undesirable properties from a piece of css
JavaScript
14
star
87

mongotape

Run integration tests using mongoose and tape
JavaScript
14
star
88

rehearsal

Persist standard input to a file, then simulate real-time program execution.
JavaScript
13
star
89

queso

Turn a plain object into a query string
JavaScript
13
star
90

bitfin

🏦 Finance utility for Bitstamp
JavaScript
13
star
91

pandora-box

🐼 What will it be?
JavaScript
12
star
92

grunt-spriting-example

An example on how to seamlessly use spritesheets with Grunt.
12
star
93

artists

🎤 Big list of artists pulled from Wikipedia.
JavaScript
11
star
94

twitter-leads

🐦 Pull list of leads from a Twitter Ads Lead Generation Card
JavaScript
11
star
95

reaver

Minimal asset hashing CLI and API
JavaScript
11
star
96

atoa

Creates a true array based on `arraylike`, starting at `startIndex`.
JavaScript
10
star
97

BridgeStack

.NET StackExchange API v2.0 client library wrapper
C#
10
star
98

ama

📖 A repository to ask @bevacqua anything.
10
star
99

virtual-host

Create virtual, self-contained `connect` or `express` applications using a very simple API.
JavaScript
10
star
100

banksy

🌇 Street art between woofmark and horsey
JavaScript
10
star