Documentation
Muon Site Engine
Build ultra-premium, enterprise-grade SaaS and corporate websites using a 100% JSON-driven headless architecture. No React or CSS knowledge required.
Zero-Code Workflow
This package allows you to control the entire structure, content, and design of a production-ready website simply by editing two JSON files.
Installation & Setup
To generate a new website, you must have Node.js installed and authenticate with the GitHub Packages Registry.
1 Authenticate with GitHub Packages
To ensure that you can use the Muon Site Engine CLI generator from anywhere on your machine, you must authenticate globally. Follow these steps:
- Generate a Personal Access Token (PAT) with
read:packagespermissions on GitHub. - Open your terminal (Terminal on Mac, or Command Prompt/PowerShell on Windows) and run the following commands to authenticate globally:
npm config set //npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT_HERE
npm config set @leoc1992:registry=https://npm.pkg.github.com/
Note: The above commands work seamlessly on both Mac and Windows. They automatically generate a global config file in your user directory:
- Mac / Linux: Creates
~/.npmrc - Windows: Creates
%USERPROFILE%\.npmrc(e.g.,C:\Users\YourName\.npmrc)
This authenticates your entire system, allowing you to run the CLI from anywhere.
2 Scaffold your Website
Run the automated CLI tool to generate a fresh website project instantly:
npx @leoc1992/site-engine my-awesome-site
cd my-awesome-site
npm install
npm run dev
Your website is now running at http://localhost:5173
AI Agent Skill Architecture
The Muon Site Engine was engineered from the ground up to be an AI-native website operating system. Because 100% of the UI, layouts, styles, SEO, and popups are defined declaratively via JSON schemas, modern autonomous agents (such as Google Antigravity, Cursor, Windsurf, Claude Code, and Copilot) can architect and modify complex, high-converting websites in seconds with zero hallucination.
Standardized Skill Directory
The repo houses .agents/skills/site-engine/SKILL.md which automatically loads engine constraints, section types, and props into the agent's context.
Zero-Code JSON Pipeline
Agents modify config.json, theme.json, seo.json, and popups.json without touching or corrupting core React components.
Developer Extension Safety
When custom logic is required, agents are instructed to leverage customComponents and slots instead of forking the engine.
The Universal AI Base Prompt Template
When starting a new session or instructing an AI agent to build or modify a website, copy and paste this base prompt. It sets up strict architectural guardrails and ensures the agent outputs production-ready code:
You are building a website using `@leoc1992/site-engine` (a 100% JSON-driven React Website Engine).
Before writing any code or modifying configurations:
1. READ and follow `.agents/skills/site-engine/SKILL.md` and the project guidelines in `.agents/AGENTS.md`.
2. Adhere strictly to the JSON-driven architecture:
- Do NOT hardcode text, images, links, or styles directly into React section components.
- Modify `src/config.json` (content/structure), `public/theme.json` (theming/customCss), `src/config/seo.json` (technical SEO), and `src/config/popups.json` (modals/lead capture).
3. If custom React logic or 3rd-party widgets are needed, use developer extensions (`customComponents`, `slots`, and `slotProps`) on ` ` rather than modifying core engine files.
4. Elevate visual design with engine tokens:
- Use `cardVariant: "glass"` with frosted blurs, or `cardVariant: "neumorphic"` / `"neumorphic-inset"`.
- Enable interactive cursor spotlights (`spotlight: true` or `hoverEffect: "spotlight"`).
- Use kinetic shimmer typography (`shimmer: true`, `gradientPreset: "aurora"`).
--- TASK SPECIFICATION ---
- Company / Project Name: [Insert Name]
- Industry / Vibe: [e.g. Ultra-modern AI Developer Platform, Dark Mode, Sapphire & Cyan accents]
- Target Pages: [e.g. Home (/), Pricing (/pricing), Features (/features), Docs (/docs)]
- Specific Requirements: [e.g. Exit-intent lead capture modal, Google Analytics 4 integration, Mega Menu header]
Anatomy of a High-Converting Engine Prompt
pages.
Task-Specific Prompt Recipes
Use these specialized prompt snippets for specific website building and optimization tasks:
Recipe 1 Enterprise SaaS Platform Generation
Generates complete site configuration, dark theme tokens, mega-navigation, and comparison pricing:
Using `@leoc1992/site-engine`, generate `src/config.json` and `public/theme.json` for "CognitiveMesh AI" — an autonomous workflow orchestration platform.
Requirements:
1. Theme: Dark mode (`#0b0f19` background), cyan (`#06b6d4`) primary, violet (`#8b5cf6`) secondary, `glass` cardVariant.
2. Pages: Home (`/`) with Hero (split layout, kinetic shimmer badge), Bento grid features, social proof stats, and CTA. Pricing (`/pricing`) with 3-tier comparison layout and annual billing toggle.
3. Navigation: Multi-column `mega` menu with "Products", "Solutions", and "Enterprise Guides".
4. Copywriting: Enterprise-grade, technical, and high-converting.
Recipe 2 Zero-Code Technical SEO & Rich Snippets
Optimizes search engine metadata, OpenGraph tags, and Schema.org JSON-LD structured data:
Generate a comprehensive `src/config/seo.json` for `@leoc1992/site-engine`:
1. Site: titleTemplate: "%s | QuantumFlow AI", canonical baseUrl: "https://quantumflow.ai", OpenGraph image, Twitter card summary_large_image.
2. Structured Data: Organization schema with logo and contactPoint; WebSite SearchAction schema.
3. Page Overrides: Detailed meta title, description, and FAQPage schema for `/faq`; Product/Offer schema for `/pricing`.
4. Analytics: Google Analytics 4 (G-XXXXXXXXXX) and Microsoft Clarity (clarity_project_id).
Recipe 3 Exit-Intent & High-Converting Popups
Configures lead-generation and exit modals with frequency capping and route suppression:
Add a high-converting exit-intent modal in `src/config/popups.json` using the `@leoc1992/site-engine` popups schema:
1. ID: "exit-lead-magnet", variant: "glass", trigger: "exitIntent" (sensitivity: 25px, fallbackDelayMs: 25000).
2. Frequency: maxImpressions: 2, cooldownDays: 5, oncePerSession: true, stopOnConversion: true.
3. Targeting: includeRoutes: ["/", "/pricing", "/features*"], excludeRoutes: ["/checkout", "/dashboard/*"].
4. Content: Badge: "Exclusive Sandbox", Title: "Deploy 50 Autonomous Agents Free", CTA: "Claim Instant Sandbox".
Recipe 4 Developer React Slots & Component Injection
Injects custom interactive React components into JSON-driven sections without forking the engine:
In my `@leoc1992/site-engine` Next.js/Vite app:
1. Show me how to use the `slots` prop on ` ` to inject a custom interactive 3D Three.js canvas into the hero section (`hero-media` slot).
2. Show how to use `customComponents` to replace the contact section with a multi-step Typeform-like interactive quote estimator while consuming theme tokens via `useThemeTokens()`.
Prompt Blueprint Matrix by Industry
| Industry / Use Case | Recommended Theme & Colors | Card Variant & FX | Key Sections & Layouts |
|---|---|---|---|
| AI & Developer Tools | Dark mode (#090d16), Cyan (#38bdf8), Indigo (#818cf8) | glass (blur: 20px), spotlight: true | Hero (split), Bento Grid (features), Terminal / Code, CTA |
| Enterprise Fintech | Dark mode (#0b132b), Emerald (#10b981), Slate (#94a3b8) | neumorphic, shimmer: true | Hero (centered), Security Badges, Comparison Table, FAQ |
| Creative Agency | Light mode (#fcfcfd), Coral (#f43f5e), Violet (#8b5cf6) | glass, hoverEffect: "lift" | Hero (fullscreen video), Masonry Gallery, Team Cards, Contact |
| B2B SaaS / Analytics | Light mode (#f8fafc), Sapphire (#0f52ba), Amber (#f59e0b) | elevated, spotlight: true | Hero (split), Metric Counters, 3-Tier Pricing, Popups |
File Structure
Once scaffolded, your project is highly minimized. You only need to care about the two highlighted JSON files.
my-awesome-site/
├── .npmrc <-- Pre-configured for GitHub Packages
├── AI_INSTRUCTIONS.md <-- AI Assistant rules
├── MUON_COMPONENTS_DOCS.html <-- Offline component schema docs
├── package.json
├── public/
│ ├── favicon.ico
│ └── theme.json <-- Edit this for Colors, Fonts, & Design
└── src/
├── App.jsx
├── config.json <-- Edit this to Build Your Website
└── main.jsx
Understanding config.json
The config.json file controls what appears on your website. It is divided into two main parts: the site metadata and the sections array.
{
"site": {
"title": "My Company",
"seo": {
"title": "My Company | Premium Services",
"description": "We deliver excellence.",
"keywords": ["saas", "enterprise"]
}
},
"sections": [
// Your website structural blocks go here
]
}
Multi-Page Routing
The engine natively supports React Router. If you want to build a multi-page website (instead of a Single-Page App), you can replace the sections array with a pages object mapping to different routes.
{
"site": {
"title": "My Company",
},
"pages": {
"/": {
"seo": { "title": "Home" },
"sections": [
{ "id": "hero-1", "type": "hero", "content": {...} }
]
},
"/pricing": {
"seo": { "title": "Pricing" },
"sections": [
{ "id": "pricing-1", "type": "pricing", "content": {...} }
]
}
}
}
Note: You can link between these pages seamlessly in the Header's navLinks or CTA button href properties.
Managing Sections
The sections array in config.json dictates the exact visual order of blocks on your webpage. The engine renders this array sequentially.
Add
Insert a new JSON object into the array. Provide an id, type, and content.
Remove
Delete the JSON object entirely from the array. The component is instantly removed.
Reorder
Move the JSON object up or down within the array to change its physical position on the page.
"sections": [
{
"id": "header-1",
"type": "header",
"layout": "glass",
"content": { ... }
},
{
"id": "hero-1",
"type": "hero",
"layout": "split",
"content": { ... }
}
]
Theming & Design (theme.json)
The theme.json file acts as the universal design system for the website. The engine uses this to dynamically generate CSS variables and a custom Material UI theme.
1. Auto Dark & Light Mode
You can set the theme mode to "light", "dark", or "system". If set to system, the website will natively sync with the user's OS preference.
{
"theme": {
"mode": "system",
"colors": {
"primary": "#4f46e5",
"secondary": "#ec4899"
}
}
}
2. Custom Font Uploads
You can bypass Google Fonts entirely by hosting your own fonts in the public/fonts/ directory and registering them in fontFaces.
{
"typography": {
"fontFaces": [
{
"fontFamily": "ClashDisplay",
"url": "/fonts/ClashDisplay-Bold.woff2",
"format": "woff2",
"weight": 700
}
],
"fontFamilyHeading": "ClashDisplay, sans-serif"
}
}
3. Glassmorphism Effects
You can switch the global card design from solid cards to frosted glass by using the glass variant.
{
"shape": {
"cardVariant": "glass",
"glassBlur": "16px",
"glassOpacity": 0.15
}
}
4. Micro-Interactions
Enable physics-based interactions like magnetic buttons and a custom trailing cursor.
{
"interactions": {
"customCursor": true,
"magneticButtons": true
}
}
5. Granular Style Overrides (styleOverrides)
Fine-tune margins, paddings, and styles for specific section IDs, CSS classes, or built-in Material UI components directly in JSON.
{
"styleOverrides": {
"#hero-section": {
"paddingTop": "120px",
"paddingBottom": "100px"
},
".feature-card": {
"padding": "36px",
"marginBottom": "24px"
},
"MuiButton": {
"borderRadius": "999px",
"textTransform": "none"
},
"MuiCard": {
"borderRadius": "24px"
}
}
}
6. Raw Custom CSS (customCss)
Inject raw CSS strings, keyframe animations, media queries, and responsive style rules without touching source code.
{
"customCss": "/* Custom Glowing Pulsing Keyframe */\n@keyframes pulseGlow {\n 0%, 100% { box-shadow: 0 0 20px rgba(79, 70, 229, 0.4); }\n 50% { box-shadow: 0 0 40px rgba(79, 70, 229, 0.8); }\n}\n\n.glow-button {\n animation: pulseGlow 3s infinite ease-in-out;\n}\n\n@media (max-width: 768px) {\n .custom-section { padding-top: 48px !important; }\n}"
}
Component Reference
Every object in the sections array must specify a type. Below is the documentation for all available types and their configurable properties.
Header
"type": "header"The top navigation bar. Includes a logo, navigation links, and a Call-To-Action (CTA) button. Automatically handles mobile responsiveness with a hamburger menu.
AI Context: Include exactly ONE header at the very top of the sections array for site navigation.
Available Layouts: "default", "sticky", "glass", "centered"
Overrides: Explicitly set "background": "var(--token-color-paper)" or a hex code to override transparency.
Dropdowns & Mega Menus: Add "type": "mega" and a "megaMenu" object inside navLinks for desktop flyout columns and mobile accordion sub-menus.
{
"id": "main-header",
"type": "header",
"layout": "glass",
"background": "var(--token-color-paper)",
"content": {
"logoText": "MyBrand",
"logoImage": "/logo.png",
"navLinks": [
{ "label": "Home", "href": "/" },
{
"label": "Services",
"type": "mega",
"megaMenu": {
"columns": [
{
"title": "Solutions",
"links": [
{ "label": "Cloud Engineering", "href": "/cloud" },
{ "label": "AI Solutions", "href": "/ai" }
]
}
],
"featured": {
"title": "Case Study: 10x Scale",
"image": "/featured.jpg",
"href": "/case-study"
}
}
},
{ "label": "Pricing", "href": "/pricing" }
],
"ctaButton": { "label": "Get Started", "href": "/contact", "variant": "contained" }
}
}
Hero
"type": "hero"The main landing section at the top of a webpage. High impact, designed to grab attention immediately.
AI Context: Use this as the very first section of the homepage (after the header) to introduce the core value proposition and drive a primary call to action.
Available Layouts: "split" (Text left, image right), "center" (Text centered)
Backgrounds: "mesh", "grid", or color tokens.
{
"id": "hero-1",
"type": "hero",
"layout": "split",
"background": "mesh",
"content": {
"badge": "New Release 2.0",
"title": "Build Faster",
"subtitle": "The ultimate tool for developers.",
"primaryCta": { "label": "Start Free Trial", "href": "#pricing" },
"secondaryCta": { "label": "Read Docs", "href": "#docs" },
"image": "https://images.unsplash.com/photo-xxx"
}
}
About
"type": "about"Introduce your company, mission, or vision.
AI Context: Use this section when you need a split layout (image on one side, text/mission/vision on the other) with optional statistics.
Available Layouts: "split", "default"
{
"id": "about-1",
"type": "about",
"layout": "split",
"content": {
"title": "Our Mission",
"description": "We are dedicated to building the future of the web.",
"image": "https://images.unsplash.com/photo-xxx",
"stats": [
{ "value": "10+", "label": "Years Experience" },
{ "value": "500+", "label": "Clients" }
]
}
}
Features
"type": "features"Displays a list of product features, value propositions, or services.
AI Context: Use this extensively to highlight product capabilities in a grid of 3 or 4 columns. It's the bread-and-butter of SaaS landing pages.
Available Layouts: "grid" (Standard cards), "bento" (Asymmetrical grid), "tabs" (Interactive left/right)
{
"id": "features-1",
"type": "features",
"layout": "bento",
"content": {
"title": "Why Choose Us",
"subtitle": "Everything you need to succeed.",
"items": [
{
"icon": "cloud", // Lucide-react icon name
"title": "Cloud Sync",
"description": "Always backed up securely."
}
]
}
}
Clients
"type": "clients"Display logos of companies you have worked with to establish trust.
AI Context: Place this immediately after the hero section (or bottom of page) to provide social proof.
Available Layouts: "grid", "marquee" (infinite horizontal scroll)
{
"id": "clients-1",
"type": "clients",
"layout": "marquee",
"content": {
"title": "Trusted by industry leaders",
"logos": [
{ "name": "Company A", "image": "/logo-a.png" },
{ "name": "Company B", "image": "/logo-b.png" }
]
}
}
Pricing
"type": "pricing"Displays subscription tiers or service packages.
AI Context: Use this to display standard 3-tier SaaS pricing models.
Available Layouts: "cards"
{
"id": "pricing-1",
"type": "pricing",
"layout": "cards",
"content": {
"title": "Simple Pricing",
"plans": [
{
"name": "Pro",
"price": "$29",
"period": "/mo",
"popular": true, // Elevates and highlights this card
"features": ["Feature A", "Feature B"],
"cta": "Buy Now"
}
]
}
}
Stats
"type": "stats"Highlight numerical achievements, user counts, or operational metrics.
AI Context: Great for building credibility right above the footer or below the features section.
Available Layouts: "grid"
{
"id": "stats-1",
"type": "stats",
"layout": "grid",
"content": {
"title": "By the numbers",
"items": [
{ "value": "10M+", "label": "Active Users" },
{ "value": "99.9%", "label": "Uptime" }
]
}
}
Team
"type": "team"Introduce your team members, founders, or board of directors.
AI Context: Standard grid layout for an "About Us" page or agency site to show the faces behind the company.
Available Layouts: "grid"
{
"id": "team-1",
"type": "team",
"layout": "grid",
"content": {
"title": "Meet the Team",
"members": [
{
"name": "Alice Smith",
"role": "CEO",
"image": "https://images.unsplash.com/photo-xxx",
"social": { "twitter": "#", "linkedin": "#" }
}
]
}
}
Testimonials
"type": "testimonials"Social proof and client reviews.
AI Context: Include this to build trust. Marquee layout is best for SaaS, grid is best for agencies.
Available Layouts: "grid", "carousel", "marquee"
{
"id": "testimonials-1",
"type": "testimonials",
"layout": "marquee",
"content": {
"title": "Loved by thousands",
"items": [
{
"quote": "This product changed my life completely.",
"author": "Jane Doe",
"role": "CEO, Startup"
}
]
}
}
Timeline
"type": "timeline"Display a chronological company history, roadmap, or process steps.
AI Context: Use for "How it works" steps (1, 2, 3) or company history.
Available Layouts: "vertical"
{
"id": "timeline-1",
"type": "timeline",
"layout": "vertical",
"content": {
"title": "Our Journey",
"events": [
{
"year": "2024",
"title": "Company Founded",
"description": "Started in a garage."
}
]
}
}
Gallery
"type": "gallery"Showcase high-resolution images of your products, portfolio, or office.
AI Context: Use this for visual portfolios, photography, or event showcases.
Available Layouts: "masonry", "grid"
{
"id": "gallery-1",
"type": "gallery",
"layout": "masonry",
"content": {
"title": "Our Work",
"images": [
{ "src": "https://images.unsplash.com/...", "alt": "Project Alpha" }
]
}
}
Articles
"type": "articles"Display a blog feed, recent news articles, or press releases.
AI Context: Great for adding a "Latest News" section near the bottom of a homepage.
Available Layouts: "grid", "list"
{
"id": "articles-1",
"type": "articles",
"layout": "grid",
"content": {
"title": "Latest News",
"posts": [
{
"title": "Understanding the Cloud",
"excerpt": "A brief guide to...",
"date": "Oct 12, 2026",
"image": "https://images.unsplash.com/...",
"link": "/blog/cloud"
}
]
}
}
FAQ
"type": "faq"Frequently Asked Questions using accessible, expandable accordions.
AI Context: Include this to address common objections before a CTA.
Available Layouts: "default" (Stacked list), "grid" (2-column layout)
{
"id": "faq-1",
"type": "faq",
"layout": "default",
"content": {
"title": "Common Questions",
"items": [
{
"question": "How do I sign up?",
"answer": "Click the button in the header."
}
]
}
}
CTA (Call To Action)
"type": "cta"High-conversion block intended to drive users to sign up or contact sales, typically placed just before the footer.
AI Context: The ultimate conversion point. Use right above the footer or Newsletter block.
Available Layouts: "default", "split"
{
"id": "cta-1",
"type": "cta",
"layout": "default",
"background": "gradient",
"content": {
"title": "Ready to get started?",
"subtitle": "Join thousands of users today.",
"primaryCta": { "label": "Start Trial", "href": "/signup" }
}
}
Contact
"type": "contact"Displays contact information and a functional contact form UI.
AI Context: Typically used on a dedicated /contact page.
Available Layouts: "split", "center"
{
"id": "contact-1",
"type": "contact",
"layout": "split",
"content": {
"title": "Get in Touch",
"email": "[email protected]",
"phone": "+1 234 567 8900",
"address": "123 Main St, City"
}
}
Bento Grids
"type": "bento"Create asymmetrical "Apple-style" layouts using colSpan and rowSpan.
AI Context: Extremely popular modern design trend. Use this instead of standard grids if the user asks for a "modern Apple-like feel".
{
"id": "bento-1",
"type": "bento",
"layout": { "columns": 3 },
"content": {
"blocks": [
{ "title": "Large Feature", "colSpan": 2, "rowSpan": 2 },
{ "title": "Small Stat", "colSpan": 1, "rowSpan": 1 }
]
}
}
Comparison Tables
"type": "comparison"Build SaaS feature matrices (Us vs Them, Free vs Pro) with sticky headers.
AI Context: Use this below the Pricing section for deep-dive feature comparisons.
{
"id": "comparison-1",
"type": "comparison",
"content": {
"columns": [{ "title": "Feature" }, { "title": "Pro" }],
"rows": [
{ "label": "API Access", "values": [true] }
]
}
}
Content Tabs
"type": "tabs"Interactive switchers for grouping use-cases without long scrolling.
AI Context: Excellent for pages with "Solutions for X, Y, Z" to avoid overwhelming the user.
{
"id": "tabs-1",
"type": "tabs",
"content": {
"tabs": [
{ "label": "Developers", "title": "Built for Code", "image": "/dev.jpg" },
{ "label": "Designers", "title": "Pixel Perfect", "image": "/design.jpg" }
]
}
}
Interactive Maps
"type": "map"Easily embed Google Maps or OpenStreetMap iframes in a styled glass container.
AI Context: Use on local business websites or Contact pages to show physical locations.
{
"id": "map-1",
"type": "map",
"content": {
"title": "Visit Us",
"embedUrl": "https://www.google.com/maps/embed?..."
}
}
Infinite Marquees
"type": "marquee"Seamless looping tickers for logos, keywords, or stock prices.
AI Context: Use this as a dynamic divider between large sections, or for client logos.
{
"id": "marquee-1",
"type": "marquee",
"content": {
"speed": "fast",
"direction": "left",
"items": [
{ "image": "/logo1.png" },
{ "text": "BREAKING NEWS" }
]
}
}
3D WebGL (Spline)
"type": "spline"Embed interactive 3D Spline experiences alongside your text.
AI Context: Add a massive wow factor to landing pages. Use this in a split layout next to a Hero or Feature block.
{
"id": "spline-1",
"type": "spline",
"content": {
"title": "Interactive 3D",
"splineUrl": "https://my.spline.design/xxxx/"
}
}
🎬 Global Video Modals
Any button in the entire engine can trigger a cinematic, full-screen YouTube Lightbox Modal without writing a single line of JavaScript. Just set the button's href to #video-YOUTUBE_ID.
{
"label": "Watch Trailer",
"href": "#video-dQw4w9WgXcQ"
}
Forms & Integrations
The contact and newsletter components support out-of-the-box data capture via Web3Forms or generic webhooks (like Zapier, Make, or your own custom API).
1. Web3Forms (Email Delivery)
Web3Forms allows you to receive form submissions directly to your email without any backend server. Simply get a free Access Key from their website.
{
"type": "contact",
"content": {
"title": "Contact Us",
"formIntegration": {
"provider": "web3forms",
"accessKey": "YOUR_WEB3FORMS_ACCESS_KEY"
}
}
}
2. Generic Webhooks (Zapier / Custom APIs)
If you want to send data to Zapier, Make.com, or your own database, use the webhook provider. The engine will send a POST request with the JSON payload.
{
"type": "newsletter",
"content": {
"title": "Subscribe",
"formIntegration": {
"provider": "webhook",
"endpoint": "https://hooks.zapier.com/hooks/catch/123456/"
}
}
}
Rich Media Backgrounds
Any major section (like hero or features) supports a backgroundMedia object to inject looping videos, interactive 3D Spline scenes, or WebGL shaders natively behind your content.
1. Cinematic Video Backgrounds
Set the type to video to autoplay an mp4 or webm silently behind the text.
{
"type": "hero",
"backgroundMedia": {
"type": "video",
"url": "/assets/my-cinematic-bg.mp4",
"opacity": 0.5,
"overlayColor": "#000000"
},
"content": {
"title": "Welcome to the Future"
}
}
2. Interactive 3D (Spline & WebGL)
Set the type to iframe to seamlessly embed a 3D scene from Spline. The engine automatically handles pointer-events so it doesn't block scrolling.
{
"type": "hero",
"backgroundMedia": {
"type": "iframe",
"url": "https://my.spline.design/your-scene-url/",
"opacity": 1.0,
"overlayColor": "transparent"
}
}
3. Lottie Animations
Set the type to lottie to natively parse and play lightweight JSON vector animations.
{
"type": "hero",
"backgroundMedia": {
"type": "lottie",
"url": "/assets/hero-animation.json",
"opacity": 0.8
}
}
4. Parallax Scrolling Depth
You can add "parallax": true to any background media to instantly enable hardware-accelerated scroll depth effects powered by Framer Motion.
{
"type": "features",
"backgroundMedia": {
"type": "video",
"url": "/assets/stars-bg.mp4",
"parallax": true
}
}
Architecture & SEO
The engine goes beyond UI components, providing deep infrastructural layers for SEO, Internationalization, and Next.js support.
1. i18n Multi-Language
Define a global i18n dictionary in your config. Use the {{t:key}} syntax in any text field to dynamically interpolate translations based on the active locale.
{
"i18n": {
"defaultLocale": "en",
"translations": {
"en": { "hero_title": "Welcome" },
"fr": { "hero_title": "Bienvenue" }
}
},
"sections": [
{
"type": "hero",
"content": { "title": "{{t:hero_title}}" }
}
]
}
2. Dynamic OpenGraph & SEO
Define an seo block in your config. The engine will dynamically inject `<title>` and `<meta>` tags into the document head for social sharing, as well as auto-inject Google Analytics if you provide a googleTagId.
AI Context: ALWAYS proactively ask the user if they want Google Analytics. If yes, instruct them to provide their Measurement ID (G-XXXX) and inject it here.
{
"seo": {
"title": "Muon Site Engine",
"description": "The best platform.",
"ogImage": "https://mysite.com/og.jpg",
"googleTagId": "G-XXXXXXXXXX"
}
}
3. A/B Testing Engine
Run split tests without external tools. Define abTests and the engine will roll a weighted dice, save the cohort to localStorage, and patch the JSON config on the fly.
{
"abTests": {
"hero_cta": {
"weights": [50, 50],
"variants": [
{ "sections": [ { "type": "hero", "content": { "title": "Buy Now" } } ] },
{ "sections": [ { "type": "hero", "content": { "title": "Start Free" } } ] }
]
}
}
}
4. Next.js Adapter
Building a Next.js App Router project? We export a dedicated NextEngineProvider that uses the "use client" directive to safely wrap the engine and bypass SSR hydration mismatches.
Custom Component Overrides
The Muon Site Engine gives developers total control over rendering. You can inject custom React components into any page using the customComponents prop on DynamicPage or DynamicSections.
Resolution Priority Hierarchy:
customComponents[id] (Target specific section by unique ID) →
customComponents[type] (Override all sections of a given type) →
SECTION_REGISTRY[type] (Core Engine Default)
Example: Overriding a Section by ID or Type
import React from 'react';
import { DynamicPage, PrimitiveCard, PrimitiveTypography, useThemeTokens } from '@site-engine/core';
// Custom Interactive Widget Component
function CustomInteractivePricing({ content, isDark }) {
const { colors } = useThemeTokens();
return (
<div className="p-8 my-12" style={{ background: colors.background }}>
<PrimitiveTypography variant="h2" shimmer>
{content.title || 'Custom Billing Engine'}
</PrimitiveTypography>
<p>Bypassed standard layout with fully custom React state!</p>
</div>
);
}
// Pass customComponents directly to DynamicPage
export default function Page({ config }) {
return (
<DynamicPage
config={config}
slug="/"
customComponents={{
// Target a specific section by its 'id' in config.json
'custom-hero-01': MyCustom3DHero,
// Or override all pricing sections globally
pricing: CustomInteractivePricing,
}}
/>
);
}
Slots & Render Props Injection
Want to use the built-in sections but inject custom UI elements (like an interactive annual billing switch, email validation form, or 3D badge) without replacing the whole section? Use Slots and SlotProps.
| Component | Available Slots | Description |
|---|---|---|
| HeroSection | badge, actions, media, background | Inject custom CTAs, 3D canvas, or glowing badge overlays. |
| PricingSection | billingToggle, planFooter, planBadge | Inject custom currency switchers or annual/monthly toggles. |
| CTASection | form, actions, background | Inject custom multi-step lead capture or Hubspot forms. |
| PrimitiveCard | header, footer, media | Composable card header/footer subcomponents. |
| PrimitiveContainer | top, bottom, background | Full section backdrop overlays or divider decorations. |
Example: Injecting a Slot into Pricing
<DynamicPage
config={config}
slug="/pricing"
slots={{
pricing: {
billingToggle: (
<div className="flex justify-center items-center gap-3 my-6">
<span className="text-sm font-semibold">Monthly</span>
<Switch onChange={(e) => setIsAnnual(e.target.checked)} />
<span className="text-sm font-semibold text-indigo-600">Annual (Save 20%)</span>
</div>
)
}
}}
/>
useThemeTokens Hook API
The useThemeTokens() hook provides instant, reactive access to computed palette colors, typography fonts, shape radii, glassmorphism tokens, and neumorphic box shadows.
import { useThemeTokens } from '@site-engine/core';
export function CustomCard() {
const { colors, typography, shapes, effects, isDark } = useThemeTokens();
return (
<div
style={{
background: colors.cardBackground,
borderRadius: shapes.borderRadius,
boxShadow: effects.neumorphic,
border: effects.glassBorder,
padding: shapes.cardPadding,
fontFamily: typography.bodyFont,
}}
>
<h3 style={{ color: colors.primary, fontFamily: typography.headingFont }}>
Token Synchronized Card
</h3>
</div>
);
}
Interactive Cursor Spotlight Cards
Replicate the signature Linear, Raycast, and Apple glowing card effect. When the cursor hovers and moves over the card, an ambient radial glow follows the cursor position with hardware-accelerated precision.
PrimitiveCard Spotlight
Add spotlight={true} or hoverEffect="spotlight" directly to any PrimitiveCard.
<PrimitiveCard spotlight spotlightColor="rgba(99, 102, 241, 0.25)">
<h4>Interactive Card</h4>
</PrimitiveCard>
PrimitiveSpotlight Wrapper
Wrap entire grids with PrimitiveSpotlight to track coordinates across all child cards simultaneously.
<PrimitiveSpotlight>
<PrimitiveGrid columns={3}>
<PrimitiveCard spotlight>Card 1</PrimitiveCard>
<PrimitiveCard spotlight>Card 2</PrimitiveCard>
</PrimitiveGrid>
</PrimitiveSpotlight>
Kinetic Shimmer & Gradient Typography
Turn static text into eye-catching, high-converting focal points with kinetic shimmer shine animations and curated gradient presets.
Preset: aurora
Cyan → Blue → Slate
Preset: sunset
Neon Crimson → Peach
Preset: cyberpunk
Fuchsia → Purple → Sky Blue
Preset: gold
Metallic Lustrous Gold
Preset: silver
Platinum Chrome
Preset: ocean
Emerald → Deep Cyan
// Shimmer Animated Heading
<PrimitiveTypography variant="h1" shimmer>
Next-Gen Cloud Architecture
</PrimitiveTypography>
// Aurora Gradient Heading
<PrimitiveTypography variant="h2" gradient gradientPreset="aurora">
Supercharged Developer Engine
</PrimitiveTypography>
Neumorphic & Inset Styling
Create soft, tactile, embossed interfaces with extruded or recessed shadows tailored for both Light and Dark themes.
Extruded Neumorphic
variant="neumorphic"
<PrimitiveCard variant="neumorphic">
<p>Soft Extruded Surface</p>
</PrimitiveCard>
Inset / Recessed Neumorphic
variant="neumorphic-inset" or inset={true}
<PrimitiveCard variant="neumorphic-inset">
<p>Recessed Surface Well</p>
</PrimitiveCard>
Enhanced Glassmorphism
Achieve Apple-level frosted glass with specular border illumination, multi-layer backdrop blurs, and gradient transparency.
{
"theme": {
"shape": {
"cardVariant": "glass",
"glassBlur": "20px",
"glassOpacity": 0.5
}
}
}
Aurora Mesh & Spotlight Backdrops
Set section backdrops to fluid multi-color ambient radial meshes using background="aurora" or glowing top beams with background="spotlight" in PrimitiveContainer.
<PrimitiveContainer background="aurora" paddingY="120px">
<HeroSection content={heroContent} />
</PrimitiveContainer>
Enterprise JSON-Driven SEO Subsystem
The Muon Site Engine provides a 100% JSON-driven Technical SEO, Analytics, and Structured Data engine. An external SEO team or marketing agency can configure, optimize, and audit meta tags, JSON-LD schemas, webmaster verifications, and analytics trackers without modifying any React source code.
Decoupled SEO JSON
Provide an independent seo.json or embed directly inside config.json under the seo key.
Schema.org JSON-LD
Automated generation of Organization, LocalBusiness, WebSite (SearchAction), BreadcrumbList, FAQPage, and Product schemas.
Zero-Latency Trackers
Asynchronous, non-blocking injection of GA4, GTM, Meta Pixel, Microsoft Clarity, and custom tracking scripts.
1. Complete seo.json Configuration
Pass an SEO config file directly to <EngineProvider seo={seoJson}> or <DynamicPage seo={seoJson}>:
{
"$schema": "https://muoninfotech.com/schemas/website-os.seo.json",
"site": {
"siteName": "QuantumFlow AI",
"baseUrl": "https://quantumflow.ai",
"titleTemplate": "%s | QuantumFlow AI",
"defaultTitle": "QuantumFlow AI - Next-Gen Autonomous Enterprise Platform",
"defaultDescription": "Orchestrate multi-agent workflows, autonomous services, and observability.",
"defaultOgImage": "https://quantumflow.ai/og-banner.jpg",
"themeColor": "#0f172a",
"language": "en",
"robots": "index, follow, max-image-preview:large",
"keywords": ["AI Platform", "Autonomous Agents", "Enterprise Intelligence"]
},
"verification": {
"google": "google-site-verification-token",
"bing": "bing-verification-token",
"yandex": "yandex-token",
"pinterest": "pinterest-meta-key",
"facebookDomain": "facebook-domain-verification-token"
},
"analytics": {
"googleAnalytics": {
"measurementId": "G-XXXXXXXXXX",
"anonymizeIp": true,
"sendPageView": true
},
"googleTagManager": {
"containerId": "GTM-XXXXXXX"
},
"metaPixel": {
"pixelId": "123456789012345"
},
"microsoftClarity": {
"projectId": "clarity_sample_id"
}
},
"structuredData": {
"organization": {
"type": "Corporation",
"name": "QuantumFlow AI Inc.",
"url": "https://quantumflow.ai",
"logo": "https://quantumflow.ai/logo.png",
"sameAs": [
"https://twitter.com/quantumflow",
"https://linkedin.com/company/quantumflow"
]
},
"enableSearchAction": true
},
"pages": {
"/": {
"title": "QuantumFlow AI - Autonomous Enterprise Intelligence",
"description": "Unified platform to design and deploy autonomous multi-agent systems.",
"canonical": "https://quantumflow.ai/"
},
"/pricing": {
"title": "Predictable Enterprise Pricing",
"description": "Transparent tiers from startup scale to dedicated clusters.",
"structuredData": {
"product": {
"name": "QuantumFlow Enterprise Cluster",
"price": "499.00",
"priceCurrency": "USD",
"brand": "QuantumFlow AI"
}
}
},
"/faq": {
"title": "Frequently Asked Questions",
"description": "Compliance, security, SOC2, latency, and integration FAQ.",
"autoFaqSchema": true
}
}
}
2. OpenGraph, Twitter Cards & Reactive Head Injection
When a user navigates between routes, SEOMetadata automatically updates the document title, canonical link, OpenGraph tags (og:title, og:description, og:image, og:url), and Twitter Cards (twitter:card, twitter:site) synchronously.
import { EngineProvider, DynamicPage } from '@leoc1992/site-engine';
import config from './config.json';
import seoConfig from './seo.json';
export default function App() {
return (
<EngineProvider config={config} seo={seoConfig}>
<DynamicPage />
</EngineProvider>
);
}
3. Schema.org JSON-LD Builders
The engine automatically creates rich, search-engine ready JSON-LD payloads for Google Search Rich Results:
| Schema Type | JSON Configuration | Google Search Impact |
|---|---|---|
| Organization / Corporation | structuredData.organization |
Brand Knowledge Graph card with logo and social links |
| LocalBusiness | structuredData.localBusiness |
Google Maps & Local Pack integration with address & phone |
| WebSite (SearchAction) | structuredData.enableSearchAction: true |
Direct Google Sitelinks Searchbox in search results |
| BreadcrumbList | Automatic on all subpage routes | Hierarchical navigation crumbs in search snippets |
| FAQPage | faqItems or autoFaqSchema: true |
Expandable rich FAQ dropdowns under search listing |
| Product / Offer | pages["/pricing"].structuredData.product |
Pricing, currency, and availability rich badges |
4. Analytics, GTM, Meta Pixel & Clarity
Trackers are safely loaded with async script injection. Single-page route transitions trigger automatic virtual pageviews across all configured measurement IDs:
import { trackPageView, initAnalytics } from '@leoc1992/site-engine';
// Track custom page transition manually if needed
trackPageView('/custom-route', 'Custom Page Title');
5. Sitemap & Robots.txt Generators
Export static sitemap.xml and robots.txt strings directly from your build pipeline or Next.js / Vite API route:
import { generateSitemap, generateRobotsTxt } from '@leoc1992/site-engine';
import seoConfig from './src/config/seo.json';
// Generate sitemap.xml
const sitemapXml = generateSitemap(seoConfig);
// Generate robots.txt
const robotsTxt = generateRobotsTxt(seoConfig, {
disallow: ['/admin', '/dashboard/private']
});
JSON-Driven Popups & Exit-Intent Subsystem
Turn departing visitors into leads and customers with zero custom code. The engine features a fully integrated modal and trigger system capable of detecting cursor velocity, window boundary exit, scroll depth, and idle timeouts, paired with client-side impression capping and cooldown persistence.
Exit-Intent Tracking
Tracks cursor velocity toward top viewport boundary on desktop and visibility change on mobile devices.
Frequency Capping
Configurable impression limits, cooldowns in days/hours, session suppression, and permanent conversion locking.
Visual Stunners & Slots
Built-in glassmorphism and neumorphism modal styles with full developer slot override capability.
1. Popups JSON Specification
Popups can be defined directly inside config.json under the popups array or passed via <EngineProvider popups={popupsJson}> / <DynamicPage popups={popupsJson}>:
[
{
"id": "exit-lead-magnet",
"enabled": true,
"type": "leadCapture",
"variant": "glass",
"trigger": {
"type": "exitIntent",
"sensitivity": 20,
"fallbackDelayMs": 20000
},
"frequency": {
"maxImpressions": 2,
"storage": "local",
"cooldownDays": 7,
"oncePerSession": true,
"stopOnConversion": true
},
"targeting": {
"includeRoutes": ["/", "/pricing", "/features*"],
"excludeRoutes": ["/checkout", "/dashboard/*"],
"device": "all"
},
"content": {
"badge": "Limited Time Offer",
"title": "Before you leave — Claim 30 Days Free Sandbox Access",
"description": "Join 5,000+ AI engineers deploying autonomous workflows with sub-millisecond orchestration.",
"image": "https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?auto=format&fit=crop&w=600&q=80",
"inputPlaceholder": "Enter your work email",
"ctaText": "Claim Free Access",
"secondaryCtaText": "No thanks, I'll explore later",
"disclaimer": "No credit card required. Instant sandbox provisioning."
},
"animation": {
"backdropBlur": "16px"
}
}
]
2. Supported Trigger Types
Choose from four reactive trigger mechanisms:
| Trigger Type | Parameters | Description |
|---|---|---|
| exitIntent | sensitivity (px), fallbackDelayMs (ms) | Fires when mouse departs top of viewport or user switches browser tabs on mobile. |
| timeDelay | delayMs (ms) | Fires after the visitor spends N milliseconds on the page. |
| scrollDepth | percentage (%) | Fires once the visitor scrolls past a percentage (e.g. 50% or 75%) of the document height. |
| inactivity | timeoutMs (ms) | Fires when no mouse, keyboard, or scroll movement is detected for N milliseconds. |
3. Frequency Capping & Target Rules
Prevent user fatigue by enforcing intelligent suppression rules:
maxImpressions: Maximum number of times the popup can ever be displayed to a single browser.cooldownDays/cooldownHours: Minimum delay before the popup is eligible to reappear.oncePerSession: Restricts display to at most once per active browser session.stopOnConversion: Permanently locks and suppresses the popup once the user submits the form or clicks CTA.includeRoutes/excludeRoutes: Target specific URL routes with wildcard pattern matching (e.g.["/features*"]).
4. Developer Custom Slot Overrides
Need to replace the modal UI with a custom React component while retaining the engine's exit-intent detection and frequency engine? Use the slots prop:
import React from 'react';
import { DynamicPage } from '@leoc1992/site-engine';
import config from './src/config/config.json';
import popups from './src/config/popups.json';
function CustomExitModal({ popup, onClose, onConvert }) {
return (
<div className="bg-slate-950 p-8 rounded-3xl border border-indigo-500/30 text-white max-w-md">
<h3 className="text-2xl font-black">{popup.content.title}</h3>
<p className="text-slate-400 mt-2">{popup.content.description}</p>
<button onClick={() => { onConvert(popup.id); onClose(); }} className="mt-4 px-6 py-3 bg-indigo-600 rounded-xl">
Claim Voucher
</button>
</div>
);
}
export default function App() {
return (
<DynamicPage
customConfig={config}
popups={popups}
slots={{
'popup-exit-lead-magnet': CustomExitModal
}}
/>
);
}
Future Enhancements Coming Soon
We are constantly evolving the Muon Site Engine to be the most powerful, highly-customizable JSON-driven platform on the web. Below is our comprehensive roadmap for upcoming features.
CMS Integration
- • Contentful/Sanity Connectors: Direct fetch support for headless CMS content.
- • Blog Engines: Markdown/MDX parser integration for long-form content.
E-Commerce Ready
- • Stripe Integration: Native buy buttons and pricing table checkout links.
- • Product Grids: Specialized components for displaying SKUs, prices, and reviews.
- • Slide-Out Cart: Global context cart drawer for multi-page shopping.