Design

• Derive From User Value
• Balance And Direction
• Explore Before Committing
• Compression And Framework
• Choose Form
• Widget Layout
• Layout Rules
• Visual Design
• Implementation Notes

Derive From User Value

Use this order for functional widget design:

known user situation and concrete problem
→ limited value the widget can provide
→ indispensable information or action relationships
→ compression
→ visual framework
→ content and implementation

Use premises already established by the user, project, or available evidence. A feature name or visual reference alone does not establish the user's situation or the value of a particular layout. If a missing premise would determine the design, ask for it before committing dependent choices. Keep proposed scenarios and solutions explicit as hypotheses; do not invent them to keep the design moving.

Limit the claimed value to what the widget can actually deliver with its known data and interactions. Identify what the user needs to learn or do in the current state before selecting fields. Remove information that does not contribute to that result. Compression may change the unit of description and eliminate work entirely; it does not mean shrinking a complete interface until it fits.

Form follows function: use the user's familiar mental model of the function to choose forms that make its relationships easier to understand. State which relationship the form helps the user recognize. Familiarity with a visual category alone does not establish that connection.

An explicitly requested visual study, reproduction, or decorative widget can have visual expression as its purpose. Honor that scope without inventing a utility function. When only a visual direction is known, study its evidence provisionally; do not lock a functional layout and later choose a purpose that fits it.

Balance And Direction

Imbalance creates contrast, information, and direction. Ask what the user gains by following each prominent direction. A direction that leads to nothing useful invites an unnecessary act of attention and can make following it feel mistaken.

When no information needs to be communicated in a relationship, that absence is itself a functional condition: use balance to avoid introducing an unhelpful contrast or direction. Preserve tension where a difference conveys something worth recognizing. Balance does not require absolute symmetry or uniformity across a widget that has meaningful differences.

Check this at each relevant scale. The widget may need to stand out as one whole in its surroundings while keeping internal regions quiet. Low-difference whitespace gives the primary relationship room to be read; do not fill it merely because space remains.

Explore Before Committing

Keep explicit user requirements fixed. Explore candidate forms for the established value and indispensable relationships, with the actual widget family, size, available data, and state changes as constraints.

First sketch the framework using areas, position, direction, contrast, and whitespace. Keep text, numbers, and decoration out of this first structural pass, while deriving it from the already-known content needs. Then insert representative content to test meaning, reading, and fit. If content invalidates the framework, revise the framework.

For reference-led work, use Reference to distinguish observed traits from traits required by the current task. A reference constrains appearance to the degree requested; it does not establish a new user need.

Keep candidates provisional until a real preview passes the applicable review gates. Check the value, truthful data, and state model before committing the visual direction. A successful composition cannot validate an invented function. If the form conflicts with an established function, revise the form; if evidence challenges the premise, revisit that premise explicitly.

Compression And Framework

After the value is established, keep only the differences needed to produce it. Do not begin with a complete interface and make every part smaller. Change the unit of description when that lets low-priority information and work disappear entirely.

Map:

limited product value
→ indispensable information or action relationship
→ the states in which that relationship changes
→ area, position, direction, contrast, and whitespace

Draw this framework before adding content. A frame, container, icon, color change, type change, gap, offset, or ornament creates a difference. Add it only when that difference helps express the indispensable relationship or an explicit visual purpose. Several facts may read continuously when the user does not need to compare or act on them separately. Separate them only when the function requires that separation.

The framework should remain intelligible without finished copy or decoration, but it is not an autonomous composition. Its relationships come from the content it will carry. If representative content disproves the framework, revise it.

Choose Form

Choose forms from the function's mental model and the relationship being expressed. Record the connection plainly: what the form represents, what direction it creates, and what the user obtains by following that direction. A visual role such as hierarchy, grouping, rhythm, material, or emphasis describes what a form does inside the composition; it does not establish why the form should exist.

Use style and references within this boundary. Preserve visual properties the user explicitly requests, and select other properties only when they express the established relationship. Do not invent a theme, object, era, culture, or narrative to make a sparse framework feel complete.

When the user explicitly asks for a visual reproduction or decorative result, visual recognition or expression can be the function. State that scope and judge the form against it. Do not attach an invented utility story.

Use Object-Like Design only when an object is requested or its mental model makes the function easier to understand. Lock a direction only after its premises and actual-size preview pass Review.

Widget Layout

Widget Size

Size is the first layout constraint. Widgets are much smaller than app screens, so the view must be designed for the widget's actual dimensions. Information can use smaller type than it would in an app, leaving more space for the primary content.

Widget views are responsive, but most widgets do not need to support every size variant. Use widgetFamilies in Await.define to declare the sizes the widget supports.

Widget size values use iOS logical points pt.

Use the runtime size parameter as the source of truth for layout. Both widget() and widgetTimeline() receive parameters that include the widget size.

Use the numbers below for design intuition, not as layout constants. Actual dimensions may vary by device, OS version, and preview context.

Common Layouts

Common widget families follow a unit-and-spacing grid. As a rough reference, unit is about 170 pt and spacing is about 20 pt.

Size	Grid	Approx. dimensions	Notes
small	1 x 1	170 x 170 pt	-
medium	2 x 1	360 x 170 pt	-
large	2 x 2	360 x 360 pt	-
extraLargePortrait	2 x 3	360 x 550 pt	Requires iOS 27 or later
extraLarge	4 x 2	740 x 360 pt	iPad and Mac only

The rough dimensions come from this grid formula:

width  = columns x unit + (columns - 1) x spacing
height = rows    x unit + (rows    - 1) x spacing

Each additional row or column adds one unit and one spacing, except for the first unit.

Size Composition

The unit-and-spacing grid suggests natural relationships between widget sizes, but these relationships are design options, not rules. When two families share a dimension, one layout may extend or focus the other. Use this approach only when the content composes naturally; otherwise, design each size as a distinct view of the same subject.

• small and medium share height. medium is roughly small plus one extra width unit — when the content composes well, small can read as the focused portion of medium.
• medium and large share width. large is roughly medium plus one extra height unit — when the content composes well, large can extend medium downward with secondary content.
• small and large are more loosely related. Prefer shared components, content vocabulary, and visual identity over literal layout reuse.
• extraLargePortrait and extraLarge continue the same idea with even less obligation to mirror smaller layouts.

Special Layouts

These layouts do not follow the unit-and-spacing grid.

Size	Description	Approx. dimensions
accessoryInline	Lock Screen inline text	342 x 36 pt
accessoryCircular	Lock Screen circular widget	58 x 58 pt
accessoryRectangular	Lock Screen rectangular widget	148 x 58 pt
fullscreen	Full-screen preview inside the Await app	-

For accessoryInline, only the first Text is rendered.

Layout Rules

Fill the Root View

The widget size represents the available layout space for the widget itself.

Unless you intentionally want transparent margins around the widget, the root view returned by widget() should fill the entire widget area.

For example:

<ZStack maxSides background={color} />

or

<ZStack>
  <Color value={color} />
</ZStack>

or

<ZStack>
  <Image url={image} resizable aspectRatio='fill' />
</ZStack>

Since the widget size is available as the size parameter, you can also write:

<ZStack frame={size} background={color} />

This also fills the entire widget layout.

Account for Every Inset

Every inset should be added deliberately and serve a clear design purpose. Distinguish accidental stack spacing from low-difference space that avoids unnecessary direction; unused area is not by itself a layout error.

Stacks center undersized content by default, so unallocated space can quietly turn into gaps around the content.

When content extends to the widget edge and clipping it to the widget boundary and corners does not compromise information, interaction areas, or the recognizability of the subject, let the outer widget perform the clipping. Do not unconsciously add another layer of inset or corner radius.

Widget Corners

Widgets are rounded rectangles. The exact corner radius can vary by system version and device. As a reference, widget corner radius on iOS 26/27 is 86 / 3 pt.

Interior views near the widget edge usually look more natural when their corners are concentric with the outer widget corner:

const cornerRadius = 86 / 3 - padding;

Stack Views

VStack, HStack, and ZStack center their children as a group by default.

Use the alignment prop to control alignment between children. Use the alignment value in the frame modifier to position the whole child group inside its container:

frame={{width: ..., height: ..., alignment: ...}}

Use offset for visual displacement, not for layout alignment.

Avoid placing offset and scaleEffect on the same view layer, because that makes layout mistakes more likely.

Aspect Ratio

aspectRatio sizes the view content before the modifier into the view container after the modifier. Modifier order therefore matters.

When an image should fit or fill a specific frame, put aspectRatio before frame, and append a clipped modifier to avoid image overflow:

<Image url={image} resizable aspectRatio='fill' frame={{width: 120, height: 80}} clipped />

Do not put the target frame before aspectRatio:

<Image url={image} resizable frame={{width: 120, height: 80}} aspectRatio='fill' clipped />

When an image view is set to resizable, it automatically fills all available space. For setting a background image, use the following syntax:

<Image url={image} resizable aspectRatio='fill' />

Visual Design

Contrast And Separation

Keep important content distinguishable from its surroundings, especially text. Do not place same-family text over a same-family background with similar brightness.

Do not add layers merely to make the widget look richer. Add a surface, frame, foreground element, shadow, or texture only when it carries content or defines grouping, construction, occlusion, interaction, or an established visual requirement.

Element Roles

For every visible element, trace its role back to the established value, necessary information or action, or explicit visual requirement. Ask what would be lost if it were removed. A label such as grouping, material, lighting, or visual subject is not sufficient by itself.

Remove an element when no required relationship or requested visual property depends on it. For example, a shadow can explain a raised panel, but that does not explain why the panel should exist. Check the panel's necessity before refining its shadow.

Typography

Derive typography from the actual information hierarchy. Give two text elements different size, weight, design, or color only when the distinction helps users interpret their roles. Do not add expressive, data-like, or micro-text categories solely for visual variety.

Typography can group several facts into one continuous language object. Preserve adjacency and reading flow when the facts form a natural statement; use emphasis inside the flow without accidentally splitting every value or phrase into its own visual unit. Keep facts separate when users need to compare, scan, or act on them independently.

Do not use the fontWidth modifier unless the user explicitly requests it. It imposes a strong, conspicuous visual character, so never treat it as a routine fitting or hierarchy tool. When uncertain, omit the modifier.

Since widgets have limited space and text is often constrained by the layout, prefer minimumScaleFactor={0.1} or minimumScaleFactor={1 / fontSize} for informational text that must remain visible. This makes it practical to start with a larger font size and let the system shrink it only when space becomes tight.

The fontDesign modifier supports default, rounded, serif, and monospaced. Custom fonts are not supported directly, but text can be converted into image or SVG assets instead.

Copy And Meaning

Use primary copy to explain what the widget shows, what state it is in, or what the user can do. When several facts form a natural statement, write and lay them out as one continuous expression instead of assigning each fact a separate label and container. Keep atmospheric or branded wording secondary unless the primary meaning is already obvious from the content itself.

Use system-known facts without inferring the user's location, feeling, progress, or outcome. Keep optional advice distinguishable from facts and preserve the user's choice. Add secondary or microcopy only when it contributes necessary information the primary content cannot carry. Do not let evocative wording replace basic meaning. Read the copy without the artwork; if its purpose becomes unclear, revise the hierarchy.

Users usually know which widget they added, so a title is usually unnecessary. Add one only when it clarifies content the user must see or when it has a necessary informational or construction role.

Emoji As Content

Use emoji only when they encode content such as a state, category, or value, or when the user explicitly requires them. Do not add them as generic accents. Emoji render as fixed, full-color glyphs and cannot be tinted to match the widget palette.

Reference Strategy

Use a physical object as a design reference only when the user authorizes it or the brief independently selects it. Study the relevant construction, proportion, material, or information relationship; do not copy the object's category or add its characteristic parts by default.

Use implementation examples to learn API usage, interaction behavior, data mapping, and layout relationships. Do not inherit their visual style unless the user requested it or the brief independently supports it.

Use photographs or physical references to study construction, proportions, materials, highlights, shadows, and edge behavior. Compare multiple references when lighting or perspective may distort the result.

Use Reference before implementing from visual references and Review after capturing the real widget preview.

Separate these questions before implementing:

• How is it built? Answer with runtime declarations and implementation examples.
• How should it look? Answer with fixed requirements, structural and compositional decisions, and authorized visual references.

Structural Realism Before Surface Effects

Use physical or material construction only when it serves an established functional relationship or explicit visual requirement. Then build the chosen metaphor from its construction logic. Establish thickness, overlap, insets, edge exposure, concentric radii, and contact with neighboring surfaces before adding gradients, highlights, or shadows.

Use each nested layer to represent a distinct surface or structural transition. Keep the number of layers minimal, but do not ask one flat surface effect to imply missing geometry.

Treat gradients and shadows as consequences of the structure. Do not use a bright strip, a strong gradient reversal, or a large shadow to compensate for absent thickness or unclear layering.

Material And Lighting Model

When material rendering is part of the chosen form, choose an implied light direction, softness, and environmental hue. Apply that model consistently across surfaces.

• Place highlights on surfaces and edges that plausibly face the light.
• Place the brightest and darkest gradient stops where the material would actually receive or lose light.
• Keep a single material within a coherent hue family unless a reflected color has a physical source.
• Tint shadows with the environment when pure black would disconnect them from the palette.
• Make cast shadows describe separation and contact; make surface gradients describe material and orientation.

Avoid isolated highlight lines that do not follow an edge, bevel, or curvature. Prefer integrating a highlight into the surface gradient when the reflection is broad, and use a separate highlight view only when the material produces a genuinely sharp reflection.

Building Visual Metaphors

Material Or Image Assets

Use a texture or image asset when the surface evidence, illustration, or protected reference primitive genuinely requires one. Establish the structure first; an asset should render an intended surface or subject, not conceal missing geometry. See Resources for sourcing, licensing, and project storage.

A texture can be used as an image layer with a mask, so the material appears only inside the masked shape. It can also be overlaid above the main view with a source-atop style blend mode, so the texture is applied only over the visible content below it.

When the asset is a photo or illustration, it can be loaded directly into the view tree as a background or content layer.

Basic Shapes

Use basic shapes for simple graphic construction and for object-like surfaces whose geometry remains legible with a small number of layers. Use SVG or image assets when dense geometry or surface evidence would otherwise require a large view tree.

Do not accumulate basic shapes solely to simulate richness. Each layer should express a surface, boundary, relation, or piece of information that survives at actual size.

For a protected reference primitive, follow the substitution decision in the visual-primitive inventory before choosing basic shapes.

Implementation Notes

Animation Stability

Widget views render from entry content. iOS WidgetKit automatically computes the view tree diff between two rendered entries. Property interpolation works only when the target view stays at the same position in the view tree and keeps the same id value, or when both old and new id values are empty. Otherwise, WidgetKit treats the old and new views as unrelated.

Buttons

Use FullButton to quickly create a transparent tappable area that fills the available space.

Use Button when it has a child view to display. Use a custom buttonStyle to define its normal and press states. See the Widget Button guide for setup and platform constraints.

Conditional And Repeated Layout

Use transparent or layout-neutral views for positions that should occupy space without drawing content. Do not use a visible shape as a spacer or placeholder.

Inspect both populated and empty branches in repeated layouts. A mapping can be mathematically correct while an empty branch still renders an unintended fill, hit area, or alignment artifact.