Renewed stylus readme

packages/stylus/README.md

@@ -1,18 +1,87 @@
 # stylus
 
-[Stylus](http://learnboost.github.com/stylus/) is a CSS pre-processor with a simple syntax and expressive
-dynamic behavior. It allows for more compact stylesheets and
-helps reduce code duplication in CSS files.
+[Stylus](http://learnboost.github.com/stylus/) is a CSS pre-processor with a
+simple syntax and expressive dynamic behavior. It allows for more compact
+stylesheets and helps reduce code duplication in CSS files.
 
-With the `stylus` package installed, `.styl` files in your application are
-automatically compiled to CSS and the results are included in the client
-CSS bundle.
+With the `stylus` package installed, `.main.styl` files in your application are
+automatically compiled to CSS and the results are included in the client CSS
+bundle.
 
-The `stylus` package also includes `nib` support. Add `@import 'nib'` to
-your `.styl` files to enable cross-browser mixins such as
-`linear-gradient` and `border-radius`.
+The `stylus` package also includes `nib` support. Add `@import 'nib'` to your
+`.main.styl` files to enable cross-browser mixins such as `linear-gradient` and
+`border-radius`.
 
 If you want to `@import` a file, give it the extension `.import.styl`
 to prevent Meteor from processing it independently.
 
 See <http://tj.github.io/nib/> for documentation of the nib extensions of Stylus.
+
+
+## Usage
+
+The package processes all `.styl` files, treating `.main.styl` as entry points
+and all other `.styl` as potential imports.
+
+Example:
+
+A component stylus file, importable, but not an entry-point:
+
+```stylus
+// app/components/my-component/styles.styl
+$primary-color = #A7A7A7
+.my-component
+  input
+    border 1px solid
+  textarea
+    color $primary-color
+```
+
+The main app entry point for the styles, `app.main.styl`:
+
+```stylus
+// app/app.main.styl
+@import './components/my-component/styles'
+
+// ... rest of app styles
+```
+
+
+## Cross-packages imports
+
+This package allows apps to import Stylus styles from packages and vice-versa.
+The import syntax from importing files from other packages is curly braces:
+
+```stylus
+// app.main.styl
+// import styles from a package
+@import '{procoder:fancy-buttons}/styles/buttons.styl'
+
+// use imported styles in our code
+.my-buttons
+  @extend .fancy-buttons
+  color: white
+```
+
+To import a file from the app, leave the content of curly braces empty:
+
+```stylus
+// packages/my-package/generic-buttons.main.styl
+// import the base styles from app
+@import '{}/client/colors.styl'
+
+// use the colors from app in this component
+.generic-buttons
+  background-color: $app-base-color
+```
+
+
+## Limitations
+
+Since this package uses custom code for `@import`s, some of the import syntax is
+not supported at the moment:
+
+- globbing: `@import './folder/*'`
+- importing `index.styl`: `@import ./folder/` - should automatically load
+  `./folder/index.styl`
+