Widget Design Guidelines

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.

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

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. 

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:

• color = color Black
• angle = 0
• type = linear
• inputRange = 0, 0.75
• width = 100% height =50%    

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.

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.