Eve library

OSHUN V1 Action Placement Rules

Guide

Revision 1

On this page

Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-062
Related:

  • docs/releases/v1/scope/minimal-chrome-rules.md
  • docs/releases/v1/scope/scan-first-content-hierarchy-rules.md
  • docs/releases/v1/specs/ergonomic-budgets.md
  • docs/releases/v1/scope/grid-gutter-max-width-rules.md
  • apps/oshun/web/src/components/ShellLayout.tsx
  • apps/oshun/web/src/components/QuickActionsTrayPanel.tsx
  • apps/oshun/web/src/components/library/ResearchPracticeJourneyRail.tsx
  • apps/oshun/web/src/components/profile/DataRightsSection.tsx
  • apps/oshun/web/src/components/profile/shared.tsx
  • apps/oshun/web/src/components/domains/veritas/VeritasSourceDirectory.tsx
  • apps/oshun/mobile/src/components/MobileAssistantLauncher.tsx
  • apps/oshun/mobile/src/components/QuickActionsTray.tsx
  • apps/oshun/mobile/src/components/DomainSwitcherEntry.tsx
  • apps/oshun/mobile/src/library/UnifiedLibraryView.tsx
  • docs/releases/v1/specs/todos.md

1. Purpose#

This document defines the canonical placement rules for:

  • sticky footers and sticky action bars
  • floating actions and tray triggers
  • compare tools
  • assistant entry points
  • destructive actions

OSHUN should not make users hunt for the next step, but it also should not pin, float, or emphasize every possible action at once. Placement is part of the product's calmness and clarity, not just a layout detail.

2. Current Repo Signals And Gap#

The current repo already shows the main action families:

  • shell-level assistant entry in ShellLayout.tsx
  • floating quick actions in QuickActionsTrayPanel.tsx
  • mobile assistant launcher positioned above tab chrome in MobileAssistantLauncher.tsx
  • contextual assistant and journey actions in ResearchPracticeJourneyRail.tsx
  • compare entry inside content flows such as VeritasSourceDirectory.tsx
  • local destructive patterns in DataRightsSection.tsx, ConfirmationModal, and UnifiedLibraryView.tsx

The gap is action hierarchy. Current implementation review shows:

  • desktop surfaces can expose both a top-bar assistant trigger and a floating assistant FAB at the same time
  • quick-action, assistant, scroll-top, offline, and other persistent controls all compete for edge territory
  • compare actions are present, but there is not yet one canonical rule for when compare starts inline versus when it earns sticky persistence
  • destructive actions are usually local, but not yet governed by one placement standard across web and mobile

This document defines that placement hierarchy.

3. Core Doctrine#

3.1 Actions Live As Close To Their Object As Possible#

Default order of placement is:

  1. inline with the object
  2. in the local section header or section footer
  3. in the route toolbar
  4. in a sticky action bar or sticky footer
  5. in a floating edge launcher

Move outward only when the user would otherwise lose reachability, context, or frequency efficiency.

3.2 Persistence Must Be Earned#

An action may become sticky or floating only if at least one of these is true:

  • the flow is long enough that the action would scroll away during decision work
  • the action is shell-global and needed across many routes
  • the action controls a live selection or compare set that must stay visible
  • repeated use materially benefits from constant reach

3.3 Only One Primary Persistent Action Family Per Edge#

At any given edge or corner, one family may dominate:

  • assistant
  • quick actions
  • compare
  • sticky save / approve / publish

If multiple families need to coexist, one must become quieter, relocate, or collapse into the other.

3.4 Dangerous Actions Must Never Masquerade As Progress Actions#

Delete, erase, reject, revoke, or destructive reset actions must not sit in the same emphasis band as:

  • save
  • continue
  • approve
  • publish
  • confirm

They require spatial and tonal separation.

4. Canonical Placement Ladder#

Placement type Use when Maximum emphasis Canonical examples
inline action belongs to one object, row, field, or cardless content item one dominant inline action remove item, select compare target, open detail
section action row action belongs to one module or subsection one primary plus one utility View all, Ask assistant, local filter reset
toolbar / header trail action affects the whole route or current workspace one primary cluster route-level assistant entry, compare mode entry
sticky summary/action action must remain reachable during long scroll or review one dominant action plus supporting state save footer, approve bar, compare summary rail
floating launcher action is shell-global or cross-surface utility one launcher family per corner assistant launcher, quick-action tray trigger
danger zone + confirm action is destructive or high consequence isolated destructive emphasis only account deletion, irreversible removal, destructive clear

Interpretation rules:

  • not every important action deserves sticky treatment
  • floating is reserved for cross-surface utility, not routine local commit
  • destructive actions should usually begin local and confirm in a separate state or modal

5. Sticky Footers And Sticky Action Bars#

5.1 When Sticky Is Canonical#

Use sticky footers or sticky summary/action bars for:

  • long forms
  • long reviews or approvals
  • compare workflows with persistent selection state
  • mobile flows where the primary commit would otherwise require repeated scroll jumps

Do not use sticky footers when:

  • the form is short
  • the primary action is already within the first viewport
  • the surface is mostly browse or reading and the action is secondary

5.2 Sticky Bar Anatomy#

A canonical sticky bar contains:

  • current object or selection summary
  • one dominant primary action
  • one secondary escape or defer action when necessary
  • lightweight status only if it changes the decision

It should not become a second full toolbar.

5.3 Sticky Bar Density Rules#

  • one primary action is preferred
  • two actions are acceptable when the secondary is clearly lower emphasis
  • three or more peer actions is non-canonical
  • filters, sort menus, and helper copy do not belong in sticky action bars

5.4 Sticky And Destructive Separation#

Destructive actions should not share the primary side of a sticky footer with a positive commit action.

If a destructive action must remain available during a long flow:

  • place it on the opposite side
  • lower its default emphasis
  • require a dedicated confirmation state

6. Floating Actions And Edge Launchers#

6.1 What Floating Is For#

Floating actions are reserved for:

  • shell-level assistant entry
  • quick-action trays
  • rare utility jumps such as scroll-to-top

They are not for:

  • save
  • publish
  • submit review
  • route-specific compare commit
  • destructive actions

6.2 Corner Competition Rule#

The same corner must not host multiple equal-weight floating controls.

If a corner already contains a primary floating launcher, additional controls must:

  • collapse into that launcher
  • move to the header or toolbar
  • appear only conditionally
  • yield by state priority

6.3 Edge Clearance Rule#

Floating controls must clear:

  • bottom navigation
  • safe-area insets
  • offline or sync banners
  • sticky action bars
  • the last actionable list row

The user should never need to dodge a floating control to tap the main surface.

6.4 Tray Trigger Rules#

Tray triggers should stay edge-attached and compact, consistent with OSHUN_V1_MINIMAL_CHROME_RULES.md.

They may open:

  • a small set of fast actions
  • a short continuity list
  • one clear assistant entry

They may not become:

  • mini dashboards
  • long forms
  • complex compare workspaces
  • destructive control hubs

7. Compare Tool Placement Rules#

7.1 Compare Starts Inline#

Compare begins at the object level:

  • selection chips
  • checkboxes
  • add-to-compare toggles
  • row-level compare affordances

The user must be able to understand what is being compared before compare becomes a mode.

7.2 Compare Earns Persistence After Selection Exists#

Once the compare set is non-empty or reaches a meaningful threshold, surface a sticky summary bar, tray, or split-view affordance that shows:

  • count of selected items
  • dominant Compare action
  • clear Clear or Exit compare control

The compare launcher should stay near the content region, not jump to unrelated global shell chrome.

7.3 Compare Placement By Surface Type#

  • browse and directory views: inline selection plus sticky summary once active
  • research and reading flows: compare rail or split-view entry near evidence context
  • mobile: compare should usually escalate into a bottom sheet, sticky footer, or dedicated route rather than a small floating button

8. Assistant Entry-Point Rules#

8.1 Assistant Is Shell-Level, But Context-Aware#

Assistant entry should be consistent enough to build habit, while still carrying route context.

Canonical pattern:

  • desktop utilitarian surfaces: one shell-level entry in header or one floating launcher, not both at equal emphasis
  • mobile tab surfaces: one floating launcher offset above tab chrome
  • contextual journeys: lighter inline assistant actions may appear inside the current module

8.2 Primary Versus Secondary Assistant Entry#

Primary assistant entry is the durable shell affordance.

Secondary assistant entry may appear:

  • in a continuity rail
  • in library or recovery flows
  • beside a stalled research path

Secondary assistant entry must never outrank the surface's actual primary task.

8.3 Assistant Placement Anti-Duplication Rule#

If a persistent shell assistant button already exists in the current viewport, do not add a second equally loud assistant trigger unless:

  • one is a collapsed mobile-safe variant of the same entry
  • one appears only when the other is hidden
  • one is contextual and clearly subordinate

9. Destructive Action Placement Rules#

9.1 Destructive Actions Stay Local To The Object They Harm#

Place destructive controls:

  • inside the affected row
  • in a clearly labeled danger zone
  • at the end of a settings section
  • inside a confirmation modal or dedicated confirmation state

Do not place destructive actions in global shell chrome.

9.2 Escalation Ladder#

Use the smallest honest destructive pattern:

  • reversible or low-scope removal: inline action with confirm-on-second-press
  • route or object deletion: isolated danger zone plus confirmation modal
  • irreversible destructive operation: dedicated confirm state with explicit consequence copy

9.3 Spatial Separation Rules#

  • destructive actions should be last in reading order within their group
  • destructive actions should be visually separated from positive primaries by space, divider, or dedicated zone
  • destructive actions should rarely sit side-by-side with primary progress actions in the same filled-button style

9.4 Confirmation Rules#

Confirmation is required when:

  • the action is irreversible
  • multiple items are affected
  • identity, billing, or account data is affected
  • the loss cannot be trivially restored

Micro-removals may use two-step inline confirm when scope is small and obvious, as long as the target remains visible.

10. Customer Versus Admin Translation#

10.1 Customer#

Customer surfaces should minimize persistent action load:

  • one shell assistant entry
  • one primary commit when needed
  • compare actions close to content
  • destructive actions isolated and rarely persistent

10.2 Admin#

Admin surfaces may use more persistent action posture, but only when it reduces loop cost:

  • sticky review bars are acceptable for approvals and queue work
  • compare and diff controls may persist when they define the workflow
  • destructive or policy-sensitive actions still require isolation and explicit confirmation

Admin is allowed to be denser, not messier.

11. Anti-Patterns#

The following are non-canonical for OSHUN V1:

  • multiple floating buttons competing for the same corner
  • sticky footers on short forms just because they seem modern
  • compare hidden only behind unrelated shell utilities
  • assistant entry repeated in header, floating FAB, panel banner, and section CTA at the same time
  • destructive buttons sharing equal visual weight with Save or Publish
  • trays used as substitute screens for complex workflows

12. Implementation Alignment Checklist#

Follow-on implementation should align the current repo as follows:

  • ShellLayout.tsx: choose a clearer hierarchy between top-bar assistant entry, floating assistant FAB, and scroll-to-top corner usage
  • QuickActionsTrayPanel.tsx and QuickActionsTray.tsx: keep them compact, edge-attached, and distinct from sticky primary workflow actions
  • MobileAssistantLauncher.tsx: preserve tab-bar clearance and keep the assistant as one primary floating family
  • ResearchPracticeJourneyRail.tsx and compare-heavy surfaces such as VeritasSourceDirectory.tsx: make compare persistence emerge from active selection instead of feeling like a detached global command
  • DataRightsSection.tsx, ConfirmationModal, and UnifiedLibraryView.tsx: keep destructive actions local, separated, and confirmation-aware by scope

13. Acceptance Standard#

An action placement pattern is canonical only if:

  • the next step is easy to find without adding extra chrome
  • persistence is earned by scroll distance, frequency, or shell scope
  • the user never has to decode which action is primary
  • destructive actions are separated from progress actions
  • the viewport edge does not become a pile of competing utilities