Permalink
Browse files

Merge branch 'master' of github.com:jasonkuhrt/shorthand-edge-omissio…

…ns-stylus
  • Loading branch information...
2 parents 79ef8ce + 20f4da3 commit 3e758a88ddb710e81ede660ebf636c2cdaa2e695 @jasonkuhrt committed Mar 14, 2013
Showing with 31 additions and 77 deletions.
  1. +31 −77 Readme.md
View
108 Readme.md
@@ -1,99 +1,53 @@
-# Shorthand Omissions for [Stylus](http://learnboost.github.com/stylus/)
-[![Build Status](https://travis-ci.org/jasonkuhrt/better-clockhand-stylus.png)](https://travis-ci.org/jasonkuhrt/better-clockhand-stylus)
+# shorthand-edge-omissions-stylus [![Build Status](https://travis-ci.org/jasonkuhrt/better-clockhand-stylus.png)](https://travis-ci.org/jasonkuhrt/better-clockhand-stylus)
-Allow omitted values in shorthand 1-value, 2-value, 3-value, 4-value `padding` and `margin`.
+Permit [clockhand-stylus](https://github.com/jasonkuhrt/clockhand-stylus/blob/master/README.md#stylus-clockhand-shorthand) in `padding`/`margin`.
-.
-.
-.
-
-### Install
-```
-npm install shorthand-edge-omissions-stylus --save
-```
-
-Then in your stylus compile function
-
-```
-...
-stylus.use(require('better-clockhand-stylus')())
-stylus.import('shorthand-edge-omissions')
-...
+### Preview
```
+.foo
+  padding 1 _
+  margin _ 1 2 _ !important
-Or in your stylus CLI command
-```
-stylus ... --import ./node_modules/better-clockhand-stylus
+.foo {
+  padding-top : 1;
+  padding-bottom: 2;
+ 
+  margin-right : 1 !important;
+  margin-bottom : 1 !important;
+}
```
+### Summary
+- [Stylus](https://github.com/learnboost/stylus) [mixin](https://github.com/LearnBoost/stylus/blob/master/docs/mixins.md) (not [function](https://github.com/LearnBoost/stylus/blob/master/docs/functions.md))
+- `_` in `padding`/`margin` shorthand ([clockhand-stylus syntax](https://github.com/jasonkuhrt/clockhand-stylus/blob/master/README.md#stylus-clockhand-shorthand))
+- Opinion:
+ - Writing `margin`/`padding` assignment becomes brisker since you can use shorthand 100% of the time
+ - Edges are represented with "graphics" not words: `margin: 4 3 _ _; vs margin-top:3; margin-right:3;`
+ - Collecting all `padding` or `margin` edges on one line eases maintainence and visual scanning
+ - At scale, writing `margin: 4px 0 0 17px;` when you don't actually want zeros destablizes your css codebase with rule overriding possibilities
.
.
.
-
-### Examples
-2-value
-```
-.foo-selector
-  padding 4rem _
-```
-```  
-.foot-selector {
-  padding-top   : 4rem;
-  padding-bottom: 4rem;
-}
+### Install
```
+npm install shorthand-edge-omissions-stylus --save
-.
-4-value
-
-```
-.foo-selector
-  padding 4rem 4rem _ 4rem
-```
-```
-.foot-selector {
-  padding-top  : 4rem;
-  padding-right: 4rem;
-  padding-left : 4rem;
-}
+stylus.use(require('shorthand-edge-omissions-stylus')())
+stylus.import('shorthand-edge-omissions') // global import, optional
+$ stylus ... --import ./node_modules/better-clockhand-stylus // global import alt, optional
```
-.
-.
-.
-
-### What
+### Documentation
-With omissions you never *have* to leave shorthand `margin`/`padding` syntax. CSS often forces you to leave shorthand even if you'd prefer not to. For instance you cannot specify just `margin-top`/`margin-bottom`.
+Omissions allow you to skip values, whereas CSS forces you to assign something.
-Native CSS `padding`/`margin` [shorthand syntax](https://developer.mozilla.org/en-US/docs/CSS/Shorthand_properties) vs omissions:
```
-.foo { margin : 4px 0; } .foo { padding: 0 25px 46px; } .foo { padding: 4px 0 0 17px; }
+CSS .foo { margin : 4px 0; } .foo { padding: 0 25px 46px; } .foo { padding: 4px 0 0 17px; }
```
```
-.foo { margin : 4px _; } .foo { padding: _ 25px 46px; } .foo { padding: 4px _ _ 17px; }
+Stylus .foo { margin : 4px _; } .foo { padding: _ 25px 46px; } .foo { padding: 4px _ _ 17px; }
```
-Omissions allow you to skip values, whereas CSS forces you to assign something.
-
-.
-.
-.
-
-### Why
-- It makes writing your CSS more fun
-- Collecting all `padding` or `margin` side properties (`top`/`right`/`bottom`/`left`) on one line helps readers visually scan for dimensions information.
-- In my experience writing CSS can be a verbose, repetitive, and fatiguing experience; small effecientcy wins like ommissions will eventually make the load noticably lighter
-- Writing `margin: 4px 0 0 17px;` when you don't actually need those zeros is error-prone, especially when using modern OOCSS patterns that break styling across discrete classes because `0` on a generic class might blow away an actually meaningful unit on another generic class. It is also a diservice to readers and logic to provide meaningless data for the sake of shorthand syntax.
-
-.
-.
-.
-
-### License
-
-MIT
+See [clockhand-stylus syntax](https://github.com/jasonkuhrt/clockhand-stylus/blob/master/README.md#stylus-clockhand-shorthand)
-### Further Reading
-Learn more about CSS shorthand: https://developer.mozilla.org/en-US/docs/CSS/Shorthand_properties

0 comments on commit 3e758a8

Please sign in to comment.