Documentation

1. Introduction

The Xivig Philosophy

Xivig is engineered for developers who demand clean code, modularity, and high performance. Unlike traditional admin templates that ship with bloated jQuery plugins and messy HTML, Xivig uses a modern Hybrid Workflow (Vite + Gulp) and Vanilla JS logic to ensure your application remains fast even as it scales to hundreds of pages.

Modular UI

Handlebars-based components ensure you write code once and deploy it everywhere.

Performance First

Assets are optimized, images are compressed, and JS is bundled into tiny chunks.

Theme Aware

Native Dark Mode support built into the CSS variable-driven design tokens.

2. Tech Stack

Technology	Role	Benefit
Bootstrap 5.3	Core UI Framework	Responsive grid and robust component base.
Vite 5.x	Development Server	Instant HMR and modern JS bundling.
Gulp 5.x	Production Pipelines	Advanced image optimization and vendor exports.
Handlebars	Templating Engine	Partial-based layouts for modularity.

3. Getting Started

Available CLI Commands

DEV npm run dev

Starts the Vite dev server at localhost:3000. Features Hot Module Replacement (HMR) for both SCSS and HTML partials.

BUILD npm run build

Triggers the Gulp production pipeline. Optimizes images, compiles minified assets, and generates the final dist/ folder.

Configuration Note

Always ensure you are using Node v18+. If dependencies fail to install, try deleting package-lock.json and running npm install again.

4. Folder Structure

app/

pages/ // HTML Source

src/

partials/ // HBS Components

scss/ // System Styles

scripts/ // Module Logic

tasks/ // Gulp Pipelines

public/ // Static Vendors

Key Definitions:

src/partials: Essential blocks like header, sidebar, and layout templates.
src/scss: Uses Dart Sass module system. Variables and tokens are central.
public/: Files here are copied directly to dist/ without processing.
tasks/: Contains individual Gulp task logic for exports and optimization.

5. Theme & Colors

Xivig uses Design Tokens (CSS Variables) to manage themes. Dark mode is triggered by the data-bs-theme="dark" attribute on the <html> tag.

Modifying Brand Colors:

To change the primary identity, update the tokens in src/scss/_tokens.scss:

// Light Token
--elite-primary: #6366f1;
--bg-body: #f8fafc;

// Dark Token Override
[data-bs-theme="dark"] {
--bg-body: #0b0f12;
--card-bg: #15191c;
}

JS Initialization

Theme persistence is handled via localStorage in src/scripts/settings.js, ensuring the user's preference is remembered across sessions.

6. Component Usage

Adding a Notification Badge

Xivig features a modular notification badge system. Use the Handlebars partial to insert it anywhere:

5

Dynamic Management (JS):

import { NotificationBadge } from './scripts/notification-badge.js';

// Initialize
const myBadge = new NotificationBadge('my-badge');
myBadge.setCount(10); // Updates UI instantly

7. Deployment

Production Ready

When you are ready to deploy, run npm run build. This generates a clean dist/ folder containing:

Minified Assets: All CSS and JS files are bundled and uglified.
Image Optimization: All PNG/JPG assets are compressed via Gulp.
Clean Paths: Vite ensures all asset links are relative and ready for any host (GitHub Pages, Netlify, Vercel).

Hosting on GitHub Pages?

Ensure the .nojekyll file (included in public/) is present in your root directory to prevent build errors.

Interface Architect

Global Theme

Sidebar Style

Menu Dropdown Icon