AVS Display Cards for Tablets 1.1
The guidance on this page is based on implementing the TemplateRuntime 1.0 and PlaybackController 1.1 APIs for Tablets. If you are using different versions, choose another page from the drop-down menu above. This page contains Tablet-specific Display Card design guidance. For general multimodal best practices, please see Multimodal Display.
Display Cards for Alexa provide visuals to support verbal responses, and give your customers an additional way to interact with Alexa.
If you are implementing Display Cards on a device, the Cards should properly display all content, templates, media attributions, and media controls. In addition, we expect that:
- A Display Card will appear as soon as Alexa begins responding or media begins playing, and the Display Card’s contents will match the Alexa response or media.
- Transitions between Display Cards will be smooth, as will the transition into displaying Cards and dismissing Cards.
- Display Cards will respond to screen interactions and voice utterances as described in the design guidelines for your product’s device class.
- Alexa attention states for Listening and Thinking will appear on top of any visible Display Card, and will not be obscured.
Details for each of these are provided in the guidelines below.
Static Display Cards
Global elements
Alexa shows Static Display Cards in response to certain non-media queries. All Display Cards in this section have the following global elements.
Elements
The numbered elements in the illustration above are described in more detail here.
-
Titles: All cards will have a mainTitle. Some will have a subTitle.
-
Alexa Skills Icon: This icon (top right) appears when a third-party provides the information being displayed on the Card. If the information is not being provided by a third-party, this icon will not appear.
-
Barge-In Button: This button (bottom center) can be tapped at anytime to activate and talk to Alexa.
-
GUI Dismiss Button: Tapping the "X" hides the GUI and ends the Alexa response.
Notes on the guidelines for static Display Cards
-
All specs are based on a reference template of 1280 x 800dp.
-
Layout is given in percentages to help adapt the template to your device’s screen resolution.
-
Font sizes are given on the reference screen. These sizes should scale as the resolution of screen changes. If no line-height is given, the line-height is the same as the font size.
-
mainTitle and subTitle should never exceed one line. If the text exceeds the width of the container, the crop the text and use an ellipsis.
-
Image assets and icons marked in dp size should scale as the resolution of screen changes.
-
All of the assets URL can be found in the Asset section of this documentation.
Voice Chrome
Voice chrome is a visual indicator of the Alexa attention states such as Listening, Thinking, and Responding. Most tablets will use on-screen voice chrome, although it is possible to use on-device LEDs to display the states instead.
Details of how and when voice chrome should be displayed can be found in the Interactions section below, and in the Interruption Scenarios section on this page. The colors and animations of voice chrome should follow the patterns specified in the Attention System documentation.
Interactions
There are two modes you can choose from for the static Display Cards: light and dark. Depending on the color scheme of the card, Alexa will be evoked on a white or black overlay.
Note: NowPlaying cards use only dark mode.
The following is an example of the screen states a customer might view when interacting with Alexa.
Invoke Alexa in light mode
Note: Active voice chrome is on the top of a white overlay with 50% opacity.
Invoke Alexa in dark mode
More information on dark mode is available under Dark Mode.
Note: Active voice chrome is on the top of a black overlay with 50% opacity.
Example interaction breakdown
Step 1: Invocation
The customer activates Alexa with the wake word “Alexa” or with a control on the device (physical or GUI button for example). This activates voice chrome to show Alexa is listening.
Step 2: Listening
Once Alexa is invoked and voice chrome is displayed, the customer can control Alexa with their voice. If Alexa recognizes an utterance, it processes the intent and display a Card. If Alexa doesn’t hear anything from the customer within 8 seconds, voice chrome dismisses.
Step 3: Response and Dismissal
Alexa responds verbally, and when applicable, with a Display Card. Audio and visuals should always be in sync, showing the card and playing audio simultaneously. Once Alexa finishes speaking, the card should dismiss automatically after 2 seconds of inactivity.
If, before playback is complete, the customer:
-
Taps the barge-in button (the Alexa logo), then TTS stops and voice chrome should display on top of the Card.
-
Taps the “X”, then the card clears and the TTS stops.
The Card should not be dismissed before TTS is complete, unless the customer has done so manually. Tapping the barge-in button (the Alexa logo) should stop the TTS, dismiss the Card, and open the voice chrome.
Additional interaction scenarios are described in the Interruption Scenarios section.
BodyTemplate1
BodyTemplate1 is used for Q&A, Wikipedia queries, and third-party Skill requests that do not contain a photo. Sample utterances that would invoke BodyTemplate1 include:
- “How deep is the ocean?”
- “What is the definition of “paradox”?”
- "What is the Karman line?"
- "What is bike polo?"
Style
Layout
Note: The body content (textField) can extend off the bottom of the screen, which the customer can access by scrolling.
Data
JSON
{
"directive": {
"header": {
"namespace": "TemplateRuntime",
"name": "RenderTemplate"
},
"payload": {
"token": "{{STRING}}",
"type": "BodyTemplate1",
"title": {
"mainTitle": "Who is Usain Bolt?",
"subTitle": "Wikipedia"
},
"skillIcon": {
"sources": [
{
"url": "https://example.com/smallSkillIcon.png",
"size": "small"
}
]
},
"textField": "Usain St Leo Bolt, OJ, CD born 21..."
}
}
}
BodyTemplate2
BodyTemplate2, like BodyTemplate1, is used for Q&A, Wikipedia queries, and third-party Skill requests but, unlike BodyTemplate1, it also returns an image. Sample utterances that would invoke BodyTemplate2 include:
- “Who is Usain Bolt?”
- “What is 5 miles in kilometers?”
- “Who wrote To Kill a Mockingbird?”
- “Where is New Mexico?”
Style
Layout
Note: The image height and width are maximum dimensions. Images should resize to avoid exceeding either dimension.
Data
JSON
{
"directive": {
"header": {
"namespace": "TemplateRuntime",
"name": "RenderTemplate"
},
"payload": {
"token": "{{STRING}}",
"type": "BodyTemplate2",
"title": {
"mainTitle": "Who is Usain Bolt?",
"subTitle": "Wikipedia"
},
"skillIcon": {
"sources": [
{
"url": "https://example.com/smallSkillIcon.png",
"size": "small"
}
]
},
"textField": "Usain St Leo Bolt, OJ, CD Born 21 August...",
"image": {
"contentDescription": "Image with two sources."
"sources": [
{
"url": "https://example.com/smallUsainBolt.jpg",
"size": "small"
},
{
"url": "https://example.com/largeUsainBolt.jpg",
"size": "large",
"widthPixels": 1200 ,
"heightPixels": 800
}
]
}
}
}
}
ListTemplate1
ListTemplate1 is used to display items in a list, such as a calendar or shopping list. Sample utterances that would invoke ListTemplate1 include:
- “What’s on my to do list?”
- “Add eggs to my shopping list.”
- “When is my next event?”
- “Add “Lunch with Jayla” to my calendar.”
Style
Layout
Note: The distance between leftTextField and rightTextField is static. For example, if leftTextField displays more characters than shown here, rightTextField should push right and the distance between the two should remain the same.
Data
Variation: Calendar
Note: The distance between the time and event is static.
JSON
{
"directive": {
"header": {
"namespace": "TemplateRuntime",
"name": "Render"
},
"payload": {
"token": "{{STRING}}",
"type": "ListTemplate1",
"title": {
"mainTitle": "Title",
"subTitle": "Subtitle"
},
"skillIcon": {
"contentDescription": "Source for the skill icon.",
"sources": [
{
"url": "https://example.com/smallSkillIcon.jpg",
"size": "small"
}
]
},
"listItems": [
{
"leftTextField": "1.",
"rightTextField": "Alfa"
},
{
"leftTextField": "2.",
"rightTextField": "Bravo"
},
{
...
}
]
}
}
}
WeatherTemplate
WeatherTemplate is used with all weather-related utterances, such as:
- “What’s the weather?”
- “Will it rain today?”
- “What’s the weather in [location]?”
Style
Layout
Weather template layout in 3 digits
Data
JSON
{
"directive": {
"header": {
"namespace": "TemplateRuntime",
"name": "RenderTemplate"
},
"payload": {
"token": "{{STRING}}",
"type": "WeatherTemplate",
"title": {
"mainTitle": "San Francisco",
"subTitle": "Friday, October 31"
},
"skillIcon": null,
"currentWeather": "75°",
"description": "Mostly cloudy and more humid with a couple of showers and ...",
"currentWeatherIcon" {
"contentDescription": "Weather image sources.",
"sources": [
{
"url": "https://example.com/mediumPartlyCloudy.jpg",
"size": "medium"
}
]
},
"highTemperature": {
"value": "76°",
"arrow": {
"contentDescription": "Up arrow sources.",
"sources": [
{
"url": "https://example.com/mediumUpArrow.jpg",
"size": "medium"
}
]
},
},
"lowTemperature": {
"value": "45°",
"arrow": {
"contentDescription": "Down arrow sources.",
"sources": [
{
"url": "https://example.com/mediumDownArrow.jpg",
"size": "medium"
}
]
},
},
"weatherForecast": [
{
"image": {
"contentDescription": "Partly cloudy...",
"sources": [
{
"url": "https://example.com/smallChanceOfRain.jpg",
"size": "small"
}
]
},
"day": "Sat",
"date": "Oct 22",
"highTemperature": "71°",
"lowTemperature": "55°"
},
{
...
}
]
}
}
}
Dark mode
You may want to adapt the templates to use a dark mode, for example for night-time use. Dark mode provides a more pleasant experience in low lighting. To implement dark mode:
- Change body and footer backgrounds to black (#000000).
- Change all black text (#151320) to white (#ffffff).
- For image URLs on the WeatherTemplate, use “darkBackgroundUrl” instead of “url”.
Here are examples of the result.
Global Elements
Alexa shows the NowPlaying GUI in response to media queries. All NowPlaying Cards in this section have the following global elements.
The global elements in the NowPlaying Card include:
-
Media metadata
-
Playback controls: These will vary depending on the media type and the service.
-
Progress bar: Appears with most media types.
-
Barge-in button (Alexa logo): This button can be tapped at any time to activate and talk to Alexa.
-
“X" button: Tapping the “X" should hide the GUI and stop playback.
-
Media artwork: This could be album art, a radio station logo, a program logo, or book artwork.
-
Music provider logo: The logo of the service providing the media.
Controls Per Music Service Provider
Alexa can play music from multiple Music Service Providers. Controls vary per provider offering. For example, a live radio station might not have forward and back controls. The correct controls for each offering will be specified in the PlayerInfo directive.
Interactions
The following is an example of the screen states a customer might view when interacting with Alexa.
Response and dismissal
In response to media requests, Alexa displays a NowPlaying GUI, with media metadata and playback controls.
If the customer:
-
Dismisses the GUI by tapping the “X" or navigating away from the Card with device controls, then both the Card dismisses and audio stops. Note: If your device supports playback controls elsewhere on your device (see Additional Playback Controls), then the "X" should dismiss only the GUI and allow music playback to continue.
-
Pauses or stops the music via voice or button, then the audio stops but the Card remains. The Card should then auto-dismiss after 1 minute of inactivity.
-
Activates Alexa again while the music is playing, then the music attenuates, and voice chrome reappears awaiting the next command.
Additional interaction scenarios are described in the Interruption Scenarios section.
Specs
Style
Layout
Note: Media artwork is constrained by the container shape and should never exceed these dimensions. In cases where artwork is not a square or is smaller than the container shape, it should be horizontally and vertically centered within the container shape.
Notes
- The source/author information is one line, and the mainTitle can be two lines maximum. If the mainTitle exceeds two lines, truncate the text and use an ellipsis.
- If content extends past its maximum number of lines, truncate the text and use an ellipsis.
- When mainTitle has two lines, titleSubtext1 and titleSubtext2 push down to accommodate. The controls and progress bar do not move.
Data
Examples
Example 1: Amazon Prime Music
“Alexa, play Smoke & Retribution”
Toggle state on
When a toggle (shuffle or loop, for example) is turned on, the icon will remain in active state.
JSON
The name key-value pair may come back as “Amazon Music”, “Prime Music”, or “Prime Station”. If Prime is not enabled, name will be “Digital Music Store.”
{
"directive": {
"header": {
"namespace": "TemplateRuntime",
"name": "RenderPlayerInfo",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}"
},
"payload": {
"audioItemId": "{{STRING}}",
"content": {
"title": "{{STRING}}",
"titleSubtext1": "{{STRING}}",
"titleSubtext2": "{{STRING}}",
"header": "{{STRING}}",
"headerSubtext1": "{{STRING}}",
"mediaLengthInMilliseconds": {{LONG}},
"art": {{IMAGE_STRUCTURE}},
"provider": {
"name": "{{STRING}}",
"logo": {{IMAGE_STRUCTURE}}
}
}
"controls": [
// This array includes all controls that must be
// rendered on-screen.
{
"type": "{{STRING}}",
"name": "{{STRING}}",
"enabled": {{BOOLEAN}},
"selected": {{BOOLEAN}}
},
{
"type": "{{STRING}}",
"name": "{{STRING}}",
"enabled": {{BOOLEAN}},
"selected": {{BOOLEAN}}
},
{
...
}
]
}
}
}
Example 2: iHeartRadio Live Radio
“Alexa, play Hollywood Breakdown on iHeartRadio”
JSON
{
"directive": {
"header": {
"namespace": "TemplateRuntime",
"name": "RenderPlayerInfo",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}"
},
"payload": {
"audioItemId": "{{STRING}}",
"content": {
"title": "The summer of \"sequel-itis\" and beginning of awards season",
"header": "KCRW's Hollywood Breakdown",
"mediaLengthInMilliseconds": 0,
"art" : {
"sources" : [
{
"size" : "medium",
"url" : "http://example.com/AlbumArt.svg"
}
]
},
"provider": {
"name": "iHeartRadio Live Radio",
"logo" : {
"sources" : [
{
"url" : "https://example.com/ProviderLogo.jpg"
}
]
}
}
}
"controls": [
{
"type": "BUTTON",
"name": "PLAY_PAUSE",
"enabled": true,
"selected": false
},
{
"type": "TOGGLE",
"name": "THUMB_UP",
"enabled": true,
"selected": false
},
{
"type": "TOGGLE",
"name": "THUMB_DOWN",
"enabled": true,
"selected": false
}
]
}
}
}
Example 3: Amazon Music Station
“Alexa, play my favorite station”
Example 4: Audible Books
“Alexa, read my Audible book”
Example 5: Pandora Music
“Alexa, read my Pandora music”
Note: If Back, Pause/Play, or Forward is disabled, use the "disabled" version of the icon.
Controls-Only Template
There may be instances when no metadata is returned from a NowPlaying request. In this instance, use the Controls-Only Template, which includes a minimized set of visuals.
Note: For certain Music Service Providers, the PlayerInfo directive is sent after the PlaybackStarted Event. In these cases, we recommend adding logic to wait 2 seconds for the PlayerInfo directive. If metadata is not returned after this time, display the Controls-Only Template.
Controls-Only Template
Style
Layout
Data
Native Playback Controls
Many tablets support playback controls on the customer's notifications panel or other universally accessible panel. If your device supports this native framework, then you should support the use of these controls for music playback from Alexa.
This playback controller should display the following metadata:
- art (album artwork)
- title
- titleSubtext1
- provider name
- any other applicable playback controls.
Tapping on the metadata should return the customer to the nowPlaying GUI of the current song.
Transitions
Transitions should be quick (< 1 sec) and employ easing to create a smooth feel. First the background fades in, followed by the content. To account for latency, a background placeholder box should appear in place of an image, which transitions to the fully loaded image when it arrives.
Cards exit the opposite way they came in. The text fades out first and then the Card fades.
Interruption Scenarios
The following are examples of the states the customer sees when interrupting Alexa's response.
Card to Card
Step 1: Utterance1
At Utterance1, voice chrome overlays the existing screen.
Step 2: TTS1 + GUI1
Alexa responds.
Step 3: Utterance 2 (Interruption)
When the customer interrupts Alexa (via tap or wake word), Alexa stops speaking and voice chrome overlays the existing card.
Step 4: TTS2 + GUI2
Alexa responds to utterance2 via voice and replaces the old card with a new one. This card dismisses according to regular dismissal rules.
NowPlaying to Card
Step 1: Utterance1
At Utterance1, voice chrome overlays the existing screen.
Step 2: TTS1 + GUI1
Alexa responds. Music plays.
Step 3: Utterance 2 (Interruption)
When the customer interrupts Alexa (via tap or wake word), the music attenuates and voice chrome overlays the nowPlaying GUI.
Step 4: TTS2 + GUI2
If the utterance is understood and a card is required, Alexa responds to the utterance via voice and a new card. Once the TTS completes, the music returns to the regular volume. The card dismisses according to regular dismissal rules, except that when dismissed, the customer returns to the nowPlaying card.
If the song changes during this time, when returning the nowPlaying GUI should reflect the new song.
Card to NowPlaying
Step 1: Utterance1
At Utterance1, voice chrome overlays the existing screen.
Step 2: TTS2 + GUI1
Alexa responds.
Step 3: Utterance2 (Interruption)
When the customer interrupts the music (via tap or wake word), Alexa stops speaking and the voice chrome overlays the existing card.
Step 4: TTS + GUI2
Alexa responds to Utterance 2 via voice and a new card. Once the TTS completes, music begins playing. This card dismisses according to regular dismissal rules.
NowPlaying to Error
Step 1: Utterance1
At Utterance1, voice chrome overlays the existing screen.
Step 2: TTS2 + GUI1
Alexa responds. Music plays.
Step 3: Utterance2 (Interruption)
When the customer interrupts the music (via tap or wake word), the music attenuates and voice chrome overlays the nowPlaying GUI.
Step 4: GUI1
If no utterance is understood, the voice chrome removes, returning to the nowPlaying GUI, and the music returns to it’s original volume.
Assets
These resources are provided for you to use with your display cards.
For tablets with a resolution of 1280x800dp or higher, we recommend using the large assets listed below. For lower resolution tablets, use the small assets. For resolutions that are much larger or smaller, you can also scale the assets for your needs.
Alexa
- Alexa logo (barge-in button): small tablets, large tablets
- GUI dismiss button ("X" button): small tablets, large tablets
Transport controls
The following are assets for media player controls.
Play
Pause
Next
Prev
Shuffle
Loop
Thumbs Up
Thumbs Down
30 Seconds Forward
30 Seconds Backward
Alexa font
Use the following font families for Alexa-related screens, features, and functionality:
- Amazon Ember Display
- Bookerly
- Noto Sans CJK
Bookerly is used mainly for Things to Try text, and Noto Sans CJK is supplied for Chinese, Japanese, and Korean language support. Amazon Ember Display and Bookerly are reserved for Alexa-related uses only.
Find the Amazon font files on the Amazon Developer Portal (requires login) under the Resources tab.