The Alexa Skills Kit provides the ability to display visual information, both text and images, via skill cards. These cards are a useful way to provide your users with additional information from your Alexa skill that may be too verbose or too difficult to include in the voice user interface. Skill cards can be displayed in many form factors across different types of devices. This includes the Alexa app via iOS and Android devices, the Alexa app via a web browser, on Fire Tablet, and on the big screen while interacting with skills on Fire TV.
Creating a Skill Card
There are currently three types of skill cards you can create: Standard, Simple and LinkAccount.
- Standard – these cards card display both text and an image. You provide the card title, content, and an image (via a URL).
- Simple – use this type to display only text. You provide the text for the card title and content.
- LinkAccount – these cards are used during Account Linking to third-party accounts. LinkAccount cards are the same as Simple cards with additional link to your authorization URL
When you create a skill card, you will provide textual information (in both plain text and SSML) along with an optional image. Here is an example of a Standard card that I have added to my own skill hosting in AWS Lambda using the well-known alexa-skills-kit-color-expert blueprint. When my skill’s LaunchRequest returns its JSON response, you can see both the SSML as well as a new image inside of the Alexa App, in this case running on my iPhone.
You can see I have provided the following information in the card:
- Title: “Color Picker with Images – Welcome”
- Skill name: “standard cards demo”
- Image: small image of Echo devices hosted via an Amazon S3 instance
- Content: displaying some SSML-embedded text
Creating a similar card in your own Alexa skill is a simple process and involves updating your existing skill card JSON response and adding the proper permissions to your hosted image. For more information on the building a JSON skill card response check out this post.
Tips for Displaying Skill Card Text
1. You may have noticed something in the skill card above however, that doesn’t look quite right. While having SSML tags is important to enabling a more human like conversation with Alexa it will appear as a bunch of gibberish to your users. By default, SSML is not stripped out of the skill card display which is why you are seeing both the <speak> and <break> tags rendered. This is a common skill card error we have seen during Alexa skill certification and one that can easily be fixed using a regex expression or string replace.
2. You can also use either “\r\n” or “\n” within the text of the card to insert line breaks. Use line breaks to help format individual lines of addresses, product details or information. However, we don’t recommend adding double line breaks when separating parts of a street address to make this content more easily legible.
3. Keep your text responses short, informative and clear: Structure text for cards in brief, informative sentences or lines of text. Avoid unstructured product details.
4. Also, don’t rely on large blocks of text but instead keep details to a minimum so your users can evaluate the card at a quick glance.
5. Since URLs in cards are not clickable links, don’t just include URLs on cards to direct users to other sites. Instead, provide instructions to direct the user vocally. For example, have Alexa say, “Go to the Settings section of (the website name).”
You should write the text on your cards like you would in a document. Use sentence case for body text and title case for headlines. Also, don’t forget to do a grammar check! Unlike your Alexa response, the text here is not going to be read aloud by Alexa; it is going to be displayed exactly as you type it.
Tips for Displaying Skill Card Images
Skill card images are displayed in two different sizes: a smaller resolution image and a larger resolution image. The different sizes are used when displaying skill cards on different sized screens. It is recommended you follow similar sizes for the best results:
Recommended Size (in pixels)
Displayed on smaller screens
720w x 480h
Displayed on larger screens
1200w x 800h
Please Note: Images must be in PNG or JPG format and cannot exceed 2MB. If you only provide one Image URL, the Alexa app uses that image regardless of the screen size where it is displayed.
Here are some tips for generating an image that will provide the best experience to your user:
- Use simple, high-quality images: Choose images with simple shapes and details that can be seen from several feet away to several inches away. Think: Fire TV vs. mobile. Save them at 72dpi.
- Use both small and large images: Small images are 720px x 480px. Large images are 1200px x 800px.
- Don’t use text on images: Err on the side of no text on imagery to ensure the best card experience, but if you must make sure it’s easy to read at smaller sizes.
- Give credit: Include any image credit/reference as text on the skill card. Do not place the credit on the image. Don’t use images from the Internet or images you do not have express written license to use.
Fire TV also introduces variability in the card experience due to the size of the viewing screen and its inherent design elements. Here are some things to keep in mind when designing your cards:
- Images appear differently: The images you use on cards will appear in the background of Fire TV cards in addition to the card in the foreground.
- Prioritize important information: Put must-read information at the top of the card as the user may not scroll through the full text.
- Test your cards using Fire TV: Ensure you understand the constraints and optimize cards with the audience for Fire TV’s in mind.
- Don’t use long passages of text: It is annoying for users to have to scroll through lots of text on Fire TV.
When to Use Skill Cards
Think about how often you are using a skill card. Is it in every single response you send to Alexa? That might be ok while you are debugging your skill, but it may overload your user with too much information.
Don’t make viewing cards a necessary step. You should strive to include all important information in your voice experience while the visual card provides additional, optional information.
Skill cards make perfect sense when they provide additional information about a specific piece of content. For example, providing an image of an owl in an animal trivia skill or perhaps an album cover in a music streaming skill.
Don’t Rely on History
The Alexa mobile app has a scrollable history, but the Fire TV does not support a history of skill cards. Therefore, it is important to use cards as one-off individual experiences
Use cards as individual experiences: Don’t depend on the card before or after using the skill since the user might not be able to access it.
Don’t expect users to save information on the cards as they can’t be saved. For instance, while details about a transaction are useful as a card, the card can’t serve as a transaction receipt since the user can’t save it. In addition, users can’t search for old cards.
Help the User Navigate
Cards can be a great way to get a lost user back on track, or enable self-service to show users what they can do.
Provide guidance: Give enough detail for the user to move forward when lost – without going overboard. Suggest sample utterances when they need help.
Also, keep the timing and context in mind. Don’t offer utterances on a card that can’t be used in the context of the current situation. For example, don’t suggest a checkout utterance on a card when there aren’t any items in the user’s cart yet.
Provide Interesting and Relevant Content
Think of skill cards as a way to build on the overall conversation, not simply a log of information to spew out while your user is interacting with Alexa. Keep it interesting: don’t re-use the same content over and over again or your users may begin to ignore the cards all together. Instead, delight the user with moments of surprise and visually interesting images based on the relevant content they’ve asked for.
For more information about Alexa skill cards, check out the following:
Best Practices for Skill Card Design
Including a Card in Your Skill's Response
Voice Design Best Practices Video
Alexa Developer Forums
Alexa Dev Chat Podcast