Design Guide: Layout and Rendering
How Alexa renders your payload
Alexa renders your UI payload as large as possible within the device canvas, and natively applies CSS scaling to adaptively fit your content inside the native viewport. You don't need to design for specific device dimensions. Alexa handles sizing for you.
Viewport types
Two viewport types scale your design programmatically across Alexa device classes.
- Block viewport. Scales and scrolls horizontally. Recommended for native Alexa+ designs.
- Card viewport. Scales and scrolls vertically. Primarily intended for web interfaces. For Alexa screen-based devices, adapt Card patterns to Block treatments where possible.
Orientation determines viewport
- Designs that are taller than they are wide render as a Card.
- Designs that are wider than they are tall render as a Block.
You don't need to design for specific breakpoints. Alexa snaps your viewport to an established grid, then applies CSS scaling to each component.
How your widget learns its surface
Alexa tells your widget what surface it's running on, so you don't need to guess from viewport dimensions.
At render time, the host delivers a hostContext object to your widget over the MCP Apps postMessage channel. It contains: deviceClass, maxWidth, maxHeight, isMobile, platform, displayMode, safeAreaInsets, deviceCapabilities, and theme.
Resolve once, at render time. Map hostContext to a single breakpoint and put the result on your root element as a CSS class. Let CSS handle the rest.
Re-adapt on host-context-changed. The host re-sends context when the surface changes, such as a device rotating, or a customer's focus moving between surfaces. Re-resolve on that event. No page reload and no additional tool calls are needed. The MCP wire is identical across surfaces.
deviceClass is authoritative. When present, it wins outright. Treat maxWidth and displayMode heuristics only as a best-effort fallback for hosts that omit it, and surface a dev-time warning rather than silently degrading.
Keep your surface list a single source of truth. One place for all breakpoints means a new device class is a single edit.
Runtime envelope
Your UI payload runs in a sandboxed environment. Treat it as an isolated, opaque-origin document, not a regular web page.
Sandboxed iframe. Don't rely on window.parent access, cross-origin reads, or persistent localStorage or cookies. The frame may be an opaque origin; storage and cross-origin assumptions are the wrong foundation (and a potential security issue).
The postMessage bridge is the only channel to the host. Communicate with the host exclusively through the provided bridge (ui/notifications/*). Don't attempt ad-hoc parent access.
Declare your network destinations. Your payload's CSP (set in _meta.ui.csp) controls what your widget can reach over the network:
connectDomains— domains your widget fetches from (XHR, fetch, WebSocket), for example, map tile serversresourceDomains— domains your widget loads images or media from
Alexa blocks anything not declared. Keep both lists minimal and limited to what you own.
UI payload packaging
Your UI payload is fetched by the host and, ideally, cached. Its weight directly affects first render time. Even if your tool calls are fast, a heavy payload re-fetched on every turn is a latency and cost problem.
Ship as one self-contained bundle. Package your widget as a single HTML file with all dependencies inlined or co-located. A self-contained bundle is simpler to cache and version.
Version your resource URI with a content hash. Use a URI that includes a hash of the file contents — for example, ui://…/widget-a3f9c12b.html. A cached host serves the cached version automatically and busts the cache only when the hash changes.
Compress the response. Gzip your bundle before serving it. A widget that is several megabytes uncompressed should compress to a fraction of that.
Lazy-load heavy dependencies. Don't bundle a map library or charting library into the initial payload if most views don't use it. Load it only for the views that need it, so the common case stays fast.
Device support
By default, your MCP add-on is available on all devices that support Alexa+, with no device-specific targeting required. Your add-on will be evaluated for equal functionality, quality, and performance across all supported devices.
Before you test on hardware, use a surface simulator. The Local Inspector is a standalone tool that emulates the Alexa host environment locally. It synthesizes hostContext per device class, drives the MCP Apps postMessage bridge, and renders your widget in a device bezel with light and dark mode switching. You can use it to check most layout and scaling issues before you ever touch a device. Use it to iterate quickly across surfaces: mobile, Echo Show 8, Echo Show 15, and voice-only in a single session. The simulator is a pre-hardware iteration loop, not a replacement for on-device verification. Final testing must happen on real devices. See Testing your add-on CX for the on-device testing checklist.
We recommend testing on a representative set of real devices yourself, including mobile, web, voice-only, and Echo Show devices. Verify on each device that your experience renders cleanly, remains navigable, and allows the customer to complete the same tasks. Test both light and dark mode. Look for text truncation that renders content unintelligible (too much information cut off), and buttons that fall below the minimum touch target (see also Accessibility).
Related topics
| Go back to: Display Modes | Next: Visual Foundations |
Last updated: Jul 21, 2026
