Using Sketch with Qwikly

This documentation is for Qwikly 0.5.4. Updated docs for Qwikly 0.6.0. will be available soon.

The Qwikly team loves Sketch, and we want you to use it however you want. There are, however, some things you need to know in order to get the most out of Sketch with Qwikly.

Installing the Sketch Plugin

Qwikly includes a custom Sketch plugin that will integrate the current document with Qwikly. To install the plugin:

  1. Select Menu > Qwikly > Download Sketch Plugin
  2. Choose a destination from the dialog that appears
  3. Double-click to extract the .zip file in the destination folder
  4. Double-click the Qwikly.sketchplugin file to install the plugin

Running the Sketch Plugin

The Qwikly plugin lets you integrate the current Sketch document with Qwikly. You will use the plugin to send your design to Qwikly as well as to interact with our flexible layout system.

The plugin contains four commands that you can run from Menu > Plugins > Qwikly:

  • Export to Qwikly
  • Set Flexible Layout
  • Update Layout
  • Show Flex Layers

Command: ‘Export to Qwikly’

This is the primary command. It links the current document with Qwikly and sends the design information over so you can bring it to life.

When you run this command against a Sketch document for the first time, it will create a new document in the same folder as the current Sketch document with a .qwikly extension. This .qwikly file is where Qwikly saves the information it needs to generate your app.

You will also use this command whenever you want to send changes to a Sketch document to Qwikly. Just run the command, and you’ll see the changes updated in Qwikly immediately.

run-sketch-plugin

Command: ‘Set Flexible Layout’

Qwikly uses a flexible layout system based on Flexbox to let you specify complex, flexible layouts for your designs. When you run this command, a dialog box will appear in which you can set the flexible layout properties for the selected layer. Qwikly will incorporate these properties into your app, providing a powerful toolset to handle almost any design requirements.

set-flexible-layout

Here’s a flexbox cheatsheet and a fun game for learning flexbox.

Command: ‘Update Layout’

This command will apply the flexible layout properties you’ve selected for the current layer inside Sketch. We use the same rendering techniques in Qwikly as we do in the generated apps and in this command, so you can preview how your designs will render without leaving Sketch.

Command: ‘Show Flex Layers’

This command will show the under-the-hood guide layers that drive the flexible layout system in Qwikly. This can be useful in troubleshooting why a particular part of your design isn’t rendering quite right.


Setting up your Sketch Document

Currently, Qwikly can only import artboards that have certain sizes:

Supported Artboard Sizes:

  • 320 x 480 (640x960 for @2x)
  • 320 x 568 (640x1136 for @2x)
  • 375 x 667 (750x1334 for @2x)
  • 414 x 736 (1242x2208 for @3x)

If your Sketch document contains artboards of other sizes, they will be ignored when you import your design. The easiest way to generate artboards that will work with Qwikly is to use the built-in iPhone presets in Sketch.


Naming Your Layers

In general, we want you to organize your Sketch document however you want to. However, there are a few naming conventions that you can use to tell Qwikly about a particular layer. We refer to these conventions as ‘tags’, and there are only a handful that you need to know.

Supported Tags

For each tag below, the layer name starts with the tag (including the ‘@’), followed by a space, followed by the actual layer name. For example: ‘@ListView Users’

@TabBar
Tab bars have their own section in the Properties Inspector. Be sure to name your tab bars consistently - if the same tab bar appears in multiple artboards (as is usually the case), they should all have the same tagged layer name. Qwikly will combine these layers into one component for you.
@NavBar
If an artboard contains a layer with the ‘@NavBar’ tag, Qwikly will use that layer to determine how the corresponding scene behaves when used inside a navigation controller. For example, Qwikly will attempt to map the background color for the nav bar layer to the background color used in the generated app.
@ListView
@ListView layers help Qwikly know how to generate collection views and apply data bindings to the list cells contained within them. When you tag a layer as a list view, Qwikly will not render it’s child layers directly. Rather, it will expect you to configure a data binding for the list view and render the results using the @ListCell layers you specify.
@ListCell
List cell layers should only be included inside @ListView layers. When you tag a layer as a list cell, Qwikly knows to use that layer as a template for the rows of the containing list view. Currently, Qwikly only supports one @ListCell per @ListView. If more than one @ListCell is included inside a @ListView, Qwikly will use the first one it finds.
@ScrollView
Applying a @ScrollView tag to a parent group will render all of it’s children in a scroll view. This is helpful if you have static content that you would like to be able to scroll instead of a @ListView which generally handles dynamically bound content.
@TextInput
Applying a @TextInput tag to a text layer will make it an editable field when you build your app.

Supported Properties

For each property below, the layer name starts with the property (including the ‘#’). For example: ‘#barTintColor’

@NavBar props
  • #barTintColor - Used to set the background color of the NavBar. barTintColor