# OSHUN V1 Imagery, Illustration, Texture, and Ambient-Media Rules

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

- `docs/releases/v1/design/customer-visual-thesis.md`
- `docs/releases/v1/design/brand-system.md`
- `docs/releases/v1/design/motion-language.md`
- `docs/releases/v1/scope/immersive-vs-utilitarian-posture-rules.md`
- `docs/releases/v1/scope/grid-gutter-max-width-rules.md`
- `apps/oshun/web/src/components/welcome/WelcomePageView.tsx`
- `apps/oshun/web/src/components/OptimizedImage.tsx`
- `apps/oshun/web/src/components/domains/NisabaSurface.tsx`
- `apps/oshun/web/src/app/not-found.tsx`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical imagery, illustration, texture, and
ambient-media rules for OSHUN V1 so hero and landing surfaces have a real visual
anchor without collapsing into clutter.

The repo already contains partial visual signals:

- the customer visual thesis explicitly says decorative gradients alone are not
  enough
- `WelcomePageView.tsx` uses particles, gradients, and cards, but no truly
  dominant hero image or scene
- `OptimizedImage.tsx` provides an image primitive that can support real media
  loading and fallbacks
- some surfaces such as `not-found.tsx` already use custom illustration logic

What is missing is a canonical rule set defining when OSHUN should use real
imagery, when illustration is acceptable, how texture should stay subordinate,
and how ambient media can deepen atmosphere without becoming distraction.

## 2. Current Repo Signals And Gap

Current implementation review shows the following:

- OSHUN already has strong typography and color primitives
- customer surfaces already aim for atmosphere through gradients and accent
  washes
- welcome and hero-like pages still risk reading as token-rich but visually
  generic because the first viewport is not anchored by real media
- domain landing sections often fall back to bordered cards, gradient fills, or
  atmospheric color alone

This task closes that gap by making imagery and ambient media first-class
composition tools rather than optional decoration.

## 3. Core Doctrine

### 3.1 Every Hero Needs One Real Anchor

A launch-critical hero or landing surface should have one dominant visual idea.

That anchor may be:

- photography
- editorial illustration
- product-integrated media scene
- controlled ambient-motion canvas

It must not be:

- only a gradient
- only particles
- only a card grid
- only decorative icons

### 3.2 Imagery Must Do Narrative Work

Media should clarify the surface's emotional and functional promise:

- presence
- study
- wonder
- rigor
- momentum

If the media does not change the meaning of the first viewport, it is probably
ornament rather than anchor.

### 3.3 Texture Supports, It Does Not Lead

Texture may deepen material feel through:

- paper
- grain
- glow haze
- celestial dust
- environmental shadow or light falloff

Texture must not become the main idea or compete with content.

### 3.4 Ambient Media Exists To Create Presence, Not Novelty

Motion-led visual fields may be used when they make the product feel more
embodied, expansive, or alive.

They are valid only when:

- the content remains readable
- the motion stays low-amplitude
- the surface still works as a still frame

## 4. Canonical Media Roles

| Media role               | Job                                                   | Typical use                                                    |
| ------------------------ | ----------------------------------------------------- | -------------------------------------------------------------- |
| `hero anchor`            | establish the first-view emotional and narrative idea | welcome pages, public landing, domain-first impressions        |
| `support image`          | deepen one section without replacing hierarchy        | feature sections, continuity modules, editorial callouts       |
| `editorial illustration` | explain a concept or add symbolic clarity             | onboarding, empty states, rare trust/support moments           |
| `texture layer`          | add material feel and atmosphere                      | backgrounds, section transitions, domain mood layers           |
| `ambient media field`    | create spatial or temporal presence                   | Nyx wonder moments, ritual calm scenes, immersive welcome hero |

## 5. Hero And Landing Rules

### 5.1 One Dominant Composition

The first viewport should be built around one dominant visual plane.

Allowed structures:

- full-bleed media with constrained text column
- split composition with one calm media side and one text/action side
- immersive background field with clearly anchored text

Forbidden structures:

- centered hero above a wall of cards
- gradient-only hero with token-rich but visually generic content
- multiple competing illustrations in the same first viewport
- dashboard-style stat strips as the main landing impression

### 5.2 The Anchor Must Be Stronger Than The Chrome

The image or visual field should carry more first-view weight than:

- nav ornament
- metric chips
- icon rows
- decorative gradients

If the first screen still reads like a generic app after hiding the media, the
media is too weak.

### 5.3 Text Must Sit In A Calm Area

Hero copy should sit over:

- a stable tonal area
- a restrained visual edge
- a clearly darkened or lightened overlay when needed

Do not place hero copy over:

- busy detail
- embedded signage or text
- high-contrast focal clutter

## 6. Imagery Rules

### 6.1 Preferred Image Types

Preferred visual anchors for OSHUN customer surfaces:

- real-life contemplative environments
- study materials, annotated texts, or archival detail for Nisaba
- night-sky or telescope-adjacent imagery for Nyx
- grounded documentary or newsroom-adjacent evidence scenes for Veritas
- movement, discipline, and lived routine imagery for Arete

These should feel specific and credible, not generic lifestyle filler.

### 6.2 Cropping Rules

- Crop for one clear focal idea.
- Preserve a calm region for text.
- Avoid collage logic inside a single image.
- Prefer one image per section over one busy montage trying to do everything.

### 6.3 Quality Rules

- Images should feel premium and intentional, not stock-site generic.
- Avoid visible brand signage, watermarks, or embedded UI.
- Avoid over-saturated wellness or sci-fi cliches.
- Avoid any image that makes the product feel spiritually vague or visually
  unserious.

## 7. Illustration Rules

### 7.1 When Illustration Is Allowed

Illustration is allowed for:

- onboarding explanation
- empty or support states
- rare narrative landing accents
- symbolic domain framing where photography would be less coherent

### 7.2 When Illustration Is Not Enough

Illustration alone is not sufficient for hero or landing work when the surface
needs to communicate:

- premium product depth
- real-world trust
- scholarly seriousness
- strong emotional atmosphere

In those cases, illustration must be paired with stronger imagery or a richer
ambient field.

### 7.3 Illustration Style Rules

- Favor editorial, restrained illustration over mascots or cartoon systems.
- Use one illustration language across a given experience.
- Treat whimsical illustration as exceptional, not default. The current
  `not-found.tsx` ghost is acceptable for recovery tone but should not define
  primary product art direction.

## 8. Texture Rules

### 8.1 Texture Is Subordinate

Texture may appear as:

- film grain
- paper tooth
- star haze
- soft radial atmosphere
- edge vignetting

It should remain background support for the primary composition.

### 8.2 Texture Limits

- Use one dominant texture treatment per section at most.
- Avoid stacking multiple grains, glows, and overlays until the surface feels
  noisy.
- Texture should usually be legible only after a second look, not as the first
  thing the user notices.

### 8.3 Texture Must Not Replace Meaningful Media

A premium gradient plus texture does not count as a hero anchor on its own.

## 9. Ambient-Media Rules

### 9.1 Approved Ambient-Media Use Cases

Ambient media is most appropriate for:

- Nyx sky and cosmic orientation
- Tara-led calming or breathing presence
- high-end welcome or landing scenes
- rare domain transitions where continuity is the point

### 9.2 Behavior Rules

- Ambient motion must stay slow and low-amplitude.
- Loops should feel continuous rather than obviously repeating.
- Silent by default; do not auto-play audio as ambient atmosphere.
- The surface must ship with a still-frame fallback.
- Reduced-motion mode should freeze or simplify the field immediately.

### 9.3 Anti-Noise Rules

Do not use ambient media that:

- competes with reading
- flashes or pulses aggressively
- introduces game-like spectacle on customer landing work
- relies on constant movement to feel impressive

## 10. Domain Translation

### 10.1 Tara

- Prefer embodied calm, natural light, breath, still water, or grounded ritual
  cues.
- Avoid cliché wellness illustration packs and pastel-blob aesthetics.

### 10.2 Veritas

- Prefer documentary, source, and evidence-adjacent imagery.
- Avoid panic-newsroom chaos, warning-red overload, or sterile enterprise
  dashboards as the primary mood.

### 10.3 Nyx

- Prefer expansive astronomical imagery, observational tools, and precise
  nocturnal atmosphere.
- Avoid neon sci-fi noise, HUD clutter, or generic space wallpaper.

### 10.4 Arete

- Prefer disciplined real-world motion, practice environments, and lived
  commitment cues.
- Avoid gamified trophy imagery or hyper-athletic cliches.

### 10.5 Nisaba

- Prefer text, margin, manuscript, annotation, and study-desk materiality.
- The surface should feel scholarly and durable, not museum-kitsch or fantasy
  parchment cosplay.

## 11. Implementation Guidance

Implementation surfaces that should converge on these rules:

- `apps/oshun/web/src/components/welcome/WelcomePageView.tsx`
- `apps/oshun/web/src/components/domains/NisabaSurface.tsx`
- `apps/oshun/web/src/components/OptimizedImage.tsx`
- future domain and marketing landing routes

Implementation expectations:

- use `OptimizedImage` or an equivalent governed media primitive for hero and
  support imagery
- require alt text and resilient loading/fallback behavior
- prefer media-backed composition over adding more bordered boxes to create
  visual interest

## 12. Anti-Patterns

The following are non-canonical for OSHUN V1:

- gradient-only heroes pretending to be visually rich
- first-view card grids used as the visual anchor
- multiple decorative illustrations fighting each other
- hyperactive particles or motion used to hide weak composition
- stock wellness, productivity, or sci-fi cliché imagery
- texture stacks so strong they muddy contrast or hierarchy

## 13. Acceptance Standard

A redesigned hero or landing surface satisfies `V1-UX-058` only when all are
true:

- it has one dominant visual anchor
- the anchor does narrative work rather than decorative filler work
- texture and ambient media remain supporting layers
- the first viewport stays readable and uncluttered
- reduced-motion or image-fallback states still preserve the intended hierarchy
