Published: April 24, 2023
Key takeaways
This section includes all components in detail, which can be used depending on the purpose of the widget.
Need quick advice?
See Component Overview and the Widget Responsive Component Tech Docs.
In this article:
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.
- Name of the widget (e.g., Recipe)
- Brand attribution (e.g., Amazon Music logo)
- Contextual Information (e.g. City name for Weather Widget): this is only applicable when the widget content is self-explanatory, meaning customers understand what the widget is about without the header text.
Writing guidelines for widget Header
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 guidelines:
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 Footer Action Button component acts as a Call to Action button for customers to interact with the widget via touch. Footer text should clearly communicate the action, such as “Create Sticky” is better than “Create.”
Dos & Don'ts
Checklist for Footer Action Button guidelines:
▢ Maximum of 15 characters (with spaces) for the button to avoid the text being cut off
▢ Text alignment for Footer text must be center-aligned
▢ Type size is 28 dp and must use Bookerly Typeface
▢ Color backgrounds are not recommended for the Footer Action Button component; it is recommend to use a transparent background
▢ 8 dp corner radius applied to the top corners of the component
A Widget collection is a pattern that allows a single widget to page through multiple pieces of content within the Favorites Widget Panel (FWP). Collections will allow pages to ambiently update and rotate through to dynamically show the different pages available. Once the collection has reached its last page in rotation, it will loop back to the start. This pattern should be applied when it's beneficial for a widget to surface multiple pages of content in a non-list format. Widgets that use the Widget Collections pattern should include pagination dots, which help customers identify and browse the collections.
Checklist for Widget Collection guidelines:
▢ Widgets using the Widget Collections pattern should include pagination dots
▢ Widget collections should hold a maximum of 5 pages to rotate through; this will allow for variety and flexibility of pages without becoming too lengthy for customers to browse and navigate through
Pagination dots are used to help customers identify and explore widget collections, which allows a single widget to have multiple pages. As the customer swipes through the widget, the dots will animate within the Footer Action Button space of the widget. Pagination dots are required in widgets that utilize the Widget Collection pattern.
If your widget has multiple pages, choose a variation based on whether your widget has a Footer Action Button or not:
- Solid pagination dots have a solid container to help separate itself from the footer component.
- Gradient pagination dots have a scrim applied to the component to show the contents below in a widget with no footer.
Dos & Don'ts
Checklist for Pagination Dots guidelines:
▢ Pagination dots should be used in widgets that utilize the Widget Collection pattern
▢ Use a scrim when the pagination dots are overlapping text in a widget, do not use a container
▢ If a Footer Action Button is present the Pagination Dots will be placed below the button
The Progress Bar allows customers to easily identify status of an activity, such as music, videos, podcasts, etc. It is recommended that the Progress Bar is placed at the bottom of the widget as this is not done automatically. It is not an interactive component.
Dos & Don'ts
Checklist for Progress Bar guidelines:
▢ The Progress Bar may only be placed at the bottom of the widget; if an Action Button is present it is placed above the Action Button
▢ The color for the progress bar fill is restricted to its default state for consistency
▢ The progress type displayed is a progression of an activity with a known duration
▢ The Progress Bar doesn't display timestamps or durations; they are not interactive
Transport controls allow customers to interact with a play button component, which ingresses a customer to a full-screen video experience. Currently widgets do not support video within the widget itself.
Dos & Don'ts
Checklist for Transport Control guidelines:
▢ The Transport Control doesn’t include other buttons such as pause, fast forward, or back
▢ The primary button sizing should follow official size specifications
▢ The Transport Control is available in light or dark modes
▢ Check for a contrast ratio of 4.5:1
In the event customers may need to customize their widget experience, there are several responsive components to allow for a seamless configuration process for both the developer, and the end customer. These components were designed to provide widget experience makers with the opportunity to mix and match to create the ideal configuration experience for their particular widget.
These components are built upon APL (Alexa Presentation Language) and leverage existing colors, text styles, spacing and margin variables, and components.
Text List
The widget configuration Text List component can be used in a variety of ways and can be paired with other components such as selection controls, search and/or reorder.
- Text List can be paired with any other configuration component.
- Can include Primary Text, Secondary Text, and Tertiary Text.
- Text List can contain imagery per the Alexa Text List Item ARL component.
Reorder
The widget configuration Reorder component can be used in a variety of ways and can be paired with other components such as the Text List and/or Selection Controls.
- Reorder can be paired with any other configuration component.
- Arrows are utilized to move an item up and down the list so a customer can configure what they would like to appear in what order.
- When paired with selection controls the arrows are displayed to the right of the control.
Selection Controls
The widget configuration Selection Controls component can be used in a variety of ways and can be paired with other components such as the Text List and/or Reorder.
- Selection Controls can be paired with any other configuration component.
- Controls available for use are Radio Buttons, Checkboxes, and Switches.
- The color of the selection control cannot be altered.
Header
▢ Header should communicate representation of what the widget does or provides
▢ Follows font style, size and character limit
▢ Place the attribution logo only if the header overlaps with your brand attribution
Footer
▢ Footer can only be placed at the bottom of the widget
▢ Only one Footer Action button may be included in each widget
▢ All text should use Bookerly font
Widget Collections
▢ Widgets using the Widget Collections pattern should include Pagination dots
▢ Widget collections should hold a maximum of 5 pages to rotate through; this will allow for variety and flexibility of pages without becoming too lengthy for customers to browse and navigate through
Pagination Dots
▢ Use a scrim when the pagination dots is overlapping text in a widget, do not use a container
▢ If an Action Button is present the Pagination Dots will be placed below the button
Progress Bar
▢ Progress bar may only be placed at the bottom of the widget, if an Action Button is present it is placed above the Action Button
▢ Color for the progress bar fill is restricted to blue #2BBDD3
▢ Progress type is restricted to determinate progress bars to display the progression of an activity with a known duration
▢ Progress bars don’t display timestamps or durations and are not interactive
Transport Control
▢ Do not include other buttons such as pause, fast forward, or back
▢ Primary button sizing should follow official size specifications
▢ Button can be customized but make sure to meet the contrast of 4.5:1
Configuration Components
▢ It is optional to include configuration options for your Widget experience
▢ Configuration components include Text List, Reorder, and Selection Controls