Introducing Slate: A Shopify Theme Scaffold and Command Line Tool

Introducing Slate: A Shopify Theme Scaffold and Command Line Tool
Introducing Slate: 2017

Starting something from scratch is often really difficult. Even more difficult is building a theme from scratch with no idea where to start.

You could take a look at an existing theme, like Debut, but there’s a lot of stuff in there — which can be intimidating to root through, as well as distracting when first trying to learn how to build a Shopify theme with Liquid.

At Shopify we wanted to make that process easier, especially when developing themes with custom designs. So we built Slate — a theme scaffold and command line tool for building Shopify themes.

With Slate you can build themes using modern tooling and the command line, making theme development easier, faster, and more efficient.

View Slate documentation View Slate repository

Lessons learned from Timber

Many theme developers build directly on top of themes, such as Debut, or frameworks, such as Timber. The problem we found was that for many theme developers, a lot of time was spent on removing extra classes and unneeded markup, and overwriting or removing unwanted CSS to ensure that their themes didn’t look like the framework itself. Theme developers want to customize their themes for clients, and ensure that their custom themes don’t look Timber.

With Slate there’s no need. It’s been intentionally left blank. Slate only includes standard Liquid tags and logic that will likely be used in each template.

Little-to-no markup, classes, and other code that might need to be stripped out has been included — we’ve left it bare bones intentionally. This unopinionated approach allows Slate to act as your starting point, regardless of your theme’s intended look or functionality.

What’s included with Slate?

Templates and configuration

Slate includes all the required files, layouts, and Liquid templates for a functioning online store. What that means is you don’t have to think about what you need to include, it’s all there out-of-the-box for you. The templates and sections that come with Slate are largely boilerplates and provide a starting point for theme developers.

Styles Page Template

There’s a page.styles.liquid template included in Slate that you can set to be used by any existing page on your online store. This template outputs elements that are common across themes, such as headings, paragraphs, type styles, tables, blockquotes, form elements, and lists.

Introducing Slate: The page.styles.liquid template rendered page

It’s meant to help visualize all the shared components between themes, and for theme developers to make sure they didn’t miss anything when creating their theme styles. This is just an aide during development, so make sure to delete this theme template before deploying to a production site.

Sections

Sections allow merchants to control the layout and appearance of their themes from the online theme editor. With a handful of sections built into Slate, we’ve made it easier to learn how to start building and using sections in your theme.

There are recommended static sections, which allow for in-context settings when that section is visible in the theme editor. These include header, footer, and product, however they only appear in the theme editor when navigated to — so a merchant will see the editable product section once they navigate to a product page.

We’ve also included three dynamic sections in Slate. Dynamic sections allow merchants to add, edit. and reorder various content on their homepage or other pages. If you’re interested in learning more about creating sections, you can follow this great tutorial by Tyson Tredger.

You might also like: An Introduction to Theme Options.

Sass helpers

Slate is not a CSS framework. Slate includes Sass scaffolding and helpers, such as a normalize.css as well as some additional helper styles that Shopify’s internal theme developers rely on for theme development. These include helpers that fix known bugs in IE, improve text rendering with certain WebKit form fields, prevent zooming when inputs are focused on mobile, and several others.

Slate includes a responsive grid system based on the csswizardry-grids, which are easy to use and infinitely nestable.

Slate also has SVG icon style helpers that can be easily targeted with CSS classes like .icon-cart, and rendered using simple Liquid includes: {% include 'icon-cart' %}. The icons are rendered inline using these includes, and there are a bunch of useful icons that are shipped with Slate.

Introducing Slate: List of all available icons shipped with Slate
List of all available icons shipped with Slate.

In addition, there are a few more styles we’ve included to help theme developers out:

  • Accessibility helpers, such as making visually hidden text accessible to screen readers.
  • Default styling for responsive tables and iframes, because no one likes styling tables and iframes 😉.
  • Styles for form elements with default, disabled, error, and focus states.
  • Blank state SVGs for placeholder images, products, collections and logos, and more. You can see an example in the documentation.

One thing to note is even though there is some styling, it’s minimal, so you’ll most likely still want to style elements yourself. You should also know how easy it is to remove stylesheets you don’t want to include. Because Slate Sass scaffolding uses @import statements in the theme.scss file, you might not want to include the grid.scss. To remove it, simply remove the @import declaration in theme.scss, and it won’t be included in the final dist directory.

Introducing Slate: The theme.scss file @import declarations.
The theme.scss file @import declarations.

JavaScript helpers

One of the main goals of Slate is to handle Shopify-specific considerations. The intention is to have theme developers coding as quickly as possible. To do this, we’ve provided a number of helper scripts that we use in our own themes at Shopify, and that we think will be helpful for theme developers.

These scripts include:

  • a11y.js
  • currency.js
  • images.js
  • rte.js
  • sections.js
  • util.js
  • variants.js

Each of these scripts aim to make a specific aspect of theme development easier - whether its accessibility, working with store images and currencies, building sections, or handling product variants.

variant.js

One of the helper scripts we’re most excited about is variant.js. To get things up and running, you simply need to provide a little bit of information about your page’s markup.

Slate separates product variant options into multiple <select> elements. When a variant changes, variant.js updates the master select. The master select is the default <select> element that contains all variant IDs needed to properly submit the form.

Tip: The product option <select> elements can be substituted for other form inputs and Slate’s helper script will still work. See our documentation on using product.options_with_values to see how you could write your HTML.

Introducing Slate: The variant.js file making changes to the user interface.

Slate’s variant.js can then trigger a number of custom events to handle various state changes on a page, including: variantChange, variantImageChange, or even a variantPriceChange.

These custom events can be passed a callback unique to your theme, for example this might be a updateProductImage function. Once we’ve created this function, we simply need to add it to our event listener, variantImageChange, and the updateProductImage function will be fired whenever the variant image changes.

You can find a full example of this functionality on GitHub in the product.js file of Slate’s starter project.

Translation keys

Making sure we have themes whose storefront language can be set by the merchant to accommodate their customers is something every Shopify theme developer should do.

We’ve made it easier to do so by adding in the translated .json files to the locales directory, with translation strings included. With Slate, there are translations for English, French (Canadian), Spanish, German, and two dialects of Portuguese (Brazilian and European). You can check out more information on translations in our documentation.

Installing Slate

Installing Slate is really straight forward, make sure you have the latest version of Node.js installed on your computer, and then it’s as simple as running the following code from the command line:

npm install -g @shopify/slate

This will install slate globally on your computer.

Introducing Slate: Installing Slate

Basic Commands

Once Slate is installed installed simply run:

slate theme [name]

Where [name] is the name of the new theme directory you want to create, and Slate will build you a new Slate scaffold theme in that directory.

Introducing Slate: Creating a new theme with Slate via the command line.
After running slate theme test, Slate creates a new theme named test.

You can also convert an existing theme to use Slate’s folder structure and package.json file by running slate migrate in the root directory of your theme. However, you should know that the slate migrate command only gives you the folder structure and node package, so you’ll be able to use slate-tools, but it doesn’t include the helper scripts and boilerplate liquid templates.

Build Commands

All of Slate’s source theme files are in the root src directory. These are the files you would edit, and using Slate commands, compile to your final theme in the dist directory. To compile your theme files, you can use the build command or zip commands.

slate build

The build command will compile theme files and assets into a Shopify theme found in the dist directory.

slate zip

The zip command will perform a fresh build of your theme, and zip it into a compatible Shopify zip file. The zipped theme is placed in the upload directory in the root of your theme project. Each time the zip command is run, it overwrites the existing zipped file.

Sync Commands

There are several ways you can sync your theme with a Shopify store, using deploy, watch, and start. Slate uses Theme Kit which is part of slate-tools, to move files back and forth between your project’s dist/ folder and the remote server. To hook the local theme up to a Shopify store, you can follow the instructions provided on Slate’s getting started guide which are almost identical to hooking up Theme Kit.

You might also like: 3 Simple Steps for Setting Up a Local Shopify Theme Development Environment.

Deploy

You can run slate deploy, and Slate will perform a fresh build followed by a full deploy onto your connected Shopify store, replacing all existing files on the remote server and replacing them with the new build. The slate deploy command also removes remote files that are no longer in use, and takes options to deploy to multiple environments at once, or to deploy manually.

To deploy to multiple environments, just add the -e flag (short for --env), followed by the environment name listed in your theme’s config.yml file. Each additional environment should be comma separated. For example:

slate deploy -e development,staging,production

You might also like: Using Git to Simplify Shopify Theme Deployment.

Watch

The watch commands set up the watchers for all theme assets, and syncs the compiled versions to your specified environment. In addition, it opens a Browsersync window with live reloading after changing and saving a file. You can specify which environment to watch using the -e flag followed by the name of the environment. The default environment is development. You can also disable Browsersync using the -n flag as part of your watch command.

Start

The start command combines both deploy and watch commands together. It performs a full deploy of your theme, and starts all the watchers.

Start theming with Slate

Slate is available now, so start building today!

View Slate documentation View Slate repository

If you’re new to Shopify theming, and familiar with the command line, Slate is a great starting point for you. It provides a lot out-of-the-box in terms of theme development, while being unopinionated and allowing you to build any look or functionality into it.

The intent with Slate was to provide the tools and resources for theme developers to see how a theme is made and structured, without a lot of constraints or customized functionality.

Have you already started using Slate? Share some of your Slate experiences and projects in the comments below!

About the Author

Tiffany is a Partner Education & Front End Developer Advocate at Shopify. She specializes in front end development, user experience design, and accessibility. She is passionate about inspiring young designers and developers, and is the Ottawa chapter co-lead for Ladies Learning Code.

Grow your business with the Shopify Partner Program

Learn more