aura-glass

v3.4.7

Published

7 days ago

Liquid Glass React and Next.js component library for polished dashboards, AI apps, media tools, and SaaS interfaces.

AuraGlass by AuraOne

Build Liquid Glass React and Next.js interfaces without rebuilding glass surfaces, tokens, motion, accessibility guardrails, and SSR-safe package wiring from scratch.

Developers use AuraGlass to:

Ship polished dashboards, AI products, media tools, creator apps, and SaaS workspaces with a glass-native visual system.
Start from styled React components instead of assembling blur, borders, shadows, depth, motion, and focus treatment by hand.
Keep theming, design tokens, reduced motion, contrast handling, SSR helpers, and TypeScript types in one npm package.
Add copyable product surfaces with the aura-glass recipe CLI when a full screen is faster than a blank component file.

Install

npm install aura-glass
pnpm add aura-glass
yarn add aura-glass
bun add aura-glass

Quickstart

Import the stylesheet once, then compose components from the public package entrypoint:

import { GlassButton, GlassCard } from 'aura-glass';
import 'aura-glass/styles';

export function BillingCard() {
  return (
    <GlassCard>
      <h2>Revenue</h2>
      <p>$128,400</p>
      <GlassButton>Open dashboard</GlassButton>
    </GlassCard>
  );
}

What You Can Build

| Product job | Start with | | --- | --- | | Core glass surfaces | GlassCard, GlassButton, OptimizedGlass, LiquidGlassMaterial | | Command and overlay UI | GlassCommandPalette, GlassDropdownMenu, GlassModal, GlassPopover | | App navigation | GlassNavbar, GlassSidebar, GlassTabs, GlassBreadcrumb | | Data-heavy dashboards | GlassDataGrid, GlassDataTable, GlassDataChart, GlassHeatmap | | Workspaces and shells | GlassAppShell, GlassWorkspace, GlassWorkflowShell, GlassTopBar | | Media and creator tools | GlassFileUpload, GlassImageViewer, LiquidGlassMediaControls, GlassMusicVisualizer | | Copyable screens | npx aura-glass add saas-dashboard, npx aura-glass add ai-command-center |

Why AuraGlass?

A finished visual language. Use glass-native surfaces, motion, depth, and tokens that already work together instead of styling neutral primitives from zero.
React and Next.js package ergonomics. Install from npm, import from stable package entrypoints, and add aura-glass/styles once in your app shell or root layout.
Product-surface coverage. Build dashboards, AI consoles, media controls, data tables, calendars, kanban boards, and workspace shells from one component system.
Guardrails for polished UI. TypeScript types, SSR helpers, reduced-motion behavior, contrast utilities, theme providers, and token exports are part of the package.
Optional advanced integrations. Charts, 3D, AI services, collaboration transport, and form-builder surfaces stay behind feature-specific imports and peers.

AuraGlass vs shadcn/ui

| Need | AuraGlass | shadcn/ui | | --- | --- | --- | | Finished Liquid Glass styling | Ships opinionated glass surfaces, CSS, tokens, and component variants | Provides neutral source-owned primitives you style yourself | | npm package workflow | Install and upgrade as a package with typed entrypoints | Copy component source into your app and own local changes | | Premium dashboards and product surfaces | Strong fit for polished SaaS, AI, media, and data-heavy apps | Strong fit for teams that want full source ownership and lower visual opinion | | Customization | Tokens, CSS variables, providers, props, and className | Direct code edits after copy | | Tradeoff | Larger and more opinionated than a primitive-only kit | More manual work to create a distinctive glass visual system |

API At A Glance

import {
  GlassButton,
  GlassCard,
  GlassCommandPalette,
  GlassDataChart,
  OptimizedGlass,
} from 'aura-glass';
import 'aura-glass/styles';

Stable package entrypoints include:

| Entrypoint | Purpose | | --- | --- | | aura-glass | Primary React component API. | | aura-glass/styles | Global AuraGlass CSS bundle. | | aura-glass/tokens | Runtime token and persona access. | | aura-glass/tokens/tailwind | Tailwind theme preset. | | aura-glass/icons | First-party AuraGlass icons for app chrome. | | aura-glass/primitives | Slot, portal, focus, dismissal, roving focus, and positioning primitives. | | aura-glass/app-shell | Dashboard, SaaS, AI, media, and collaboration app shell components. | | aura-glass/workspace | Workspace and workflow shell components. | | aura-glass/theme | Theme Engine 2.0 creation, brand theme, density, motion, and contrast APIs. | | aura-glass/registry | Copyable recipe metadata and registry helpers. | | aura-glass/ssr | SSR provider and hydration helpers. | | aura-glass/three | Optional 3D, AR, and React Three Fiber integrations. |

Recipes And CLI

List available recipes:

npx aura-glass list

Inspect one recipe:

npx aura-glass info saas-dashboard

Add a copyable recipe to an app:

npx aura-glass add ai-command-center

The CLI writes into src/components/auraglass/recipes by default and supports --out, --cwd, --dry-run, --force, and --json.

Migration and audit commands are available for package adoption:

npx aura-glass audit deps --json
npx aura-glass audit imports --json
npx aura-glass migrate icons --from lucide --dry-run
npx aura-glass migrate radix --dry-run
npx aura-glass migrate mui --dry-run
npx aura-glass doctor --json

Compatibility And Limits

Requires Node.js 18.18+ and npm 9+ for the package toolchain.
Supports React 18 and React 19, including Next.js 14 and 15 projects.
Import aura-glass/styles once from your app root or client entry.
Core app chrome does not require MUI, Radix, Lucide, or shadcn/ui packages.
Install optional peers only for the feature families you import: charts, 3D, AI services, collaboration transport, and form-builder integrations.
Use shadcn/ui or another primitive kit instead if you want neutral, source-owned components with minimal visual opinion.

Contributing

Contributions should improve package reliability, developer adoption, visual quality, accessibility, SSR behavior, documentation, or release evidence without weakening the public package boundary. Read CONTRIBUTING.md before opening a pull request.

Security

Report vulnerabilities using the guidance in SECURITY.md. Security-sensitive changes should preserve package-only installs, avoid credential leakage, and keep provider-backed hosted runtime behavior opt-in.

License

AuraGlass is released under the MIT License.

Package-Only And Optional Hosted Runtime

The public npm package is the primary supported AuraGlass surface. Package-only apps install aura-glass, import components and CSS, and do not need AuraGlass API, WebSocket, Redis, OpenAI, Pinecone, Google Vision, Remove.bg, or Sentry infrastructure.

The repository also contains optional backend and service-layer code for teams that want to host AI routes or realtime collaboration themselves. Treat that hosted runtime as opt-in infrastructure with its own environment, auth, provider, deployment, and evidence requirements. The canonical local contract for the hosted runtime is:

| Service | Local default | Environment variable | | --- | --- | --- | | Frontend/demo app | http://localhost:3000 | PORT | | API server | http://localhost:3002 | API_SERVER_PORT=3002 | | WebSocket server | ws://localhost:3001 | WS_PORT=3001 | | Public API URL | http://localhost:3002 | NEXT_PUBLIC_API_URL | | Public WebSocket URL | ws://localhost:3001 | NEXT_PUBLIC_WS_URL |

Production deployment guidance should use the real TypeScript API server built from server/index.ts and the WebSocket server in server/websocket-server.js. The legacy server/api-server.js path contains demo/mock API behavior and must not be used as a production entrypoint.

Optional provider-backed routes should fail safely when credentials are missing. A hosted route that needs a disabled or unconfigured provider should return a structured response like this instead of a hardcoded mock success:

{
  "error": "Provider not configured",
  "message": "openai is not configured for generate-form",
  "code": "AURA_PROVIDER_UNCONFIGURED",
  "provider": "openai",
  "feature": "generate-form",
  "docsUrl": "https://auraglass.auraone.ai/docs/ai-providers"
}

Best-Fit Use Cases

AuraGlass is for teams that need a finished visual system, not only neutral primitives. It is strongest when the interface itself carries product value: command centers, analytics surfaces, media controls, AI workspaces, premium dashboards, immersive admin tools, and high-polish product experiences.

Use AuraGlass when you need:

Apple-style Liquid Glass visual language for production React apps.
Next.js-compatible components with SSR-safe package entrypoints.
Premium app surfaces that look finished with default styling.
Tokens, dark mode, reduced motion, and contrast guardrails built into the system.
Optional advanced surfaces for media, AI, charts, dashboards, 3D, AR, and collaboration.
Checked-in release evidence for exports, tokens, runtime cleanliness, Storybook certification, package verification, and integration smoke coverage.

Flagship Components

The broader package surface remains available, but these are the components most teams should evaluate first.

| Product job | Start with | | --- | --- | | Core glass surfaces | OptimizedGlass, GlassCard, GlassButton, EnhancedGlassButton | | Overlays and command UI | GlassDropdownMenu, GlassSelectCompound, GlassModal, GlassDrawer, GlassPopover, GlassCommandPalette | | App navigation | GlassNavbar, GlassSidebar, GlassTabs | | App shell and workspaces | GlassAppShell, GlassTopBar, GlassSidebarRail, GlassWorkspace, GlassWorkflowShell | | Data-heavy dashboards | GlassDataGrid, GlassDataTable, GlassDataChart, GlassHeatmap | | Scheduling and workflows | GlassCalendar, GlassKanbanBoard, GlassWizard | | Media and creator tools | GlassFileUpload, LiquidGlassMediaControls, GlassImageViewer, GlassMusicVisualizer | | Liquid Glass primitives | LiquidGlassMaterial, LiquidGlassSourceTransition, LiquidGlassScrollEdge, LiquidGlassLayerProvider | | Product-ready surfaces | GlassDashboard, GlassPrismComparison, CollaborativeGlassWorkspace, GlassProductRecommendations, GlassSmartShoppingCart |

Agent-safe examples should import from the root package entrypoint and include the CSS import:

import {
  GlassButton,
  GlassCard,
  GlassCommandPalette,
  GlassDataChart,
} from 'aura-glass';
import 'aura-glass/styles';

Do not import from private source paths. Use optional peer packages only for the component families that need them.

Registry Details

AuraGlass includes a package-level recipe registry and CLI for scaffolding product-ready Liquid Glass app surfaces. The registry is available from aura-glass/registry; the CLI is installed as the aura-glass binary.

The package registry includes 28 recipes:

SaaS dashboard shell
AI command center
Media player surface
Analytics overview
Settings and billing page
Kanban workspace
Calendar schedule page
Collaborative workspace
Admin data table
Ecommerce product panel
SaaS admin shell
AI product console
Media review workspace
Commerce operations panel
Team collaboration hub
Settings and billing suite
Analytics command center
Calendar operations board
Customer support console
Creator studio dashboard
AI ops control room
Semantic search console
Vision review workbench
Collaboration room console
Support triage workspace
Release command center
Developer docs portal
Marketing launch kit

Use the registry directly when building custom tooling:

import { auraGlassRecipes, getAuraGlassRecipe } from 'aura-glass/registry';

const dashboard = getAuraGlassRecipe('saas-dashboard');

Recipe acceptance criteria and follow-up evidence are tracked in the 3.3 release evidence:

API And Usage Details

Install the package if you have not already:

npm install aura-glass

Import styles once from your root layout, app shell, or client entry:

import 'aura-glass/styles';

Use components from the root package entrypoint:

import { GlassButton, GlassCard, OptimizedGlass } from 'aura-glass';
import 'aura-glass/styles';

export function MetricsPanel() {
  return (
    <OptimizedGlass elevation="level2" className="glass-p-6">
      <GlassCard>
        <h2>Revenue forecast</h2>
        <p>Glass surfaces stay tokenized, readable, and motion-aware.</p>
        <GlassButton variant="primary">Review</GlassButton>
      </GlassCard>
    </OptimizedGlass>
  );
}

Next.js root layout example:

import 'aura-glass/styles';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Use the SSR provider when your app needs AuraGlass hydration helpers:

import { AuraGlassSSRProvider } from 'aura-glass/ssr';

export function Providers({ children }: { children: React.ReactNode }) {
  return <AuraGlassSSRProvider>{children}</AuraGlassSSRProvider>;
}

Peer Dependencies

React and React DOM are required. Other peers are feature-family dependencies. Install only what your app uses.

| Feature family | Peer packages | | --- | --- | | Core React UI | react, react-dom | | Motion | framer-motion | | Forms | react-hook-form | | Charts and data visualization | react-chartjs-2, chart.js | | 3D and AR | three, @react-three/fiber, @react-three/drei | | Error reporting integrations | @sentry/react |

Example full peer install for apps that use forms, charts, and 3D:

npm install react react-dom framer-motion react-hook-form react-chartjs-2 chart.js
npm install three @react-three/fiber @react-three/drei

See INSTALLATION.md for the deeper peer dependency matrix, SSR setup, 3D setup, and troubleshooting.

Theming And Tokens

AuraGlass ships a typed token system, generated CSS variables, Tailwind token entrypoint, and runtime persona support. Normal customization should use tokens, CSS variables, component props, className, style, and theme providers instead of overriding internals.

import { PersonaPicker, ThemeProvider, usePersonaTheme } from 'aura-glass';

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider initialPersona="midnight-slate" persistPersona>
      <PersonaPicker orientation="horizontal" />
      {children}
    </ThemeProvider>
  );
}

export function PersonaLabel() {
  const { persona } = usePersonaTheme();
  return <span>{persona.meta.name}</span>;
}

Token entrypoints:

import auraTokens, { personas } from 'aura-glass/tokens';

console.log(auraTokens.version);
console.log(personas[0].metadata.displayName);

Tailwind setup:

import type { Config } from 'tailwindcss';
import theme from 'aura-glass/tokens/tailwind';

export default {
  content: ['./src/**/*.{ts,tsx}'],
  theme,
} satisfies Config;

When persona tokens change, regenerate and validate the generated CSS:

npm run glass:generate-persona-css
npm run glass:validate-persona-css

Accessibility And Reduced Motion

AuraGlass components are expected to preserve:

readable text contrast across glass backgrounds and adaptive themes
semantic HTML, ARIA labels, roles, and state where needed
visible keyboard focus through focus-management guardrails
reduced-motion behavior for animation, transition, and physics effects
desktop and mobile Storybook renderability

AuraGlass 3.4 layers the Liquid Glass white-frost surface redesign (see CHANGELOG.md) on top of the 3.3-era evidence, which records first-party icons, first-party primitives, native app shell and workspace entrypoints, Theme Engine 2.0, 28 package registry recipes, focused forms/data/navigation/overlays/workflows/marketing subpaths, hosted-runtime contract tests, Docker Compose smoke coverage, migration CLI commands, tree-shaking gates, pack verification, export tests, and React 18/19 Next.js integration smokes. The older 356/356 certification inventory remains checked in as historical 3.0 Storybook and audit evidence; it is not the current package export count or launch claim.

Primary evidence sources:

Performance And SSR

AuraGlass keeps the root package focused on React UI and isolates heavier surfaces behind optional peers and explicit entrypoints.

| Entrypoint | Purpose | | --- | --- | | aura-glass | Primary React component API. | | aura-glass/styles | Global AuraGlass CSS bundle. | | aura-glass/tokens | Runtime token and persona access. | | aura-glass/tokens/json | Raw token manifest for tooling. | | aura-glass/tokens/tailwind | Tailwind theme preset. | | aura-glass/tokens/manifest | Lightweight token and persona metadata. | | aura-glass/tokens/css | Built token CSS file. | | aura-glass/tokens/keyframes | Built keyframe CSS file. | | aura-glass/ssr | SSR provider and hydration helpers. | | aura-glass/three | Optional 3D, AR, and React Three Fiber integrations. | | aura-glass/client | Client-specific helpers. | | aura-glass/server | Server-specific helpers. | | aura-glass/icons | First-party AuraGlass icons for app chrome. | | aura-glass/icons/navigation | Tree-shakable navigation icon category entrypoint. | | aura-glass/primitives | First-party primitives for slot, portal, focus, dismissal, roving focus, and positioning. | | aura-glass/primitives/slot | Slot/asChild primitive. | | aura-glass/primitives/portal | SSR-safe portal primitive. | | aura-glass/primitives/focus | Focus scope primitive. | | aura-glass/primitives/dismissable-layer | Dismissable overlay primitive. | | aura-glass/primitives/roving-focus | Roving focus primitive. | | aura-glass/primitives/positioning | Anchor positioning primitive. | | aura-glass/app-shell | Native dashboard, SaaS, AI, media, and collaboration app shell components. | | aura-glass/workspace | Workspace and workflow shell components. | | aura-glass/theme | Theme Engine 2.0 creation, brand theme, density, motion, and contrast APIs. | | aura-glass/registry | Styled registry compatibility plus copyable recipe metadata. | | aura-glass/hooks/useGlassProbes | Runtime glass style probe hooks. | | aura-glass/services/ai/openai-service | Optional OpenAI-backed backend integration. | | aura-glass/services/ai/vision-service | Optional Google Cloud Vision backend integration. | | aura-glass/services/websocket/collaboration-service | Optional hosted collaboration client integration. |

Use aura-glass/utils/env for guarded browser access, safe media queries, and deterministic hydration helpers. Install three, @react-three/fiber, and @react-three/drei only before importing from aura-glass/three. Install optional backend peers such as openai or @google-cloud/vision only before constructing the matching AI service classes.

AI Agent Guidance

Use these rules when asking Codex, Cursor, Claude Code, GitHub Copilot, Gemini CLI, or another coding agent to work with AuraGlass:

Install with npm install aura-glass.
Import components from aura-glass.
Import CSS with import 'aura-glass/styles';.
Prefer GlassButton, GlassCard, OptimizedGlass, GlassCommandPalette, GlassDataGrid, and LiquidGlassMaterial for first examples.
Do not invent component names.
Do not import from private paths under src.
Do not use 3D, media, AR, or advanced components without optional peer dependencies.
Do not wrap compound children without their parent components.
Do not use WebGL/canvas-heavy components for simple cards.

The package repo includes llms.txt as the short agent-facing context file. Current package and recipe readiness evidence is tracked in reports/3.3-release.

Development

npm install
npm run storybook
npm run typecheck
npm run lint:check
npm run audit:components

Useful scripts:

| Command | Purpose | | --- | --- | | npm run storybook | Starts local Storybook. | | npm run build-storybook | Builds static Storybook. | | npm run build | Builds package outputs. | | npm run typecheck | Runs TypeScript checking. | | npm run lint:check | Runs the repository lint check. | | npm run lint:tokens | Validates token rules. | | npm run lint:styles | Validates style rules. | | npm run audit:components | Prints the historical certification inventory, docs, story, test, accessibility, and certification coverage. | | npm run audit:exports | Verifies public exports against source and declaration files. | | npm run audit:api | Reports public API typing, declaration, and ref-forwarding follow-ups. | | npm run audit:runtime | Reports production-source console, debugger, and TODO/FIXME findings. | | npm run glass:full-check | Runs the package glass validation workflow. | | npm run verify:pack | Verifies package output before publishing. | | npm run test:integration:next | Builds temporary Next.js consumer apps for React 18 and React 19 smoke coverage. | | npm run release:dry-run | Runs CI and npm dry-run publish. Do not run it unless you intend to exercise the full release path. |

Repository Map

| Path | Purpose | | --- | --- | | src/components | Component source. | | src/stories | Shared Storybook audit and certification stories. | | src/reports | Static audit data consumed by Storybook and tests. | | docs | Technical documentation. | | docs/components | Organized component docs. | | reports | Generated and hand-authored audit evidence. | | reports/3.1-release | 3.1 launch evidence scaffold and sign-off baselines. | | reports/3.2-release | Historical 3.2 package launch evidence, recipe evidence, app-chrome visuals, and completion audit. | | reports/3.3-release | 3.3-era package launch evidence, hosted-runtime evidence, recipe evidence, app-chrome visuals, security review, and manual-certification scaffold. | | scripts/audit | Audit and certification scripts. | | tests/visual/design-system | Playwright guardrails for visual certification and audit coverage. | | .github | GitHub workflow and collaboration templates. | | .storybook | Storybook configuration and shared preview wrappers. |

Release Evidence

The 3.4 surface redesign is verified by the release gate commands below — typecheck, token and style lints, the 31-check glass pipeline, 90 WCAG AA contrast checks, and 432 Jest suites with 2,373 tests — while 3.3-era package launch claims remain backed by checked-in evidence under reports/3.3-release. The normal publish path uses npm publish --access public --tag latest from a clean release commit after the dry-run, pack, and integration gates pass; package.json enables npm provenance for trusted publishing environments.

Package gates:

npm run audit:components
npm run audit:exports
npm run audit:api
npm run audit:runtime
npm run typecheck
npm run lint:check
npm run lint:tokens
npm run lint:styles
npm run build
npm run verify:pack
npm run test:integration:next -- --skip-build
npm run build-storybook
npm run release:dry-run
git diff --check

3.3-era evidence: