├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 Guilherme Rv Coelho 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # css 2 | 3 | *Opinionated CSS styleguide for scalable applications* 4 | 5 | This guide was heavily inspired by experiments, awesome people like [@fat](https://github.com/fat) and [@necolas](https://github.com/necolas) and awesome projects made by [Google](https://github.com/google), [Airbnb](https://github.com/airbnb) and [Medium](https://github.com/medium). 6 | 7 | ## Table of Contents 8 | 9 | 1. [Terminology](#terminology) 10 | 1. [Rule Declaration](#rule-declaration) 11 | 1. [Selectors](#selectors) 12 | 1. [Properties](#properties) 13 | 1. [Formatting] (#formatting) 14 | 1. [Spacing] (#spacing) 15 | 1. [Nesting] (#nesting) 16 | 1. [Quotes] (#quotes) 17 | 1. [Comments] (#comments) 18 | 1. [Syntax] (#syntax) 19 | 1. [Components] (#components) 20 | 1. [Descendants] (#descendants) 21 | 1. [Modifiers] (#modifiers) 22 | 1. [States] (#states) 23 | 24 | ## Terminology 25 | 26 | The following are some terms used throughout this styleguide. 27 | 28 | ### Rule declaration 29 | 30 | A “rule declaration” is the name given to a selector (or a group of selectors) with an accompanying group of properties. Here's an example: 31 | 32 | ```sass 33 | .avatar { 34 | font-size: 18px; 35 | line-height: 1.2; 36 | } 37 | ``` 38 | 39 | ### Selectors 40 | 41 | In a rule declaration, “selectors” are the bits that determine which elements in the DOM tree will be styled by the defined properties. Selectors can match HTML elements, as well as an element's class, ID, or any of its attributes. Here are some examples of selectors: 42 | 43 | ```sass 44 | .avatar { 45 | font-size: 20px; 46 | } 47 | 48 | #id { 49 | font-size: 20px; 50 | } 51 | ``` 52 | 53 | ### Properties 54 | 55 | Finally, properties are what give the selected elements of a rule declaration their style. Properties are key-value pairs, and a rule declaration can contain one or more property declarations. Property declarations look like this: 56 | 57 | ```sass 58 | .avatar { 59 | background: rgb(255,255,255); 60 | color: rgb(33,33,33); 61 | } 62 | ``` 63 | 64 | ## Formatting 65 | 66 | The following are some high level page formatting style rules. 67 | 68 | ### Spacing 69 | 70 | CSS rules should be comma separated and leave on a new line: 71 | 72 | ```sass 73 | /* wrong */ 74 | .avatar, .tweet { 75 | 76 | } 77 | ``` 78 | 79 | ```sass 80 | /* right */ 81 | .avatar, 82 | .tweet { 83 | 84 | } 85 | ``` 86 | 87 | Properties should use a space after `:` but not before: 88 | 89 | ```sass 90 | /* wrong */ 91 | .avatar { 92 | font-size : 12px; 93 | } 94 | 95 | .tweet { 96 | font-size:12px; 97 | } 98 | ``` 99 | 100 | ```sass 101 | /* right */ 102 | .avatar { 103 | font-size: 12px; 104 | } 105 | ``` 106 | 107 | 108 | Rule declarations should have one property per line: 109 | 110 | ```sass 111 | /* wrong */ 112 | .avatar { 113 | font-size: 12px; letter-spacing: 2px; 114 | } 115 | ``` 116 | 117 | ```sass 118 | /* right */ 119 | .avatar { 120 | font-size: 12px; 121 | letter-spacing: 2px; 122 | } 123 | ``` 124 | 125 | Declaration should be separated by two new lines: 126 | 127 | ```sass 128 | /* wrong */ 129 | .avatar { 130 | font-size: 12px; 131 | } 132 | .tweet { 133 | letter-spacing: 2px; 134 | } 135 | ``` 136 | 137 | ```sass 138 | /* right */ 139 | .avatar { 140 | font-size: 12px; 141 | } 142 | 143 | .tweet { 144 | letter-spacing: 2px; 145 | } 146 | ``` 147 | 148 | ### Nesting 149 | 150 | Do not nest elements. Keep nesting to pseudo-classes and direct interactions with the parent element. Although nesting is a powerful feature provided by several preprocessors and plugins, it can easily get out of control and generate a terrible css ouput with high specificity or spoil the code legibility. 151 | 152 | ```sass 153 | /* wrong */ 154 | .avatar { 155 | font-size: 12px; 156 | 157 | &:hover { 158 | font-size: 11px; 159 | } 160 | 161 | &__link { 162 | color: rgb(210,210,22); 163 | } 164 | 165 | &__photo { 166 | height: 20px; 167 | } 168 | } 169 | ``` 170 | 171 | ```sass 172 | /* right */ 173 | .avatar { 174 | font-size: 12px; 175 | 176 | &:hover { 177 | font-size: 11px; 178 | } 179 | } 180 | 181 | .avatar__link { 182 | color: rgb(210,22,221); 183 | } 184 | 185 | .avatar__photo { 186 | height: 20px; 187 | } 188 | ``` 189 | 190 | Nesting can also be used to when an element is dependent of a parent's modifier. This helps to keep all code related to an element on the same block. 191 | 192 | ```sass 193 | .avatar { 194 | font-size: 12px; 195 | } 196 | 197 | .avatar__photo { 198 | height: 20px; 199 | 200 | .avatar--big & { 201 | height: 40px; 202 | } 203 | } 204 | ``` 205 | 206 | ### Quotes 207 | 208 | Quotes are optional in CSS. You should use single quotes as it is visually clearer that the string is not a selector or a style property. 209 | 210 | ```sass 211 | /* wrong */ 212 | .avatar { 213 | background-image: url(/img/you.jpg); 214 | font-family: Helvetica Neue Light, Helvetica Neue, Helvetica, Arial; 215 | } 216 | ``` 217 | 218 | ```sass 219 | /* right */ 220 | .avatar { 221 | background-image: url('/img/you.jpg'); 222 | font-family: 'Helvetica Neue Light', 'Helvetica Neue', Helvetica, Arial; 223 | } 224 | 225 | ``` 226 | 227 | ### Comments 228 | 229 | Avoid comments as hard as you can. Comments are not easily mantainable and are usually used to supress application design mistakes. Leave comments only to things that are **really** not straightforward such as browser-specific hacks. Put comments on their own lines to describe content below them. 230 | 231 | ```sass 232 | /* wrong */ 233 | .avatar { 234 | height: 200px; /* this is the height of the container*/ 235 | background-color: rgb(221,33,21); /* brand color */ 236 | } 237 | ``` 238 | 239 | ```sass 240 | /* right */ 241 | .avatar { 242 | height: 20px; 243 | 244 | /* this is a hack to fix click behavior on Safari 6.0 */ 245 | pointer-events: none; 246 | } 247 | ``` 248 | 249 | ## Syntax 250 | 251 | Syntax: `[--modifier-name|__descendant-name]` 252 | 253 | Component driven development offers several benefits when reading and writing HTML and CSS: 254 | 255 | * It helps to distinguish between the classes for the root of the component, descendant elements, and modifications. 256 | * It keeps the specificity of selectors low. 257 | * It helps to decouple presentation semantics from document semantics. 258 | 259 | You can think of components as custom elements that enclose specific semantics, styling, and behaviour. 260 | 261 | ### Components 262 | 263 | Syntax: `component-name` 264 | 265 | The component's name must be written in kebab case. 266 | 267 | ```sass 268 | .my-component { 269 | font-size: 20px; 270 | } 271 | ``` 272 | 273 | ```html 274 |
275 | ``` 276 | 277 | ### Descendants 278 | 279 | Syntax: `component-name__descendant-name` 280 | 281 | A component descendant is a class that is attached to a descendant node of a component. It's responsible for applying presentation directly to the descendant on behalf of a particular component. Descendant names must be written in kebab case. 282 | 283 | ```html 284 |
285 |
286 | {$alt} 287 | … 288 |
289 |
290 | … 291 |
292 |
293 | ``` 294 | 295 | ### Modifiers 296 | 297 | Syntax: `component-name--modifier-name` 298 | 299 | A component modifier is a class that modifies the presentation of the base component in some form. Modifier names must be written in kebab case and be separated from the component name by two hyphens. The class should be included in the HTML _in addition_ to the base component class. 300 | 301 | ```sass 302 | .btn { 303 | padding: 20px 10px; 304 | } 305 | 306 | .btn--primary { 307 | background: rgb(148,146,231); 308 | } 309 | ``` 310 | 311 | ```html 312 | 313 | ``` 314 | 315 | ### States 316 | 317 | Syntax: `component-name.is-state-of-component` 318 | 319 | Use `is-stateName` for state-based modifications of components. The state name must be kebab case. **Never style these classes directly; they should always be used as an adjoining class.** 320 | 321 | JS can add/remove these classes. This means that the same state names can be used in multiple contexts, but every component must define its own styles for the state (as they are scoped to the component). 322 | 323 | ```sass 324 | .tweet { 325 | height: 90px; 326 | } 327 | 328 | .tweet.is-expanded { 329 | height: 200px; 330 | } 331 | ``` 332 | 333 | ```html 334 |
335 | ``` 336 | 337 | ## License 338 | 339 | [MIT](https://github.com/grvcoelho/css/blob/master/LICENSE) © 2016 340 | 341 | --------------------------------------------------------------------------------