Documentation updates (#92)

* Rewrite Basic Usage, move to basic-usage.md

* add .vscode to git/npmignore

* update docs

* update titles in profile-cards gql/primitives

* add images to examples.md

* update docs URLs in TOC

* gitbook doesn't like emoji shortcodes

* add allcontributors - closes #90

* add gitter to README - closes #89

* Sketch 43 is out of beta

* typos

* fix broken links to docs

* typos

* Ignore gh-pages branch on circle

* fix code of conduct link

* add 'What Can I Do With It?' to homepage

* add Contributing link to homepage

* resolve extra merge conflict

* suggested doc changes

* replace references to onRun

* remove Core Concepts doc page

* update styling docs

* quicker quickstart

* fix broken Style.md tables

* typo in README

* update TextStyles docs

* update universal rendering guide

* fix proptypes in basic-skpm example

* update example docs

* move react-primitives -> profile-cards-primitives

* Revert "add allcontributors - closes #90"

This reverts commit 5e2ec8a6bfb4bfcf5cae79ce8e30c49b931b1617.

* Use arrow functions for examples' main exports

* merge FAQ & Troubleshooting, rewrite some of FAQ

* remove Is It Stable from FAQ and table from README

* fix typos in data-fetching section

* remove comments in API.md

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Contributions are welcome and are greatly appreciated! Every little bit helps, and credit will always be given. By contributing, you agree to abide by the [code of conduct](https://github.com/airbnb/react-sketchapp/blog/master/CODE_OF_CONDUCT.md).
+Contributions are welcome and are greatly appreciated! Every little bit helps, and credit will always be given. By contributing, you agree to abide by the [code of conduct](https://github.com/airbnb/react-sketchapp/blob/master/CODE_OF_CONDUCT.md).
 
 ## Reporting Issues and Asking Questions
 

README.md

@@ -1,95 +1,64 @@
-> **requires [Sketch 43 Beta](https://sketchapp.com/beta/) or higher**
-> This project is currently in **alpha and APIs are subject to change**. If you found the repo on npm — the source (& docs, oops) is private for now; it will be announced on <a href="jon.gold/txt">my mailing list</a> and <a href="http://twitter.com/jongold">Twitter</a> very soon :)
+> This project is currently in **beta and APIs are subject to change**.
 
-<img alt="react-sketchapp" src="https://cloud.githubusercontent.com/assets/591643/22898688/146aea8e-f1dd-11e6-934c-cdbd29b82a0e.png" height="72px" />
+<div align="center">
+  <img alt="react-sketchapp" src="https://cloud.githubusercontent.com/assets/591643/22898688/146aea8e-f1dd-11e6-934c-cdbd29b82a0e.png" height="72px" />
+</div>
 
-A React renderer for [Sketch.app](https://www.sketchapp.com/) :atom_symbol: :gem:
+<div align="center">
+  <strong>render React components to Sketch; tailor-made for design systems</strong>
+</div>
 
-[![npm](https://img.shields.io/npm/v/react-sketchapp.svg)](https://www.npmjs.com/package/react-sketchapp)
-[![CircleCI](https://circleci.com/gh/airbnb/react-sketchapp.svg?style=shield&circle-token=6a90e014d72c4b27b87b0fc43ec4590117b466fc)](https://circleci.com/gh/airbnb/react-sketchapp)
-![Sketch.app](https://img.shields.io/badge/Sketch.app-43-brightgreen.svg)
-
-## Features
-
-* **Declarative.** All the lessons we've learnt from the React model of programming. A comfortable layer over Sketch’s API.
-* **Familiar.** Flexbox layouts. `react-native` components. You already know how to use `react-sketchapp`.
-* **Data-based.** Pipe in real data from JSON files, APIs, and databases.
-* **Universal.** Start from scratch, or use your existing component libraries
-
-## Documentation
-
-* [Usage](#usage)
-* [Examples](/docs/examples.md)
-* [Styling](/docs/styling.md)
-* [API Reference](/docs/API.md)
-* [Universal Rendering](/docs/guides/universal-rendering.md)
-* [Data Fetching](/docs/guides/data-fetching.md)
-* [Troubleshooting](/docs/troubleshooting.md)
-* [FAQ](/docs/FAQ.md)
-
-## Usage
-`react-sketchapp` projects are implemented as [Sketch plugins](http://developer.sketchapp.com/).
-
-There are several ways to build Sketch plugins:
-
-### Using a template
-The simplest way to build Sketch plugins with modern JavaScript is [`skpm`](https://github.com/sketch-pm/skpm) 💎📦 with the `react-sketchapp-skpm-example` template. Feel free to remove anything you're not using.
-
-Install `skpm`, if you don't have it already:
+## Quickstart 🏃‍
+First, make sure you have installed [Sketch](http://sketchapp.com) version 43+, & a recent [npm](https://nodejs.org/en/download/).
 ```bash
-npm install -g skpm
-```
+curl -L https://github.com/jongold/react-sketchapp-example/archive/master.zip | tar -xz 
+cd react-sketchapp-example-master && npm install
 
-Create a new project:
-```bash
-mkdir my-rad-sketch-plugin
-cd my-rad-sketch-plugin
-# Initialize this plugin with the template
-skpm init git+ssh://git@github.com:jongold/react-sketchapp-skpm-example.git
-# Install dependencies
-npm install
-# Setup an alias from the .sketchplugin to the sketch plugins folder
-skpm link .
+npm run render
 ```
 
-Then, to build your plugin (will auto update when you change the code)
-```bash
-npm run watch
-```
-
-Write your plugin in `src/my-command.js`
-```js
-import React from 'react';
-import { render, Text, View } from 'react-sketchapp';
-
-const Document = props =>
-  <View>
-    <Text>Hello world!</Text>
-  </View>;
-
-export default function (context) {
-  render(<Document />, context.document.currentPage());
-}
-```
+![readme-intro](https://cloud.githubusercontent.com/assets/591643/24777148/e742cd0e-1ad8-11e7-8751-090f6b2db514.png)
 
-Run your plugin in Sketch via `Plugins → [plugin name] → my-command`. The plugin name is determined by `src/manifest.json`
+[![npm](https://img.shields.io/npm/v/react-sketchapp.svg)](https://www.npmjs.com/package/react-sketchapp)
+[![CircleCI](https://circleci.com/gh/airbnb/react-sketchapp.svg?style=shield&circle-token=6a90e014d72c4b27b87b0fc43ec4590117b466fc)](https://circleci.com/gh/airbnb/react-sketchapp)
+![Sketch.app](https://img.shields.io/badge/Sketch.app-43+-brightgreen.svg)
+[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/react-sketchapp/Lobby)
 
-Refer to the [skpm docs](https://github.com/sketch-pm/skpm) for more information about skpm.
+## Why?!
 
-### The manual way
+Managing the assets of design systems in Sketch is complex, error-prone and time consuming. Sketch is scriptable, but the API often changes. React provides the perfect wrapper to build reusable documents in a way already familiar to JavaScript developers.
 
-Feel free to use whatever build process you're comfortable with — just [disable CocoaScript](http://developer.sketchapp.com/introduction/plugin-bundles/#disablecocoascriptpreprocessor) and disabled [Sketch's caching mechanism](http://developer.sketchapp.com/introduction/preferences#always-reload-scripts-before-running)
-```
-defaults write ~/Library/Preferences/com.bohemiancoding.sketch3.plist AlwaysReloadScript -bool YES
+## What does the code look like?
+```js
+import { render, Text, Artboard } from 'react-sketchapp';
+
+const App = props => (
+  <Artboard>
+    <Text style={{ fontFamily: 'Comic Sans MS', color: 'hotPink' }}>
+      { props.message }
+    </Text>
+  </Artboard>
+);
+
+export default (context) => {
+  render(<App message="Hello world!" />, context);
+}
 ```
 
-You can then use [react-native-packager](https://github.com/facebook/react-native/tree/master/packager), [rollup](http://rollupjs.org/), [webpack](https://webpack.github.io/) etc.
+## What can I do with it?
+* **Manage design systems—** `react-sketchapp` was built for [Airbnb’s design system](http://airbnb.design/building-a-visual-language/); this is the easiest way to manage Sketch assets in a large design system
+* **Use real components for designs—** Implement your designs in code as React components and render them into Sketch
+* **Design with real data—** Designing with data is important but challenging; `react-sketchapp` makes it simple to fetch and incorporate real data into your Sketch files
+* **Build new tools on top of Sketch—** the easiest way to use Sketch as a canvas for custom design tooling
 
-### Examples
-`react-sketchapp` includes [several examples](examples/) showing how you might use it — including GraphQL data fetching and multi-platform universal rendering.
+Found a novel use? We'd love to hear about it!
 
-### Contributing
-Contributions are more than welcome. Just submit a PR with a description of your changes. Please attach screenshots and Sketch files (if relevant) to your Pull Requests for review.
+## Documentation
 
-### Issues, bugs, or feature requests
-File GitHub issues for anything that is unexpectedly broken. If there are issues with generated Sketch files please attach them to the issue. If you have ideas or feature requests you should also file a GitHub issue.
+* [Examples](http://airbnb.io/react-sketchapp/docs/examples.html)
+* [API Reference](http://airbnb.io/react-sketchapp/docs/API.html)
+* [Styling](http://airbnb.io/react-sketchapp/docs/styling.html)
+* [Universal Rendering](http://airbnb.io/react-sketchapp/docs/guides/universal-rendering.html)
+* [Data Fetching](http://airbnb.io/react-sketchapp/docs/guides/data-fetching.html)
+* [FAQ](http://airbnb.io/react-sketchapp/docs/FAQ.html)
+* [Contributing](http://airbnb.io/react-sketchapp/CONTRIBUTING.html)

circle.yml

@@ -1,3 +1,8 @@
+general:
+  branches:
+    ignore:
+      - gh-pages
+
 machine:
   environment:
     PATH: "${PATH}:${HOME}/${CIRCLE_PROJECT_REPONAME}/node_modules/.bin"

docs/API.md

@@ -41,8 +41,9 @@ const Document = props =>
     <Text>Hello world!</Text>
   </View>;
 
-const onRun = context =>
+export default (context) => {
   render(<Document />, context.document.currentPage());
+}
 ```
 
 ### `renderToJSON(element)`
@@ -58,7 +59,7 @@ The top-most Sketch layer as JSON.
 ### `<Artboard>`
 Wrapper for Sketch's artboards.
 
-#### Props
+#### props
 | Prop | Type | Default | Note |
 |---|---|---|---|
 | `name` | `String` | | The name to be displayed in the Sketch Layer List |
@@ -107,6 +108,7 @@ type ResizeMode = 'contain' | 'cover' | 'stretch' | 'center' | 'repeat' | 'none'
 
 ### `<RedBox>`
 A red box / 'red screen of death' error handler. Thanks to [commissure/redbox-react](https://github.com/commissure/redbox-react)
+--SUGGESTION: can you give a screenshot of what this looks like?
 
 #### Props
 | Prop | Type | Default | Note |
@@ -115,7 +117,7 @@ A red box / 'red screen of death' error handler. Thanks to [commissure/redbox-re
 
 #### Example
 ```js
-const onRun = context => {
+export default (context) => {
   try {
     render(<BrokenComponent />, context.document.currentPage());
   } catch (err) {
@@ -190,6 +192,7 @@ View primitives
 ##### `obj`
 
 ## StyleSheet
+Compared to single-use `style` objects, `StyleSheets` enable creation of re-usable, optimized style references.
 
 ### `hairlineWidth`
 The platform's global 'hairline width'
@@ -266,7 +269,7 @@ const styles = StyleSheet.create({
 });
 
 StyleSheet.resolve(styles.foo);
-// { style: { fontSize: 24, color: 'red' } }
+// { fontSize: 24, color: 'red' }
 ```
 
 ## TextStyles
@@ -276,9 +279,9 @@ An interface to Sketch's shared text styles. Create styles with or without rende
 The primary interface to TextStyles. **Call this before rendering**.
 
 #### params
-##### `options: { context, styles }`
+##### `options: { context, clearExistingStyles }`
 ###### `context` **(required)**
-The Sketch API context from the main plugin `onRun` function.
+The Sketch API context.
 
 ###### `clearExistingStyles`
 Clear any styles already registered in the document.
@@ -288,7 +291,7 @@ An object of JavaScript styles. The keys will be used as Sketch's Text Style nam
 
 #### Example
 ```js
-const onRun = context =>
+export default (context) => {
   const typeStyles = {
     Headline: {
       fontSize: 36,
@@ -314,6 +317,7 @@ const onRun = context =>
     </View>
 
   render(<Document />, context.document.currentPage());
+}
 ```
 
 ### `resolve(style)`
@@ -335,7 +339,7 @@ The style name
 
 #### Example
 ```js
-const onRun = context =>
+export default (context) => {
   const typeStyles = {
     Headline: {
       fontSize: 36,
@@ -361,6 +365,7 @@ const onRun = context =>
     </View>
 
   render(<Document />, context.document.currentPage());
+}
 ```
 
 ### `clear`

docs/FAQ.md

@@ -3,60 +3,37 @@
 #### Why?!??!
 `react-sketchapp` evolved out of our need to generate **high-quality, consistent Sketch assets** for our design system at Airbnb. Wrapping Sketch’s imperative API is a pragmatic solution for a great developer experience and predictable rendering.
 
-#### Is it stable? :horse:
-Some data points:
-* This project follows [semantic versioning](http://semver.org/)
-* We haven't baked a 1.0 release yet; until then, APIs are liable to change as we make them comfortable & productive.
-* There's a [changelog](https://github.com/airbnb/react-sketchapp/releases)
-* We're using it day-to-day at Airbnb.
-
-#### `<View>` & `<Text>`? Where are the shapes at?
-
-Early versions of `react-sketchapp` mirrored Sketch's primitives — `<Rect>`, `<Oval>` etc. This was adequate for rendering simplistic designs such as grids of color palettes, but **our focus is on production design systems.**
-
-At some point, we had to translate from our engineering primitives to Sketch's primitives. We tried translating trees of React Native elements into `<Rect>`s etc ~==
-```js
-// designSystem/components/Widget.js
-const Widget = props =>
-  <View style={{
-    backgroundColor: 'red',
-    borderRadius: 10,
-    flexDirection: 'row', // how do we handle flex?!
-  }} />;
-
-// DSToSketch.js
-const switcherooElement = (el: NativeElement): SketchElement => {
-  let type;
-  let props = {};
-  switch (el.type) {
-    case 'View': {
-      type = 'Rect';
-      props.x = props.style.x;
-      props.width = props.style.width;
-      // etc, translating every property
-      break;
-    }
-    // etc, for every single native element
-  }
-  return {
-    type,
-    props,
-  }
-}
-const translate = tree = ({
-  ...switcherooElement(tree),
-  children: tree.children.map(translate),
-})
-
-// => <Rect radius={20} fill={{color: 'red'}} />
+#### How do I `console.log`?
+If you're using `skpm`, use `console.log` as usual.
+
+You can view the logs using `Console.app -> ~/Library/Logs -> com.bohemiancoding.sketch -> Plugin Output.log`, or in the terminal
+```bash
+tail -f ~/Library/Logs/com.bohemiancoding.sketch3/Plugin\ Output.log
+```
+
+Occasionally this file disappears — in that case, run this and then try `tail`ing again.
+```bash
+touch ~/Library/Logs/com.bohemiancoding.sketch3/Plugin\ Output.log
 ```
 
-This was clumsy. Not every Sketch property has an analog in react-native, but **every react-native property is translatable to Sketch** (because our app is designed in Sketch and implemented in React).
+Outside of `skpm`, use `log` instead of `console.log`.
+
+#### I'm running a project as a plugin & Sketch isn't showing my changes
+Sketch has a [developer mode](http://developer.sketchapp.com/introduction/preferences#always-reload-scripts-before-running) which refreshes plugins before running. If you're using `skpm` this should be set up automatically, but just in case try running
+```bash
+defaults write com.bohemiancoding.sketch3.plist AlwaysReloadScript -bool YES
+```
 
-By switching to react-native's primitives we:
+#### `<View>` & `<Text>`? Where are the shapes? Talk to me about your API decisions!
+
+Early versions of `react-sketchapp` mirrored Sketch's layers — `<Rect>`, `<Oval>`, `<Star>` etc. This was adequate for rendering simplistic designs such as grids of color palettes, but our focus is on production design systems.
+
+At some point, we had to translate from our component codebase's primitives to Sketch's shapes. We tried translating trees of React Native elements into `<Rect>`s etc, but it felt clumsy. Not every Sketch property has an analog in react-native, but **most react-native properties are translatable to Sketch**.
+
+By aligning with react-native's API we:
 * think in the same primitives as we actually use in production
 * use the same layout algorithm in design & code
-* [render real components](/docs/universal-rendering.md) into Sketch with `react-primitives` (a platform independent set of primitives)
+* [render real components](http://airbnb.io/react-sketchapp/docs/guides/universal-rendering.html) into Sketch with `react-primitives` (a platform independent set of primitives)
 
 Where it makes sense we're open to creating Sketch-specific components —there's no analog for `<Artboard>` on web or mobile—but the goal of `react-sketchapp` is to bring design & engineering closer together.
 
@@ -92,7 +69,4 @@ Rather than tying us into one design tools, reasoning about design in cross-plat
 #### Can I use [Flow](flowtype.org) or [TypeScript](https://www.typescriptlang.org/)?
 Of course!
 
-Flow definitions are published with the npm package in `lib/*.flow.js`.
-
-#### Why is it called `react-sketchapp` rather than `react-sketch`?
-`react-sketch` was taken on npm.
+Flow definitions are published with the npm package in `lib/*.flow.js`.

docs/README.md

@@ -5,19 +5,18 @@
 * [Guides](/docs/guides/README.md)
     * [Data Fetching](/docs/guides/data-fetching.md)
     * [Universal Rendering](/docs/guides/universal-rendering.md)
+    * [Styling](/docs/styling.md)
 * [API Reference](/docs/API.md)
-    * [`render`](/docs/API.md#renderelement-container)
-    * [`renderToJSON`](/docs/API.md#rendertojsonelement)
-    * [`<Artboard />`](/docs/API.md#artboard)
-    * [`<Image />`](/docs/API.md#image)
-    * [`<RedBox />`](/docs/API.md#redbox)
-    * [`<Text />`](/docs/API.md#text)
-    * [`<View />`](/docs/API.md#view)
-    * [`Platform`](/docs/API.md#platform)
-    * [`StyleSheet`](/docs/API.md#stylesheet)
-    * [`TextStyles`](/docs/API.md#textstyles)
-* [Styling](/docs/styling.md)
-* [Troubleshooting](/docs/troubleshooting.md)
+    * [render](/docs/API.md#renderelement-container)
+    * [renderToJSON](/docs/API.md#rendertojsonelement)
+    * [Artboard](/docs/API.md#artboard)
+    * [Image](/docs/API.md#image)
+    * [RedBox](/docs/API.md#redbox)
+    * [Text](/docs/API.md#text)
+    * [View](/docs/API.md#view)
+    * [Platform](/docs/API.md#platform)
+    * [StyleSheet](/docs/API.md#stylesheet)
+    * [TextStyles](/docs/API.md#textstyles)
 * [Change Log](/CHANGELOG.md)
 * [FAQ](/docs/FAQ.md)
 * [Contributing](/CONTRIBUTING.md)