# OSHUN V1 Minimal Chrome Rules

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.
