Eve library

OSHUN V1 Minimal Chrome Rules

Guide

Revision 1

On this page

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

  • docs/releases/v1/design/customer-visual-thesis.md
  • docs/releases/v1/design/admin-visual-thesis.md
  • docs/releases/v1/design/ux-principles.md
  • docs/releases/v1/design/brand-system.md
  • docs/releases/v1/specs/experience-scorecards.md
  • docs/releases/v1/specs/todos.md

1. Purpose#

This document defines the canonical minimal-chrome rules for OSHUN V1 shells, workspaces, drawers, filters, trays, and toolbars across customer web, PWA, mobile, and admin surfaces.

The goal is not to remove capability. The goal is to remove non-essential framing so the work itself stays visually primary.

These rules exist because the current repo already contains multiple powerful chrome-bearing surfaces, including:

  • apps/oshun/web/src/components/ShellLayout.tsx
  • apps/oshun/web/src/design-system/components/Sidebar.tsx
  • apps/oshun/web/src/design-system/components/TopBar.tsx
  • apps/oshun/web/src/design-system/components/DomainSurfaceLayout.tsx
  • apps/oshun/web/src/components/QuickActionsTrayPanel.tsx
  • apps/oshun/web/src/components/WidgetSidebar.tsx
  • apps/oshun/mobile/app/_layout.tsx
  • apps/oshun/mobile/app/(tabs)/_layout.tsx

Without a shared rule set, those surfaces can each become reasonable in isolation while still producing too much combined chrome.

2. Core Doctrine#

2.1 Chrome Exists To Orient, Not Decorate#

Chrome may do four jobs only:

  • orient the user
  • preserve navigation and return paths
  • surface a small number of high-value actions
  • expose state that changes decisions

If a chrome element does none of those jobs, it should be removed or turned into content.

2.2 One Persistent Region Per Edge By Default#

Each viewport edge gets at most one persistent structural region by default.

  • left: navigation rail or sidebar
  • top: title/context/action bar
  • bottom: mobile tab bar or sticky action bar
  • right: no persistent region by default

Adding a second persistent region on the same edge requires explicit product value and must displace less important chrome, not stack on top of it.

2.3 Content Owns The Largest Plane#

At every breakpoint, the working content or decision surface must visually own more area than chrome.

The interface should read as:

  1. work
  2. context
  3. control chrome

Never the reverse.

2.4 Persistence Must Be Earned#

A control stays persistent only if hiding it would meaningfully slow common work or create recovery risk.

Everything else should be:

  • contextual
  • collapsible
  • on-demand
  • route-specific

2.5 Chrome Must Compress Before Content Does#

When space becomes constrained:

  1. ornamental treatments disappear first
  2. secondary labels compress second
  3. optional controls collapse third
  4. content density changes last

OSHUN should not preserve decorative chrome while truncating the actual work.

3. Canonical Chrome Budgets#

These are structural budgets, not decorative suggestions.

Surface Canonical persistent chrome budget
Customer desktop shell One left rail (72-260px) and one top bar (56-64px)
Admin desktop shell One left rail (72-280px) and one top context bar (56-64px); an extra persistent strip is allowed only for critical operator boundary/state
Customer mobile shell One top header and one bottom tab bar; helper banners must collapse after acknowledgement or scroll away
Domain surface header One title/context band plus optional tabs; combined height should usually stay within 128px before content begins
Workspace local toolbar Single row by default; a second row is allowed only for dense expert-mode operator work
Drawer No more than 40vw on large desktop or full-width sheet behavior on small screens
Tray Compact edge-attached surface sized for quick decisions, not full workflows

Any surface that exceeds these budgets must justify the extra chrome in its design review and show what was removed to compensate.

4. Shell Rules#

4.1 Shells Use One Loud Structural Idea#

Customer shell:

  • calm navigation rail
  • restrained top context bar
  • domain accent only as a cue, never as a second chrome layer

Admin shell:

  • durable navigation rail
  • low-noise top context bar
  • explicit boundary styling only where operator/customer confusion is a real risk

Mobile shell:

  • bottom tab bar is the primary persistent control surface
  • headers should orient, not duplicate tab-bar functions

4.2 Shells Must Not Stack Competing Helpers#

A shell should not show multiple persistent helper systems at once unless they solve different urgent jobs.

Avoid this stack:

  • global banner
  • progress bar
  • assistant trigger
  • floating quick-action trigger
  • sticky status strip
  • route-local toolbar

If more than two of those are visible simultaneously, the shell is over-framed.

4.3 Shell Navigation Must Feel Quiet#

  • Navigation backgrounds stay neutral.
  • Borders are thin and structural.
  • Accent color belongs to selection, not to every nav item.
  • Persistent nav badges are exceptional, not default.
  • Collapse behavior should reduce width and label noise before adding more layout containers.

5. Workspace Rules#

5.1 Workspaces Are For Work, Not For Framing#

A workspace may include:

  • a title and operational context
  • a compact status summary
  • a local toolbar
  • the working canvas, table, queue, form, or evidence stack

It should not start with a hero, marketing panel, decorative card deck, or oversized introductory copy.

5.2 Workspace Headers Must Stay Short#

The header should answer only:

  • where am I
  • what object or queue am I operating on
  • what is the current state
  • what is the next primary action

If a workspace header needs more than one short supporting sentence, the copy belongs somewhere else.

5.3 Workspace Surfaces Default To Open Layouts#

Default structure:

  • plain sections
  • list rows
  • split panes
  • tables
  • inspectors
  • inline dividers

Do not wrap every subsection in another bordered box. The workspace should feel like one operating surface, not a card pile.

6. Drawer Rules#

6.1 Drawers Are For Context Preservation#

Use a drawer when the user should keep the underlying surface visually present while handling a secondary task such as:

  • inspecting details
  • editing metadata
  • reviewing evidence
  • resolving a lightweight approval

If the task becomes primary or long-running, route to a full page or workspace.

6.2 Drawers Must Stay Single-Purpose#

Every drawer gets:

  • one clear title
  • one short context sentence if needed
  • one dominant action cluster

Do not put tabs inside drawers by default. Do not open a drawer from another drawer.

6.3 Drawer Chrome Must Be Lighter Than Page Chrome#

  • thinner headers
  • fewer actions
  • no secondary navigation
  • no decorative gradients
  • no standalone dashboard content

The drawer is supporting structure, not a second app shell.

7. Filter Rules#

7.1 Filters Start Inline, Then Escalate#

Filter hierarchy:

  1. one or two primary inline filters
  2. compact chip row or segmented control
  3. overflow into drawer/sheet only when the filter model is genuinely complex

Users should not open a full filter drawer for a common single-toggle decision.

7.2 Filters Must Reveal Their Cost#

Every filter system should make these visible:

  • current active filters
  • changed result scope or count when applicable
  • one-step reset or clear action

Hidden filters that silently distort results violate OSHUN clarity rules.

7.3 Filter Chrome Must Not Outweigh Results#

The visible filter area should rarely consume more height than the first screen of results.

If filters dominate the viewport, the surface is behaving like a form instead of a browsing or queue experience.

8. Tray Rules#

8.1 Trays Are For Fast Access, Not Parallel Products#

Use trays for:

  • quick actions
  • continuity shortcuts
  • lightweight status peeks
  • assistant entry points

Do not use trays for long forms, multi-step setup, or dense review workflows.

8.2 Trays Stay Edge-Attached And Compact#

Trays should feel attached to the invoking edge or trigger, not like detached floating windows.

They should open quickly, expose a small decision set, and close cleanly after task completion or explicit dismissal.

8.3 Only One Tray Family May Demand Attention#

If quick actions, widgets, assistant entry, and notifications all animate or glow at once, the shell becomes noisy.

Only one tray family may use active attention-seeking treatment at a time.

9. Toolbar Rules#

9.1 Toolbars Serve The Current Object#

A toolbar is not a second header. It exists to operate on the current selection, queue, canvas, or document.

Toolbar content priority:

  1. primary action
  2. high-frequency object actions
  3. view/sort/filter controls
  4. low-frequency overflow actions

9.2 Toolbars Default To One Row#

One-row toolbar is the default across customer and admin surfaces.

Two-row toolbars are reserved for expert-mode operator work where:

  • the object is dense
  • the action set is genuinely high frequency
  • overflow would materially slow critical work

9.3 Toolbars Use Grouping, Not Decoration#

Use:

  • spacing
  • alignment
  • dividers
  • text-label clarity

Avoid:

  • nested capsules
  • oversized filled containers
  • repeated icon backgrounds
  • ornamental shadows around every control group

10. Explicit Anti-Patterns#

The following are non-canonical for OSHUN V1:

  • stacked hero plus shell plus local toolbar on routine product screens
  • dashboard-card mosaics used as chrome instead of as content
  • drawers with nested tabs, banners, and multi-zone footers
  • filter systems hidden behind a single icon when filtering is core to the task
  • quick-action trays that become mini dashboards
  • multiple persistent floating buttons competing for the same corner
  • accent-heavy navigation rails
  • workspace headers that explain the product instead of the present task

11. Implementation Contract#

These rules should directly govern current shared shell components and the next round of redesign work:

  • apps/oshun/web/src/components/ShellLayout.tsx
  • apps/oshun/web/src/design-system/components/Sidebar.tsx
  • apps/oshun/web/src/design-system/components/TopBar.tsx
  • apps/oshun/web/src/design-system/components/DomainSurfaceLayout.tsx
  • apps/oshun/web/src/components/QuickActionsTrayPanel.tsx
  • apps/oshun/web/src/components/WidgetSidebar.tsx
  • apps/oshun/mobile/app/_layout.tsx
  • apps/oshun/mobile/app/(tabs)/_layout.tsx

Any future shared component or route-local pattern that adds new chrome must first prove that an existing chrome layer cannot absorb the job.

12. Exit Standard#

A shell or workspace is minimally chromed only when:

  • the work surface visually dominates
  • orientation remains obvious
  • primary actions stay reachable
  • chrome count feels quieter after use, not louder
  • removing one chrome region would obviously make the product worse

If removing a chrome element improves the experience or changes nothing, that element should not exist.