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/framework@v1.3.1/dist/vanduo.min.css">
<script src="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.3.1/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.