Edit

Widget design fundamentals

This article provides guidance for designing a Windows widget's layout, sizing, color, and typography. Adaptive Card examples use host-rendered controls. Apply the same design principles to HTML web widgets, but verify their layout in the target host rather than relying on an Adaptive Cards Designer preview.

Widget sizes

A screenshot showing blank widget templates illustrating small, medium, and large sizes. A screenshot showing examples of small, medium, and large sizes for a weather widget. A screenshot showing examples of small, medium, and large sizes for a traffic widget.

Widgets support small, medium, and large sizes, as declared in the provider's manifest. Design for all three sizes when practical and adapt the content to each size. Large widgets can display more information, while smaller widgets should focus on the most important content or action. Supporting multiple sizes gives users flexibility when arranging their board.

Small and medium sizes provide better discoverability as they get surfaced more often within the dynamic feed.

Small

The widget principles glanceable and focused become more important in design decisions made for the small size widget. The small size widget should not try to force all of the functionality that could comfortably fit in a large widget. Focus on one user interaction or piece of key information that can be surfaced here with 1 touch target.

Medium

The medium size widget allows more room compared to the small, and so more functionality or additional information can be included. The medium widget could also provide the same focused experience as the small widget, but provide 2-3 touch targets.

Largeâ€Ŋ

Large sizes allow for more information to be presented, but the content should still be focused and easily consumable. Alternatively, a large size card could highlight one image or topic and have a more immersive experience. The large size should have no more than 3-4 touch targets.

Color and theming

Three example widget templates demonstrating the light theme. The first is an empty widget with a white backgronud. The second is an empty widget with a light gradient background. The third is a widget with an image background. All three have the word "text" in dark font to demonstrate the contrast with the light background.

Three example widget templates demonstrating the dark theme. The first is an empty widget with a black backgroud. The second is an empty widget with a dark gradient background. The third is a widget with an image background. All three have the word "text" in a light font to demonstrate the contrast with the dark background.

Windows 11 supports two color modes: light and dark. Each mode consists of a set of neutral color values that are automatically adjusted to ensure optimal contrast. For each widget size you support, make sure to create separate designs for light and dark themes so that the widget integrates seamlessly within the wider operating system and user's theme choice. The widget background supports customization with either a solid light/dark background, gradient tint, or image background.

Two widget examples side by side. The left example has a light gradient background and text in a light grey font. The image is marked with a red X to indicate that the low contrast makes the text unreadable. The right image has a light gradient background and text in a dark black font. The image is marked with a green check to indicate that the high contrast makes the text legible.

Two widget examples side by side. The left example has a highly saturated color background image and text in a dark font. The image is marked with a red X to indicate that the low contrast makes the text unreadable. The right image has a desaturated color background and text in a dark black font. The image is marked with a green check to indicate that the high contrast makes the text legible.

When choosing background colors, images, and content, make sure that there is enough color contrast to ensure legibility and accessibility.

The Web Content Accessibility Guidelines (WCAG) 2.0 level AA requires a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text. WCAG 2.1 requires a contrast ratio of at least 3:1 for graphics and user interface components (such as form input borders). WCAG Level AAA requires a contrast ratio of at least 7:1 for normal text and 4.5:1 for large text. Large text is defined as 14 point (typically 18.66px) and bold or larger, or 18 point (typically 24px) or larger.

Margins

A diagram of a widget with guidelines indicating the margins. Next to this is a diagram of a widget where the area inside the margins is colored blue to show the content area.

The illustrated default layout uses a 16px margin and reserves a 48px attribution area for the header. Keep regular content outside that area when using the default header. Where header customization is supported, a provider can set header to null to extend content into the header region, but that region isn't clickable. See Customize the widget header area.

In the illustrated layout, only pagination dots occupy the right and bottom margins. For examples, see Pagination.

Two widget examples side by side. The left image shows guide lines dividing the widget into three columns, illustrating 4 pixel gutters between the columns. The right image shows guide lines dividing the widget into three rows, illustrating 4 pixel gutters between the rows.

For widgets that use containers, the gutter between each element is 4px, and the containers should touch the edges of the margins. Your content should also use spacing and sizing values of Multiples of Four Px to achieve a clean, pixel perfect design across different screen resolutions.

You should also consult the guidance for spacing and gutters in Content design basics for Windows apps when designing your content.

Typography

Two strings of the phrase "The quick brown fox jumped over the lazy dog" side by side. The one on the right has a heavier font weight.

A table showing example text for different type elements of a widget. The table is recreated in plain text without the rendered appearance within the text below the image.

For accessibility, the following table presents the text of the table shown in the image above.

Example Size / Line height Adaptive cards formula
Caption 12/16 epx Small, Lighter
Body 14/20 epx Default, Lighter
Body (for hyperlinks) 14/20 epx Default, Lighter, Accent
Body Strong 14/20 epx Default, Bolder
Body Large 18/24 epx Medium, Lighter
Body Largest 18/24 epx Medium, Bolder
Subtitle 20/28 epx Large, Bolder
Title 28/36 epx Extra Large, Bolder

Use Segoe UI and the type ramp above for a consistent Windows widget presentation. The Adaptive Cards column gives the corresponding template properties; the target host controls their rendered appearance. For more information on creating widget templates, see Create a widget template with the Adaptive Cards Designer.

Two example widgets with the phrase "The quick brown fox jumped over the lazy dog" and the text "Hyperlink". The left image has dark text on a light background. The right image has light text on a dark background. The hyperlink text is blue in both images.

Use the default color associated with the widget theme for titles and body copy. You can use the subtle version of the default color to differentiate body copy, provided it maintains sufficient contrast. Reserve the accent color for hyperlinks in this design. Check the result in both light and dark themes in the Widgets Board.

Profile pictures

Four instances of a circular profile picture in descending sizes from left to right. The images are labeled "96", "48", "32", and "24".

If your widget includes showing user profiles (for example, a social media feed or stream) use one of the following allowed circle profile sizes: 96x96px, 48x48px, 32x32px, or 24x24px.

Tool tips

An image of a calendar widget showing a calendar appointment. The mouse cursor is hovering over the appointment subject line, which is truncated, and a tool-tip shows the full subject line.

Tool tips can be used when title text gets truncated in the widget. For best practices, text should fit neatly within the widget space and not need truncation however, that may not always happen depending on scenarios like language localization, system text scaling, or when quoting something (i.e. article title, name of a song). This does not apply to body text on a widget.

  • Last updated on