Documentation

Interface #

Canvas #

The canvas in the center of Principle is where you'll do most of your work. It contains all artboards, and the transitions between them. The current artboard is highlighted with a green border.

Preview #

The Preview allows you to interact with your design at any time, and is docked in the corner of the canvas. It can be detached into its own window by dragging it off the canvas. You can change the preview mouse cursor by selecting View->Toggle Preview Cursor Type.

Layer List #

The layer list on the bottom left of the window shows all of the layers in your design. Layers can be grouped and un-grouped by dragging their rows. The artboard order on the canvas can be changed by dragging an artboard's row. Hovering over a layer's row shows the eye button, which hides the layer in the editor, but does not affect the layer's visibility in the Preview.
Learn more about layers

Inspector #

On the left of the window and above the layer list, the Inspector displays the properties of selected layers.

Animate Panel #

Appearing at the bottom of the window, the Animate panel is used to customize animations between artboards. It can be shown by clicking the Animate button on the toolbar, or by selecting a transition arrow on the canvas.
Learn more about animation

Drivers Panel #

At the top of the window, the Drivers panel shows the currently selected Artboard's drivers. Drivers are used to create sophisticated continuous interactions.
Learn more about Drivers


Drawing #

At first glance, Principle feels like a graphic design tool, just like other tools you've used. Basic elements can be created right inside Principle, and images can be imported for everything else.

Artboards #

Principle's artboards work similarly to other drawing programs: each represents a unique state of your design. The size of all artboards can be changed to fit different devices, or window sizes. Some artboards may be conceptually the same screen, but with slight differences. For example: two Artboards of a music player design may be identical except for the play/pause button. The artboard shown by the preview window will have a green boarder around it in the editor; new layers will be added to this artboard.

Rectangles #

Click the toolbar's Rectangle button or press "R" to add a new rectangle to the current artboard. Circles can be created by setting the radius of a rectangle to a large value. An image background can be added to a rectangle by dragging an image (PNG, JPEG, TIFF) onto the image well in the inspector. Rectangles are created with a size of 44x44 points - the recommended tap area size for iOS.

Text #

Text layers have similar properties to Rectangle layers, with the addition of font face, alignment, and size. The font face and alignment properties can not be animated.

Custom fonts #

Not all of the fonts on your computer are available on iOS, and will not appear in Principle Mirror. Use an app like AnyFont to install non-iOS fonts on your device.

Images, Videos, Audio #

Images, Video and Audio can be imported into Principle by dragging from Finder, or with copy/paste. If you're a Sketch user, copying from Sketch flattens the selection to a single image. Image and Video layers have their aspect ratio locked by default, this can be turned off by clicking the lock icon in the inspector.

Assets are copied into the Principle file so that the design can be moved, emailed and viewed without losing its assets. Because of this, try to use the shortest video and audio assets possible to keep the file size down. Keeping your asset size down will also improve previewing speed over USB.

Animated gifs are not supported in designs because they can be simultaneously very large (poor compression) and low quality (only supports 256 colors). They also perform very poorly because, unlike video, there isn't a hardware decoder. We recommend using videos for small animations instead of trying to use gifs.

Changing A Layer's Asset #

To change a layer's image, drag a new image onto the media button in the inspector, or click the media button in the inspector and click "Choose..." in the menu. If there are other layers that also use the old asset, Principle will give you the option to update all of those layers with the new asset.

An asset can be removed from a layer by clicking the media property in the inspector and clicking "cut" in the menu.

High Resolution Images #

Images with "@2x" or "@3x" at the end of their filename will be imported at 1x point size and the asset will look correct when viewed on a retina screen. If you have already imported a high resolution image without the suffix, manually halving the width and height of the layer results in the same thing. (Pro tip: the inspector text fields understand basic equations like "320/2")

Copying and pasting from Sketch or other tools will usually result in 1x assets, so exporting at retina resolution before importing into Principle ensures the assets are the correct size.

Video and Audio Playback #

Video and Audio assets will play while the mouse is over the preview window. By default, assets will loop forever, but this can be changed by clicking the media button in the inspector and selecting "Play Once".

To play video or audio seamlessly between artboards, just copy the video or audio layer to both artboards and ensure the layers have the same name. The Media time property is frozen by default which allows seamless playback, but can be manually unfrozen to make the playback start over. Learn more about Frozen Properties

Groups #

Layers can be grouped in Principle by selecting them and clicking the Group button in the toolbar, or pressing Command+G. You can also group layers by dragging one row in the layer list on top of another.

Groups in Principle are actually just Rectangle layers with some child layers. Groups have their own position and size regardless of their child layer's positions. This is how UIKit, Android, and the DOM draw and animate elements, and may be unexpected if you're used to the way groups work in programs like Photoshop and Sketch. This behavior is useful to make the interactive area of a layer larger, rotate a layer around a different origin, or layer multiple animations on top of each other.

Cropping / Masking / Clipping #

You can crop layers by grouping (Command+G) and enabling "Clip Sublayers" on the group. To get a round mask, turn up the group's radius property.


Continuous Interactions #

There are three common interactions that are built in to Principle: Dragging, Scrolling and Paged Scrolling. These can be enabled independently on a layer's vertical and horizontal axis.

Dragging #

Enable dragging on a layer when you'd like to allow the layer's position to move when a touch is held over it.

Scrolling #

Scrolling can be enabled on a group layer. When a finger is dragged on a scrolling layer, the child layers will move with the finger, but the group itself will not change position. Maps, Message threads, or any large content make great candidates for scrolling. If you turn on scrolling on a layer that doesn't have any sublayers, Principle will automatically create a scrolling window group for you, how nice. Turn on "Clip sublayers" on the scrolling layer to hide the child layers when they scroll outside.

Paging #

Paging is just like scrolling, except it automatically snaps its scroll position to group-sized increments when scrolling ends. Use paging for image carousels, home screens with icons, any of those card UIs that are so popular now-a-days. If you'd like to add padding between pages, make the paging group a little larger than one element, and space the elements out.


Events #

Events trigger transitions between artboards. To add an event, select a layer on the canvas and click the lightning bolt button that appears to the right of it, then drag from one of the circles to the destination artboard. A transition arrow will be added to the canvas that points from the source artboard to the destination artboard.

Dragging the outlet arrow to the selected layer's artboard will create a duplicate artboard.

Layers with an opacity of 0% are not interactive. To create a clear tappable area, use a clear fill instead of 0% opacity.

There are several types of events:

  • Tap #
    Fires when the layer is touched and released without moving. Commonly used for buttons.

  • Drag Begin #
    This event fires when a finger is placed on the layer and begins moving. Adding this event to a layer will make the layer draggable if it is not already. If a layer with the same name is in the destination artboard, its draggable state will determine if the drag interaction continues after the event fires.

  • Drag End #
    Fires when a finger that was moving on the layer is lifted. Adding this event to a layer will set its vertical and horizontal properties to Drag.

  • Scroll Begins #
    Fires when a scrollable layer begins scrolling. Adding this event to a layer will set its vertical and horizontal properties to Scroll.

  • Scroll Released #
    Fires when a finger scrolling the layer is lifted. This event works for both scrolling and paging. The contents may continue scrolling after this event due to deceleration, or the paging animation. Adding this event to a layer will set its vertical and horizontal properties to Scroll.

  • Scroll Ended #
    Fires when scrolling comes to a complete stop. This event works for both scrolling and paging. Because deceleration takes a while to completely stop, this event may have a longer-than expected delay before it fires. Adding this event to a layer will set its vertical and horizontal properties to Scroll.

  • Touch Down #
    Fires when finger comes into contact with the layer. Useful for transitioning a button to a highlighted state.

  • Touch Up #
    Fires when finger lifts off a layer. Useful for un-highlighting buttons. Doesn't fire if the touch originated on another layer.

  • Long Press #
    Fires when a finger has been held on the layer for half a second.

  • Hover Inside #
    Fires when the mouse is inside of the layer

  • Hover Outside #
    Fires when the mouse is outside of the layer

  • Auto #
    Fires automatically and without user interaction. Can be used for looping prototypes and animations. Auto events only fire when the mouse is over the Preview, in order to conserve battery life, and your sanity.

    To add a delay to an Auto event, click the Auto event arrow and delay its animations in the Animate panel.

    To delay auto events between screens that have no animations, you can add a dummy layer off-screen of both artboards at slightly different positions. This will create an animation that can be delayed.

Changing an Event Type #

If you would like to change the type of event that triggers a transition, you can delete the transition (click the transition arrow and press delete on your keyboard), and create a new transition with the desired event type. Your animation keyframes and curves will not be lost because they are stored in the artboard, and not in the transition. Learn more about shared animations.


Animation #

When an event is triggered, Principle animates between the current artboard and the event's destination artboard.

Animation Mappings #

If two layers on different artboards have the same name, Principle will treat the layers as if they are the same, and will automatically animate between them. If there is not a layer with the same name on both the source and destination artboard, the layer will simply disappear or appear with no animation.

Custom Animations #

By default, all animations have a duration of 0.3 seconds, and use the default easing curve used in iOS and OSX. The Animate view is where you can customize this. Clicking a transition arrow above the artboards will show the Animate view, which lists all the the properties that will be animated and a timeline to change timing and easing.

Keyframes #

Each row in the Animate view shows two keyframes, one representing the start time of the animation, the other, the end. Dragging these keyframes changes the delay and duration of the animation.

Easing Curves #

The easing curve determines the rate at which a property animates: does it move slowly and then speed up? Does it lurch quickly to the end, and then gradually slow to a stop? Behaviors like this are controlled with the easing curve.

Clicking the blue area between two keyframes shows the Curve Selector. The Curve Selector has several built in curves, as well as a graph of the selected curve.

The built in curves are the same curves used in iOS and OSX. At any time the curve can be tweaked by dragging the handles in the preview, or typing in new coordinates for the handles at the bottom of the popup.

Springs #

Spring animations can be used by selecting "Spring" in the Curve Selector. This is useful for adding physicality and playfulness to layers, but should not be overused as it can be distracting. The Curve Selector has options for the spring's Tension and Friction. A spring animation does not have an end keyframe because the spring animation's end time will be determined by the physics simulation. You can indirectly change the duration of a spring animation by changing the tension and friction values.

Frozen Properties #

Sometimes it is useful maintain the value of a property from the previous artboard during a transition. Principle calls these types of properties "Frozen". You can Freeze a property by clicking the snowflake icon in the animate panel. Freezing a property prevents it from being changed, and thus animated, during a transition. Frozen properties can be used to remember things from other artboards such as a group's scroll offset, the position of a draggable layer, or the opacity of a selected element. Principle Freezes the Scroll X and Scroll Y properties by default so that scroll position is maintained between artboards. If you need an event to scroll to a specific position, you can unfreeze Scroll X and Y.

Animations are Shared #

The animation information for every transition is stored in the transition's destination artboard. This means that all transitions going to a particular artboard will have the same animation settings. For example, if you use a spring animation in the transition going from artboard A to artboard B, then a spring animation will also be used in the transition going from artboard C to artboard B.


Drivers #

Want to make an interactive parallax effect? Want a layer to rotate while it is dragged? Drivers are for you. Drivers connect properties to each other using keyframes. Unlike Animated transitions, which occur "between" artboards, drivers work in artboards. Click the Drivers button show or hide the current artboard's drivers. If your mouse doesn't support horizontal scrolling, hold space and drag the Drivers panel to scroll.

Drivers work similarly to a typical animation timeline, except drivers animate based on a changing property, instead of time.

Driver Sources #

In order to create a driver, a property which could change needs to exist on the artboard, this is called a driver source. Draggable layers, scrollable layers, and optional properties will automatically be listed as driver sources in the Drivers view.

Driven Properties #

Once you have a Driver Source, you can use it to control other properties. Select a layer you'd like to control, click the blue "+" button in the Driver view and choose which property you'd like to drive. This will create a driver with a keyframe for the current value. By itself, this single keyframe will not do anything, which leads us to:

Driver Keyframes #

To add keyframes, drag the gray driver cursor to a position that you'd like to add a keyframe and then change the value of that property. Principle will insert a new keyframe for you automatically. Keyframes can be removed by clicking on them, and then clicking the red button to the left of the keyframe's row.


Import #

Overview

Sketch is a vector drawing program often used for static interface design. Designs created in Sketch can be imported into Principle by clicking the import button in the toolbar, or going to File > Import.

There are a few things you'll need to import from Sketch:
1. Sketch or Sketch Beta must be running
2. Sketch must have a document open
3. The Sketch document must have at least one artboard on the current page

If Sketch has multiple documents open, the active document window will be imported into Principle. If the Sketch file has multiple pages, the current page will be imported.

The size of the bottom-most artboard in Sketch's layer list will be used for Principle's artboard size. The artboards will appear in Principle in the order they appear in the Sketch layer list, which may be different from the order they are positioned on the canvas.

Scaling

In the import dropdown, you can select how flattened images will get scaled when imported from Sketch. The scale factor doesn't affect the dimensions of a layer, just the resolution of its image, if it has one. This feature is useful if your Sketch file is at 1x resolution, but you'd like to have the Principle prototype look nice on a 2x or 3x retina screen. Principle will remember the last scale factor you used so you don't have to select it each time you import.

Importing again

If you have made changes to your Sketch file, it can be re-imported into Principle so animations, events, and layer mappings will remain intact. If you want to change the position or other properties of a layer that was imported from Sketch, it's easiest to make that change in Sketch and then import again. Sometimes you may delete a layer in Sketch and then remake it, perhaps with a different approach; in these situations Principle won't know that this new layer is conceptually the same layer, so any events that were placed on the old layer will be lost. Artboards that have been deleted from the Sketch file, or were imported from another Sketch file will not be affected by importing again.

Making changes

If you find you need to make visual changes to your layers, it's best to do so in the original Sketch document, and then import again. This includes creating duplicate artboards or layers. Duplicating an imported layer in Principle will create a layer that doesn't have a 1:1 mapping to the Sketch document, so it will not be affect to change you make in the Sketch file.

Layer flattening

As much as it can, Principle will try to import Sketch layers as native Principle layers so their properties can be animated. If you don't need to animate layers in a group, you can flatten the group into a single layer by adding an asterisk (*) to the end of it's layer name in Sketch.

There are a few things that will cause a layer to get flatted into an image during Sketch import:

  • Paths
    Layers that are more than just a rounded rectangle with a single radius will be flattened

  • Fills
    Layers must have a single, solid color fill in order to avoid being flattened.

  • Borders
    Layers must have at most a single, solid, inside border, or they will be flattened

  • Shadows, Blur, other effects
    Layers with a shadow, blur, or other effect will be flatted

  • Masks
    Groups or Artboards with a mask layer will be flatted into a single layer. In order to minimize the number of layers that get flatted due to a mask, group the mask layer and the layers it masks.


Export #

Once you've created the perfect interaction, you'll want to show the world. There are a few ways to do this.

Videos and Animated Gifs #

To export a video or animated Gif of the design, click record in the toolbar. You have the option to use the round touch cursor, the arrow cursor, or have the cursor hidden in the recording. After selecting an option for the cursor, Principle begins a screen recording of the Preview window. Once you're done recording your design, click the Record button again to stop recording.

Gif Settings

When exporting a Gif, you can choose custom export sizes by choosing a preset from the dropdown or entering in settings with this format:

  • 45%
    Any number followed by a percent sign will export a Gif that is a scaled down version of what you recorded, the output will be scaled by the percent you enter. If a percent is specified, width and height values will be ignored.

  • 134h
    export a gif with the specified height, keeping the same aspect ratio as the artboards.

  • 320w
    export a gif with the specified width, keeping the same aspect ratio as the artboards.

  • 400w 300h
    export a gif with the specified size. The recording will be scaled down to fit within this dimension, but will retain its original aspect ratio. Padding and a drop shadow are automatically added. The color set in the color well will be used to fill the background of the gif.

Export for Mac #

If you'd like to share your designs to others that may not have Principle, you can export a standalone Mac app that anyone with a Mac can open. Note: Export for Mac runs on Mac computers, not iPhones. If you'd like to share you're design for iOS, see Running on Device. To export your design for Mac, go to File > Export for Mac. The resulting app can be emailed or shared however you'd like.

Unidentified Developer Warning #

The people you send the app to may get a message saying it "can't be opened because it's from an unidentified developer". This is because it was created by you (the unidentified developer). They can easily run it anyway by control clicking the app icon, selecting open and then a dialog will appear allowing them to open your design.

Running on Device #

Principle Mirror for iOS can be used to view and share your designs on iOS. Download the Principle Mirror app onto your device and connect it to your computer's USB port. Principle for Mac and Principle Mirror will find each other automatically and the top-most Principle document will be sent to your device. In design reviews, press Cmd~ to quickly switch between open Principle documents and the iOS app will switch files as well.

The design will continue to run even after disconnecting from USB, making it easy to show teammates.

Sharing an interactive design #

If you'd like to share your design with others so that they can interact with it, they can install Principle Mirror on their iOS device and you can send them the file. The file you share must have the .prd extension and cannot be zipped in order for iOS to open it in Principle Mirror.

  • Email
    To open an attached PRD file from an email, tap the attachment and then the iOS share button. Select Principle Mirror in the sharing panel, or the "Open In..." button if Principle isn't visible.

  • Your own server
    If you're concerned about using a file sharing service for security reasons, you can put the .prd file on your own FTP server. Share a direct link to the file and others can view it on their phone. Safari will show an "Open in Principle" button.

  • Dropbox, Google Drive, Box, etc
    You can upload your .prd file to a file sharing service and generate a link to the file.

Note about Dropbox:
By default, Dropbox links will take you to a Dropbox page rather than to the file itself. You can bypass this by changing the end of the Dropbox link from "dl=0" to "dl=1"

Note about Google Drive:
The Google Drive app has problems with special file types, so we do not recommend using it to share Principle files.

Animation Values #

Principle doesn't currently export animation values, but engineers can see them in Principle. Click and hold a keyframe to see its time offset. Clicking the blue area between keyframes to access its easing curve. These values are platform agnostic.


Shortcuts #

Layers

Add rectangle: R (Alt + R to add as child)
Add Text: T (Alt + T to add as child)
Add Artboard: A
Group: Cmd + G
Ungroup: Cmd + Shift + G
Bring to Front: Shift + Cmd + ]
Bring forward: Cmd + ]
Send Backward: Cmd + [
Send to Back: Shift + Cmd + [

Editing

Nudge: Arrow Keys
Big Nudge: Shift + Arrow Keys

Rotate: Cmd + Drag handle
Rotate in 15 degree increments: Cmd + Shift + Drag handle

Duplicate: Cmd+D
Duplicate and Move: Alt+Drag

Inspector Textfields: understand basic equations like "320/2+10"
Inspector Labels: dragging textfield labels quickly scrubs values

Rename Layer: Cmd+R

Canvas Navigation

Pan: Space + drag
Zoom in: Z + Click
Zoom out: Alt + Z + Click: 
Continuous Zoom: Alt + Space + Drag
Zoom in: Cmd + =
Zoom out: Cmd + -
Zoom All: Cmd + 1
Zoom Selection: Cmd + 2
Center Selection: Cmd + 3
Actual Size: Cmd + 0

Driver Navigation

Pan: Space + drag
Zoom in: Z + Click
Zoom out: Alt + Z + Click: 
Continuous Zoom: Alt + Space + Drag

Animate Navigation

Pan: Space + drag

Selection

Select Parent: Esc
Select Child: Enter
Select Next Sibling: Tab
Select Previous Sibling: Shift+Tab
Select all Siblings: Cmd + A

Preview

Change cursor type: View->Toggle Preview Cursor Type
Rewind Prototype: W
Start recording video: Ctrl+V
Start recording video without cursor: Ctrl+alt+V


Frequently Asked Questions #

Do you have educational discounts?

We have a 50% educational discount for students and faculty. Once you've tried the free trial and are ready to purchase, email a photo of your class schedule and student ID and we'll make a discount link for you! The link expires two days after we make it.

Will Principle be released for Windows / Linux / Android / Web?

Principle and Principle Mirror are built on core technologies exclusive to OS X and iOS, so it won't be available on other platforms.

Can you provide a Quote?

Principle is $99 per user. License keys that can be used by more than one person can be purchased by changing the quantity on the purchase page. We do not offer reseller discounts.

Can I add additional users to an existing license?

Not at this time, you must purchase a new license.

Do you accept purchase orders, faxes, etc?

Nope, our website handles the entire purchase process.

Will Principle be available on the Mac App Store?

We're not planning to release Principle on the Mac App Store because of all its frustrations. By selling outside the store, we can release updates as often as we like and are free to pursue advanced features that may not be possible if Principle were in the App Store.

What is the road map for Principle?

We don't talk about our future plans. If there is a feature you'd like to see added, send us an email!

Buying for Someone Else

Licenses can be purchased for someone else by clicking the gift icon at checkout. The recipient will get an email with the license keys, and the purchaser get one with the invoice.

Invoices

You can generate an invoice by clicking the link in the email you receive after purchase.

EULA

Check it out.

Contact us

You can contact us at hello@principleformac.com, on Twitter @principleApp, or on our Facebook group.