Lumina OS Documentation

Spatial context for
the modern web.

Learn how to implement high-fidelity, physically accurate spatial interfaces in your Next.js applications using Lumina's hardware-accelerated core.

Introduction

Lumina OS replaces flat math-based web animations with true physics. It operates on the principle that the web should no longer consist of planar layers stacked on top of one another, but rather a volumetric, spatial environment.

By leveraging native GPU acceleration features embedded directly into the browser, Lumina allows standard DOM elements to catch light, cast shadows, and interact with realistic inertia without requiring heavy WebGL canvases.

Sub-millisecond latency

Interactions are tied directly to hardware refresh rates (120fps).

Real material properties

Glass, metallic sheen, and matte textures built directly into CSS limits.

Quickstart

Integrating Lumina OS into your React or Next.js project takes less than a minute.

1. Install the Core Engine

First, install the primary Lumina OS package along with its framer-motion dependency.

bash

npm install @lumina-os/core framer-motion

2. Wrap your application

Wrap your root layout or application component in the LuminaProvider. This initializes the physics engine globally and hooks into window scroll telemetry.

tsx

import { LuminaProvider } from '@lumina-os/core';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <LuminaProvider config={{ precision: 'high', framerate: 120 }}>
      <Component {...pageProps} />
    </LuminaProvider>
  );
}

Spatial Context

In a spatial environment, no item exists flatly. We enforce the Z-axis by injecting variables automatically mapped to scroll and cursor telemetry.

"Objects on screen do not vanish; they shift in depth, obscuring perfectly with absolute blur values."

To use spatial cards, simply import the GlassNode component. This component automatically reacts to the cursor, adjusting its rim lighting and scaling physically.

tsx

import { GlassNode } from '@lumina-os/core/ui';

export function Dashboard() {
  return (
    <div className="grid">
      <GlassNode elevation={10} material="frosted">
        <h3>Metrics Overview</h3>
      </GlassNode>
    </div>
  );
}

GitHub Discord

Spatial context for the modern web.