Design notes
Layout rules
All sizes are in points on the 844 × 390 pt reference screen (iPhone 12 to 14 in landscape). Other phones scale from it; see "Scaling" below.
Thumbs cover the bottom corners (AGENTS.md). In landscape the player holds the phone with both hands, and the thumbs rest about a fifth of the way in from each side, low down.
- Thumb corners: the bottom-left and bottom-right 190 × 156 pt (22% of the width, 40% of the height). Nothing fixed goes there: no buttons, no text you need to read, no status. Scrolling content (a list, a page of notices) may pass under them, as long as nothing in it can only be reached there.
- Stage: x 190–654, y 0–234. What the screen is about and its primary action go here.
- Top rails: the top-left and top-right corners inside the safe area. System actions live here, the same on every screen: Back top-left, Close top-right, and in the field the objective tracker (top-left), Map and Pause (top-right). A thumb reaches them with a stretch, which suits actions used now and then.
- Between the thumbs: x 190–654 below the stage. The dialogue box, captions and secondary actions. Choices, quest text and the main button stay in the stage.
- Drawing zones: in battle, field casts and practice, the whole lower half on each side of the centre line is where each thumb draws. UI drawn there must ignore touches (today
UiScale.Block/IsBlocked; VEL-72 wires UI Toolkit into the same rule).
Safe area and the sensor housing. Velan runs in both landscape orientations (allowedAutorotateToLandscapeLeft and Right are on), so the notch or Dynamic Island is on the left or the right depending on how the phone is held, and layouts must mirror cleanly. The reference phone's landscape insets are 47 pt left and right and 21 pt at the bottom (the home indicator); Dynamic Island models use 59 pt left and right. Always read Screen.safeArea at run time and never hard-code these numbers. Backgrounds, world views and scrims run to the screen edges; content and touch targets stay inside the safe area, plus a 12 pt margin.
Touch targets. At least 44 × 44 pt (Apple's minimum), with 8 pt between targets. Primary buttons are 48 pt tall. The visible shape may be smaller than the hit area, but the hit area never is. Today's IMGUI canvas is 540 units tall, so 44 pt is 61 to 64 units depending on the phone.
Type. Body text at least 15 pt and captions at least 12 pt at the Standard text size. Every screen must still lay out at the largest text size (section 6, Accessibility), with lines wrapping, not cut off.
Scaling. For UI Toolkit (VEL-72): PanelSettings scale mode "Scale with screen size", reference resolution 844 × 390, match height. A taller or wider phone then gets more room at the sides, not bigger buttons, and 44 pt stays 44 pt on every iPhone in landscape.
Layers (one UIDocument each, as VEL-72 plans): HUD, screens (a stack), modal, toast, and the fader above everything. A modal blocks every layer under it. Screens in the menu pause the game (Time.timeScale = 0); the HUD and toasts never do.
Navigation. Back (top-left) pops the stack, and Close (top-right) leaves the whole menu and resumes play. There are no edge swipes, because they fight with drawing. Every screen that changes something saves at once; there are no Save buttons, except Save and quit.