Bottom sheet

Problem Context

• The user is on a mobile screen where the current background context still matters.
• The extra content is contextual, temporary, and easier to use from the bottom edge than in a centered dialog or side panel.
• The sheet may need peek, half, or full heights so users can inspect more detail without losing orientation.
• The product can define scrim behavior, background interaction, gesture handling, focus movement, and safe-area spacing.

Selection Rules

• Choose bottom sheet when contextual details, options, or controls are best reached from the lower edge of a mobile viewport while the background remains useful for orientation.
• Use sheet when the surface is a broader temporary child task that does not depend on bottom-edge anchoring or mobile detents.
• Use drawer when side placement and comparison with a list, table, or chart matter more than thumb reach.
• Use bottom navigation when the bottom surface contains persistent top-level destinations rather than temporary contextual content.
• Use action menu or menu button when the user only needs a short command list near the trigger and no preview, grouping, or detent behavior.
• Use modal dialog or alert dialog when the user must focus on a compact blocking task or urgent response and bottom reach is not the deciding factor.
• Use a full page when the content needs deep reading, multiple steps, route history, saved progress, or durable sharing.
• Use a standard bottom sheet only when background interaction remains intentional; use a modal bottom sheet when background changes would conflict.

Required States

• Closed state with a trigger tied to the current map item, feed card, route, media item, or contextual action.
• Peek state that shows a meaningful title, summary, or first action rather than only a handle.
• Half or medium state that exposes the common controls while leaving enough background context visible.
• Full state for detailed review or longer lists, with clear scroll boundaries.
• Dragging or resizing state that makes the target detent understandable and does not conflict with inner scrolling.
• Modal state with scrim, background inactivation, focus containment, and dismissal behavior.
• Standard state where background content and sheet state remain intentionally coordinated.
• Dismissed or collapsed state that preserves the selected background object and returns focus or touch target context.

Interaction Contract

• The sheet enters from the bottom edge and remains visually attached to that edge or device safe area.
• The drag handle, title, and first visible content explain why the sheet appeared.
• Each detent has a useful purpose: peek for identity, half for primary controls, and full for details or list scanning.
• Drag gestures, inner scrolling, and swipe-to-dismiss have explicit priority rules.
• The sheet does not cover persistent bottom navigation or critical device safe-area controls without replacing them intentionally.
• Modal bottom sheets use a scrim and prevent background changes until dismissed.
• Standard bottom sheets keep background interaction meaningful and synchronize selected objects or map/feed state.
• Closing, collapsing, saving, selecting, scrim tap, Escape, and back all return users to the correct background object or control.

Implementation Checklist

• Define whether the sheet is modal or standard and which background controls remain usable.
• Define allowed detents, default detent, expansion limits, and what content appears at each height.
• Provide a visible handle when the sheet can be dragged and a close route when dismissal is allowed.
• Keep primary actions visible above safe-area insets and outside ambiguous scroll traps.
• Decide when dragging moves the sheet, scrolls inner content, changes detent, or dismisses the sheet.
• Preserve selected map pins, feed cards, media items, or route context while the sheet opens and closes.
• Use scrim, inert background, focus containment, and focus return for modal sheets.
• Test one-handed reach, small screens, landscape, keyboard appearance, screen reader order, reduced motion, and large text.

Common Generated-UI Mistakes

• Using a bottom sheet as hidden global navigation or a dumping ground for unrelated commands.
• Opening a bottom sheet at a height that hides the map, feed, or object the user needs for context.
• Providing a peek state with no meaningful content.
• Letting sheet dragging fight inner list scrolling.
• Covering bottom navigation, home indicator, or primary actions without safe-area treatment.
• Putting long multi-step workflows into a bottom sheet with no route, progress, or save recovery.
• Relying only on swipe gestures for close or resize without accessible controls.

Critique Questions

• What background context must remain visible when this bottom sheet is open?
• What useful content appears at peek, half, and full heights?
• Should the sheet be modal, or can users keep interacting with the map, feed, or media behind it?
• When the user drags inside the sheet, does the gesture move the sheet, scroll content, or dismiss it?
• Does the sheet collide with bottom navigation, safe areas, keyboard, or primary actions?
• Would a regular sheet, drawer, modal dialog, action menu, or full page better match this content?