└── readme.md
/readme.md:
--------------------------------------------------------------------------------
1 | # CSS Coding Standards
2 |
3 |
4 | [Documentation](http://documentup.com/Salesfloor/css-architecture?theme=v1)
5 |
6 |
7 | ## Philosophy
8 |
9 | The easiest way to keep CSS maintainable is by writing less of it.
10 |
11 | * Write object oriented CSS ([OOCSS](https://github.com/stubbornella/oocss/wiki)) that allows common design solutions to be extended and re-used repeatedly. This methodology is scalable, maintainable, and standards-based.
12 | * Writing less CSS means there is a less chance of things going wrong, resulting in a more robust front-end.
13 | * [Specificity](http://css-tricks.com/specifics-on-css-specificity/) is the biggest problem in CSS, but we can work around it by respecting the cascade and building complete styles progressively through extending common styles.
14 | * All styles should follow the principle of keeping specificity as low as possible.
15 |
16 |
17 | ## Architecture
18 |
19 | The source order is designed to take advantage of inheritance in the cascade with the goal of writing DRYer code.
20 |
21 | * Reset
22 | * Variables (used throughout the project)
23 | * Mixins (used throughout the project)
24 | * Patterns/Objects (any repeatable or extendable patterns/skeletons)
25 | * Components (combinations of patterns/objects + extended styles)
26 | * Sections (combinations of components)
27 | * Overrides
28 |
29 | The source order:
30 |
31 |
32 | * Settings
33 | * Global variables
34 | * Configs
35 | * Tools
36 | * Mixins
37 | * Functions
38 | * Base
39 | * Reset
40 | * Patterns
41 | * Forms
42 | * Buttons
43 | * Alerts
44 | * Etc.
45 | * Components
46 | * Video Player
47 | * Newsletter Signup
48 | * Etc.
49 | * Sections (should have a very small amount of content)
50 | * Confirmation page
51 | * Rep listing page
52 | * Themes
53 | * retailers overrides
54 | * Trumps
55 | * Others overrides, helper
56 |
57 | ## Coding Style
58 |
59 | ### Selectors
60 |
61 | * IDs are not to be used in any stylesheets.
62 | * They are far too high in specificity. It would take 256 classes to override one ID.
63 | * Anything an ID can do, a class can do, however classes are more useful since they are reusable.
64 | * You can read arguments for this rule from [Chris Coyier](http://css-tricks.com/a-line-in-the-sand/), [Stubbornella](https://github.com/stubbornella/oocss/wiki/FAQ#should-i-use-ids-to-style-my-content), [Harry Roberts](http://csswizardry.com/2011/09/when-using-ids-can-be-a-pain-in-the-class/)
65 | * Always Avoid over-qualifying selectors. For example: ```p.intro {}``` could have been ```.intro {}```
66 | * Makes the selector non-reusable.
67 | * Increases specificity unnecessarily.
68 | * Always Avoid chaining selectors unnecessarily. For example: ```.msg.error {}``` could have been ```.error-msg {}```. Chaining two selectors makes it doubly specific with no real benefit. It is less clear for a new developer to understand at a glance what exactly a generic error class does.
69 | * Selectors should be lowercase with dash-separated words, no camel case.
70 |
71 | ### Values
72 |
73 | #### Units
74 |
75 | * Use px for font-size, because it offers absolute control over text.
76 |
77 | * The line-height should always be a multiple of the vertical rhythm variable (unit-less).
78 | All other values should be as relative as possible. (see [magic numbers and absolutes](#magic-numbers-and-absolutes))
79 | * All vertical spacing around elements should consider the vertical rhythm.
80 | * Use [single direction](http://csswizardry.com/2012/06/single-direction-margin-declarations/) (downward) margin declarations. This would mean only use margin-bottom, no margin-top, to keep a constant downward flow of elements.
81 | * Easier to define vertical rhythm in one fell swoop.
82 | * More confidence in (re)moving components if you know their margins all push in the same direction.
83 | * Components and elements don't have to necessarily live in a certain order if their margins aren't dependent on adjoining sides.
84 | * Not being concerned with collapsing margins means one less thing to worry about.
85 |
86 | #### Colors
87 |
88 | * Colors should be set as variables for theming purpose.
89 |
90 | * Hex notation is prefered for convenience and shortness.
91 |
92 | ### Formatting
93 |
94 | Single-line styles should be formatted as follows:
95 |
96 | ```
97 | [selector(s)] { [property]: [value]; }
98 | ```
99 |
100 | Multiple-line styles should be formatted as follows:
101 |
102 | ```
103 | [selectors] {
104 | [property]: [value];
105 | [property]: [value];
106 | }
107 | ```
108 |
109 | Use soft-tabs with a two space indent. Spaces are the only way to guarantee code renders the same in any person's environment.
110 |
111 | **Avoid [unnecessary nesting](http://thesassway.com/intermediate/avoid-nested-selectors-for-more-modular-css) in SCSS.**
112 |
113 | At most, aim for two levels. It is perfectly reasonable to use nesting when creating components, however limit the amount of levels as much as possible.
114 |
115 | * Increases specificity unnecessarily.
116 | * Limits portability.
117 | * Less efficient.
118 | * If you cannot help it, step back and rethink your overall strategy (either the specificity needed, or the layout of the nesting).
119 |
120 | #### Organisation
121 |
122 | CSS attributes should be organized by types, like:
123 |
124 | ```
125 | [selectors] {
126 | //layout
127 | margin: 0 0 0 0;
128 | [property]: [value];
129 |
130 | //skin
131 | background: $background-color;
132 | [property]: [value];
133 |
134 | //typo
135 | font-size: 12px;
136 | [property]: [value];
137 | }
138 | ```
139 |
140 | ### Naming conventions
141 |
142 | Follow a very simple naming convention: hyphen (-) delimited strings, with BEM-like naming for more complex pieces of code.
143 |
144 | #### Hyphen Delimited
145 |
146 | All strings in classes are delimited with a hyphen (-), like so:
147 |
148 | ```
149 | .page-head {}
150 |
151 | .sub-content {}
152 | ```
153 |
154 | Camel case and underscores are not used for regular classes; the following are incorrect:
155 |
156 | ```
157 | .pageHead {}
158 |
159 | .sub_content {}
160 | ```
161 |
162 | ### BEM like Naming
163 |
164 | BEM, meaning Block, Element, Modifier, is a front-end methodology coined by developers working at Yandex. Whilst BEM is a complete methodology, here we are only concerned with its naming convention. Further, the naming convention here only is BEM-like; the principles are exactly the same, but the actual syntax differs slightly.
165 |
166 | BEM splits components classes into three groups:
167 |
168 | * Block: The sole root of the component.
169 | * Element: A component part of the Block.
170 | * Modifier: A variant or extension of the Block.
171 |
172 | This gives:
173 |
174 | ```
175 |
176 |
177 |
![]()
178 |
179 |
...
180 |
181 |