Eve library

OSHUN V1 Scan-First Content Hierarchy Rules

Guide

Revision 1

On this page

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.