├── LICENSE
├── README.md
└── makefile


/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2015 Adam Kochanowicz
 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 | <!-- START doctoc generated TOC please keep comment here to allow auto update -->
  2 | <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
  3 | **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
  4 | 
  5 | - [Amadeus](#amadeus)
  6 | - [Variables](#variables)
  7 |   - [How it works](#how-it-works)
  8 |   - [Syntax](#syntax)
  9 |     - [Name syntax](#name-syntax)
 10 |     - [Examples](#examples)
 11 |   - [Default CSS Properties, Values and HTML Tags](#default-css-properties-values-and-html-tags)
 12 |   - [Custom modules](#custom-modules)
 13 |   - [Non-CSS values](#non-css-values)
 14 |   - [Grouping](#grouping)
 15 |     - [Defaults](#defaults)
 16 |     - [Sizing](#sizing)
 17 |     - [Color](#color)
 18 |     - [Logic](#logic)
 19 |   - [Duplicate properties](#duplicate-properties)
 20 |     - [Separate properties](#separate-properties)
 21 |     - [Properties with identical prefixes](#properties-with-identical-prefixes)
 22 | - [Selectors](#selectors)
 23 |     - [Why replace BEM?](#why-replace-bem)
 24 |   - [What does it do?](#what-does-it-do)
 25 |   - [How to use](#how-to-use)
 26 |     - [Controller/Action](#controlleraction)
 27 |     - [Blocks](#blocks)
 28 |     - [Component](#component)
 29 |     - [Element](#element)
 30 | - [Formatting](#formatting)
 31 |   - [Example](#example)
 32 |   - [Nesting rules](#nesting-rules)
 33 |   - [Multiple selectors](#multiple-selectors)
 34 |   - [Ordering](#ordering)
 35 |     - [Scoped variables](#scoped-variables)
 36 |     - [Regular attributes](#regular-attributes)
 37 |     - [Subselectors](#subselectors)
 38 |     - [Appended selectors](#appended-selectors)
 39 |     - [Media queries](#media-queries)
 40 | - [Credits](#credits)
 41 | 
 42 | <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 43 | 
 44 | # Amadeus
 45 | Keep your CSS tidy and your team all on the same page. Amadeus is a set of **CSS Conventions** for naming **variables** and **selectors** and **formatting nested CSS**.
 46 | 
 47 | # Variables
 48 | 
 49 | Conceived as a convention for future versions of [Kickstart](http://getkickstart.com), Amadeus is a set of conventions to **keep your CSS variables organized and intuitive**. These are not conventions for CSS *classes* however.
 50 | 
 51 | Inspired by recommendations from [CSS Tricks](http://css-tricks.com/strategies-keeping-css-specificity-low/?utm_content=bufferdc5e1&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer).
 52 | 
 53 | This documentation uses the Sass syntax, however these conventions are compatible with any CSS pre-processor. This is also designed to integrate nicely into a future [native CSS variable](http://www.w3.org/TR/css-variables-1/) syntax. Love it or hate it, you can do something about it! Start a discussion in the Issues and let's evolve these conventions together.
 54 | 
 55 | ## How it works
 56 | 
 57 | Let's start with some easy stuff. Let's set a red color that is closer to our site's branding than default red.
 58 | 
 59 |     $RED: rgb(248, 240, 255)
 60 |     
 61 | Hang on, we actually have a few different shades of red, let's add a modifier
 62 | 
 63 |     $RED_light: rgb(245, 129, 129)
 64 |     $RED:       rgb(234, 40, 40)
 65 |     $RED_dark:  rgb(194, 21, 21)
 66 | 
 67 | Now we want to set a font size for the `<button>` element. The button tag is native to HTML and font-size is not only native but an actual CSS property, so just like `$RED`, we write it like this:
 68 | 
 69 |     $BUTTON--fontSize: 16px
 70 |     
 71 | That looks good, but what about the font color of our news feed? News feed isn't a native element, so we just omit the uppercasing
 72 | 
 73 |     $newsFeed--color: $RED_light
 74 |     
 75 | Wait, we have both a breaking news and local news section. No problem. Modifier to the rescue.
 76 | 
 77 |     $newsFeed_breaking--color: $RED_light
 78 |     $newsFeed_local--color: $RED_light
 79 |     
 80 | I want to set some `@media` queries, and it would be nice to set a breakpoint once and use it everywhere.
 81 | 
 82 |     @media only screen and (min-width: 650px)
 83 |     
 84 | But this is more of a utility, it does't get placed after a `:` in CSS. So we use the utility syntax:
 85 | 
 86 |     $_query: "only screen and (min-width: 650px)"
 87 |     
 88 | Of course, we'll probably have multiple of thesse so we use modifiers again.
 89 | 
 90 |     $_query_md: "only screen and (min-width: 650px)"
 91 |     $_query_lg: "only screen and (min-width: 800px)"
 92 | 
 93 | ## Syntax
 94 | 
 95 |     // General syntax
 96 |     $[name]--[property]: value
 97 |     
 98 | ### Name syntax
 99 |     
100 |     // Default CSS properties, values, or HTML tag
101 |     FOOBAR or --fooBar
102 |     
103 |     // Refers to a custom module
104 |     fooBar
105 |     
106 |     // Variations and Utilities
107 |     _fooBar
108 |     
109 | ### Examples
110 | 
111 |     $heading_sm--fontSize: 1.5rem
112 |     $FOOTER--paddingTop: 25px
113 |     $breakingNewsFOOTER--paddingTop: 50px
114 |     $headings--fontFamily: Helvetica
115 |     $LINEHEIGHT: 1.2rem
116 |     $FONTFAMILY: Courier
117 |     $RED: rgb(255, 15, 15)
118 |     $_fontSizes: (small: 14px, medium: 16px, large: 18px)
119 | 
120 | ## Default CSS Properties, Values and HTML Tags
121 | 
122 | This syntax is used exclusively for names that are native to CSS and HTML. When used on their own, they should be uppercase:
123 | 
124 |     $[FOO]: value // CSS value or property
125 |     $LINEHEIGHT: 1.2rem
126 |     $FONTFAMILY: Courier
127 |     $RED: rgb(255, 15, 15)
128 |     
129 | Use a `variation` if and only if the variable still directly describes a CSS value
130 | 
131 |     $[FOO]: value // CSS value or property
132 |     $RED: rgb(255, 15, 15)         
133 |     
134 |     $[FOO_bar]: value // CSS value + variation
135 |     $RED_muted: rgb(245, 157, 157)
136 |     $RED_dark: rgb(92, 24, 24)     
137 | 
138 | Use a `--camelCase` syntax when using as a suffix. This example uses both versions:
139 | 
140 |     $[fizzFOO--bar]: value // custom module + HTML Tag + CSS property
141 |     $newsHeadingARTICLE--fontSize: 25px    
142 | 
143 | ## Custom modules
144 | 
145 | Custom modules are named components in your application like "User menu," "News Bar," "Call to Action Button," etc. They don't describe a style and are not native to the HTML/CSS API. These should also always be followed by the css property they are defining.
146 | 
147 |     $[foo--bar]: value // custom module + CSS property
148 |     $userMenu--padding: 50px
149 |     $newsBar--marginBottom: 25px
150 |     $cTA--backgroundColor: $RED
151 |     
152 | You can also add the variation syntax to create multiple versions of the same thing.
153 | 
154 |     $[foo_fizz--bar]: value // custom module + variation
155 |     $heading_lg--fontSize: 20px
156 |     $heading_md--fontSize: 15px
157 |     $heading_sm--fontSize: 12px
158 |     
159 | ## Non-CSS values
160 | 
161 | In modern CSS preprocessors, variables can be used for values that do not immediately translate to CSS values. In this case, variables should announce their special traits with a leading `_`.
162 | 
163 | For example, Sass maps:
164 | 
165 |     $[_foo]: value
166 |     $_heading: (fontSize: 24px, lineHeight: 26px)
167 |     
168 | or custom reusable pieces of your CSS's mixins:
169 | 
170 |     $[_foo]: value
171 |     $_scalingFactor: 1.2
172 |     
173 | Use this syntax twice, both to denote a non css value and to create a group of variations.
174 | 
175 |     $[_foo_bar]: value
176 |     $_heading_lg: (fontSize: 24px, lineHeight: 26px)
177 |     $_heading_md: (fontSize: 18px, lineHeight: 20px)
178 |     $_heading_sm: (fontSize: 14px, lineHeight: 15px)
179 |     
180 |     $_query_lg: "only screen and (min-width: 400px)"
181 |     $_query_md: "only screen and (min-width: 650px)"
182 |     $_query_lg: "only screen and (min-width: 800px)"
183 | 
184 | ## Grouping
185 | 
186 | Here are some helpful guidelines on how to group your variables 
187 | in a variables.sass (or whatever extension you use) file.
188 | 
189 | ### Defaults
190 | 
191 |     $RED: rgb(255, 15, 15)
192 | 
193 | ### Sizing
194 | 
195 |     $FOOTER--marginTop: 25px
196 |     
197 | ### Color
198 | 
199 |     $A--color: rgb(50, 25, 30)
200 |     
201 | ### Logic
202 | 
203 |     $_query_lg: "only screen and (min-width: 400px)"
204 | 
205 | ## Duplicate properties
206 | 
207 | Often, you'll need to define properties that inherently apply to two different 
208 | CSS attributes.
209 | 
210 |     .square {
211 |       width: 50px
212 |       height: 50px
213 |     }
214 | 
215 | ### Separate properties
216 | 
217 | For this, we use the same `--` prefix to indicate a real css property and 
218 | simply concatenate the other with another `--`.
219 | 
220 |     $square--width--height: 50px;
221 | 
222 |     .square {
223 |       width: $square--width--height;
224 |       height: $square--width--height;
225 |     }
226 | 
227 | ### Properties with identical prefixes
228 | 
229 | Other properties only differ by their directionality suffix like `padding-top` and
230 | `padding-bottom`. Conveniently, these are both individual properties for another real
231 | CSS property, padding.
232 | 
233 | So we start with this
234 | 
235 |     $rectangle--padding
236 | 
237 | And define the numerical position of the property with 0, 1, 2, n... numbering.
238 | 
239 | We want to end up with this output:
240 | 
241 |     .rectangle {
242 |       padding: 25px 50px;
243 |     }
244 | 
245 | So `25px` is at position 0 and `50px` is at position 1
246 | 
247 |     .rectangle {
248 |       padding: 25px 50px;
249 |       /*       [0]  [1] */
250 |     }
251 | 
252 | Our variables then become:
253 | 
254 |     $rectangle--padding_0: 25px;
255 |     $rectangle--padding_1: 50px;
256 | 
257 |     .rectangle {
258 |       padding: $rectangle--padding_0 $rectangle--padding_1;
259 |     }
260 |     
261 | # Selectors
262 | 
263 | Based on [Scoped Components](https://gist.github.com/adamjgrant/599530dab67db17c5b2d)
264 | 
265 | Amadeus selectors seek to replace BEM to empower preprocessors and cleaner HTML.
266 | 
267 | ## Why replace BEM?
268 | 
269 | [BEM](https://en.bem.info/method/) is a good naming strategy for a younger world of web development.
270 | In this world, CSS preprocessors were not nearly as powerful or widely implemented and JavaScript libraries were not as component-sophisticated as they are today.
271 | 
272 | This is not just about CSS classes, but CSS selectors in general. It is designed for use with robust backend frameworks and DOM-building JavaScript libraries like **React**
273 | 
274 | ## What does it do?
275 | 
276 | Amadeus provides a convention for **succinct**, **namespaced**, **componentized** CSS classes. 
277 | 
278 | ## How to use
279 | 
280 | The user should strive to write very simplistic, one or two word classes like
281 | 
282 |     `.bio`, `.news-item`, `.cancel`
283 |     
284 | This is made possible by namespacing with the following properties:
285 | 
286 |   - controller/action (optional)
287 |   - block (optional)
288 |   - component
289 | 
290 | ### Controller/Action
291 | 
292 | ![Home view](http://cdn.everything.io/chopin/home.png)
293 | 
294 |     [data-controller="home"] {
295 |       background-color: blue;
296 |     }
297 | 
298 | This is essentially the page or page class. If using a backend MVC framework like Rails, this should map directly to the respective controller and action.
299 | 
300 |     [data-controller="products"] {
301 |       // Styles to be applied to all product pages
302 |     }
303 |         
304 |     [data-controller="products"][data-action="show"] {
305 |       // Styles to be applied only to a product view page.
306 |     }
307 |         
308 | Of course, you shouldn't have to write your CSS page by page, so this is an optional namespace.
309 | 
310 | These selectors target the `data-[property]` attribute on HTML elements
311 | 
312 |     <body data-controller="products" data-action="show">
313 | 
314 | ### Blocks
315 | 
316 | ![Product index](http://cdn.everything.io/chopin/products_index.png)
317 | 
318 |     [data-block="products"] {
319 |       margin: 0px auto;
320 |       display: block;
321 |     }
322 | 
323 |     [data-component="product"] {
324 |       background-color: violet;
325 |     }
326 | 
327 | <span>
328 | 
329 |     <div data-block="products">
330 |       <div data-component="product">...</div>
331 |       <div data-component="product">...</div>
332 |       <div data-component="product">...</div>
333 |       ...
334 |     </div>
335 | 
336 | Blocks describe visually large areas of the application that contain many components.
337 | 
338 | ### Component
339 | 
340 | ![Product index](http://cdn.everything.io/chopin/products_index.png)
341 | 
342 |     [data-component="product"] {
343 |       background-color: violet;
344 |     }
345 | 
346 | A component is a top-level controllable item having an aggregate of elements.
347 | 
348 | Examples: Slideshows, sidebars, message window, anything that is not a whole page or just a small element of the page.
349 | 
350 |     [data-controller="products"] {
351 |       [data-component="product"] {
352 |         // Applies only to a product thumbnail, but only on product pages.
353 |       }
354 |     }
355 |     
356 |     [data-component="product"] {
357 |       // Applies to all product thumbnail components.
358 |     }
359 |     
360 | ### Element
361 | 
362 | ![Product page](http://cdn.everything.io/chopin/products_show.png)
363 | ![Product index](http://cdn.everything.io/chopin/products_index.png)
364 | 
365 |     [data-component="product"] {
366 |       .title {
367 |         font-size: 1.2rem;
368 |       }
369 |     }
370 | 
371 | Elements can be HTML elements or just very small sets of elements that don't qualify in one's mental model as a "component" ([I know it when I see It](http://en.wikipedia.org/wiki/I_know_it_when_I_see_it))
372 | 
373 | Element naming is stupidly simple, as it should be. Amadeus's element naming leads to smaller, more readable HTML and more manageable, modular CSS.
374 | 
375 | Elements should be well-namespaced and simplistic
376 | 
377 |     [data-controller="products"] {
378 |       [data-component="product"] {
379 |         .title {
380 |           // The title of only product thumbnails, but only on product pages.
381 |         }
382 |       }
383 |     }
384 |     
385 |     [data-component="product"] {
386 |       .title {
387 |         // The title of only product thumbnails.
388 |       }
389 |     }
390 |     
391 |     .title {
392 |       // Not recommended. Applies to all title classes.
393 |     }
394 |     
395 | # Formatting
396 | 
397 | Standards for keeping nested CSS/SCSS/Sass, etc. readable, consistent, and maintainable.
398 | 
399 | ## Example
400 | 
401 |     selector1,
402 |     selector2 {
403 |       $someVariable: 3;
404 | 
405 |       first-attribute: first-property;
406 |       second-attribute: second-property;
407 |       third-attribute: $someVariable;
408 |       
409 |       subselector1,
410 |       subselector2 {
411 |         first-attribute: first-property;
412 |         second-attribute: second-property;
413 |       }
414 |       
415 |       &:appended-selector1,
416 |       &:appended-selector2 {
417 |         first-attribute: first-property;
418 |         second-attribute: second-property;
419 |       }
420 |       
421 |       @media screen and (min-width: 100px) {
422 |         /* Media query for selector1, selector2 */
423 |       }
424 |       
425 |       @media screen and (min-width: 200px) {
426 |         /* Media query for selector1, selector2 */
427 |         /* This goes below because the screen is bigger. */
428 |       }
429 |     }
430 |     
431 |     selector1 { /* Selector 1 only rules */
432 |       first-attribute: first-property;
433 |       second-attribute: second-property;
434 |     }
435 |     
436 |     selector2 { /* Selector 2 only rules */      
437 |       first-attribute: first-property;
438 |       second-attribute: second-property;
439 |     }
440 | 
441 | ## Nesting rules
442 | 
443 | Attributes should always stay together, without carriage returns until a new selector appears
444 | 
445 |     p {
446 |       display: block;
447 |       margin: 0px auto;
448 | 
449 |       a {
450 |         color: blue;
451 |       }
452 |     }
453 | 
454 | Attributes are **hoisted** to their selector. They should always appear directly after the
455 | selector but after scoped variables without continuing below a subselector
456 | 
457 |     p {
458 |       display: block;
459 | 
460 |       a {
461 |         color: blue;
462 |       }
463 | 
464 |       /* Don't do this! */
465 |       margin: 0px auto;
466 |     }
467 | 
468 | ## Multiple selectors
469 | 
470 | Each selector of a single set of rules should appear on its own line.
471 | 
472 |     p.big,
473 |     h1,
474 |     span.important {
475 |       font-size: 5rem;
476 |     }
477 | 
478 | The last selector begins the first bracket of the rule set.
479 | 
480 | ## Ordering
481 | 
482 | Inside the brackets, declarations should appear as such:
483 | 
484 |     .selector {
485 |       /* Scoped variables */
486 | 
487 |       /* Regular attributes for .selector */
488 | 
489 |       /* Subselectors */
490 | 
491 |       /* Appended selectors */
492 | 
493 |       /* Media Queries */
494 |     }
495 | 
496 | See the example at the beginning of this section.
497 | 
498 | Each group requires a carriage return except the last to appear.
499 | 
500 | So this requires no carriage return:
501 | 
502 |     .selector {
503 |       display: block;
504 |     }
505 | 
506 | Because `display: block` is last. However, if we add another group,
507 | 
508 |     .selector {
509 |       display: block;
510 | 
511 |       &:before {
512 |         ...
513 |       }
514 |     }
515 | 
516 | `display:block` gets a carriage return, but not `&:before`.
517 | 
518 | ### Scoped variables
519 | 
520 | Are variables that can only be read within this ruleset.
521 | 
522 | ### Regular attributes
523 | 
524 | Are simply css attributes for the selector like
525 | 
526 |     display: block;
527 | 
528 | ### Subselectors
529 | 
530 | Are child selectors for the current selector. This does not include `&`-appended selectors
531 | as these are not children (or in the case of pseudo elements) do not describe an independent
532 | element.
533 | 
534 | ### Appended selectors
535 | 
536 | Are either child selectors or pseudo elements like `::before`.
537 | 
538 | ### Media queries
539 | 
540 | Are media queries for the current selector.
541 | 
542 | # Credits
543 | 
544 | [@coreyti](https://github.com/coreyti) for his work on [Emerson](https://github.com/GetEmerson/emerson-rb). The data-attribute selection strategy of the selectors is heavily based on his work.
545 | [@pixeljanitor](https://github.com/pixeljanitor) for his guidance on good formatting for CSS.
546 | 


--------------------------------------------------------------------------------
/makefile:
--------------------------------------------------------------------------------
1 | build:
2 | 	@echo Running DocToc in github mode
3 | 	@doctoc ./README.md --github
4 | 
5 | setup:
6 | 	@echo "Installing doctoc"
7 | 	@npm install -g doctoc
8 | 	@make build
9 | 


--------------------------------------------------------------------------------