README.md in sewing_kit-0.7.1 vs README.md in sewing_kit-0.8.0

@@ -1,9 +1,89 @@
 # sewing_kit
 
-A solid foundation for modern FED stacks in Shopify apps.
+Zero configuration, high performance front end development at organization scale.
 
-## Other repos
+This document focuses on Rails integration.  For details of `sewing-kit`'s configuration and usage, see the [sewing-kit documentation](https://github.com/Shopify/sewing-kit#sewing-kit).
 
-https://github.com/rails/webpacker
-https://github.com/shakacode/react_on_rails
-https://github.com/mipearson/webpack-rails
+## Quick Start
+Create a Rails project using `dev init` then:
+
+### Install Sewing Kits
+```sh
+# Add Ruby/Node dependencies
+bundle add sewing_kit
+yarn add --dev @shopify/sewing-kit
+yarn add --dev react-hot-loader@3.0.0-beta.7
+
+# Optional - add Polaris
+yarn add @shopify/polaris react react-dom
+
+yarn
+dev up
+```
+
+### Add JavaScript
+sewing_kit looks for JavaScript in `app/ui/index.js`.  The code in `index.js` (and any imported JS/CSS) will be built into a `main` bundle.
+
+### Link to JS/CSS with `erb` Helpers
+The `main` bundle is imported into `erb` files using Rails helpers:
+
+```erb
+<%= sewing_kit_link_tag *sewing_kit_asset_paths('main') %>
+<%= sewing_kit_script_tag *sewing_kit_asset_paths('main') %>
+```
+
+**Note:** CSS `<link>` tags appear only in production; in development, CSS is embedded within the `main.js` bundle.
+
+## Minimal Project Layout
+```
+├── Gemfile (must contain "gem 'sewing_kit")
+├── package.json (must specify '@shopify/sewing-kit' as a 'devDependency')
+│
+└── app
+   └── ui
+   │   └─- index.js
+   └── views
+       └─- layouts
+           └─- application.html.erb (must link to JS / CSS using sewing_kit_script_tag / sewing_kit_link_tag
+```
+
+## Rails, Polaris, and React Layout
+A typical Polaris app will use React to render views and components.  The following layout shows best practice locations for:
+- Global SCSS settings
+- App sections (roughly analogous to Rails routes)
+- Components
+- Co-located CSS modules
+- Co-located unit tests
+
+```
+└── app
+    └── ui
+        ├─- index.js (renders React into the DOM)
+        ├── styles (optional)
+        │   └── settings.scss (global vars and @polaris overrides)
+        │
+        └── components (optional)
+            ├── App
+            │   ├── index.js
+            │   ├── App.js
+            │   └── tests
+            │       └── App.test.js
+            │
+            ├-─ MyComponent
+            │   ├-─ index.js
+            │   ├-─ MyComponent.js
+            │   ├── MyComponent.scss (optional; component-scoped CSS styles, mixins, etc)
+            │   └── tests
+            │       └── MyComponent.test.js
+            │
+            └── sections (optional; container views that compose presentation components into UI blocks)
+                └── Home
+                    ├-─ index.js
+                    └── Home.js
+```
+
+## React Boilerplate
+* Create a React app in `app/ui/App.js` ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/ui/App.js#L11))
+* In an `erb` view, add a placeholder for React content ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/views/home/index.html.erb#L4))
+* In `index.js`, render a React component into the placeholder element ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/ui/index.js))
+* Use `sewing_kit_script_tag`/`sewing_kit_link_tag` helpers to link erb/js ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/views/layouts/application.html.erb#L8))