Skip to content

UXI Implementation in this Repo

This page explains how the UXI architecture is instantiated in the uxi-landing project.

Project Role

  • Blueprint: This repo is the reference implementation of the OVES UXI architecture.
  • Demo: It acts as a live demo for:
  • JSON-configured pages rendered via UXI blocks
  • Cloudinary-backed media registry
  • Block-with-props pattern for all UXI components

Key Directories

  • src/uxi/
  • blocks/: domain blocks such as Hero, FeatureGrid, StatsStrip, StoryTimeline, and Cta.
  • layout/: AppShell, header, footer, navigation wrappers.
  • media/: media.json registry, typed registry.ts, and UxiImage wrapper for Cloudinary assets.
  • PageRenderer.tsx: maps JSON page configs into block rendering via BlockRegistry.
  • BlockRegistry.tsx: central type -> component mapping with typed props.
  • content/pages/
  • home.json: homepage defined as a sequence of UXI blocks with props.
  • mobility.json: mobility-focused page using the same blocks and a Cloudinary background video.
  • src/app/
  • page.tsx: loads home.json, applies UxiHeader/UxiFooter, and calls PageRenderer.
  • mobility/page.tsx: loads mobility.json and renders it through the same UXI engine.

Block with Props + JSON Pattern

  • Each block in src/uxi/blocks defines a TypeScript props interface (e.g. HeroProps).
  • BlockRegistry defines a typed union of { type, props } where props must match that interface.
  • Page JSON files provide type and props for each block instance.
  • PageRenderer simply loops through blocks[] and calls renderBlock to instantiate the right component.

JSON Schema Validation

To prevent typos and ensure type safety in JSON content:

  • schema/block-config.schema.json: Defines all valid block types and their prop structures
  • schema/page-config.schema.json: Defines the full page configuration format
  • .vscode/settings.json: Wires schemas into VS Code for authoring-time validation and autocomplete
  • scripts/validate-content.js: Build-time validation script (runs before npm run build)

Benefits: - ✅ Catch typos like "hero1" before runtime - ✅ IDE autocomplete for block types and props - ✅ Build fails early if content is invalid - ✅ MCP-ready schemas for AI agent integration

See schema/README.md for full documentation.

Media and Cloudinary

  • Cloudinary is used as the central media repository.
  • The UXI media layer is organized as:
  • media.json: JSON catalog of media assets with semantic IDs (e.g. logo.oves.primary.lockup.en).
  • registry.ts: typed access to those assets via getMedia and UxiMediaId.
  • UxiImage.tsx: abstraction over next/image that accepts mediaId instead of raw URLs.
  • Page JSON can also pass Cloudinary URLs directly as imageUrl / backgroundEmbedUrl props when appropriate.

Background Video Behavior

  • Hero blocks can accept a backgroundEmbedUrl (Cloudinary player URL).
  • The component appends autoplay=true&muted=true&loop=true&controls=false and renders the video at 50% opacity so it stays in the background while content remains primary.

For broader architectural principles, see UXI Architecture in the navigation.