⚡ LUMINA

The Generative Frontend Engine & Automated MCP for AI Developers

Linear · Apple · Vercel · Stripe · Teenage Engineering Tier Standards

Lumina is an autonomous generative frontend engine and Model Context Protocol (MCP) server for Google Antigravity (AGY) and Claude Code.
It eradicates repetitive "AI Slop" (generic purple gradients, unchamfered flat cards, raw untracked fonts, and dead buttons) and empowers LLMs with bespoke, tactile, and living design systems.

⚡ Global Installation (One-Liner)

Install Lumina globally in seconds. The installer configures the CLI binary, sets up your system PATH, and automatically registers the Lumina MCP server into your AI environment without touching existing tools.

🪟 Windows (PowerShell - Recommended)

irm https://raw.githubusercontent.com/Farukes/lumina/main/install.ps1 | iex

🐍 Python (Windows / macOS / Linux)

python -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/Farukes/lumina/main/install.py').read())"

📦 Alternative: Clone & Install Locally

git clone https://github.com/Farukes/lumina.git
cd lumina
python install.py

What Does Installation Do?

1. Syncs the engine to ~/.lumina/engine.

2. Registers the global lumina executable into your User PATH.

3. Automatically configures the Lumina MCP server in Antigravity (~/.gemini/config/mcp_config.json) and Claude Desktop without touching other servers (your existing MCP servers remain 100% intact).

Related MCP server: vibecraft-mcp

🎮 Core Commands (Intuitive & Minimal)

Lumina replaces complex subcommands with 4 primary actions:

🛠️ Quick Utilities

• lumina theme $\rightarrow$ Explore and switch between 9 handcrafted luxury archetypes.

• lumina view $\rightarrow$ Launch the interactive HTML5 live showcase directly in your default browser.

• lumina add <block> $\rightarrow$ Add battle-tested AAA blocks (bento-grid, command-bar, floating-dock, glow-hero, etc.).

• lumina mcp $\rightarrow$ Launch the Model Context Protocol stdio server (or lumina mcp -i to re-register).

🧠 Smart AI Assistant Detection (Zero Clutter)

Lumina automatically inspects your machine to avoid generating clutter:

• Antigravity (AGY) detected: Injects only GEMINI.md and .agents/rules. If Claude Code is not on your PC, no unnecessary CLAUDE.md or .claude/ files are generated.

• Claude Code detected: Injects Claude Code directives and skills.

• Manual Override:

  lumina on --ai agy      # Target Antigravity exclusively
  lumina on --ai claude   # Target Claude Code exclusively
  lumina on --ai both     # Target both environments

🎨 9 Luxury Design Archetypes

Lumina features 9 original, copyright-clean design archetypes to guide generative AI models:

1. obsidian-craft (Linear Tier): Deep obsidian (#09090b), 1px inner metallic specular chamfer (border-white/[0.08] shadow-[inset_0_1px_0_0_rgba(255,255,255,0.06)]), emerald accents.

2. industrial-machina (Teenage Engineering): Matte aluminum (#18181b), dot-matrix typography, tactile Safety Orange (#ff4400) switches.

3. liquid-spatial (visionOS): Liquid refraction, multi-tier backdrop blur (backdrop-blur-2xl), specular top rim reflection (border-t-white/40), viscous spring physics.

4. parchment-editorial (Stripe Press): Warm unbleached paper tone (#fbf9f5), editorial serif typography (Newsreader), 0.5px razor dividers.

5. stark-monolith (Vercel Discipline): Pure monochrome contrast, Geist font pairing, razor 0.5px structural grids.

6. fintech-horizon (Stripe SaaS): Midnight deep slate, ambient mesh auroras, soft dimensional elevation.

7. amber-terminal (Raycast Cyber): Phosphor amber glow (#f59e0b), monospace telemetry, keyboard-first navigation (⌘K).

8. pure-cupertino (Apple Clean): Multi-layer squircle geometry, generous negative space, translucent glass morphology.

9. refined-brutalism: Crisp 2px ink borders, 3px zero-blur hard offset drop shadows (shadow-[3px_3px_0_0_#000]), electric acid accents.

🤖 Model Context Protocol (MCP) Suite

Lumina exposes 5 generative AI tools via Model Context Protocol:

• synthesize_design_tokens: Generates OKLCH color palettes, chamfer highlights, and spring physics tailored to archetype, data density, and materiality.

• get_composition_grammar: Teaches AI structural layout laws, visual hierarchy balances, and ASCII wireframes without enforcing rigid cookie-cutter templates.

• get_visual_primitive: Returns mathematical formulas and micro-interaction primitives (Border Beam, Spotlight Follow, 3D Perspective Tilt, Text Scramble, Web Audio).

• get_component_blueprint: Provides reference architecture for complex living blocks (Living Bento Grid, Command Bar, Dynamic Island Dock).

• critique_ui_design: Audits submitted JSX/TSX/HTML code through the lens of a Senior Design Director.

🗑️ Zero-Trace Uninstallation

Lumina is strictly isolated. It never creates Windows Registry entries, runs background daemons, or leaves orphaned files.

To remove Lumina from your entire computer:

lumina uninstall

Clean Removal Guarantee:

• Purges the global engine directory (~/.lumina).

• Removes ~/.lumina/bin from your user PATH environment variable.

• Safely removes "lumina" from mcp_config.json (all other MCP servers remain completely untouched).

• Removes workspace-level constitutions and CSS tokens.

• Leaves exactly 0 bytes and 0 traces behind.

📦 Repository Structure

lumina/
├── install.py             # Global cross-platform Python installer
├── install.ps1            # Windows single-line PowerShell installer
├── lumina/
│   ├── cli.py             # Click & Rich CLI master entrypoint
│   └── core/
│       ├── installer.py   # Global installation, PATH & MCP configuration engine
│       ├── auditor.py     # 12+ AI-slop pattern scanner and scoring engine
│       ├── polisher.py    # Automated code refactoring and chamfer injector
│       ├── themes.py      # 9 luxury design archetypes with OKLCH tokens
│       ├── registry.py    # AAA component blueprints
│       └── rules_generator.py # Smart environment-aware AI rule injector
├── mcp/
│   └── server.py          # Model Context Protocol (MCP) stdio server
├── components/blocks/     # React & Tailwind living UI blocks
└── showcase/              # Interactive live browser showcase

📄 License

This project is licensed under the MIT License. Open-source, free for personal and commercial use.