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.mddocs/releases/v1/scope/scan-first-content-hierarchy-rules.mddocs/releases/v1/specs/ergonomic-budgets.mddocs/releases/v1/scope/grid-gutter-max-width-rules.mdapps/oshun/web/src/components/ShellLayout.tsxapps/oshun/web/src/components/QuickActionsTrayPanel.tsxapps/oshun/web/src/components/library/ResearchPracticeJourneyRail.tsxapps/oshun/web/src/components/profile/DataRightsSection.tsxapps/oshun/web/src/components/profile/shared.tsxapps/oshun/web/src/components/domains/veritas/VeritasSourceDirectory.tsxapps/oshun/mobile/src/components/MobileAssistantLauncher.tsxapps/oshun/mobile/src/components/QuickActionsTray.tsxapps/oshun/mobile/src/components/DomainSwitcherEntry.tsxapps/oshun/mobile/src/library/UnifiedLibraryView.tsxdocs/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, andUnifiedLibraryView.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:
- inline with the object
- in the local section header or section footer
- in the route toolbar
- in a sticky action bar or sticky footer
- 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
Compareaction - clear
ClearorExit comparecontrol
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
SaveorPublish - 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 usageQuickActionsTrayPanel.tsxandQuickActionsTray.tsx: keep them compact, edge-attached, and distinct from sticky primary workflow actionsMobileAssistantLauncher.tsx: preserve tab-bar clearance and keep the assistant as one primary floating familyResearchPracticeJourneyRail.tsxand compare-heavy surfaces such asVeritasSourceDirectory.tsx: make compare persistence emerge from active selection instead of feeling like a detached global commandDataRightsSection.tsx,ConfirmationModal, andUnifiedLibraryView.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