Eve library

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

Guide

Revision 1

On this page

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