Design Guidelines

A panel in AR competes with the real world behind it: a moving camera image, bright windows, busy textures. What reads well on a flat screen can be hard to read on a panel two metres away. These guidelines give concrete values that work. They follow Apple's Human Interface Guidelines, translated into the units the UI editor uses.

The short version: few elements, generous space, large text, real contrast.

Know your viewing distance

Sizes in the UI editor are in points. Where the panel is decides what a point means:

• Screen space – a point is a point on the phone or tablet screen, exactly as in any app. Apple's iPhone and iPad sizes apply as they are.
• In the world – about 1360 points make one metre. That is close to the scale of an Apple Vision Pro window at its usual distance, so Apple's Vision Pro sizes work for a panel viewed from about 1–1.5 m.

Text has to grow with distance. A panel read from 3 m needs roughly twice the text size of one read from 1.5 m. Rather than retyping every size, scale the whole object up in the main editor: everything inside it grows together and keeps its proportions.

On an iPhone or iPad, a panel in the world is seen through a small screen, often from further away than people expect. Put text people must read – instructions, scores, critical labels – in a screen-space panel on handheld devices, and keep world panels for content that belongs to a place or an object. Per-device anchoring does both with one panel.

Sizing panels

Pick the panel size mode by what the panel does:

• Hug for almost everything. The panel fits its content, grows when a label gets longer, and works on every device without adjustment.
• Fixed when the panel must keep its outline – a scoreboard whose numbers change, a panel beside other content, or anything Scrollable.
• Fill only for screen-space panels that should cover the whole screen, such as a start screen or a pause overlay.

Inside a Hug panel, set the width through the content, not the panel: a Max Width on the main text block sets the panel's width, and rows set to Fill stretch to match it. A Hug panel with no Max Width anywhere grows to about 1 m before its text wraps.

Physical sizes for panels in the world, at 1360 pt per metre:

Panel	Width	About
Label or tag on an object	200–320 pt	15–25 cm
Info card	400–600 pt	30–45 cm
Large panel, read from a few metres	800–1000 pt	60–75 cm

Size for the distance, not for the screen you edit on. The UI editor's canvas shows the panel at screen size, which always looks larger than it will appear in the room. Check sizes in Preview on the device people will use, at the distance they will stand.

Screen-space panels have to fit the smallest screen. An iPhone in portrait is about 375 pt wide. Keep screen-space panels at or under about 340 pt wide (Hug with a Max Width, or Fixed), so they fit with a margin on every phone; iPad and Mac then simply show them with more room around them. On Apple Vision Pro, screen-space panels share a layer of about 730 × 540 pt, so design them to fit inside that.

Adapting per platform

A panel that works on a phone isn't automatically right on Vision Pro, and the other way round. Three tools, from simplest to most flexible:

1. Per-device anchoring. One panel, placed differently per device category: Handheld → Screen Space for a readable HUD on phones and tablets, Spatial → Position for a panel in the room on Vision Pro. Set it under Device Configuration in the object's anchor settings.

2. One panel per device category. When the layouts should really differ – a compact HUD on iPhone, a larger card with more detail on Vision Pro – build two panels and use Hidden in Device Configuration so each one appears only on its devices. Both can listen to the same events and show the same variables.

3. A script. A script can read the device category and adjust the panel before anyone sees it. Put a Run Script action on an On Will Appear event of the panel object itself:

// Object event on the panel: On Will Appear → Run Script
var panel = scriptContext.sourceEvent.objectEntity;

if (environment.deviceCategory === 'spatial') {
    // Apple Vision Pro: people stand further back, so the whole panel grows
    panel.scale = Vector3(1.5, 1.5, 1.5);
} else {
    // iPhone, iPad and Mac: keep it compact
    panel.representation.findView({ name: 'Details' }).isHidden = true;
}

environment.deviceCategory is 'handheld' (iPhone, iPad), 'spatial' (Apple Vision Pro) or 'desktop' (Mac). Scaling the object resizes everything in a world panel together; a screen-space panel ignores the object's scale. Showing and hiding views lets one panel carry a short and a long version of its content. See Find and update views for what a script can change.

Pick the hook that runs before the panel is visible. On Will Appear fires once the panel has loaded, before it is shown and before its Reveal Animation plays, so the adjustment is already in place when it appears. Two hooks look similar but cause problems:

• On Experience Start or a scene start event runs before the panel has loaded. Its views don't exist yet, so findView returns nothing and the change is lost.
• On Did Appear runs after the panel is on screen. The change is visible as a jump – the panel appears, then resizes or loses a row – and it fights the Reveal Animation.

The same applies to anything a script sets up on a panel: label text, bindings, on(…) listeners. Do it in the panel's On Will Appear.

Typography

Role	Size	Weight
Title	24–28 pt	Semibold or Bold
Body	17 pt	Regular or Medium
Secondary text, captions	13–15 pt	Regular or Medium
Absolute minimum	12 pt (11 pt in screen space on iPhone)	–

• Use two or three sizes per panel, not more. Hierarchy comes from a clear jump in size or weight, not from many small steps.
• One font family. System or Rounded suit most panels; add Monospaced only for numbers that change, like timers and scores.
• No thin weights. Regular is the lightest weight to use; small text often reads better in Medium or Semibold in AR.
• Keep lines short. Turn on Wraps Text and give body text a Max Width of about 400–560 pt. That keeps lines to a comfortable length (around 60 characters at 17 pt) instead of one long line across a wide panel.
• Emphasise with weight, not colour alone. **Bold** in a label is clearer than a coloured word.
• Uppercase sparingly. Text Transform → Uppercase works for short labels and section headings, not for sentences.

Contrast and colour

• Panels always render in dark appearance: light text on a dark, translucent surface. White and light grey text is the safe default.
• Aim for a contrast ratio of at least 4.5:1 for text up to 17 pt, and 3:1 for larger or bold text.
• Text needs a surface. Text on a Transparent panel sits directly on the camera image and becomes unreadable over bright or busy backgrounds. Put readable text on the System material or a Solid fill.
• Don't rely on shadows to rescue contrast; give the text a surface or a bolder weight instead.
• Don't use colour as the only signal. A selected state, an error or a correct answer should also change an icon, a label or a shape.
• Use one accent colour for the primary action, and keep the rest neutral.

Touch targets

Where	Minimum size of anything tappable
Screen space on iPhone and iPad	44 × 44 pt
In the world, and on Apple Vision Pro	60 × 60 pt

• A button's padding is part of its target, and padding is how you reach the size. With the default 8 pt top and bottom padding, a 15 pt title makes a button only about 34 pt tall. A 17 pt title with 12 pt top and bottom padding is about 44 pt; with 20 pt it is about 60 pt.
• On Vision Pro, keep the centres of neighbouring buttons at least 60 pt apart, with 16 pt or more between them, so people's gaze lands on the one they mean.
• Make the whole row tappable rather than a small icon at its end.

Spacing and padding

Use an 8-point grid: 4, 8, 12, 16, 24, 32. Values off the grid make a panel look slightly wrong even when nobody can say why.

Space	Value
Panel padding (around everything, on the root stack)	16–24 pt
Between items that belong together (a title and its text)	4–8 pt
Between groups (text block and buttons)	16–24 pt
Between buttons in a row	8–12 pt, 16 pt on Vision Pro
Inside a button or chip	8–12 pt vertical, 12–16 pt horizontal

• Whitespace is the structure. Group with space first; reach for Dividers and boxes only when space isn't enough.
• Never let content touch the panel edge. Always pad the root stack.
• Align to one edge. In a VStack, use one alignment – usually Leading for text, or Fill so rows share a width. Mixed alignments make a panel look unplanned.
• Equal buttons get equal widths: put them in an HStack with Fill Equally.
• Use a Spacer to push items apart, not a large fixed spacing.

Corners and surfaces

• Nested corners are concentric: an element inside the panel gets a radius of the panel's radius minus the padding between them. A panel with a 24 pt radius and 16 pt padding takes cards or buttons with an 8 pt radius.
• Pick one radius family per panel – for example 24 pt for the panel, 12 pt for cards, Capsule for buttons – and reuse it.
• One surface is usually enough. A System panel with flat content reads better than a panel full of shadowed cards. Use a card (a stack with Fill, Shape and Shadow) only to set one group apart.
• Prefer translucent surfaces over large opaque ones in the world: an opaque wall of colour blocks the view and feels heavy. Use Solid fills for small elements – buttons, badges, chips.

Where to put UI in AR

• Keep the camera view clear. On iPhone and iPad, put a screen-space HUD at an edge or a corner and leave the centre of the screen to the scene.
• Show only what is needed now. Split a long flow into steps and show one panel at a time with Add to Scene and Remove from Scene, rather than one panel that holds everything.
• Keep words few. People in AR are looking at the world, not reading. A title and one or two short lines usually do.
• Face the viewer. Give text panels in the world the Billboard alignment so they stay readable from an angle, and place them at about eye height.
• Don't make people move to use the UI. Controls they need often belong in screen space or within comfortable reach, not across the room.
• Mind the 50-view limit. A panel that needs more than a few dozen views is usually several panels.

A worked example

An info card placed next to an object, read from about 1.5 m:

Panel       Size Hug · Material System · Corner Radius 24
└── VStack  alignment Leading · spacing 16 · padding 24 · Max Width 480
    ├── VStack  alignment Leading · spacing 4
    │   ├── Label  "Lounge Chair"            Font 28 pt Bold
    │   └── Label  "Oak and wool, 2026"       Font 15 pt Medium, light grey
    ├── Label  "Hand-finished in Berlin …"  Font 17 pt Regular · Wraps Text
    └── HStack  distribution Fill Equally · spacing 16
        ├── Button  "Colours"   Style Primary · Shape Capsule · Font 17 pt Semibold · padding 20 / 24
        └── Button  "Details"   Style Secondary · Shape Capsule · Font 17 pt Semibold · padding 20 / 24

(Padding 20 / 24 means 20 pt top and bottom, 24 pt leading and trailing.)

Three text sizes, one family, 16 and 24 pt spacing on the grid, 60 pt buttons, and nothing touching the edge.

Checklist

Before you finish a panel – and when an AI agent builds one – check:

• [ ] The root stack has 16–24 pt padding and nothing touches the panel edge.
• [ ] All spacing and padding values are on the 8-point grid (4, 8, 12, 16, 24, 32).
• [ ] Body text is 17 pt or larger; nothing is under 12 pt; no Thin or Light weights.
• [ ] There are at most three text sizes and one font family.
• [ ] Long text has Wraps Text on and a Max Width of about 400–560 pt.
• [ ] Every tappable view is at least 44 pt (screen space) or 60 pt (world, Vision Pro) in both directions.
• [ ] Readable text sits on a System or Solid surface, not directly on a Transparent panel.
• [ ] Groups are separated by space, and items within a group sit closer together than the groups do.
• [ ] Nested corner radii are concentric, and one radius family is used.
• [ ] Buttons that belong together have equal widths (Fill Equally).
• [ ] The panel size suits its distance: world panels follow the size table above, screen-space panels are at most about 340 pt wide.
• [ ] Each device category gets a placement that suits it (Device Configuration), checked in Preview on the real device.
• [ ] Scripts that set up the panel run from its On Will Appear event, not from the scene start or On Did Appear.
• [ ] The panel shows only what is needed at this moment, in as few words as possible.
• [ ] Views that events or scripts use have a Name.