Published: April 24, 2023
Key takeaways
Consistent design across Widget experiences allows for seamless interactions for customers. Follow the guidelines below as you create your widget and understand best practices for core widget elements to achieve cohesiveness.
Need quick advice?
See the Design Guidelines Checklist.
In this article:
If your widget requires a custom design, rather than using a Widget Responsive Template, there are four key attributes that are essential to support an end-to-end widget experience:
Header, Body, Widget Gallery Thumbnail, and Widget Detail Page.
Other components can be leveraged to create a specific experience. See the Widget Responsive Components article for more information.
The Header component provides clarity to the customer on what the widget is about. The Header component can act as an ingress into the full-screen experience via touch.
The Header should include one of the following options.
Writing guidelines for widget headers
Choose a succinct widget name. Having a succinct name avoids having your widget name potentially truncated in the Widget Gallery display.
Avoid ending the widget name with the word “widget.” When a customer adds a widget, Alexa will play “Okay, adding a <widget name> widget.” If the <widget name> ends with the word “widget,” this can result in awkward TTS prompts like “Okay, adding a <stock market widget> widget.”
Avoid using punctuation or articles in the widget name. Hyphens, em dashes, slashes, parenthesis make it difficult for customers to say the widget name. For example “Alexa, add the Restaurants hyphen Near Me widget.” Additionally refrain from beginning a widget name with articles “A,” “An,” and “The.”
Exclude the word “Alexa” in the widget name. If a customer uses voice to add a widget (e.g. “Alexa, add an Alexa To Do List widget”), saying the wake word as part of their utterance may trigger other nearby devices, or may re-wake the current device.
Dos & Don'ts
Checklist for Header:
If Header includes text,
▢ Keep the widget name to no more than 20 characters (including spaces) to minimize truncation when translated to other languages
▢ Text alignment for Header text is left-aligned
▢ Type size Small, Medium, and Large Hub is 24 dp
If Header includes brand attribution,
▢ Place the attribution logo within the safe zone (144 x 35 dp)
▢ Check if the logo meet the minimum contrast requirements of 4.5:1
The body section of the widget is the main area for customers to view content. This section can contain text and images to best represent the widget’s objective. See Style Guide for Type Ramp, Margins and Gutters, Corner Radius, and Drop Shadow guidelines.
Within the widget, ingress points can be set to open the full-screen experience via touch. Avoid setting multiple ingress points to the same destination.
Checklist for Body:
▢ Text on the Body follows the font style and size based on the text types (e.g. primary text)
▢ Defined color options are recommended as a background color
▢ Widget’s background passes the contrast requirements of 4.5:1 (Color contrast tool link)
▢ Widget have the right corner radius, drop shadow, margins and gutter (see See Style Guide)
▢ Widget doesn’t allow multiple ingress point to the same full-screen experience.
The Widget Gallery is where customers will browse widgets they can add to their Favorite Widget Panel (FWP). Square thumbnail images used in the gallery will serve as the customer’s first impression of your widget experience.
Widget Gallery Thumbnail size: 450 px x 450 px
Checklist for Widget Gallery Thumbnail guidelines:
▢ The thumbnail showcases the purpose and function of the widget
▢ The background should completely fill the image thumbnail
▢ Avoid using a bright color in the background as it can result in poor accessibility
▢ The Primary Text wraps up to two lines with a max character count of 40
Brand attribution
It is optional to include a brand attribution like logo in the Widget Gallery thumbnail image. Below are the guidelines for including any type of attribution logos within the image.
Checklist for brand attribution guidelines:
▢ Logos can be logo only, text logo, or logo with text
▢ Logo sizing carries a maximum height of 56 dp and width is auto
▢ Color options include light (#FAFAFA) or dark (#1E2222) modes
▢ Logos can include gradient overlay if necessary:
The Detail Page is where customers can view more granular detail regarding a widget. From this page they can add the widget to their Favorite Widget Panel (FWP).
A preview image of the widget is used here to showcase the experience in further detail versus what the gallery thumbnail image may offer.
Preview image size: 328 x 552 px
Writing guidelines for Detail Page descriptions
Aim to begin description with an action/verb. Customers will be more engaged and have a better understanding of what the widget does if they know what they will be able to achieve with it. Start descriptions with a verb, e.g., “Discover,” “Get,” “See.” To avoid redundancy and unnecessary characters, do not use “This widget...” in the copy.
Describe the widget as if it were to a friend. Write the descriptions as if you’re describing what the widget offers to a friend. Don’t refer to the “customer” or “user” in the copy.
Describe “Why would a customer want this?” Your description should answer the questions, “Why would a customer want this?” and “What does this widget offer?”
Do not add a CTA. Do not add any calls to action to the description, e.g., “Add widget to get started.” The “Add Widget” button below the description is the CTA.
Maximum Character Limit of 145 characters. Descriptions can be a maximum of 145 characters. Remember to account for 30% localization stretch. Aim for 50 to 100 characters.
Checklist for Widget Detail Page guidelines:
▢ Supply a preview image with dimensions of 328 x 552 px for the medium widget; this image showcases the purpose and function of the widget
▢ The Primary Text wraps up to two lines with a max character count of 40
▢ The Detail Text wraps up to four lines with a max character count of 145
Touch interaction
When creating a widget, keep in mind that we support a variety of touch interactions that customers can perform on their widgets. Please ensure that you follow the motion guidelines when implementing any animations on your own.
Voice interaction
If the widget header matches or is similar to the widget name, consider including commands such as “Alexa, open <header>,” “Alexa, view <header>,” and “Alexa, show <header>.” Make sure these utterances ingress into the full screen skill experience.
Consider including commands that match the footer CTA. Alexa customers are accustomed to being able to speak the content of the buttons they see on screen. For this reason, the footer “More Food Options” is better than “More Options;” if the customer says, “Alexa, show more food options,” we know exactly what they want to do (as opposed to the more ambiguous, “Alexa, show more options).”
If the widget contains any explicit Alexa hint text (words in quotation marks), the corresponding utterances should be recognized and handled by Alexa.
Avoid playing a text-to-speech (TTS) prompt after the customer adds a widget. The widget framework already plays a prompt after the customer uses voice to add a widget (“Okay, adding a <widget name> widget”). Playing an additional TTS prompt would be redundant.
Touch interactions with a widget should not trigger a TTS prompt. Widget interactions should honor the customer’s chosen modality. If a customer speaks to the device, then Alexa should respond with voice; however, if the customer touches the device, then the device should not respond with voice but with appropriate screen elements.
Header
▢ The header communicates a representation of what the widget does or provides
▢ If the Header includes text, recommend using Amazon Ember Display font in 24 dp size, and left align the text with a limit of 20 characters
▢ If the Header includes brand attribution, place the attribution logo within the Safe zone (144 x 35 dp) and ensure that the color contrast meets accessibility standards (see Style Guide for brand attribution information in detail)
Widget Name
▢ Keep your widget name succinct
▢ Avoid using punctuation, articles, or the word 'Alexa,' and end the widget name with the word 'widget'
Body
▢ Text on the Body follows the font style and size based on the text types (e.g. primary text)
▢ Defined color options are recommended as a background color
▢ Widget’s background passes the contrast requirements of 4.5:1 (Color contrast tool link)
▢ Widget have the right corner radius, drop shadow, margins and gutter (see See Style Guide)
▢ Widget doesn’t allow multiple ingress point to the same full-screen experience.
Widget Gallery
▢ Provide a 1:1 square image (450 x 450 px) as a thumbnail, showcasing the purpose and function of widget
▢ The background extends the entirety of the image thumbnail
Detail Page
▢ Provide a preview image of the widget, showcasing the purpose and function of the widget
▢ Content within images will not be localized by default; if a widget will be live in multiple locales, text and/or imagery may need to be submitted separately for each locale
Detail Page Description
▢ Aim to begin the description with an action/verb
▢ Describe the widget as if it were to a friend
▢ Description should answer the questions, “Why would a customer want this?”
▢ Avoid adding a Call to Action
▢ Follow the maximum character limit of 145 characters