Vanduo Framework v1.3.1

Essential just like water is.

• Pure HTML, CSS, JS
• No third party dependencies
• Free and open source.

Overview

A lightweight, pure HTML/CSS/JS framework with 45+ components for designing beautiful interfaces. Zero runtime dependencies, no mandatory build tools, just clean and simple code.

Browse Full Documentation →

Features

• 🎨 Pure CSS/JS - No libraries, no dependencies
• 🚀 Lightweight - Minimal file size, maximum performance
• 📱 Responsive - Mobile-first design approach
• 🎯 Utility-First - Flexible utility classes for rapid development
• 🧩 Modular - Import only what you need
• ♿ Accessible - Built with accessibility in mind (WCAG 2.1 AA)
• 🌙 Dark Mode - Automatic OS preference detection + manual toggle
• 🌗 Theme Switcher - Lightweight light/dark/system toggle with shared preference storage
• 🎛️ Theme Customizer - Real-time color, radius, font, and mode customization
• 🔍 SEO-Ready - Comprehensive meta tags, structured data, and sitemap

What's New in v1.3.1

v1.3.1 is a security and correctness release (12 issues fixed, 0 breaking changes):

• XSS fix in Suggest. renderItems() now escapes user/server data before innerHTML highlight injection.
• Select component repairs. Fixed 3 broken querySelector selectors (keyboard nav + programmatic updates); generateId() now assigns element.id so ARIA aria-labelledby resolves correctly.
• Typeahead isolation. _typeaheadBuffer / _typeaheadTimer moved to per-instance state in Dropdown and Select — typing in one instance no longer corrupts another.
• Navbar scroll-lock fix. CSS class body-navbar-open replaces inline overflow:hidden, preventing conflicts with modal scroll locks.
• Validate hardening. 100-char limit on user regex patterns (ReDoS prevention); CSS.escape() applied to match rule param (selector injection fix).
• Release artifacts and docs are aligned for v1.3.1. Package metadata, generated bundles, llms.txt, and release-facing README examples now point at the current version.

The framework still ships 45+ components, including the v1.2.7 additions below.

| Component | Vanduo Name | Type | |---|---|---| | Carousel | Flow | CSS + JS | | Popover | Bubble | CSS + JS | | Scrollspy | Waypoint | CSS + JS | | Offcanvas | — (enhanced Sidenav) | CSS + JS | | Ripple / Waves | Ripple | CSS + JS | | Floating Action Button | FAB | CSS-only | | Sticky | Affix | CSS + JS | | Autocomplete | Suggest | CSS + JS | | Form Validation | Validate | JS | | Date Picker | Datepicker | CSS + JS | | Time Picker | Timepicker | CSS + JS | | Stepper | Stepper | CSS + JS | | Timeline | Timeline | CSS-only | | Rating | Rating | CSS + JS | | Transfer / Multi-select | Transfer | CSS + JS | | Tree View | Tree | CSS + JS | | Spotlight / Feature Discovery | Spotlight | CSS + JS |

Quick Start

Option 1: CDN (Recommended)

The quickest way to get started — no install, no build step. Add two lines to any HTML file:

<!-- Vanduo CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@main/dist/vanduo.min.css">

<!-- Vanduo JS -->
<script src="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@main/dist/vanduo.min.js"></script>
<script>Vanduo.init();</script>

Pin to a specific version for production:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/vanduo-oss/[email protected]/dist/vanduo.min.css">
<script src="https://cdn.jsdelivr.net/gh/vanduo-oss/[email protected]/dist/vanduo.min.js"></script>
<script>Vanduo.init();</script>

Option 2: Download

Download the dist/ folder and include locally — no internet connection required at runtime:

<link rel="stylesheet" href="dist/vanduo.min.css">
<script src="dist/vanduo.min.js"></script>
<script>Vanduo.init();</script>

The dist/ folder is self-contained (CSS, JS, Fonts, Icons).

Option 3: Source Files

For development or when you need more control, use the unminified source:

<link rel="stylesheet" href="css/vanduo.css">
<script src="js/vanduo.js"></script>
<script>Vanduo.init();</script>

Option 4: With a Bundler (Vite)

Requires a build tool. The imports below use bare module specifiers (@vanduo-oss/framework) which browsers cannot resolve on their own. For static HTML files, use the CDN or Download options above.

Scaffold a Vite project and install Vanduo:

pnpm create vite my-app --template vanilla
cd my-app
pnpm add @vanduo-oss/framework

Import in your entry file (e.g. main.js):

import '@vanduo-oss/framework/css';
import { Vanduo } from '@vanduo-oss/framework';
Vanduo.init();

Why pnpm? pnpm enforces a strict lockfile and creates an isolated node_modules structure. Vanduo's .npmrc security policies work best with pnpm out of the box.

(Note: npm install @vanduo-oss/framework and yarn add @vanduo-oss/framework will also work, but they do not enforce the same strict lockfile and isolated node_modules security guarantees.)

LLM Access

This project includes an llms.txt file — a structured markdown summary designed for AI assistants and LLM-powered code editors. It provides quick access to framework documentation, component references, and usage patterns.

Release Assets (Maintainers)

Use the hardened upload script to attach only approved bundle artifacts from dist/:

pnpm run release:assets -- v1.3.1

Notes:

• If tag is omitted, it defaults to v + version from package.json.
• Use --dry-run to preview files without uploading.

Documentation

Comprehensive documentation for all components, utilities, and customization options is available at vanduo.dev.

View Documentation

Key Capabilities

• Dark Mode: Works automatically with system preferences. Can be forced via data-theme="dark" on <html>.
• Theme Switcher: Lightweight light/dark/system toggle that can coexist with Theme Customizer.
• Theme Customizer: Built-in runtime tool to change colors, fonts, and radius.
• Modular Imports: Import only specific components (e.g., css/components/buttons.css) to keep your site lean.
• Icons: Includes Phosphor Icons (Regular + Fill weights bundled).

Project Structure

vanduo-framework/
├── dist/                  # Production ready files (minified)
├── css/
│   ├── vanduo.css         # Main framework file (imports all)
│   ├── core/              # Foundation (colors, typography, grid)
│   ├── components/        # UI components (buttons, cards, etc)
│   ├── utilities/         # Utility classes
│   └── effects/           # Visual effects
├── js/
│   ├── vanduo.js          # Main entry point
│   └── components/        # Component logic
├── icons/                 # Phosphor Icons
├── fonts/                 # Web fonts
└── tests/                 # Framework test suite

Browser Support

• Chrome (last 2 versions)
• Firefox (last 2 versions)
• Safari (last 2 versions)
• Edge (last 2 versions)

License

MIT License - see LICENSE file for details.

Credits

• Color System: Open Color by Heeyeun Jeong (MIT License)
• Icons: Phosphor Icons (MIT License)

Vanduo Framework - Built with ❤️ for the web.