Intro

Principle is a tool for designing animated and interactive user interfaces for web, mobile and desktop (some design teams are even using it for virtual reality!). By allowing you to quickly evaluate your ideas before investing valuable engineering time, Principle accelerates the design-development cycle. After deciding on the final design, Principle prototypes communicate ideas to the engineering team.

Rather than offer features specifically for passing design trends or niche use cases, Principle strives to provide a toolbox of generic features that can be combined in creative ways to produce a variety of results. Since it is impossible to cover all the ways these features can be combined, this documentation focuses on describing how Principle works and leaves it up to readers to discover creative applications.

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.

Components

Components, introduced in 2.0, allow you to reuse design elements in multiple places, and add embedded interactions to existing artboards. Internally, Components work just like a standard principle file; they have their own artboards, events and animations independent of their parent. If you edit one instance of a component, all other instances of the component will be updated. Components can also contain other components, making sophisticated combinations possible.

Events inside components work the same way that events on sublayers of groups work. If a sublayer of a group or component has a tap event, that tap event will get triggered, and not tap events on the group or parent.

If you need to make a component that changes size, such as a popup menu, the best approach is to make the component the size of the collapsed menu and then make the expanded menu layers go outside of that. If you make the component the size of the expanded menu, it will block touches even when collapsed because the artboard is so large.

Creating and Editing

To create a component, select one or more layers on an artboard and click the create component button in the Principle toolbar. The layers will be grouped together in a single component and you will be taken into the component to begin editing it. Click the "Back to Parent" button in the top left of Principle's canvas to go back to where you created the component. If you need to edit the component again in the future, you can select it and click the "Edit Component" button in the inspector. You can also double click components to edit, or press enter when the component is selected.

You can drag existing Principle files onto the canvas to import it as a component.


Import

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 opposite 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.

Re-Importing

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 affected by changes made 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. However, Principle and Sketch's features differ, so the import can't always be 1:1. For example, Principle doesn't have blend modes, so all Sketch layers are imported as having a Normal blend mode. Usually, you can work around these differences by flattening the layer, or group of layers, into a single image layer. You can flatten a group into a single layer by adding an asterisk (*) to the end of its layer name in Sketch. This is also helpful to reduce the number of layers that get imported into Principle, keeping your file clean and agile.

There are a few things that will cause a layer to get automatically 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.

  • Text Text layers are flattened to an image to ensure that all fonts render correctly when the Principle file is viewed on iOS.


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 the camera icon in the top right of the preview window. 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. When the icon starts blinking, the recording has started and you can begin to interact with your design (it may take a moment for the recording to start). Once you're done recording your design, click the camera icon again to stop recording.

Video export do not currently support audio, so if your design utilizes sound, it will not be present in the recorded video.

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.


Giving Feedback

If you have feedback, we want to hear it! The best way to get our attention is to send us feedback from within Principle itself by going to the "Help" menu item and selecting "Contact Customer Support". Unlike messaging us on Twitter or Facebook, this ensures we see it since it gets added to our queue.

Most bugs that get fixed are reported by a single person! If you see a problem, don't assume that we know about it or that someone else will report it. The most helpful bug reports include steps to reproduce the problem in a new document, along with links to any supporting media that may be required to trigger the problem (sketch files, images, etc).

Feature requests are appreciated, but it's more helpful if you describe the problem you need solved rather than suggesting a feature to solve your problem.


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.

How do I transfer my license to a new machine?

On the old machine clear the license key from the preferences window and click register. Enter the key on the new machine.

Can you provide a Quote?

Principle is $99 per user. Multiple seat License keys can be purchased by changing the quantity on the purchase page. You will get a single license key than can be used on multiple machines if you set the quantity to greater than one. We do not offer reseller discounts.

How does the license work?

Purchasing a license gets you all the updates that come out within a year of purchase for free. After the year is up, you can continue using the version you have. If you would like to get additional updates, you can purchase a new license key.

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.

Do provide reseller or bulk discounts?

We do not.

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? Are you going to add __ ?

We don't talk about our future plans. If there is a feature you need, send us an email!

What platforms does Principle support?

Principle runs on OS X 10.10 or newer, Principle Mirror runs on iOS 8 or newer.

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.

Can you send me a copy of my receipt?

Receipts are sent automatically for each purchase, but it may have been blocked, or flagged as spam, by your email system. If you don't see it, email us from the email that you use to purchase and we can look up your receipt.

EULA

Check it out.

Contact us

If the above FAQ doesn't answer your question, you can contact us at hello@principleformac.com, on Twitter @principleApp, or on our Facebook group. We typically respond after 24 hours.