edge_framework 1.4.1 → 2.0.0.a

data/README.md

@@ -3,98 +3,114 @@
 EDGE FRAMEWORK
 ==========================
 
-Edge is a light-weight responsive Sass framework. No gimmick, just the barebone to build modern website.
+Edge is a light-weight Sass framework. It specializes in making a website from scratch.
 
 It is based on [Foundation by ZURB](http://www.zurb.com).
 
-**OUR PHILOSOPHY**
+This is **v2 docs**, [go here for v1](https://github.com/hrsetyono/edge/wiki/v1-Docs).
 
-My personal preference is to have a framework not do something and implement it myself than have a framework do something and figure out how to do the opposite.
+BROWSER SUPPORT
+------------------
+
+All modern browsers:
+
+- Chrome, Firefox, Safari, Opera
+- Android 4.0 and above
+- IE 9 and above
 
 INSTALLATION
 -----------------
 
+**PC**
+
+[Install Ruby]((https://docs.google.com/document/d/155e-Dx4SnQj_bMrM24kI4_ZEmBp-TQ_tuinhMvZsIhM/edit?usp=sharing) and type this command in your *cmd* (command prompt):
+
     gem install edge_framework
 
-Windows PC doesn't come with Ruby pre-installed, so you can follow [this Ruby installation guide](https://docs.google.com/document/d/155e-Dx4SnQj_bMrM24kI4_ZEmBp-TQ_tuinhMvZsIhM/edit?usp=sharing) we wrote.
+**MAC**
 
-After you installed Ruby, type in the command above on `cmd` (command prompt).
+Open your *terminal* and type:
 
-BROWSER SUPPORT
+    sudo gem install edge_framework
+
+GETTING STARTED
 ------------------
 
-All modern browsers:
+Generate the template files by running this command in your project directory:
 
-- Chrome, Firefox, Safari, Opera
-- Android 4.0 and above
-- IE 9 and above
+    edge create <type>
+
+Available types are: `html`, `wordpress`, `email`, and `ghost`.
+
+To compile the Sass, run this command:
+
+    compass watch
 
 GRID SYSTEM
 ==================
-    .row
-    .column
-    .large-x
-    .small-x
+    
+    <h-row>
+    <h-column>
 
-Our Grid is divided into **12 columns**. Start with "row" followed by "column" used in conjunction with its width.
+Our Grid is divided into **12 columns**. Start with `<h-row>` followed by `<h-column>`.
 
-    <div class="row">
-      <div class="large-8 column"></div>
-      <div class="large-4 column"></div>
-    </div>
+    <h-row>
+      <h-column class="large-8"></h-column>
+      <h-column class="large-4"></h-column>
+    </h-row>
 
 ![Edge Grid - Large only](http://cdn.setyono.net/edge/grid-large.jpg)
 
-    <div class="row">
-      <div class="large-8 small-6 column"></div>
-      <div class="large-4 small-6 column"></div>
-    </div>
+    <h-row>
+      <h-column class="large-8 small-6"></h-column>
+      <h-column class="large-4 small-6"></h-column>
+    </h-row>
 
 ![Edge Grid - Large and Small](http://cdn.setyono.net/edge/grid-large-small.jpg)
 
-The element doesn't have to be div, it can be section, article, header, etc.
+**Note**:
 
-Sizing:
+- `h-row` must be followed by `h-column`. Nothing in between!
 
-- Large - above 768px
+- Don't add your own styling to the row or column element.
 
-- Small - below or equal to 768px, width will be 100% if not specified.
+- Large is above 768px by default.
 
-**Convention**:
-
-- Don't add your own style to the `.row` and `.column` elements.
+- Small is below or equal to 768px. If not specified, column will become 100% width.
 
 Nesting
 -----------
 
-    <div class="row">
-      <div class="large-8 column">
-        <div class="row">
-          <div class="large-2 column"></div>
-          <div class="large-10 column"></div>
-        </div>
-      </div>
-      <div class="large-4 column"></div>
-    </div>
+    <h-row>
+      <h-column class="large-8">
+        <h-row>
+          <h-column class="large-2"></h-column>
+          <h-column class="large-10"></h-column>
+        </h-row>
+      </h-column>
+      <h-column class="large-4"></h-column>
+    </h-row>
 
 ![Edge Grid - Nesting](http://cdn.setyono.net/edge/grid-nesting.jpg)
 
 Collapse
 -----------
 
-    .row.collapse
+    .collapse
 
 Remove the gutter.
 
-    <div class="row collapse">
-      <div class="large-9 small-6 column"></div>
-      <div class="large-3 small-6 column"></div>
-    </div>
-
-All nested rows inside collapsed one will be collapsed too.
+    <h-row class="collapse">
+      <h-column class="large-9 small-6"></h-column>
+      <h-column class="large-3 small-6"></h-column>
+    </h-row>
 
 ![Edge Grid - Collapse](http://cdn.setyono.net/edge/grid-collapse.jpg)
 
+**Note**:
+
+- Normal row that is nested inside collapsed row will maintain its gutter.
+
 Centering
 -----------
 
@@ -105,9 +121,9 @@ Horizontally centering a column.
 
 It is inherited on small screen.
 
-    <div class="row">
-      <div class="large-7 small-7 centered column"></div>
-    </div>
+    <h-row>
+      <h-column class="large-7 small-7 centered"></h-column>
+    </h-row>
 
 ![Edge Grid - Centered](http://cdn.setyono.net/edge/grid-centered.jpg)
 
@@ -121,51 +137,31 @@ Offset leaves a **gap** before the column.
 
 It is ignored on small screen unless the small sizing is specified.
 
-    <div class="row">
-      <div class="large-2 column"></div>
-      <div class="large-6 offset-4 column"></div>
-    </div>
+    <h-row>
+      <h-column class="large-2 column"></h-column>
+      <h-column class="large-6 offset-4 column"></h-column>
+    </h-row>
 
 ![Edge Grid - Offset](http://cdn.setyono.net/edge/grid-offset.jpg)
 
-Column Ordering
------------------
-
-    push-x
-    pull-x
-
-**Push** pushes the column to the right, while **Pull** pulls it to the left.
-
-They are ignored on small screen.
-
-**Example**:
-
-Create a sidebar that is located on the left. But if viewed with phone, it is on the bottom.
-
-    <div class="row">
-      <main class="large-8 push-4 column"></main>
-      <aside class="large-4 pull-8 column"></aside>
-    </div>
-
-The snippet above will look like this:
-
-![Edge Grid - Ordering](http://cdn.setyono.net/edge/grid-ordering.jpg)
 
 GRID SYSTEM - TILE
 =================
 
-    ul.tile-x
-    ul.small-tile-x
+    <h-tile>
+    <h-ti>
+    .block-x
+    .small-block-x
 
 Evenly divides the list into block size.
 
-    <ul class="tile-3 small-tile-2">
-      <li>1</li>
-      <li>2</li>
-      <li>3</li>
-      <li>4</li>
-      <li>5</li>
-    </ul>
+    <h-tile class="block-3 small-block-2">
+      <h-ti> 1 </h-ti>
+      <h-ti> 2 </h-ti>
+      <h-ti> 3 </h-ti>
+      <h-ti> 4 </h-ti>
+      <h-ti> 5 </h-ti>
+    </h-tile>
 
 ![Edge Grid - Tile](http://cdn.setyono.net/edge/grid-tile.jpg)
 
@@ -173,13 +169,13 @@ Each tile will expand 100% on small screen when the small size is not specified.
 
 Just like row, you can collapse it:
 
-    <ul class="tile-7 collapse"> ... </ul>
+    <h-tile class="block-7 collapse"> ... </h-tile>
 
 **Convention**:
 
-- In your own stylesheet, don't name a class that contains the word "tile".
+- Don't name any of your class starting with `block`. It is reserved for tile.
 
-- Don't add your own style to the `.tile` and `.tile > li` elements.
+- Don't add your own styling to the tile or ti element.
 
 TYPOGRAPHY
 ======================
@@ -206,96 +202,6 @@ With any class
     List 2
     List 3
 
-If you want horizontal list, add `.inline-list` class.
-
-    <ul class="inline-list">...</ul>
-    
-    Result:
-    List 1 List 2 List 3
-
-VISIBILITY
-==================
-
-    .hide-for-<size>
-    .show-for-<size>
-
-    <size> = large / small / mini
-
-**Hide** means hidden only on that size. **Show** means visible only on that size.
-
-Sizing:
-
-- Large - above 768px
-
-- Small - below or equal to 768px
-
-- Mini - below or equal to 480px
-
-**VISIBILITY SCALE**
-
-    0-----480-----768------------->
-
-    |-mini-|
-
-    |----small-----|
-
-                   |----large----->
-
-Notice that small size includes the mini portion too.
-
-**VISIBILITY TABLE**
-
-    ✓ = visible
-
-                       Large  Small  Mini
-
-    .hide-for-large      -      ✓     ✓
-    .hide-for-small      ✓      -     -
-    .hide-for-mini       ✓      ✓     -
-
-    .show-for-large      ✓      -     -
-    .show-for-small      -      ✓     ✓
-    .show-for-mini       -      -     ✓
-
-From the table, we can see that some classes like `.hide-for-large` and `.show-for-small` have same result. It is up to your preference on which word makes more sense.
-
-EXAMPLE
---------------
-    
-Sidebar hidden on mini screen
-
-    <aside class="hide-for-mini"></aside>
-
-Slider visible only on large screen
-    
-    <div role="banner" class="show-for-large"></div>
-    // or
-    <div role="banner" class="hide-for-small"></div>
-
-BOILERPLATE GENERATOR
-========================
-
-Generate basic template for your project. Run this command inside your project directory:
-
-1. Static HTML
-
-    `edge create html`
-
-2. Wordpress 3.8+ (Min PHP 5.3)
-
-    `edge create wordpress`
-
-3. Ghost Blog
-
-    `edge create blog`
-
-4. Rails (run inside Rails project)
-
-    `rails g edge:install`
-
-5. Coming soon: Sinatra and Flask
-
-
 WORDPRESS
 ====================
 
@@ -319,7 +225,7 @@ Inside `functions.php`, add these codes:
 
 The icon name is taken from [melchoyce.github.io/dashicons/](http://melchoyce.github.io/dashicons/).
 
-Tips:
+**Note**:
 
 - If you want pagination to work, the `$name` cannot be the same as any page's slug.
 
@@ -372,6 +278,47 @@ If the base size is not default, pass it as second parameter:
       }
     }
 
+MEDIA QUERY - mixin
+=========================
+
+    below($size)
+    above($size)
+    between($smaller-size, $larger-size)
+    
+    $size = large / small / mini
+
+**Below** means less than or equal to (`<=`).
+
+**Above** means more than (`>`).
+
+**Between** is inclusive to both (`>= smaller-size` and `<= larger-size`).
+
+    p {
+      color: black;
+
+      @include above(small) {
+        color: blue;
+      }
+
+      @include below(small) {
+        color: yellow;
+      }
+    }
+
+You can use pixel too:
+
+    p {
+      color: black;
+      
+      @include above(850px) {
+        color: pink;
+      }
+
+      @include between(300px, 400px) {
+        color: green;
+      }
+    }
+
 GRID - mixin
 ======================
   
@@ -385,49 +332,43 @@ GRID - mixin
       $small   : int    - The small sizing
       $mini    : int    - The mini sizing (below 480px)
       $offset  : int
-      $push    : int
-      $pull    : int
-      $collapse : bool
       $centered : bool
-      $gutter   : px
       $total    : int   - Total number of columns
       
 
 Custom grid makes the markup cleaner and easier to change.
 
     // HTML
-    <div class="row">
-      <aside class="column"></aside>
-      <main class="my-col column"></main>
-    </div>
+    <h-row>
+      <h-column class="sidebar"></h-column>
+      <h-column class="content"></h-column>
+    </h-row>
 
 
     // SCSS
-    aside.column {
-      @include column(2, 4, 12);
-      // or
+    .sidebar {
       @include column($size: 2, $small: 4, $mini: 12);
+      // or
+      @include column(2, 4, 12);
     }
 
-    .my-col {
+    .main {
       @include column(10, 8, 12);
-      // or
-      @include column($size: 10, $small: 8, $mini: 12);
     }
 
-**Convention**:
+**Note**:
 
-- Custom column must be applied to the element that has `column` class. The same goes to custom row.
+- Custom column MUST be applied to `h-column` element. The same rule goes to custom row.
 
 ### GUTTER
 
-Custom gutter must be applied to both row and column.
+Custom gutter is applied to the row
 
     // HTML
-    <div class="my-row row">
-      <aside class="column"></aside>
-      <main class="my-col column"></main>
-    </div>
+    <h-row class="my-row">
+      <h-column class="large-3"></h-column>
+      <h-column class="large-9"></h-column>
+    </h-row>
 
 
     // SCSS
@@ -435,74 +376,53 @@ Custom gutter must be applied to both row and column.
       @include row($gutter: 50px);
     }
 
-    aside.column {
-      @include column($size: 2, $gutter: 50px);
-    }
+## GUTTER on large and small
+
+Unlike the column's sizing. There's no parameter called `small-gutter` or `mini-gutter`.
 
-    .my-col {
-      @include column($size: 10, $gutter: 50px);
+So, the workaround is to use media query:
+
+    .my-row {
+      @include row($gutter: 50px);
+
+      @include below(small) {
+        @include row($gutter: 20px);
+      }
     }
 
+**Note**:
+
+- Use the same workaround for column's `offset`.
+
 ### COLLAPSE
 
-Collapse must be applied to both row and column.
+Collapse is applied to the row
     
+    // HTML
+    <h-row class="my-row">
+      ...
+    </h-row>
+
+
+    // SCSS
     .my-row {
       @include row($collapse: true);
     }
 
-    .my-col {
-      @include column($size: 10, $collapse: true);
-    }
-
 ### TOTAL COLUMNS
 
 You can either use `$total` parameter or fraction:
-
-    .my-col {
+      
+    .content {
       @include column($size: 7, $offset: 3, $total: 15);
     }
 
     // or
 
-    .my-col {
+    .content {
       @include column($size: 7 / 15, $offset: 3 / 15);
     }
 
-GRID PIXEL *beta
-===============
-
-    column-px()
-      $size     : px
-      $width    : px
-      $gutter   : px
-      $centered : boolean
-
-Let's say a designers gives you a design that doesn't follow grid system. Here's an example:
-
-![Pre-given Design](http://cdn.setyono.net/edge/custom-total-column.jpg)
-
-With `column-px()` mixin, we can create that layout easily:
-
-    // HTML
-    <div class="my-row row">
-      <main class="my-col column"> ... </main>
-      <aside class="side-col column"> ... </aside>
-    </div>
-
-    // SCSS
-    .my-row {
-      @include row($gutter: 35px);
-    }
-
-    .my-col {
-      @include column-px($size: 500px, $width: 735px, $gutter: 35px);
-    }
-
-    .side-col {
-      @include column-px($size: 200px, $width: 735px, $gutter: 35px);
-    }
-
 TILE - mixin
 ======================
 
@@ -515,74 +435,20 @@ TILE - mixin
 
 Mini sizing is available for tile's mixin too.
 
-    <ul class="products"></ul>
+    <h-tile class="products">
+      ...
+    </h-tile>
 
     .products {
-      @include tile($size: 7, $small: 4, $mini: 2);
-      
-      // or
-      
       @include tile(7, 4, 2);
     }
 
-MEDIA QUERY - mixin
-=========================
-
-    below($size)
-    above($size)
-    between($smaller-size, $larger-size)
-    
-    $size = large / small / mini
-
-**Below** means less than or equal to (`<=`).
-
-**Above** means more than (`>`).
-
-**Between** is inclusive to both (`>= smaller-size` and `<= larger-size`).
-
-    p {
-      color: black;
-
-      @include above(small) {
-        color: blue;
-      }
-
-      @include below(small) {
-        color: yellow;
-      }
-    }
-
-You can use pixel too:
-
-    p {
-      color: black;
-      
-      @include above(850px) {
-        color: pink;
-      }
-
-      @include between(300px, 400px) {
-        color: green;
-      }
-    }
-
-VISIBILITY - mixin
-========================
-
-We don't offer mixin for visibility. Use media query instead:
-
-    .sidebar {
-      @include below(small) {
-        display: none;
-      }
-    }
-
 RAILS
 =================
 
 ![Edge Rails](http://cdn.setyono.net/edge/rails-edge.jpg)
 
-Gemfile:
+Add this chunk to your gemfile (some already came in default Rails project):
 
     gem 'sass'
     gem 'sass-rails', '~> 4.0.0'
@@ -602,9 +468,18 @@ FAQ
 
   Edge leans toward those who create website based on designer's wireframe/mockup.
 
-  Bootstrap and Foundation offer pre-styled elements which are great for quick prototyping. But when you are working with a designer, you won't use any of those styling.
+  Bootstrap and Foundation offer ready-to-use elements. Trying to match a designer's work with it will just end up in you overriding most of them. And that may result in unexpected style and bloated code.
 
 2. Is Edge a mobile-first framework?
 
   No it is not.
 
+3. What's changed from v1?
+
+Major changes are:
+
+- Grid and Tile now use Web Component.
+
+- Visibility class is removed.
+
+- Source Ordering (pull and push) is removed.