Getting Started

Everything you need to start building with the Nimbus framework.

What is Nimbus?

Nimbus is a custom CSS framework designed for modern web applications, dashboards, and SaaS products. It provides a clean, minimal, and fully customizable set of components, utilities, and layouts.

Why Use Nimbus?

Built for dashboards, SaaS, and data-driven apps with pricing tables, status indicators, and more
CSS custom properties for full theming and brand customization without writing new CSS
Lightweight with no JavaScript dependencies
Dark mode built-in with automatic system preference detection
Responsive mobile-first design that works on all screen sizes

Key Features

CSS Variables Dark Mode Responsive No Dependencies Full-Stack Ready Customizable

Info Nimbus is designed to work with any brand. All colors, fonts, and spacing can be customized through CSS variables.

Installation

Getting started with Nimbus is straightforward. Follow these steps to add the framework to your project.

Download

Download the Nimbus framework files and include them in your project directory. You only need the CSS file to get started, but the JavaScript file provides additional interactive components.

Include in HTML

Add the following lines to your HTML file's <head> section. Make sure to load Google Fonts for Inter and JetBrains Mono.

HTML

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Hosting Website</title>

    <!-- Google Fonts -->
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">

    <!-- Nimbus CSS -->
    <link rel="stylesheet" href="css/main.css">
</head>
<body>

    <!-- Your content here -->

    <!-- Nimbus JS (optional, for interactive components) -->
    <script src="js/main.js"></script>
</body>
</html>

File Structure

Place the CSS and JavaScript files in your project directory. The recommended structure is:

File Tree

my-project/
├── css/
│   └── main.css
├── js/
│   └── main.js
├── index.html
└── pages/
    ├── pricing.html
    ├── contact.html
    └── ...

Warning The Google Fonts link is required. Nimbus uses Inter and JetBrains Mono for its typography system.

CSS Variables

Nimbus uses CSS custom properties (variables) for a comprehensive theming system. Override these variables to customize every aspect of the framework.

How It Works

All design tokens are defined as CSS custom properties on the :root selector. This means you can override any variable globally or scope overrides to specific elements.

CSS

/* All variables are defined on :root */
:root {
    --hu-primary: #2563eb;
    --hu-success: #16a34a;
    --hu-warning: #f59e0b;
    --hu-danger: #dc2626;
    --hu-info: #0ea5e9;
    --hu-bg: #ffffff;
    --hu-text: #171717;
    --hu-border: #e5e5e5;
}

Key Variables Reference

The table below shows the most commonly used CSS variables and their default values.

Variable	Default (Light)	Default (Dark)	Description
`--hu-primary`	`#2563eb`	`#60a5fa`	Primary brand color
`--hu-primary-hover`	`#1d4ed8`	`#93bbfd`	Primary color on hover
`--hu-success`	`#16a34a`	`#16a34a`	Success/positive state color
`--hu-warning`	`#f59e0b`	`#f59e0b`	Warning/caution state color
`--hu-danger`	`#dc2626`	`#dc2626`	Danger/error state color
`--hu-info`	`#0ea5e9`	`#0ea5e9`	Informational state color
`--hu-bg`	`#ffffff`	`#0a0a0a`	Main background color
`--hu-bg-secondary`	`#fafafa`	`#141414`	Secondary background color
`--hu-text`	`#171717`	`#fafafa`	Primary text color
`--hu-text-secondary`	`#525252`	`#a3a3a3`	Secondary text color
`--hu-text-muted`	`#a3a3a3`	`#525252`	Muted text color
`--hu-border`	`#e5e5e5`	`#262626`	Default border color
`--hu-border-strong`	`#d4d4d4`	`#404040`	Strong/emphasized border color
`--hu-radius-md`	`0.375rem`		Default border radius
`--hu-radius-lg`	`0.5rem`		Large border radius
`--hu-radius-xl`	`0.75rem`		Extra large border radius
`--hu-shadow-sm`	Small shadow		Small box shadow
`--hu-shadow-md`	Medium shadow		Medium box shadow
`--hu-shadow-lg`	Large shadow		Large box shadow
`--hu-font-sans`	`'Inter', sans-serif`		Primary font family
`--hu-font-mono`	`'JetBrains Mono', monospace`		Monospace font family
`--hu-space-4`	`1rem`		Base spacing unit
`--hu-header-height`	`4rem`		Header height
`--hu-sidebar-width`	`16rem`		Sidebar width

Dark Theme

Dark mode is handled via the [data-theme="dark"] attribute selector on the <html> element. All color variables are automatically swapped when the theme changes.

Dark theme preview:

CSS

/* Dark theme overrides */
[data-theme="dark"] {
    --hu-primary: #60a5fa;
    --hu-primary-hover: #93bbfd;
    --hu-bg: #0a0a0a;
    --hu-bg-secondary: #141414;
    --hu-text: #fafafa;
    --hu-text-secondary: #a3a3a3;
    --hu-border: #262626;
}

Customization

Customize Nimbus to match your brand by overriding CSS variables. This is the recommended approach for theming.

Override Variables Globally

Create a custom CSS file and link it after main.css to override default variables.

HTML

<!-- Nimbus CSS first -->
<link rel="stylesheet" href="css/main.css">
<!-- Your custom overrides after -->
<link rel="stylesheet" href="css/custom.css">

CSS

/* custom.css - Your brand overrides */
:root {
    /* Brand Colors */
    --hu-primary: #7c3aed;
    --hu-primary-hover: #6d28d9;
    --hu-primary-active: #5b21b6;
    --hu-primary-light: #ede9fe;
    --hu-primary-lighter: #f5f3ff;

    /* Layout */
    --hu-header-height: 3.5rem;
    --hu-sidebar-width: 14rem;

    /* Typography */
    --hu-font-sans: 'Your Brand Font', sans-serif;

    /* Border Radius */
    --hu-radius-lg: 0.75rem;
    --hu-radius-xl: 1rem;
}

Customize Dark Mode

You can also customize dark mode by overriding variables inside the [data-theme="dark"] selector.

CSS

/* Custom dark mode overrides */
[data-theme="dark"] {
    --hu-primary: #a78bfa;
    --hu-primary-hover: #c4b5fd;
    --hu-bg: #0f0f14;
    --hu-bg-secondary: #16161e;
    --hu-border: #2e2e3e;
}

Theme Toggle Behavior

The JavaScript includes a theme toggle module that stores the user's preference in localStorage. It also respects the user's system preference via prefers-color-scheme.

Click the button to toggle light/dark mode

HTML

<button data-theme-toggle aria-label="Toggle theme">
    <svg class="sun-icon">...sun icon...</svg>
    <svg class="moon-icon">...moon icon...</svg>
</button>

<script src="js/main.js"></script>

JavaScript

Nimbus's JavaScript module provides interactive functionality for components. It's completely optional - the CSS framework works standalone.

Including JavaScript

HTML

<!-- Before closing body tag -->
<script src="js/main.js"></script>

What the JS Provides

The JavaScript module initializes on DOMContentLoaded and handles all interactive behaviors.

Module	Data Attributes	Description
Theme	`data-theme-toggle`	Handles light/dark mode toggling and persists preference in localStorage
Sidebar	`data-sidebar`, `data-sidebar-toggle`, `data-sidebar-overlay`	Mobile sidebar open/close, overlay dismissal, Escape key support
CopyCode	`data-copy`	One-click code copying with "Copied!" feedback
Dropdowns	`data-dropdown`	Toggle dropdown menus by ID reference
Modals	`data-modal-open`, `data-modal-close`	Open/close modal overlays with backdrop click and Escape support
Accordions	`.hu-accordion-btn`	Auto-manages accordion open/close with ARIA attributes
Tabs	`data-tab`	Tab switching with content panes
SmoothScroll	`href="#id"`	Smooth scrolling for anchor links
Offcanvas	`data-offcanvas-open`, `data-offcanvas-close`	Offcanvas panel management
AlertDismiss	`.hu-alert-dismiss`	Dismissable alerts with animated removal
Forms	`.hu-is-valid`, `.hu-is-invalid`	Clears validation state on input

Global API

All modules are exposed on the window.Nimbus object for programmatic access.

JavaScript

// Access individual modules
Nimbus.Theme.toggle();          // Toggle theme
Nimbus.Modals.open('modal-id'); // Open a modal
Nimbus.Sidebar.toggle();        // Toggle sidebar

// All available modules:
// Theme, Sidebar, CopyCode, Dropdowns, Modals,
// Accordions, Tabs, Offcanvas

Interactive Demo - Accordion

What's included in the JS?

Theme toggling, sidebar management, copy code, dropdowns, modals, accordions, tabs, smooth scrolling, offcanvas panels, alert dismissal, and form validation helpers.

Do I need to initialize anything?

No. All modules auto-initialize on DOMContentLoaded. Just include the script and it works.

Is it framework-agnostic?

Yes. Nimbus works with any HTML page, no matter the framework. It uses vanilla JavaScript with no dependencies.

HTML

<div class="hu-accordion">
    <div class="hu-accordion-item hu-active">
        <div class="hu-accordion-header">
            <button class="hu-accordion-btn" aria-expanded="true">
                Question text
                <span class="hu-accordion-icon">...chevron...</span>
            </button>
        </div>
        <div class="hu-accordion-body">
            <div class="hu-accordion-body-inner">
                Answer content here.
            </div>
        </div>
    </div>
</div>

File Structure

Overview of the Nimbus framework's file organization and what each file provides.

File Tree

Nimbus/
├── css/
│   └── main.css          # Core framework styles (CSS variables, reset, components, utilities)
├── js/
│   └── main.js           # Interactive components (theme, sidebar, modals, etc.)
├── docs/
│   ├── main.css          # Documentation-specific styles
│   ├── docs.js           # Documentation JS (TOC, sidebar active link)
│   ├── getting-started.html
│   ├── components.html
│   ├── buttons.html
│   ├── cards.html
│   ├── alerts.html
│   ├── badges.html
│   ├── forms.html
│   ├── tables.html
│   ├── accordion.html
│   ├── lists.html
│   ├── layout.html
│   ├── spacing.html
│   ├── typography.html
│   ├── borders.html
│   ├── shadows.html
│   ├── display.html
│   ├── pricing.html
│   ├── server-status.html
│   ├── features.html
│   ├── hero-sections.html
│   ├── guides.html
│   └── guides/
│       ├── customization.html
│       ├── theming.html
│       └── responsive.html
└── index.html             # Homepage with component showcase

File Descriptions

File	Purpose	Required
`css/main.css`	Core framework with all CSS variables, reset, components, and utilities	Yes
`js/main.js`	Interactive component behavior (theme, sidebar, modals, etc.)	No
`docs/main.css`	Documentation site layout and styling	Docs only
`docs/docs.js`	Documentation-specific features (TOC, active links, search)	Docs only

Info For a basic site, you only need css/main.css and optionally js/main.js. The docs files are only needed for this documentation site.