2nd edition update

HISTORY.md

@@ -0,0 +1,37 @@
+## [v2.0.0]
+> _Unreleased_
+
+This is the first release of the second edition of RSCSS. There are some changes to recommendations:
+
+* Components are allowed to have margins. This lets you use components together in a page without worrying about their margins.
+* `@extend` is no longer recommended. This has caused a lot of debate (#9), and this hasn't really been used much in practice.
+* Variants can now have more than one word (eg, `.-no-icon`).
+
+## [v1.3.0]
+> Jun  3, 2015
+
+Reorganized the document into clearer sections. No content changes.
+
+* Introduction: updated this section to reflect the purpose of rscss better.
+
+## [v1.2.0]
+> Jun  3, 2015
+
+* Add helpers.
+* Remove 'work in progress' icon — rscss should be considered pretty stable now.
+
+## [v1.1.0]
+> Feb 10, 2015
+
+Child selectors are now the preferred convention for styling elements. ([#2])
+
+## v1.0.0
+> Jan 30, 2015
+
+Initial version of the first edition.
+
+[#2]: https://github.com/rstacruz/rscss/issues/2
+[v1.1.0]: https://github.com/rstacruz/rscss/compare/v1.0.0...v1.1.0
+[v1.2.0]: https://github.com/rstacruz/rscss/compare/v1.1.0...v1.2.0
+[v1.3.0]: https://github.com/rstacruz/rscss/compare/v.1.2.0...v1.3.0
+[v2.0.0]: https://github.com/rstacruz/rscss/compare/v.1.3.0...v2.0.0

docs/README.md

@@ -9,11 +9,14 @@
   - [Layouts](layouts.md)
   - [Helpers](helpers.md)
 - **Structure**
-  - [CSS Structure](css-structure.md)
+  - [CSS structure](css-structure.md)
+  - [CSS preprocessors](css-preprocessors.md)
 - **Notes**
   - [Pitfalls](pitfalls.md)
   - [Apprehensions](apprehensions.md)
+  - [Simplifying nested components](simplifying-nested-components.md)
   - [Other resources](other-resources.md)
 - [Summary](summary.md)
+- [History](../HISTORY.md)
 - **External resources**
   - [Translations](translations.md)

docs/css-preprocessors.md

@@ -0,0 +1,8 @@
+# CSS preprocessors
+
+It's recommended to use RSCSS conventions with a preprocessor. These preprocessors are very mature and highly recommended:
+
+- [Sass](http://sass-lang.com/)
+- [PostCSS](http://postcss.org/) (with [cssnext](http://cssnext.io/) and [postcss-import](https://github.com/postcss/postcss-import))
+
+Other preprocessors such as [Less](http://lesscss.org/) would suffice, too. You may also use RSCSS without a preprocessor.

docs/layouts.md

@@ -2,41 +2,53 @@
 
 ![](images/layouts.png)
 
-## Avoid positioning properties
-Components should be made in a way that they're reusable in different contexts. Avoid putting these properties in components:
+Components should be built in a way that it can be reused in different places. To achieve this goal, components shouldn't define where they are to be placed; rather, positioning porperties should be defined in the parent component.
+
+Layouts are a special kind of component that defines how other components are placed inside them.
+
+## Define positioning in parents
+
+In this example below, notice that the widths and floats are applied on the *list* component, not the component itself.
+
+```css
+/* ✗ Avoid: positioning properties placed in an component */
+.article-card {
+  width: 33.3%;
+  float: left;
+}
+```
+
+```css
+/* ✓ Better: positioning propreties placed in elements */
+.article-list {
+  @include clearfix;
+
+  > .article-card {
+    width: 33.3%;
+    float: left;
+  }
+}
+
+.article-card {
+  & { /* ... */ }
+  > .image { /* ... */ }
+  > .title { /* ... */ }
+  > .category { /* ... */ }
+}
+```
+
+## Positioning properties
+Avoid putting these properties in components. Instead, put them in elements of components.
 
   * Positioning (`position`, `top`, `left`, `right`, `bottom`)
   * Floats (`float`, `clear`)
-  * Margins (`margin`)
   * Dimensions (`width`, `height`) *
 
 ## Fixed dimensions
 
 Exception to these would be elements that have fixed width/heights, such as avatars and logos.
 
-## Define positioning in parents
-
-If you need to define these, try to define them in whatever context they will be in. In this example below, notice that the widths and floats are applied on the *list* component, not the component itself.
-
-  ```css
-  .article-list {
-    & {
-      @include clearfix;
-    }
-
-    > .article-card {
-      width: 33.3%;
-      float: left;
-    }
-  }
-
-  .article-card {
-    & { /* ... */ }
-    > .image { /* ... */ }
-    > .title { /* ... */ }
-    > .category { /* ... */ }
-  }
-  ```
+<!-- TODO: example -->
 
 How do you apply margins outside a layout? Try it with Helpers.
 [Continue →](helpers.md)

docs/nested-components.md

@@ -4,7 +4,7 @@
 
 ```html
 <div class='article-link'>
-  <div class='vote-box'>
+  <div class='vote vote-box'>
     ...
   </div>
   <h3 class='title'>...</h3>
@@ -14,20 +14,22 @@
 
 Sometimes it's necessary to nest components. Here are some guidelines for doing that.
 
-## Variants
-A component may need to appear a certain way when nested in another component. Avoid modifying the nested component by reaching into it from the containing component.
+## Avoid styling nested components
+A component may need to appear a certain way when nested in another component. Avoid modifying the nested component by reaching into it from the containing component. This can cause problems with specificity.
 
 ```scss
 .article-header {
-  > .vote-box > .up { /* ✗ avoid this */ }
+  > .vote-box { } // ✗ avoid this
+  > .vote-box > .up { } // ✗ avoid this
 }
 ```
 
-  Instead, prefer to add a variant to the nested component and apply it from the containing component.
+## Variants in nested components
+Instead, prefer to add a variant to the nested component.
 
 ```html
 <div class='article-header'>
-  <div class='vote-box -highlight'>
+  <div class='vote-box -small'>
     ...
   </div>
   ...
@@ -36,36 +38,7 @@ A component may need to appear a certain way when nested in another component. A
 
 ```scss
 .vote-box {
-  &.-highlight > .up { /* ... */ }
-}
-```
-
-## Simplifying nested components
-Sometimes, when nesting components, your markup can get dirty:
-
-```html
-<div class='search-form'>
-  <input class='input' type='text'>
-  <button class='search-button -red -large'></button>
-</div>
-```
-
-You can simplify this by using your CSS preprocessor's `@extend` mechanism:
-
-```html
-<div class='search-form'>
-  <input class='input' type='text'>
-  <button class='submit'></button>
-</div>
-```
-
-```scss
-.search-form {
-  > .submit {
-    @extend .search-button;
-    @extend .search-button.-red;
-    @extend .search-button.-large;
-  }
+  &.-small > .up { /* ... */ }
 }
 ```
 

docs/other-resources.md

@@ -25,6 +25,35 @@ Other solutions
 </form>
 ```
 
+### Deep components
+
+With BEM, you're allowed to have deep components where the DOM subtree can go down many levels deep. While this is true in RSCSS as well, the dependence on the child selector (`>`) makes this impractical.
+
+This more of a feature than a defect in RSCSS: it forces you to create new components for deep hierarchies, making this more manageable. RSCSS's use of `>` also makes it easy to visualize a DOM structure based on CSS styles, leading to self-documenting code.
+
+<!-- TODO: illustration -->
+
+```css
+/* BEM: ✓ allowed */
+.site-search {
+  &--icon { /*...*/ }
+}
+```
+
+```css
+/* RSCSS: ✗ confusing and impractical */
+.site-search {
+  > .top > .info > .label > .icon { /*...*/ }
+}
+```
+
+```css
+/* RSCSS: ✓ better to create sub-components for deep hierarchies */
+.site-search-label {
+  > .icon { /*...*/ }
+}
+```
+
 ## Terminologies
 
 The same concepts exist in similar ways in other CSS structuring ideologies.

docs/simplifying-nested-components.md

@@ -0,0 +1,45 @@
+# Simplifying nested components
+
+Sometimes, when nesting components, your markup can get dirty:
+
+```html
+<div class='search-form'>
+  <input class='input' type='text'>
+  <button class='search-button -red -large'></button>
+</div>
+```
+
+You can simplify this by refactoring your common component into mixins.
+
+```scss
+.search-button {
+  @include search-button;
+
+  &.-red {
+    @include search-button-red;
+  }
+
+  &.-large {
+    @include search-button-large;
+  }
+}
+```
+
+You can then use the mixins to style elements in your component.
+
+```html
+<div class='search-form'>
+  <input class='input' type='text'>
+  <button class='submit'></button>
+</div>
+```
+
+```scss
+.search-form {
+  > .submit {
+    @include search-button;
+    @include search-button-red;
+    @include search-button-large;
+  }
+}
+```

docs/variants.md

@@ -7,25 +7,32 @@ Components may have variants. Elements may have variants, too.
 <br>
 
 ## Naming variants
-Classnames for variants will be prefixed by a dash (`-`).
+Classnames for variants will be prefixed by a dash (`-`). A variant may have more than one word, as long as they are joined by dashes.
 
-  ```scss
-  .like-button {
-    &.-wide { /* ... */ }
-    &.-short { /* ... */ }
-    &.-disabled { /* ... */ }
-  }
-  ```
+```scss
+.like-button {
+  &.-wide { /*...*/ }
+  &.-short { /*...*/ }
+  &.-disabled { /*...*/ }
+  &.-no-line { /*...*/ }
+}
+```
 
 ## Element variants
-Elements may also have variants.
-
-  ```scss
-  .shopping-card {
-    > .title { /* ... */ }
-    > .title.-small { /* ... */ }
-  }
-  ```
+Both components and elements may have variants.
+
+```scss
+// Element variants
+.shopping-cart {
+  > .title { /*...*/ }
+  > .title.-small { /*...*/ }
+}
+
+// Component variants
+.shopping-cart.-inline {
+  /* ... */
+}
+```
 
 ## Dash prefixes
 Dashes are the preferred prefix for variants.