ios-hig
Apple HIG and Liquid Glass rules for the mobile app's iOS 26+ surfaces, mapped to our Expo stack. Use when choosing or reviewing an iOS control (pop-up or pull-down button, menu, context menu, sheet, toolbar, tab bar, segmented control), adding glass or blur, touching scroll edge effects, or aligning a screen with the HIG.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 852
- Forks
- 63
01 前言 Front Matter
- name
- ios-hig
- description
- Apple HIG and Liquid Glass rules for the mobile app's iOS 26+ surfaces, mapped to our Expo stack. Use when choosing or reviewing an iOS control (pop-up or pull-down button, menu, context menu, sheet, toolbar, tab bar, segmented control), adding glass or blur, touching scroll edge effects, or aligning a screen with the HIG.
02 资源文件 1
- 参考文档references/components.md9.5 KB
03 SKILL.md 正文
iOS HIG for the mobile app
Apple's Human Interface Guidelines decide which control an iOS surface uses and how it behaves; apps/mobile/DESIGN.md records what this app already decided; expo-ui, expo-router and expo-native-ui say how to build it. This skill is the bridge: HIG rules in our words, each pointing at the component we build it with.
Precedence. The platform's native design and components are the standard on both iOS and Android (DESIGN.md → Native first). A decision written in DESIGN.md (or an ADR it cites) wins over this skill. When the HIG disagrees with one, keep the shipped behaviour and name the drift in the PR, so a Human decides; never change it silently. Where DESIGN.md is silent, the HIG decides.
Steps
- Name the layer. Every element is either content (messages, rows, cards, media, backgrounds) or functional (bars, toolbars, the tab island, sheets, menus, floating buttons). Done when each new or changed element is assigned one.
- Pick the component from the decision table. Done when every interactive element maps to one HIG component and the choice is defensible from its row.
- Build it native first. Use the mapping in references/components.md: system navigation and
@expo/uiSwiftUI views before hand-drawn RN look-alikes. Done when no RN view imitates a control the system provides. - Apply the glass rules in Liquid Glass. Done when glass sits only on functional elements and every glass surface has its fallbacks.
- Check the platform split. Android follows Material 3 with its own native components (
@expo/uiJetpack Compose), perDESIGN.md→ Native first; no iOS look crosses to Android. Done when the Android branch of each change is named and uses the Material counterpart. - Review with the checklist, and capture light and dark screenshots for the PR as the project requires.
Decision table
| The user needs to… | Use | Not |
|---|---|---|
| pick one value from a short, mutually exclusive set, shown in place | pop-up button (a menu-style picker whose label is the current value) | a pull-down, a sheet of radio rows for ≤ ~7 options |
| switch between 2–5 peer views or modes, all visible at once | segmented control | a pop-up button (hides the options) |
| run one of several commands tied to one button's purpose | pull-down button (menu of actions; ⋯ "More" for secondary actions) | one pull-down holding every action on the screen |
| act on a specific item (row, message, attachment) | context menu on long-press, with the same actions reachable elsewhere | a context menu that is the only path to an action |
| choose among options that need explanation, a long list, or input | sheet (form sheet, detents, grabber) | a menu |
| confirm a destructive choice | confirmation (showAppDialog, a system alert on iOS) |
doing it straight from the menu item |
| move between top-level sections | tab bar (our tab island, ADR-0235) | tabs that trigger actions; a hidden or disabled tab |
| act on the current screen | toolbar items in the navigation bar | a row of tinted buttons in the content |
Pop-up versus pull-down is the common confusion: a pop-up shows state (its label changes to the chosen value; choosing is the whole interaction), a pull-down offers verbs (its label stays; each item does something). If the menu needs submenus, multiple selection or actions, it is a pull-down.
DESIGN.md → iOS menus and native controls adopts these rules: action menus are native pull-down and context menus, single choices are native pop-up menus, and system alerts are for confirmations only. It also lists the iOS screens not yet migrated.
Liquid Glass
Glass is the functional layer's material on iOS 26+. Its rules:
- Functional layer only. Bars, toolbars, the tab island and its +, sheets, menus, floating controls. Never rows, cards, bubbles or backgrounds. The one content exception: a slider or toggle may look glassy only while being dragged, which the system does for us.
- Few custom surfaces. System bars, sheets and menus get glass for free. Add
glassEffect/buttonStyle('glass')by hand only to the few app-owned floating controls that need it (today: the tab island, the + button, drawer tabs and the drawer title capsule). Glass on glass muddies the hierarchy. - Regular, not clear, unless the surface floats over photos or video; clear glass over bright media may need a ~35% dark dimming layer.
- Colour sparingly. Labels and symbols on glass stay monochrome; one prominent (tinted) action per view, coloured by its background, not its label. Keep the accent off most controls; selected tab, unread badge and the primary action are where it belongs. Check legibility at the resting scroll position.
- Separate controls from content with the scroll edge effect, not a painted bar background. Leave it on its automatic style; use it only where content scrolls under floating controls; one per view. The chat screen uses the native transparent header with the automatic top edge effect over a top-to-bottom (not inverted) list; an inverted list under a transparent header dims on iOS 26 (see
DESIGN.md, Chat). - Fallbacks ship with the glass: iOS < 26 → bordered/opaque
raisedsurface; Reduce Transparency → opaque (followDrawerMaterialinsrc/ui/primitives/drawer-material.ios.tsx); Increase Contrast → stronger edge; Reduce Motion → no morph; accessibility text sizes → an opaque rounded rectangle when text wraps inside a capsule. - Hit targets stay ≥ 44 × 44 pt however small the glass shape looks.
Native header recipes
Lessons from a production Expo 58 app with iOS 26 glass (t3code; notes in /mnt/project-files/t3code-design-ref/), checked against our stack:
- Transparent native header: leave the header
backgroundColorundefined. Any colour, even fully transparent, replaces the system material. - Edge blur needs automatic insets. Give the screen's scroll view
contentInsetAdjustmentBehavior="automatic"and keep the top scroll edge effectautomatic. A manualcontentInsetzeroes UIKit's adjusted inset, and the header blur disappears. - No hand-made glass on bar buttons. Declare header items (SF Symbol, stable identifier, native menu) and let UIKit draw their shared glass background. Adding
glassEffectto a bar item draws a second, thinner capsule. - Keep list and detail in one native stack so iOS 26 can morph the header and matching bar buttons between them; a nested navigator in between breaks the morph.
- No inverted list under a native header. UIKit dims and mis-blurs it, which is why the chat screen hides the native header (
DESIGN.md→ Chat). - Gate glass on capability, not only the OS version. With
expo-glass-effect, checkisGlassEffectAPIAvailable(); with@expo/ui, followDrawerMaterial. Fall back toexpo-bluror the opaqueraisedsurface, and pass the app'scolorSchemeexplicitly so glass follows the in-app appearance setting.
Review checklist
- Every interactive element maps to a row of the decision table; pop-ups show state, pull-downs offer verbs.
- Menus: title-case labels, most-used first, related items grouped, at most one submenu level, destructive items marked and confirmed, icons on all items of a group or none.
- Context-menu actions also exist somewhere visible (header, ⋯ button, or the accessibility actions).
- Sheets: grabber when resizable, swipe-to-dismiss (confirm when it would lose edits), Cancel/Close leading and Done trailing, never Done alone, one sheet at a time from the main UI.
- Tab bar: navigation only, always visible on top-level screens, labelled, never disabled.
- Glass only on the functional layer; every glass surface has the iOS < 26, Reduce Transparency, Increase Contrast and large-text fallbacks.
- At most one tinted primary action per view; labels on glass monochrome.
- Scroll edge effect automatic, only under floating controls, one per view.
- Drift from
DESIGN.mdnamed in the PR, not silently resolved.
Keeping current
Apple revises these pages around each WWDC and iOS point release (menus, scroll views and tab bars changed on 8 June 2026 for iOS 27). Each row in references/components.md links the HIG page and the change date this skill was checked against; when Apple's page shows a newer change-log entry, re-read it and update the row. Verify @expo/ui component and modifier names against the SDK 58 docs, not memory.
04 同仓库更多 Skills
slide-authoring
Technical reference for writing or editing open-slide pages — file contract, 1920×1080 canvas, type scale, layout, palette/visual direction, assets, speaker notes, stepped reveals, page transitions, and morph transitions. Consult this whenever you are about to write or modify any file under `slides/<id>/`, including from inside the `create-slide` or `apply-comments` workflows, or for any ad-hoc slide edit. Triggers on phrases like "edit slide", "tweak this page", "fix the layout", "change the palette", "reveal one by one", "add a transition", "morph transition", "write the speaker notes", "generate the script / talk track", "investigate the slide framework", "how do slides work here".
current-slide
Resolve which slide, page, and (optionally) selected element the user is currently viewing in the open-slide dev server. Consult this whenever the user references "this page", "this slide", "this element", "the slide I'm on", "the current page", or any deictic reference to slide content without naming it. Re-read `node_modules/.open-slide/current.json` at the start of every such turn — the user navigates between turns, so a value you read earlier in the conversation is almost certainly stale.
create-theme
Use this skill when the user wants to create, draft, author, or extract a slide theme in this open-slide repo. Triggers on phrases like "create a theme", "make a theme called X", "extract a theme from <slide>", "build a theme from these images". Produces two paired files under `themes/` — `<id>.md` (palette, typography, layout, fixed Title/Footer components, motion) and `<id>.demo.tsx` (a runnable demo slide that the dev-UI Themes panel previews). Do NOT use for editing real slides — only for authoring the theme bundle.
create-slide
Use this skill when the user wants to create, draft, author, or generate new slides / a presentation in this open-slide repo. Triggers on phrases like "make slides about X", "make a deck about X", "create a presentation", "draft slides for", "new slide", "a deck with speaker notes / a script", or when the user asks to add content under `slides/`. Do NOT use for editing the framework itself — only for authoring content inside `slides/<id>/`.
apply-comments
Apply pending @slide-comment markers written by the open-slide inspector tool. Use when the user asks to "apply comments", "process slide comments", "apply the inspector comments", or references markers left inside `slides/<id>/index.tsx`.
writing-shape
Writing, exploit: shape raw material into an article, paragraph by paragraph.