This document contains requirements for the design and behavior of your Spotify App. Please ensure that your app meets these requirements before submission.
The requirements are numbered, e.g. “1.2 Use the correct format for the app icon.” If you are planning to include deviations from the requirements in your app, please provide us with information of which deviations have been made and why. All deviations have to be approved by us. To get started, we recommend that you download the “Design Resources” zip file, containing the graphic resources mentioned in this document. Later on, the tab bar, play button overlays and other graphic resources will be available through our API, but until then you will have to use the resources mentioned above. Good luck!
User Experience (UX) Principles
An app in Spotify should be a self-contained user experience using Spotify music. We want your app to be a seamless part of the Spotify experience. To achieve this, there are a few things you need to consider when designing your Spotify app. Here are some general rules and pointers on how to create a great experience for your users.
All about music. The content in your app needs to be strongly connected to the music in Spotify to make sense. Your service/product might do a lot more, but inside Spotify people will expect it to be focused on features related to Spotify, in other words music.
Make it instantly personal. Show relevant content straight away by reading the user’s listening history, top tracks, top artists etc and filter out awesome matches with the content you have.
Be here now. Don’t add features that force users to go out to your website. Users don’t like disjointed experiences so make all functionality work within Spotify.
Integrate. One advantage of using your service inside ours, is that we can be neatly stitched together. Let the user easily add tracks to the Library, play tracks without leaving your page, save playlists, star tracks, share tracks, add to play queue, etc. Do this with native looking controls, using the same terminology we use. When mentioning an artist in a review, link it to the Spotify artist page. When referring to a track in a text about new releases, make it playable.
Don’t duplicate functionality from the native Spotify UI. Don’t make your own Library, called “Library”. Don’t make a player with play, next, and forward buttons, as we already have such a player in our application. Duplicating functionality will be confusing to users and take up real estate. Just let them stick to our native controls, which they are used to.
A Spotify app is not a website. Apps in apps need stronger focus so only include key features. The best apps have a clear purpose, no tabs, minimal amount of text, flat hierarchy and limited number of features, buttons and other controls.
The start page should be easy to understand and use. The first app experience should be pleasant and swift. Therefore, the start page should be easy to understand and use. This page should not be too empty of content, but instead feel welcoming and interesting to the user.
Can I have one more app? Do one thing really well rather than ten mediocre features. If you want to do more, create several focused apps.
Things that look like X should act like X. Always match native look and feel with the expected behavior. Do not surprise the user in a negative way.
1. Application Icon
Your application icon is the first thing the users will see of your app, so give it some love to make sure your app makes a great first impression.
1.1 Make your icon pop from both a light and a dark background
Your application icon might be displayed in a number of visually different contexts, so you should design your icon in colors that pop from both a light and dark background.
1.2 Use the correct format for the app icon
Your icon should be a perfect square and you should provide your icon in the following sizes:
- 300 x 300
- 128 x 128
- 64 x 64
- 32 x 32
- 36 x 18 (read more below)
We have created a sample .PSD file of the 36×18 px icon called
app-icon-example.psd, for you to use as starting point when creating your icon. You can find it in the Design Resources zip file. The 36 x 18 icon will contain two versions of a 18 x 18 px icon that will be displayed in the Spotify sidebar – one for the normal, deselected state and one for when your app is selected. Create a 16 x 16 px icon for each version that you center on a 18 x 18 px canvas, so that there is a one pixel padding with transparent pixels around the icon. You then need to place the two of them next to each other on a 36 x 18 px canvas. As with the other icons in your app, make sure the app icon is pixel-perfect by tweaking individual pixels for every size. Don’t just scale it down and leave it, because it will probably get blurry as you scale it. You should consider redrawing the 16 x 16 px icon in a simpler shape if the subject of the larger icons have a detailed shape. Feel free to add a 1–2 px border radius on your 16 x 16 icon.
2. Responsive layout
Don’t count on users having a certain screen size. The app should work on both small and large screens.
2.1 Use a responsive layout
Adjust your design dynamically to different screen sizes. A typical Spotify user has both sidebars open at all times, plus an ad banner. Based on that, the app should work from at least 640 px width (based on a screen resolution of 800 px with an 160 px ad banner) up to large screens with about 2500 px width or more. It is usually wise to have a maximum breakpoint for scaling the content of the app on large screens (for instance 1200 px). However, this is dependent on the content of the app.
Remember that the Spotify app already has two columns: The source list to the left and the friend bar to the right.
3.1 Don’t use columns
Adding another column navigation inside your app might lead to column creep.
Readability and consistency is really important in an app.
4.1 Use the correct typography
Some samples of headings using more characteristic typefaces:
For optimized readability and consistency, please use Lucida Grande, Helvetica or Georgia for text up to 18 px. For text larger than 18 px (eg. headers), feel free to implement your branding typeface through webtype techniques such as Typekit.
We advise you not to design a dominant top area with your logotype occupying too much space, which will distract the user from immediately discovering your great content.
5.1 Make the branded area no higher than 60 pixels**
If you absolutely need a branded top area place a branded area below the tab bar and use your brand color, logo and typography. Make it no higher than 60 pixels.
5.2 Link the app logo to the home tab of your app
Clicking the logo or branded area should take the user to the home tab of your app, not a website.
We advise you to use vibrant colors with care. To ensure a pleasant viewing experience, try to use black, grey or white colors for the background. If you’re using vibrant colors, then apply them for example in headings or elements you want to highlight.
Our users have got used to our standard icons, so to help to lessen the learning curve, we want you to use our icons in your app.
7.1 Use our own set of icons to convey different features and actions**
7.2 Make your own icons align with ours
If none of our icons fit for a certain feature or action in your app, you’re of course welcome to design your own. In that case, match the style of the new icon with ours, so that they all play nicely together visually. However, make sure that your icons don’t conflict with our current ones in order to not confuse our users. E.g. don’t use a yellow star for a rating functionality within you app.
7.3 Make sure your icons are sharp and crisp
When you’re scaling an icon to the size you want it, make sure the shape is pixel-perfect by tweaking the shape to fill whole pixels. You want them to be sharp and crisp, not a blurry mess. The Design Resources zip file contains a file called
icon-sharpness-example.psd where you can see an example of how to design an icon. Take a close look at the shapes of both icons to see how the vector paths of the pixel-perfect icon align to fill whole pixels, while the blurry version unsurprisingly does not:
8. Loading Content
When loading content in your app, avoid showing a blank screen with just a loading indicator in the middle.
8.1 Show the interface elements to show that content is loading inside
This gives the user a hint of what’s to come when it has finished loading, which in turn makes waiting for something to load more bearable. Also, place all the loading elements where they’re supposed to be when they have finished loading.
8.2 Use Spotify’s throbber when loading
Use Spotify’s throbber (included in the Design Resources zip file) to inform the user that your application is waiting for something:
9. Mouse cursor and dragging
The mouse has two states. The pointing hand and the standard default cursor.
9.1 Only use the “pointing hand” mouse cursor for links or images that take you to another view inside Spotify or to a website in the browser
All other links (actions) should have the default cursor.
9.2 Don’t allow text selection
Don’t allow text selection unless necessary and/or actually useful.
9.3 Dragging of images
Only images/icons that are connected to playlists or that can be used for a search can be drag-able. Only the URI should then be dragged and not the actual image itself.
10.1 When navigation is needed, use Spotify tabs
If you have a great amount of relevant content for users there are of course ways of structuring that into tabs. We want you to use our standard tab navigation for your app. If you only have one section in your app, you don’t need any tab navigation. The number of tabs should ideally be no more than five.
10.2 Keep tab navigation simple and consistent
We want the navigation within the Spotify client to be consistent. No sub tabs can be used, there is just one level of navigation. See the Spotify Applications Guidelines for more on tabs implementation.
11.1 Underline links on hover
Links should be underlined when the link text is hovered. The link text color can also be changed. Don’t underline the link when something else (e.g. a picture) is hovered.
11.2 Don’t use external links
Apps should be complete experiences. Therefore, you should deliver functionality without requiring the user to leave Spotify. If it’s absolutely necessary to link outside your app, make it clear to the user that they are about to open their browser. To make sure the user knows a link is external, use the external link icon to indicate that the user will leave the client. Share icons such as Facebook or Twitter do not need the external link icon. In addition, be explicit with your copy (eg. ‘go to’ or ‘visit’) and include the top domain such as ‘.com’ in the URL text. Visit our web page
11.3 Links to music services and websites from a Spotify app
An app in Spotify should be a self contained user experience using Spotify music. It should not promote any other alternative music services. If the app provides an external link to a page or service that contains any music video or music players, we require that the page or service also provides a link of equal prominence to the Spotify music service. This should be a link back to your Spotify app or an embedded Spotify Play Button that plays the related music. If the app contains external links, the party with control of the Spotify app must have a take-down policy and mechanism to promptly remove any links reported as inappropriate from the app.
You can give your app a footer for secondary information. That could be your website link or a log out option.
12.1 No sticky footer
A footer should never stick to the bottom but should scroll with the content, just like a usual website does. Since our free users often see banners at the bottom of the screen your app cannot have a footer that sticks to the page while scrolling. We don’t want our users to end up with double banners, seeing almost nothing in the main screen.
We want to minimize the use of pop-ups.
13.1 Don’t use pop-ups
Pop-ups, light boxes and overlays should be considered a part of navigation, and should work with Spotify back/forward buttons. The only exception from this is when the pop-up does not contain content, but rather operates on the content of the underlying page. Examples of such exceptions would be pop-ups for sharing, messages, log in and so forth. Pop-ups that contain playlists, albums, reviews and similar should be possible to navigate within using the native Spotify back/forward buttons.
14. Back and Forward Navigation
The Back and Forward navigation within the Spotify client is very important for the user experience.
14.1 Use Spotify native Back and Forward buttons
Always use the Back and Forward buttons in the header to navigate back and forth through different views in your app. That is also applicable if your app doesn’t use any tab navigation in the top but is rather a sequence of different pages.
Please note that from a user experience perspective it’s not OK to create your own back button:
14.2 Do not stack the back/forward queue
For example, when clicking the logo multiple times, only one step should be added to the back/forward queue. The user should not have to click the back button multiple times to go back.
15. Scrolling & Pagination
Scrolling and pagination can be used within your app. Which one you should choose depends on the situation.
15.1 Use of continuous scroll
If you’re showing content of the same kind in one page we advise you to use the infinite scrolling principle. If you cannot implement infinite scroll due to performance or similar you can use a ‘Show More’ button.
15.2 Use of ‘Show more’ button
The ‘Show More’ button is preferably used on overviews, e.g. when you don’t want to show a full playlist or all albums.
15.3 Don’t use scroll bars within components
Nesting scroll bars inside your app makes it difficult for the user to navigate vertically. Rely instead on scrolling the entire view of your app. Don’t use scroll bars within track listing components. Instead, use a “Show more tracks” button that will expand the full track list. Alternately, take the user to a track list page showing the complete track list. Also see the Use of ‘Show more’ button section above.
15.4 Use of pagination
In case you’re using more content types on one page and want to scroll through those different sections, please use Spotify pagination. For now, please use the two arrow buttons. We’re working on a solution that shows users their positioning in the content section. When changing to the next page, please make the transition of content as smooth as possible. If you are using your own Next and Previous buttons, it is useful to add information about where the step will take you, e.g. the name of the article next to the button.
15.5 Avoid dead ends in pagination
An example of a dead end is when the user opens an article from an overview. If they then have to click back to select another article from the overview, it is a dead end. Instead of this, consider using previous/next page navigation.
15.6 Use of overlay pagination
In case you’re using big photography or you’re filling the page with imagery you can use overlay pagination in order to scroll through different articles/content.
16. Navigation on album, track or artist images
A nice way to get a strong visual impact is to use beautiful album artwork and photographs of artists in image grids. An album title, artist name or playlist title should always take the user to the corresponding Spotify page.
16.1 Image sizes
Use our standard sizes for images: 300 x 300, 150 x 150 px, 128 x 128 px, 64 x 64 px and 40 x 40 px. The image itself is always linked to the corresponding page in Spotify, which could be the album or the artist page. When you hover the actual image the cursor should switch to the pointing hand. Hovering the image also blends in the play button, see below.
16.2 Album link
The album link opens the corresponding native album in Spotify. No track should start playing. The album link is underlined on link hover, not image hover.
16.3 Artist link
The artist link opens the corresponding native artist page in Spotify. No track should start playing. The artist link is underlined on link hover, not image hover.
16.4 Track link
The track link opens the corresponding native track page in Spotify: the single or the album. No track should start playing. The track link is underlined on link hover, not image hover.
16.5 Overlay play button
To make it as easy as possible to simply start playing music, we use play and pause buttons directly on images. These are displayed when hovering the image (only the image itself – not when hovering e.g. album/artist labels below).
For artist images, there are two cases:
- If an artist image is clearly indicated with a specific track or album title, clicking the Play button starts playing that specific track or album.
- If an artist image is not clearly indicated with metadata like a track or album title, clicking the Play button starts playing the first track of the artist’s Top Hits in Spotify.
The Play button overlays exist in different sizes depending on the size of the image. Button overlays should never fill or take most space of the image since the image itself is a link that needs to be clicked. An image smaller than 64 x 64 pixels should not have overlay buttons. Images bigger than 300 x 300 pixels use the XL Play and Pause button:
Do not place the play button in other positions:
Hover states of Play and Pause buttons:
When hovering the play and pause buttons, do not switch the mouse cursor to the pointing hand.
16.6 ‘Now Playing’ icon
On images the ‘Now Playing’ icon sits on top as an overlay to visually indicate that the album or track is playing. Hovering the Play button while the track is playing switches the ‘Now Playing’ to the Pause button. Hovering the image when the track is paused replaces that icon with the Play button.
16.7 Linking to internal content in an app
To navigate from an album, track or artist to a page within the app, for example an album review, always use an additional link or button. As an example, use a button like “Read Review” if you want to link to a review within your app.
When the artwork is the core navigation of the app, the artwork itself can be used to navigate to internal content. But, as mentioned in the overall UX principles, you should always match native look and feel with the expected behavior. So, when using artwork to navigate within your app, you have to change the look and feel. One way to do this is to make the artwork and other information around it feel more like a unit or a clickable card. The important thing is that it stands out from the native artwork look and feel.
The image above is an example of when native behavior has been customized. The native look and feel could differ to custom look and feel. Clicking the card will take the user to the relevant page within the app (instead of the native page). In this illustration, a border and a shadow is added to make the artwork and information around it feel more like a unit. Changes should be made to fit your design and brand.
16.8 Text and play button overlay
In case you want to use a text overlay on top of an image, the Play button and the ‘Now Playing’ icon appear next to the track/album title aligned with the text. The image can differ from the text, for example when using an artist image instead of a track cover, but be sure the text always represents what is going to be played when clicking the Play button. This is an alternative layout and the behaviour is the same as the standard artwork layout when it comes to linking: the picture is linked to the corresponding native page (in the case below Robyn’s artist page) and the album/track/artist names within the overlay are linked to native pages as well.
16.9 Playlist mosaic
You can use the native Spotify mosaic for playlists, or create your own custom image of the playlist. If you are creating your own image, make sure it is also shown on the native playlist page.
16.10 Keyboard navigation
The Enter key should open the selected feature. Up- and down arrow keys should be enabled in search results and drop-down menus
Components & Actions
17. Adding Apps
We have standardized the way of installing apps, so you don’t need to think of that aspect. Simply create your app logo and the app description (see more in ‘Application Icon’).
18. Track Listings
Track lists should always look and work exactly as they do elsewhere in the client. This is important because it makes sure our users understand that it’s a playable track list that they can interact with in the usual way. For example, when they right-click a track, they expect to get the regular context menu, and to be able to drag and drop to a playlist. Please always use our native Spotify right-click context menu. Don’t build your own right-click menu. This is important, as our native track list component is updated from time to time and needs to be displayed properly. For instance, in some countries there are requirements on being able to show an “Explicit” tag for tracks. Users would want to be able to interact with this properly. Therefore, you should always use our standard component instead of implementing your own.
18.1 Always use native track list component
When listing tracks in your app, use our standardized track listings. If you want to make the track listing slimmer you can remove the numbering and the time, but keep the star button next to each track.
18.2 Use of track listings on top of images
If you have a visually rich app with large images, it’s ok to have track listings on top of images. In that case, don’t make the background more transparent than 80%
18.3 Use column headings in track lists
Please add a header with column descriptions to your tracklist.
19. Logging in and out of apps
We recommend that it should be possible to use the app without having to log into (for example) Facebook first. The start experience of the app should not be just a Facebook log in page, but a page that draws the user’s attention and makes them want to discover more. We therefore recommend that the user is only prompted to log in when the app needs to access their friends, library, listening history and so forth. If it is vital that the user logs in using Facebook (etc.), the legal text for logging in must be used. Note: If you just want to separate different users from each other without using private data, you can use the anonymous identity (“identifier”) of the user available in the
api/models~User object for the current user.
19.1 Legal text for logging in
In case your users need to log in using Facebook or any other service, this legal text must be displayed:
If you are using the Spotify user identity of the current user, as available in the Spotify Apps API, you need to ask the user’s explicit permission to do so. Here is how you must do that:
19.2 Offer a log out button
In case users have the option to log into their profile for using your app you should offer a Log Out function as well. (This is also needed when you are using the Spotify identity.)
19.3 Position of the log out button
There are two options for positioning the log out button:
- One option is to place the Log Out button close to the profile information:
- The other option is to put the Log Out button in the footer:
- Please never put the Log Out button in the navigation bar or the branded area:
20. Offline Mode
No parts of the app should be accessible or visible when the app is in Offline mode.
20.1 Offline mode view
You need to create an Offline view. In this view, it should be clear to the user that no content in the app is accessible. The user should not be able to do anything within the app when in a disconnected state.
When the app is down due to maintenance issues, we also recommend that the app should give some kind of proper error message.
21. Unavailable content
Due to legal rights, certain tracks may not be available in all regions.
21.1 Unavailable tracks and playback
When many tracks are unplayable, have in mind how these tracks may affect your app. E.g. ‘Top Tracks’ might be better a better section label than ‘Top 40’.
Use native Spotify buttons as much as possible.
22.1 If there is a Spotify button for an action, it should be used
Don’t create your own button for ‘Add as Playlist’, for instance.
22.2 New buttons should resemble Spotify look and feel
If you need to create new buttons, they should resemble the look and feel of our existing ones.
22.3 Follow playlist button
When users follow a Playlist in Spotify, they always have the latest version of the Playlist – the Playlist owner’s changes are instantly reflected to all subscribers. If you display an existing Spotify Playlist, always place the “Follow” button next to the playlist image and title. Once the user clicks Follow, the button disappears. Alternately, a recommendation is that it can change into a “Following” state. A user should not be able to both ‘Follow’ and ‘Add as Playlist’ for the same playlist.
22.4 Add as Playlist button
If you display a list of tracks and/or albums and want the user to be able to save this content as an editable Playlist, show the “Add as Playlist” button. When the user clicks this button, add a playlist to the user’s account (the user is the owner of this Playlist). In addition, disable the button with a “Playlist added” state or remove the button so that the user can’t add the same playlist multiple times in a row. The flow for this would be:
- Change the button to “pressed” state when clicked.
- Remove the button after clicked.
- Create the playlist.
- After a period of time (a few seconds) the button would go back to the original state allowing to add the list as a new playlist again. Alternately, the button is made visible again the next time the user revisits the page.
22.5 Create a relevant name for created playlists
The playlists created from the app should have a logical name e.g. “Playlist name – app name” so the user can stay organized and future playlists the user creates from within your app won’t have the same name. Of course the user can rename these playlists and alter the contents.
We’ve already built a way of sharing, so we prefer that you use this and don’t create your own.
23.1 Use native sharing
The native Spotify share function should be used. When you want to highlight sharing, use the native Spotify share button, which will show our native share dialogue. Please avoid using other share features that opens outside the Spotify experience. Right-clicking any Spotify URI will give the option to share the album/artist/playlist etc. through the same dialogue. Your app will then be shown as the “source” on e.g. Facebook.
24. Web forms
If you need to add selectable fields for user information and similar, here are some things to keep in mind.
24.1 Mandatory vs. optional fields
If there are more mandatory fields than optional ones, the optional fields are clearly marked. If there are more optional fields than mandatory, the mandatory ones are clearly marked.
24.2 Selection vs. deselection of option fields
No voluntary fields should be preselected. Where applicable, there should be an option to select/deselect all voluntary fields. Last updated: December 6, 2013