# OSHUN V1 Scan-First Content Hierarchy Rules

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

- `docs/releases/v1/design/readability-standards.md`
- `docs/releases/v1/specs/layout-density-tiers.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `docs/releases/v1/specs/experience-scorecards.md`
- `docs/releases/v1/design/ux-principles.md`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical scan-first content hierarchy rules for
headings, labels, metadata, helper text, and primary actions across OSHUN web,
PWA, and mobile surfaces.

The standard is simple: a user should be able to scan a surface and understand
all of the following in seconds:

- where they are
- what matters most right now
- what they can do next
- what supporting evidence or constraints apply

If the user has to read paragraph copy before they understand the screen, the
hierarchy has failed.

## 2. Canonical Scan Order

OSHUN surfaces should resolve in this order:

1. orientation
2. task or object
3. primary action
4. supporting evidence or metadata
5. helper or recovery text

That means:

- headings beat metadata
- labels beat placeholders
- primary actions beat secondary controls
- helper text never outranks the object or task itself

## 3. Hierarchy Roles

| Role                  | Job                                                  | Typical examples                                     | Emphasis rule                                                           |
| --------------------- | ---------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------- |
| `orientation heading` | tells the user where they are                        | page title, domain title, workspace title            | exactly one dominant orientation heading per view                       |
| `section heading`     | names a meaningful content group                     | section title, list group title, panel title         | stronger than summaries and metadata, weaker than orientation heading   |
| `label`               | names a control, field, or action target             | form label, tab label, filter label, CTA text        | concise, visible, never replaced by ambiguous placeholder-only patterns |
| `metadata`            | adds status, time, provenance, scope, count, or type | source, duration, confidence, SLA, freshness, author | de-emphasized and grouped for scan speed                                |
| `helper text`         | explains consequence, requirement, or recovery       | validation hint, privacy note, failure guidance      | adjacent to the object it supports and visually subordinate by default  |
| `primary action`      | advances the main task                               | continue, save, publish, review, open, retry         | one dominant action per task region or viewport                         |

## 4. Heading Rules

### 4.1 One Dominant Orientation Heading

Every view gets one dominant orientation heading.

Allowed examples:

- screen title
- domain route title
- workspace or cockpit title

Forbidden patterns:

- two visually equal screen titles
- large decorative headings above the real title
- repeating the same title in shell, hero, and content body

### 4.2 Section Headings Must Carry Scan Meaning

Section headings should tell the user what the region is, not how the team feels
about it.

Good:

- `Recent activity`
- `Source evidence`
- `Approval queue`
- `Recommended next step`

Bad:

- `Everything you need today`
- `Smart insights for your journey`
- `Explore the power of your workflow`

### 4.3 Heading Counts Must Stay Controlled

Above the fold:

- one orientation heading
- usually no more than `2` section headings on mobile
- usually no more than `3` section headings on desktop

If more headings are competing, the screen likely needs stronger grouping.

## 5. Label Rules

### 5.1 Labels Are Mandatory For Real Controls

Critical controls, fields, filters, and tabs must have explicit labels.

Do not rely on:

- placeholder-only field naming
- icon-only controls when the action is not obvious
- vague CTA text such as `Go`, `Open`, or `Continue` without context

### 5.2 Labels Must Be Short And Specific

Preferred label style:

- noun phrase for navigation or object naming
- verb phrase for actions
- one idea only

Target length:

- buttons: usually `1-4` words
- tabs and segmented controls: usually `1-3` words
- field labels: usually `1-5` words

### 5.3 Labels Must Not Compete With Headings

Labels should be clear, but they should not become louder than the task or
object title.

If a filter chip row visually dominates the page heading, the hierarchy is
backwards.

## 6. Metadata Rules

### 6.1 Metadata Stays Compressed

Metadata should usually appear as:

- one short line
- grouped chips
- compact inline clusters
- secondary rail content

It should rarely become paragraph text.

### 6.2 Metadata Must Answer A Real Decision Need

Keep metadata that helps the user choose, trust, or prioritize:

- freshness
- confidence
- provenance
- duration
- status
- owner
- count
- severity

Remove metadata that merely proves the system knows extra facts.

### 6.3 Metadata Must Never Outrank The Object

The object or claim headline must read first.

Examples:

- search result title before source/date
- evidence statement before citation count
- queue item name before SLA countdown
- domain title before availability tag

## 7. Helper Text Rules

### 7.1 Helper Text Exists For Consequence, Constraint, Or Recovery

Use helper text only when it explains:

- what will happen
- what is required
- why something is blocked
- how to recover

Do not use helper text as ambient commentary or filler.

### 7.2 Helper Text Must Sit Next To Its Trigger

Helper text belongs directly under or beside the control, field, section, or
state it explains.

Do not place essential helper text in a distant banner or footnote if the user
needs it to complete the task.

### 7.3 Helper Text Must Stay Quiet Until Needed

Default helper text should be visually secondary.

It may grow in prominence only when:

- validation fails
- destructive consequences need confirmation
- degraded or offline behavior changes the task

Even then, it should still support the heading and action rather than replace
them.

## 8. Primary Action Rules

### 8.1 One Dominant Primary Action Per Task Region

Each meaningful task region gets one visually dominant primary action.

Examples:

- one main CTA in onboarding step content
- one dominant save or publish action in a workspace
- one dominant continue action in a home recovery module

Competing filled buttons in the same region are not allowed unless one is
clearly destructive and isolated.

### 8.2 Primary Actions Must Sit Near The Decision Point

Place primary actions:

- directly after the deciding content
- in a predictable trailing position on desktop
- in a stable footer or bottom action bar on mobile when the task is long

Do not force the user to scan unrelated metadata before finding the next step.

### 8.3 Action Language Must Match Outcome

Primary action labels should describe what happens next.

Good:

- `Start session`
- `Review evidence`
- `Approve policy`
- `Retry sync`

Bad:

- `Proceed`
- `Submit`
- `Done`

Those generic labels are allowed only when the step container already makes the
outcome unmistakable.

## 9. Cross-Element Rules

### 9.1 Headings First, Explanations Second

The user should understand the region from the heading and the first visible
action before reading helper copy.

### 9.2 Metadata Supports, It Does Not Introduce

Metadata should reinforce the object already named by the heading or label. It
should not act as the main identifier.

### 9.3 Actions Need Object Context

Primary action copy should be specific enough that the user understands the
result without rereading the entire screen.

## 10. Web And Mobile Behaviors

### 10.1 Web

- Orientation heading may share a row with one trailing primary or secondary
  action cluster.
- Section headings may trail a single compact `View all` or utility action.
- Metadata may live inline beside headings only when it stays visually lighter.

### 10.2 Mobile

- Orientation heading usually stacks above metadata and actions.
- Field labels should remain explicit even when space is tight.
- Primary actions may move to sticky footers for long forms or long review
  flows.
- Metadata must collapse before headings or action labels do.

## 11. Workflow-Specific Guidance

### 11.1 Contemplative And Customer Guidance

- Headings should stay calm and short.
- Metadata should be minimal and often delayed below the first action plane.
- Helper text should sound reassuring and direct, not technical.

### 11.2 Exploratory Guidance

- Section headings should create a strong browse path.
- Metadata should help comparison, not clutter cards.
- Labels should make filters and sorts obvious without overwhelming results.

### 11.3 Research Guidance

- Headline first, evidence next, provenance after that.
- Citation counts, source names, and confidence should be visible but not louder
  than the claim or passage.
- Helper text should clarify method, limits, or evidence quality only where it
  changes interpretation.

### 11.4 Operator Guidance

- Workspace headings should be shorter than customer headings.
- Primary actions should be direct and operational.
- Metadata may be denser, but must still be grouped and rankable.
- Helper text should be procedural and recovery-oriented, not explanatory
  marketing copy.

## 12. Explicit Anti-Patterns

These patterns are non-canonical for OSHUN V1:

- headings that read like campaign copy on product surfaces
- metadata rows above the main object title
- placeholder-only labels for critical inputs
- two filled primary buttons in the same task zone
- helper text that explains the entire product before the user can act
- badges and chips that become visually louder than headings
- timestamps, counts, and source names repeated in multiple places above the
  fold

## 13. Implementation Contract

These rules should govern current shared and route-local hierarchy patterns,
including:

- `apps/oshun/web/src/design-system/components/SectionHeader.tsx`
- `apps/oshun/web/src/design-system/components/TopBar.tsx`
- `apps/oshun/web/src/design-system/components/DomainSurfaceLayout.tsx`
- `apps/oshun/web/src/design-system/components/SearchInput.tsx`
- `apps/oshun/mobile/app/(tabs)/explore.tsx`
- `apps/oshun/mobile/app/(tabs)/activity.tsx`
- `apps/oshun/mobile/app/domain/[domainId].tsx`

Any new shared component that introduces a title, label, metadata cluster,
helper message, or CTA should declare which hierarchy role it is serving.

## 14. Exit Standard

A surface meets the scan-first hierarchy standard only when:

- the first scan reveals the current place and task
- the next action is obvious
- metadata improves confidence without slowing comprehension
- helper text is useful and local
- removing one hierarchy level would clearly make the screen worse

If a user must read everything to understand anything, the content hierarchy is
not acceptable for V1.
