/ui-context-and-scope

name: ui-context-and-scope
description: Show where the user is and what their actions affect — breadcrumbs, regions, scope labels. Use when designing deep navigation or multi-section layouts.
metadata:
  priority: 7
  pathPatterns:
    - "components/**"
    - "src/components/**"
    - "**/*.tsx"
    - "**/*.jsx"
    - "design-system/**"
    - "ui/**"
  promptSignals:
    phrases:
      - "breadcrumb"
      - "navigation hierarchy"
      - "context"
      - "scope"
      - "where am I"
      - "information architecture"
      - "user orientation"
      - "login"
      - "sign in"
      - "authentication"
      - "auth screen"
      - "act on behalf"
      - "impersonation"
      - "view as"
      - "internal tool"
retrieval:
  aliases:
    - context clarity
    - navigation hierarchy
    - breadcrumbs
    - scope communication
    - user orientation
    - information architecture
    - login screen
    - authentication UI
    - acting on behalf
    - impersonation banner
    - internal vs external tool
  intents:
    - show where the user is
    - communicate scope of changes
    - design deep navigation
    - make hierarchy clear
    - orient the user
    - design a login or auth screen
    - indicate acting on behalf of another account
    - distinguish an internal tool from the customer app
  examples:
    - make it clear which section the user is editing
    - add breadcrumbs to this deep navigation
    - show the user what their changes will affect
    - design a login page for this product
    - show that an admin is acting as a customer
    - make this internal tool distinct from the public app

UI Context and Scope

Users need to know three things at all times: 1. **Where am I?** — current location in the product hierarchy 2. **What context am I in?** — which section, record, or workspace is active 3. **What will my actions affect?** — scope of changes before committing them

When these are unclear, users make mistakes, feel lost, and lose trust in the product.

Communicating Hierarchy with Visual Structure

Lines and Dividers

Horizontal rules and borders signal the boundary between sections. Use them to separate content areas that belong to different contexts — not just for decoration.

• A line between a header and content says "the content below belongs to this header"
• A sidebar border says "this is a different region with a different purpose"
• Avoid overusing dividers — proximity and whitespace should do most of the work; dividers reinforce where space alone is insufficient

Colour Regions and Background Fills

Background colour is one of the strongest signals for "you are now in a different area."

• Use a distinct background shade for sidebars, panels, or contextual drawers
• Active or selected regions benefit from a subtle fill to confirm "this is the current context"
• When a user's changes are scoped to a specific section, that section should be visually bounded — border, fill, or both — so the scope is self-evident before the user commits

Section Labels and Context Headers

Every major region should be able to answer "what am I?" without the user having to read surrounding content.

• Name sections with the user's vocabulary, not the system's
• Show the active entity: "Editing: Invoice #2041" or "Settings for: Workspace" — not just "Settings"
• In forms that affect a specific record, show the record name prominently in the form header

Navigating Depth

Breadcrumbs

Use breadcrumbs when the product has three or more levels of hierarchy, or when users can arrive at a page from multiple paths.

Home > Projects > Website Redesign > Tasks > #142 Fix header

• Each breadcrumb item should be a clickable link back to that level
• The current page is the last item — not a link, just text
• On mobile, collapse to show only the immediate parent: `← Website Redesign`
• Breadcrumbs do not replace primary navigation — they complement it

Search and Filter as Navigation

In products with large or dynamic content trees, search reduces the cognitive cost of navigating depth.

• Global search for finding any entity across the product
• Contextual filters for narrowing within the current scope
• Search results should show enough context to distinguish similar items (e.g. project name alongside task name)

Scope Communication Before Action

When a change, setting, or action affects a specific scope, that scope must be communicated before the user commits — not discovered afterward.

• **Labels:** "This setting applies to: this workspace only" / "All users will see this change"
• **Visual bounding:** Highlight or outline the affected region when the user is about to edit it
• **Confirmation copy:** Destructive or wide-scope actions should state the scope in the confirmation dialog ("Delete this project and all 47 tasks inside it?")

Hidden Scope Needs a Visible Indicator

When a setting decides which data the whole application shows (tenant, site, environment), the control may live in a settings dialog. The state may not. Put a persistent read-only indicator in the chrome. Rarely changed is an argument about the control, never about the state. Without the indicator every screen looks correct in the wrong dataset.

Switching scope discards everything derived from the previous scope: searches, staged rows, selections.

Acting on Behalf of Someone Else

Whenever the user is viewing or changing data **as another user, customer, or account** — impersonation, admin "view as", support acting on a customer's behalf — the interface must make that unmistakably obvious the entire time, not just at the moment they enter the mode.

• **Persistent, unmissable indicator:** a coloured banner or bar that stays on screen the whole session ("You are acting as **Acme Corp** — changes affect their account"), not a toast that disappears.
• **Whose view is this:** name the account/customer being acted upon, and make it visually distinct from the operator's own