Content review and updated links

Shopify · Nov 10, 2016 · 355bf72 · 355bf72
1 parent 9f6ddc4
commit 355bf72
Show file tree

Hide file tree

Showing 14 changed files with 225 additions and 163 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 # Slate
 [![CircleCI](https://circleci.com/gh/Shopify/slate.svg?style=svg&circle-token=f18ea06638792678e7dbfa1b8413570cd2896dff)](https://circleci.com/gh/Shopify/slate)
 
-Slate is a barebones starting point and command line tool for developing Shopify themes. It is designed to assist your development workflow and speed up the process of developing, testing, and deploying themes to Shopify stores.
+Slate is a theme scaffold and command line tool for developing Shopify themes. It is designed to assist your development workflow and speed up the process of developing, testing, and deploying themes to Shopify stores.
 
-It allows you to sync local files with your live shop, deploy to multiple environment at the same time, and organize stylesheets and scripts in a flexible way.
+It allows you to sync local files with your live shop, deploy to multiple environments at the same time, and organize stylesheets and scripts in a flexible way.
 
 ----------
 

diff --git a/config-sample.yml b/config-sample.yml
@@ -2,12 +2,14 @@
 # requests and edit/update your remote theme files.
 #
 # 1. Set up a private app (https://help.shopify.com/api/guides/api-credentials#generate-private-app-credentials)
-#    with read and write access to theme templates and theme assets.
-# 2. Replace the appropriate variables for each environment below.
+#    with "Read and write" permissions for "Theme templates and theme assets".
+# 2. Replace the required variables for each environment below.
 #
-# theme_id, password and store variables must be kept within this file.
+# password, theme_id, and store variables are required.
 #
-# For more information on configuration variables, go to http://themekit.cat/docs/#config-variables.
+# For more information on this config file:
+#   Configuration variables | http://shopify.github.io/themekit/configuration/
+#   Ignore patterns | http://shopify.github.io/themekit/ignores/
 
 ---
 

diff --git a/docs/_includes/sidebar.html b/docs/_includes/sidebar.html
@@ -5,35 +5,38 @@
   </li>
   <li>
     <a class="docs-nav__link {% if page.url == '/theme/' %}active{% endif %}" href="{{ '/theme' | prepend: site.baseurl }}">What's included</a>
+  </li>
+  <li>
+    <a class="docs-nav__link {% if page.url == '/commands/' %}active{% endif %}" href="{{ '/commands' | prepend: site.baseurl }}">Commands</a>
     <ul class="docs-sub-nav">
       <li>
-        <a href="{{ '/theme/#templates-and-configuration' | prepend: site.baseurl }}" class="docs-sub-nav__link">Templates and configuration</a>
-      </li>
-      <li>
-        <a href="{{ '/theme/#sections' | prepend: site.baseurl }}" class="docs-sub-nav__link">Sections</a>
-      </li>
-      <li>
-        <a href="{{ '/theme/#sass-scaffolding-and-helpers' | prepend: site.baseurl }}" class="docs-sub-nav__link">Sass scaffolding and helpers</a>
+        <a href="{{ '/commands/#global-commands' | prepend: site.baseurl }}" class="docs-sub-nav__link">Global commands</a>
       </li>
       <li>
-        <a href="{{ '/theme/#javascript-helpers' | prepend: site.baseurl }}" class="docs-sub-nav__link">JavaScript helpers</a>
+        <a href="{{ '/commands/#build-commands' | prepend: site.baseurl }}" class="docs-sub-nav__link">Build commands</a>
       </li>
       <li>
-        <a href="{{ '/theme/#i18n-strings' | prepend: site.baseurl }}" class="docs-sub-nav__link">i18n strings</a>
+        <a href="{{ '/commands/#sync-commands' | prepend: site.baseurl }}" class="docs-sub-nav__link">Sync commands</a>
       </li>
     </ul>
   </li>
   <li>
-    <a class="docs-nav__link {% if page.url == '/commands/' %}active{% endif %}" href="{{ '/commands' | prepend: site.baseurl }}">Commands</a>
+    <a class="docs-nav__link {% if page.url == '/theme-scaffold/' %}active{% endif %}" href="{{ '/theme-scaffold' | prepend: site.baseurl }}">Theme scaffold</a>
     <ul class="docs-sub-nav">
       <li>
-        <a href="{{ '/commands/#global-commands' | prepend: site.baseurl }}" class="docs-sub-nav__link">Global commands</a>
+        <a href="{{ '/theme-scaffold/#templates-and-configuration' | prepend: site.baseurl }}" class="docs-sub-nav__link">Templates and configuration</a>
       </li>
       <li>
-        <a href="{{ '/commands/#build-commands' | prepend: site.baseurl }}" class="docs-sub-nav__link">Build commands</a>
+        <a href="{{ '/theme-scaffold/#sections' | prepend: site.baseurl }}" class="docs-sub-nav__link">Sections</a>
       </li>
       <li>
-        <a href="{{ '/commands/#sync-commands' | prepend: site.baseurl }}" class="docs-sub-nav__link">Sync commands</a>
+        <a href="{{ '/theme-scaffold/#sass-scaffolding-and-helpers' | prepend: site.baseurl }}" class="docs-sub-nav__link">Sass scaffolding and helpers</a>
+      </li>
+      <li>
+        <a href="{{ '/theme-scaffold/#javascript-helpers' | prepend: site.baseurl }}" class="docs-sub-nav__link">JavaScript helpers</a>
+      </li>
+      <li>
+        <a href="{{ '/theme-scaffold/#i18n-strings' | prepend: site.baseurl }}" class="docs-sub-nav__link">i18n strings</a>
       </li>
     </ul>
   </li>

diff --git a/docs/_layouts/demo.html b/docs/_layouts/demo.html
@@ -10,8 +10,8 @@
 
   <link rel="stylesheet" href="{{ "/css/demos.css" | prepend: site.baseurl }}">
 
-  <script src="http://sdks-staging.shopifycdn.com/slate/latest/assets/vendor.js"></script>
-  <script src="http://sdks-staging.shopifycdn.com/slate/latest/assets/theme.js"></script>
+  <script src="http://sdks.shopifycdn.com/slate/latest/assets/vendor.js"></script>
+  <script src="http://sdks.shopifycdn.com/slate/latest/assets/theme.js"></script>
 </head>
 
 <body>

diff --git a/docs/_sass/custom/layout.scss b/docs/_sass/custom/layout.scss
@@ -159,3 +159,7 @@ main {
 .demo-image {
   box-shadow: 0 0 15px 5px #eee;
 }
+
+.demo-image.demo-image--app {
+  margin-bottom: 0;
+}
diff --git a/docs/assets/images/app-credentials.jpg b/docs/assets/images/app-credentials.jpg
diff --git a/docs/assets/images/app-permission.jpg b/docs/assets/images/app-permission.jpg
diff --git a/docs/commands/index.md b/docs/commands/index.md
@@ -18,7 +18,7 @@ layout: default
 slate theme [name]
 ```
 
-Generates a theme with build tools. The name argument is required and you will be prompted to enter it if it's not provided.
+Generate a theme with build tools. The name argument is required and you will be prompted to enter it if it's not provided.
 
 ### help
 
@@ -75,17 +75,17 @@ Performs a fresh build of your theme and zips it into a file that's compatible w
 slate deploy [--options]
 ```
 
-##### Options
-
 Performs a fresh build followed by a full deploy; replacing existing files on the remote server and replacing them with the full set of build files, and removing remote files that are no longer in use.
 
-Running `slate deploy --manual` will instead create a new zip file of your theme (see [slate zip](#zip)) and open the admin themes page as defined by your environment where you can then manually install your theme from the zip file.
+##### Options
 
 ```
 -e, --environment  deploy to a comma-separated list of environments
 -m, --manual       disable auto-deployment of the theme files
 ```
 
+Running `slate deploy --manual` will instead create a new zip file of your theme (see [slate zip](#zip)) and open the admin themes page as defined by your environment where you can then manually install your theme from the zip file.
+
 Deploy to a different environment with the `-e` flag (short for `--environment`) plus the environment name, or multiple environments at once with comma separated values
 ```
 slate deploy -e staging
@@ -113,7 +113,7 @@ slate start [--options]
 
 Performs a full deploy of your theme (see [slate deploy](#deploy)) and starts the watchers (see [slate watch](#watch)).
 
-#### options
+##### Options
 ```
 -e, --environment  deploy to a comma-separated list of environments
 ```
diff --git a/docs/css-examples/index.md b/docs/css-examples/index.md
@@ -80,7 +80,7 @@ A grid as versatile as Slate's (based on [csswizardry-grids](https://github.com/
 $breakpoint-has-widths: ($small, $medium-up);
 ```
 
-Each column — or `.grid__item` — should be a direct child of a `.grid` container. Create the child element sizes with the format `breakpoint-name--one-tenth`. See the example below or look through `styles/global/grid.scss` for available sizes.
+Each column — or `.grid__item` — should be a direct child of a `.grid` container. Create the child element sizes with the format `breakpoint-name--one-tenth`. See the example below or look through `styles/global/grid.scss` for available sizes. Ideally you should not style the padding or margins of `grid` or `grid__item` classes directly or the layout may break.
 
 > No grid classes exist in the provided templates, meaning you can swap `grid.scss` from your own grid in `theme.scss` without a lot of cleanup necessary.
 
@@ -196,6 +196,8 @@ All available icons. Hover over each to get its name.
   <iframe width="100%" height="540" src="../css-examples/icons" frameborder="0"></iframe>
 </div>
 
+It is recommended to set descriptive text that also acts as a fallback for icons. See the [demo for visually hiding text and icon fallback text](#visually-hide).
+
 ### Update icons manually
 
 If you need to add an icon to a live shop without Slate's build tools, follow these steps:
@@ -209,9 +211,9 @@ If you need to add an icon to a live shop without Slate's build tools, follow th
 
 ## Responsive tables
 
-For proper accessibility, tabular data should be build as table. Tables are notoriously difficult to build responsively, and while there are a lot of ways to do it, Slate includes a basic approach of adding the column labels as data attributes. Test the demo below in mobile mode to see it in action.
+For proper accessibility, tabular data should be built as a table. Tables are notoriously difficult to build responsively, and while there are a lot of ways to do it, Slate includes a basic approach of adding the column labels as data attributes. Test the demo below in mobile mode to see it in action.
 
-> Responsive tables are build into `cart.liquid`, `customers/order.liquid`, and `customers/account.liquid` templates.
+> Responsive tables are built into `cart.liquid`, `customers/order.liquid`, and `customers/account.liquid` templates.
 
 <div class="demo-iframe">
   {% include iframe-toggles.html %}
@@ -379,13 +381,18 @@ Quickly show or hide content based on enabled breakpoints with the class `breakp
 
 ### Visually hide
 
-Sometimes it is necessary to visually hide content while keeping it accessible in the DOM. This is useful for hiding descriptive text for icons or form labels that you do not want shown. Screen readers, for example, do not read placeholder text on inputs as their label so need the `label` element.
+Sometimes it is necessary to visually hide content while keeping it accessible in the DOM. This is useful for hiding descriptive text for icons or form labels that you do not want shown. Screen readers, for example, do not read placeholder text on inputs as their label so the `label` element is required.
 
 ```
+// Visually hidden text
 <label for="test" class="visually-hidden">Email</label>
 <input type="email" name="test" id="test" placeholder="Email">
+
+// Visually hidden icon fallback text
+{% raw %}{% include 'icon-cart' %}{% endraw %}
+<span class="icon-fallback-text">Cart icon</span>
 ```
 
 <div class="demo-iframe">
-  <iframe width="100%" height="88" src="../css-examples/visually-hidden" frameborder="0"></iframe>
+  <iframe width="100%" height="274" src="../css-examples/visually-hidden" frameborder="0"></iframe>
 </div>
diff --git a/docs/css-examples/visually-hidden/index.md b/docs/css-examples/visually-hidden/index.md
@@ -2,5 +2,19 @@
 layout: demo
 ---
 
+<p>Visually hidden input label</p>
 <label for="test" class="visually-hidden">Email</label>
 <input type="email" name="test" id="test" placeholder="Email">
+
+<p>
+  Visually hidden descriptive text for icons use the <code>icon-fallback-text</code> class.<br>
+  This extends <code>visually-hidden</code>, but will show the text when SVGs are not supported thanks to Modernizr.
+</p>
+<svg aria-hidden="true" focusable="false" role="presentation" class="icon icon-cart" viewBox="0 0 20 20"><path fill="#444" d="M18.936 5.564c-.144-.175-.35-.207-.55-.207h-.003L6.774 4.286c-.272 0-.417.089-.491.18-.079.096-.16.263-.094.585l2.016 5.705c.163.407.642.673 1.068.673h8.401c.433 0 .854-.285.941-.725l.484-4.571c.045-.221-.015-.388-.163-.567z"></path><path fill="#444" d="M17.107 12.5H7.659L4.98 4.117l-.362-1.059c-.138-.401-.292-.559-.695-.559H.924c-.411 0-.748.303-.748.714s.337.714.748.714h2.413l3.002 9.48c.126.38.295.52.942.52h9.825c.411 0 .748-.303.748-.714s-.336-.714-.748-.714zM10.424 16.23a1.498 1.498 0 1 1-2.997 0 1.498 1.498 0 0 1 2.997 0zM16.853 16.23a1.498 1.498 0 1 1-2.997 0 1.498 1.498 0 0 1 2.997 0z"></path></svg>
+<span class="icon-fallback-text">Cart icon</span>
+
+<p>When SVGs are not supported, <code>no-svg</code> is added to the <code>html</code> tag. The same code as above would instead show this:</p>
+<div class="no-svg">
+  <svg aria-hidden="true" focusable="false" role="presentation" class="icon icon-cart" viewBox="0 0 20 20"><path fill="#444" d="M18.936 5.564c-.144-.175-.35-.207-.55-.207h-.003L6.774 4.286c-.272 0-.417.089-.491.18-.079.096-.16.263-.094.585l2.016 5.705c.163.407.642.673 1.068.673h8.401c.433 0 .854-.285.941-.725l.484-4.571c.045-.221-.015-.388-.163-.567z"></path><path fill="#444" d="M17.107 12.5H7.659L4.98 4.117l-.362-1.059c-.138-.401-.292-.559-.695-.559H.924c-.411 0-.748.303-.748.714s.337.714.748.714h2.413l3.002 9.48c.126.38.295.52.942.52h9.825c.411 0 .748-.303.748-.714s-.336-.714-.748-.714zM10.424 16.23a1.498 1.498 0 1 1-2.997 0 1.498 1.498 0 0 1 2.997 0zM16.853 16.23a1.498 1.498 0 1 1-2.997 0 1.498 1.498 0 0 1 2.997 0z"></path></svg>
+  <span class="icon-fallback-text">Cart icon</span>
+</div>
diff --git a/docs/index.md b/docs/index.md
@@ -4,33 +4,40 @@ layout: default
 
 # Slate
 
-Slate is a barebones starting point and command line tool for developing Shopify themes. It is designed to assist your development workflow and speed up the process of developing, testing, and deploying themes to Shopify stores.
+Slate is a theme scaffold and command line tool for developing Shopify themes. It is designed to assist your development workflow and speed up the process of developing, testing, and deploying themes to Shopify stores.
 
-It allows you to sync local files with your live shop, deploy to multiple environment at the same time, and organize stylesheets and scripts in a flexible way.
+It allows you to sync local files with your live shop, deploy to multiple environments at the same time, and organize stylesheets and scripts in a flexible way.
 
 ## Getting started
 
-* Install Slate with `npm install @shopify/slate`
-* Create a new theme with `slate theme theme-name` where `theme-name` will be a newly created folder
-* Rename `config-sample.yml` to `config.yml` and add your private app credentials. [How to create a private app](https://help.shopify.com/api/guides/api-credentials#get-credentials-through-the-shopify-admin)
-  * **store:** the shopify-specifc URL for this store/environment (ie. my-store.myshopify.com)
-  * **theme_id:** the unique id for the theme you want to write to when deploying to this store/environment. Use `"live"` for the published theme
-  * **password:** the password generated via a private app on this store/environment (necessary for API access)
-* From within your new project folder in your command line, use the commands below to build, sync, and watch your local files
+> [Node](https://nodejs.org/en/) 4+ is supported, while 6+ is recommended to fully benefit from Slate. If you want the template files without the build tools, [get the latest zip here](https://sdks.shopifycdn.com/slate/latest/slate-src.zip).
 
-> [Node](https://nodejs.org/en/) v5.3+ is required to fully benefit from Slate. If you want the template files without the build tools, [get the latest zip here](http://sdks-staging.shopifycdn.com/slate/latest/).
+1. Install Slate with `npm install -g @shopify/slate`
+2. Create a new theme with `slate theme theme-name` where `theme-name` will be a newly created folder
+3. Create a private app on your development store(s)
+  * Not sure how to create a private app? [Learn how here](https://help.shopify.com/api/guides/api-credentials#get-credentials-through-the-shopify-admin)
+  * Set the "Theme templates and theme assets" permission to "Read and write"
+  <img src="{{ "/assets/images/app-permission.jpg" | prepend: site.baseurl }}" alt="Private app permission requirements" class="demo-image demo-image--app">
+4. Rename `config-sample.yml` to `config.yml` and add your private app credentials:
+  * **store:** the shopify-specifc URL for this store/environment (ie. my-store.myshopify.com)
+  * **theme_id:** the unique id for the theme you want to write to when deploying to this store. Use `"live"` for the published theme
+  * **password:** the password generated via a private app on this store
+  <img src="{{ "/assets/images/app-credentials.jpg" | prepend: site.baseurl }}" alt="Private app credentials" class="demo-image demo-image--app">
+    * Access this information on your Shopify [admin/apps/private](https://shopify.com/admin/apps/private) page
+5. From within your new project folder in your command line, use the commands below to build, sync, and watch your local files
 
 ## Slate commands
 
 ### Global
+* `slate theme [name]` - Generate a theme with build tools
 * `slate -h` - Options available in your current directory (differs if not in a theme)
-* `slate -v` - See your current version of Slate and any dependencies
+* `slate -v` - See your currently installed version of Slate and dependencies
 
 ### Theme
 * `slate build` — Concatenates JS and SCSS, optimizes SVG icons to be used as snippets, and copies over all other files and folders to a `dist` folder
 * `slate deploy` — Builds your `dist` folder and replaces the theme set in config.yml
 * `slate watch` — Listens for changes to your local source files and deploys them to your shop
 * `slate start` — Runs build, deploy, then watch to get you developing on your shop quickly
-* `slate zip` — Builds and compresses your `dist` to a zip for easy manual upload
+* `slate zip` — Builds and compresses your `dist` to a zip file for easy manual upload
 
-> Learn more about [all commands and descriptions](/slate/commands/) or how to [deploy to multiple environments](/slate/commands/#syncing-commands).
+> Learn more about [all commands and descriptions](/slate/commands/) or how to [deploy to multiple environments](/slate/commands/#sync-commands).
diff --git a/docs/js/slate.js b/docs/js/slate.js