Stay In Context Workflows

Overview

One of the strongest interaction patterns in this platform is to let users finish related tasks without losing their place.

We refer to this as staying in context.

Instead of forcing navigation away, the UI should often let users:

• create a missing related entity inline
• change a status or category inline
• configure a nearby dependency inline
• add a missing option directly from a search-first field
• finish a small guided workflow within the current surface

This principle reduces friction, preserves context, and helps users complete work without detouring through unrelated screens.

Core Rule

When a user encounters a missing or related dependency during a workflow, prefer solving it in context rather than forcing them to navigate away, as long as the side task is still appropriately small and local.

Good Fits

Use a stay-in-context pattern when the related task is:

• closely tied to the current workflow
• small enough to understand locally
• low or moderate in complexity
• needed to unblock the current action
• easier to complete while the user still remembers why they need it

Examples:

• changing a deal status inline
• creating a missing category from a category selector
• creating a missing entity during an import flow
• choosing and lightly managing related options from the current screen

When It Does Not Fit

Do not keep the user in context when the side task:

• is large enough to deserve its own workspace
• needs broad surrounding context
• is high-risk or destructive
• would overload a small surface like a popover
• requires many independent steps or branching paths

In those cases, escalate to a Panel or a dedicated page.

The Escalation Ladder

Choose the lightest pattern that keeps the user moving:

1. Inline controls
   For tiny changes directly in the current layout.

2. Popover or InlineEntityManager
   For nearby pick/create/manage tasks anchored to the current control.

3. AutocompleteSelect with add-new or modal handoff
   For search-first form selection where the user may need to create a missing option without leaving the form.

4. GuidedFlow in a Modal
   For multi-step but still local workflows.

5. Panel
   For richer contextual workflows that still should not force page navigation.

6. Dedicated page
   Only when the task is too large or independent to stay local.

Overlay rule:

• do not open another Modal on top of a modal-based workflow
• do not open a Panel on top of a modal-based workflow
• Modal may open on top of a Panel, but not the other way around
• anchored floating UI such as Popover, Menu, Picker, and Tooltip is still allowed inside the active surface because those are local control-level layers, not major overlay surfaces

Primary Components For This Pattern

Representative Platform Examples

Inline Status Management

Change a related entity value directly from the current surface instead of navigating to a settings area first.

<InlineEntityManager.Root placement="bottom-start">
  <InlineEntityManager.Trigger>
    <InlineEntityManager.Badge
      color={getDealStatusColor(selected)}
      iconId={getDealStatusIcon(selected)}
      label={getDealStatusLabel(selected)}
    />
  </InlineEntityManager.Trigger>
  <InlineEntityManagerDefault
    headerTitle="Change Status"
    headerIcon="CircleHalfFill"
    entities={statusEntities}
    selectedIds={[selected]}
    onToggleEntity={(status) => onSelect(status.id)}
    withSearch={false}
  />
</InlineEntityManager.Root>

This is the strongest current example of a compact in-context management flow.

Search-First Add New

AutocompleteSelect can also support this pattern when the user is already in a form and the missing option can be created directly or through a local modal handoff.

That is still a stay-in-context workflow because the user does not have to abandon the current task just to satisfy a related dependency.

Create Missing Related Entity During A Workflow

If a required entity is missing, let the user create it from the current flow instead of abandoning that flow.

The current franchisee import flow demonstrates this principle: the user chooses the franchisee entity, and if it does not exist yet, they can create it from the same modal instead of leaving the import flow.

Representative Usage

Relationship To Forms And Guided Flows

Stay-in-context workflows often contain forms, but this is not just a form concern.

This is a broader platform rule about:

• reducing unnecessary navigation
• keeping related decisions close together
• choosing the right local surface for the task

GuidedFlow is one implementation of this principle, not the principle itself.

Guidelines

• Do keep users in their current workflow when the related task is small and directly connected
• Do treat AutocompleteSelect with add-new or modal handoff as part of the stay-in-context toolkit when the task is still search-first and form-local
• Do escalate from inline -> popover -> autocomplete add-new -> guided flow -> panel -> page based on complexity
• Do use InlineEntityManager for contextual choose/create/manage entity flows
• Don't force navigation away just to unblock a small related task
• Don't solve a too-large modal subtask by stacking another modal or opening a panel above it
• Don't overload tiny surfaces with tasks that really need a panel or page