AuraWall

Procedural Vector Wallpaper Generator

AuraWall is a client-side web application that generates abstract, high-resolution wallpapers using procedural algorithms and vector graphics. Unlike AI-based generators, AuraWall creates deterministic, mathematically harmonious images that are infinitely scalable and lightweight.

---

Table of Contents

• Overview
• Features
• Technology Stack
• Installation
• Usage
• Project Structure
• Customization
• Contributing
• License

---

Overview

AuraWall operates entirely in the browser with zero server dependencies. The application uses a JSON-based configuration system (WallpaperConfig) that describes shapes, colors, filters, and animations. This configuration is rendered reactively as SVG, then rasterized via Canvas API for export.

Key Principles

• Deterministic Generation: Same seed produces identical output every time
• Vector-First: All rendering happens in SVG until final export
• Procedural Intelligence: Curated randomness ensures aesthetic consistency
• Zero Dependencies: No backend, no AI APIs, no external services

---

Features

Generation Engines

Engine	Aesthetic	Characteristics
Boreal	Ethereal, soft	High blur, analogous colors, multiply/screen blend modes
Chroma	Liquid, acidic	Low blur, complementary colors, difference/exclusion blend modes
Lava	Psychedelic, warm	Retro fluid motion, warm palettes, blob shapes
Midnight	Cosmic, deep	Dark backgrounds, nebula clouds, star particles
Geometrica	Bauhaus, grid	Strict grid alignment, primary colors, sharp shapes
Glitch	Digital chaos	RGB split (chromatic aberration), artifacts, digital noise
Sakura	Floral, gentle	Pastel pinks, petal shapes, wind simulation
Ember	Fire, ash	Dark coals, bright orange sparks, rising smoke
Oceanic	Aquatic, deep	Deep blues, organic fluid motion, underwater feel
Animation	Kinetic, flowing	CSS keyframe animations for drift, pulse, rotate, noise

Controls

• Shape Management: Add, remove, and configure individual layers
• Color Science: Base gradients, hue constraints, harmonic selection
• Color Palette Extractor: Extract and copy the exact hex codes used in the composition
• Post-Processing: Vignette effect, procedural grain, blur intensity
• Motion Physics: Animation speed, flow direction, turbulence
• Zen Mode: Hide the UI for an immersive digital frame experience

Export Options

Format	Use Case
PNG	Lossless, transparent background support
JPG	Smaller file size, configurable quality
SVG	Vector source for editing in Illustrator/Figma

Resolution Presets

• Desktop: 1920x1080, 2560x1440, 3840x2160 (4K)
• Mobile: iPhone, Android, iPad
• Custom: Any aspect ratio

---

Technology Stack

Category	Technology
Core	React 19, TypeScript
Build	Vite 6, PostCSS
Styling	Tailwind CSS v4
Graphics	Native SVG DOM, Canvas API
i18n	i18next (8 languages)
Testing	Vitest, Playwright

---

Installation

Prerequisites

• Node.js 18 or higher (Node.js 20+ recommended)
• npm or yarn

Local Development

# Clone the repository
git clone https://github.com/mafhper/aurawall.git
cd aurawall

# Install dependencies
npm install

# Start development server (Main App + Promo Site concurrently)
npm run dev

# OR start them individually:
# Main Application
npm run app

# Promotional Website
npm run promo

The application will be available at http://localhost:5173.

Production Build

# Build both applications
npm run build

# Build main application only
npm run build-app

# Build promotional website only
npm run build-promo

# Preview production build
npm run preview

---

Development & Quality

AuraWall includes a comprehensive suite of scripts to ensure code quality, performance, and stability.

Health Checks

• npm run health: Full system check (clean, install, build, test).
• npm run health:fast: Quick check (build validation + lint/structure tests).

Testing

• npm run test:lint: Run ESLint static analysis.
• npm run test:structure: Verify file/folder structure integrity.
• npm run test:i18n: Validate translation keys parity.
• npm run test:contrast: Check color contrast compliance (WCAG AA).

Performance Audits

• npm run audit: Run Lighthouse audits on both App and Promo site.
• npm run perf:analyze: Analyze performance trends from reports.

See scripts/README.md for detailed documentation on automation scripts.

---

Usage

Quick Start

1. Open the application in your browser
2. Select a generation engine (Boreal or Chroma)
3. Adjust parameters using the control panel
4. Click "Generate" or use the randomizer
5. Export in your preferred format and resolution

URL Sharing

Configurations can be shared via URL. The application uses lz-string compression to encode the entire WallpaperConfig object into a shareable link.

https://aurawall.com/app/?config=N4IgDgTg...

Preset Gallery

Access the gallery to browse curated presets. Each preset can be:

• Downloaded directly as PNG (1920x1080)
• Opened in the editor for customization
• Used as a starting point for new creations

---

Project Structure

aurawall/
├── src/                      # Main application source
│   ├── components/           # React components
│   │   ├── WallpaperRenderer.tsx   # Core SVG renderer
│   │   ├── ControlPanel/     # UI controls
│   │   └── ExportModal.tsx   # Export functionality
│   ├── services/             # Business logic
│   │   ├── svgGenerator.ts   # Procedural generation
│   │   ├── colorService.ts   # Color harmony algorithms
│   │   └── variationService.ts # Preset variations
│   ├── constants.ts          # Presets and defaults
│   ├── types.ts              # TypeScript definitions
│   └── App.tsx               # Application root
│
├── website/                  # Promotional site (separate build)
│   ├── src/
│   │   ├── pages/            # Landing, Gallery, About, etc.
│   │   ├── components/       # Site-specific components
│   │   └── i18n.ts           # Translations
│   └── vite.config.ts        # Site build configuration
│
├── public/                   # Static assets
│   ├── icon.svg              # Application icon
│   ├── og-image.png          # Social sharing image
│   └── bg-*.svg              # Background textures
│
├── _desenvolvimento/         # Internal documentation (Portuguese)
│   └── docs/                 # Technical guides
│
├── vite.config.ts            # Main app build configuration
├── tailwind.config.js        # Tailwind CSS configuration
└── package.json              # Dependencies and scripts

---

Customization

Adding New Presets

Presets are defined in src/constants.ts:

export const PRESETS: Preset[] = [
  {
    id: 'my-preset',
    name: 'My Custom Preset',
    collection: 'boreal', // or 'chroma'
    config: {
      baseColor: '#1a0a2e',
      shapes: [...],
      animation: { enabled: true, speed: 2 },
      // ...
    }
  }
];

Creating Custom Engines

Engines are now modular and defined in src/engines/. To create a new engine:

1. Create a new file (e.g., src/engines/myEngine.ts) implementing the EngineDefinition interface.
2. Define metadata, default configuration, and a randomizer function.
3. Register the engine in src/engines/index.ts.

// src/engines/myEngine.ts
export const myEngine: EngineDefinition = {
  id: 'my-engine',
  meta: { name: 'My Engine', ... },
  randomizer: (config) => { ... },
  variations: [ ... ]
};

Extending the Promo Site

The promotional website is a separate Vite project in /website. It shares components from the main application:

// Import from main app
import WallpaperRenderer from '../../../src/components/WallpaperRenderer';
import { PRESETS } from '../../../src/constants';

---

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit changes: git commit -m 'Add your feature'
4. Push to branch: git push origin feature/your-feature
5. Open a Pull Request

Development Guidelines

• Follow existing code style and patterns
• Add translations for any user-facing text
• Test across multiple browsers
• Update documentation as needed

---

License

MIT License - See LICENSE file for details.

---

Author: @mafhper

Repository: github.com/mafhper/aurawall