v1.0.0 — Open Source & Free

VelinStyle

VelinStyle is the WCAG 2.2 AAA CSS framework with native JavaScript runtime and Web Components. 35+ CSS components, 36 Web Components, 27 declarative HTML attributes, 13 OKLCH themes, and agent metadata (velin-agent.json, llms.txt).

Get Started 1.0.0 runtime Live demos Install

components web components themes WCAG 2.2 AAA · ready Subpath APIs Velin-Meta

Component growth 0.5 → 1.0.0

Component-first habit

Familiar — but every surface is a bespoke bundle of class names and JS plugins for focus, overlays, and dark mode.

Utility-first habit

Flexible — but every screen re-encodes design decisions as long class strings; A11y and theming stay your responsibility.

VelinStyle

Coherent — semantic components, OKLCH tokens, @layer, container queries, and optional Web Components with focus + ARIA baked in.

Accessibility Built-in

WCAG 2.2 AAA token defaults are built in (AA via data-velin-contrast="aa"). Focus trapping, labeled dialogs, skip links, 44px targets, and forced-colors — production-ready in CSS and components.

Modern CSS Only

@layer, CSS nesting, :has(), Container Queries, OKLCH, @scope, Anchor Positioning — no preprocessors, no build step.

13 Themes + Dark Mode

Swap entire design personality with one attribute. 13 presets from Corporate to Brutalist. Dark mode auto-detects system preference — zero config.

Multi-Provider Icons

50+ built-in icons plus instant access to Lucide, Heroicons, Material, Bootstrap Icons, Font Awesome and Tabler — via one attribute. No extra imports.

CLI: scaffold, audit, scan

1.0.0: docs generate, perf audit, tokens validate, PII scan (--only pii --fix), scaffold, layout audit, and security scan.

API guide · Markdown · CLI

Security Built-in

XSS-safe Web Components, PII scanner, <velin-email> obfuscation, optional velin-secure-field, CSP, and Trusted Types.

Motion runtime (1.0.0)

initMotion, velin-stagger, scroll-driven .velin-in-view, and attribute bridges (velin-reveal, velin-fade, …). This page uses data-velin-reveal-auto on <html>.

Motion guide · Animations

Search & highlight (1.0.0)

Offline fuzzy VelinSearch, <velin-search>, and VelinHighlight with lazy in-view tokenizing via <velin-code-block> — same engine as the docs site.

VelinSearch · Highlight

Motion

Stagger & reveals

initMotion() + velin-stagger — scroll the page or resize to see cards animate in. Respects prefers-reduced-motion.

Motion guide →

VelinHighlight

Lazy in-view code

<velin-code-block> highlights when scrolled into view (IntersectionObserver + rAF batching).

import { initHighlight } from '@birdapi/velinstyle/highlight'; initHighlight(document, { selector: 'pre.playground-pane__code, velin-code-block pre', });

Syntax guide →

Velin-Meta

Agent-ready bundle

velin-agent.json + llms.txt for Cursor, Copilot, and custom tools. MIME application/vnd.velinstyle.meta+json (served as JSON on GitHub Pages).

Open JSON llms.txt Guide

New · Velin-Meta

Agent context for Cursor & Copilot

dist/velin-agent.json + llms.txt and page-level application/vnd.velinstyle.meta+json — conventions, components, CLI, doc URLs without hiding content from humans.

Velin-Meta guide Open bundle llms.txt Feature scope

Runtime

VelinSearch

Fuzzy offline search — same engine as the docs header. @birdapi/velinstyle/search

Guide →

Runtime

Motion

initMotion, stagger, scroll-driven reveals. @birdapi/velinstyle/motion

Guide →

Runtime

VelinHighlight

Lazy in-view highlighting (IntersectionObserver). Playground code panes use the same pipeline via <velin-code-block>.

Live demo ↑ Guide →

Runtime

HTML attributes

27 bridges: velin-modal, velin-reveal, velin-scroll-top, velin-code, …

Guide →

Web Component

<velin-search>

Autocomplete with keyboard navigation and grouped results.

Component →

Web Component

<velin-code-block>

Copy, line numbers, collapsible blocks with lazy highlight.

Component →

CLI · Exports

Toolchain

velinstyle search index, docs generate, meta, tokens build — subpaths /search, /motion, /attributes, /highlight, /meta.

CLI reference Generated Markdown API reference

Add the package

From your project root:

npm install @birdapi/velinstyle
Load CSS

Reference the built CSS (or import it in your bundle entry).

<link rel="stylesheet" href="node_modules/@birdapi/velinstyle/dist/velinstyle.min.css">
Optional: Web Components (ESM)

Use the minified module bundle for interactive primitives.

<script type="module" src="node_modules/@birdapi/velinstyle/dist/velinstyle-components.min.js"></script>
Markup

Use velin-* classes and optional <velin-…> elements — see the docs for patterns.

No ES modules? Use velinstyle-components.iife.js for legacy pages — covered in the download guide.

Download & paths Existing project

Drop in from a CDN

Great for static HTML or quick prototypes (pin a version in production).

<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@1.0.0/dist/velinstyle.min.css"> <script type="module" src="https://unpkg.com/@birdapi/velinstyle@1.0.0/dist/velinstyle-components.min.js"></script>

Version pinning & integrity

Use the official template

Clone templates/vite-velinstyle from the VelinStyle repo for a multi-page starter with theme toggle and navigation.
Or add to an existing Vite app

Install the package, import CSS once in your entry, and load the components module.

npm install @birdapi/velinstyle

Bundler integration Template on GitHub

Generate a config

npx velinstyle init
Build only the layers you need

npx velinstyle build
Extras

Blueprints, token export, scanner, and class-prefix helper — see CLI docs.

CLI reference

1.0.0

Scaffold & layout audit

Generate Navbars, dashboards, and modals from text prompts, then run responsive layout checks before scan.

Scaffold guide Layout audit Perf audit Generated docs

CLI docs · perf · scan · tokens

Command-line reference

Snippet emitters, velinstyle tokens build, extended scan flags (--fix-dry-run, --fix-lang), and copy-paste config samples.

CLI docs API reference Velin-Meta Design tokens

A11y

Pattern library

Skip links, live regions, dialogs, tabs, landmarks, and form error wiring — aligned with Velin components.

Open patterns →

Forms

Validation layer

:user-invalid, [aria-invalid], hints and errors — documented end-to-end.

Validation docs →

Repo

Local tooling

tools/theme-builder, tools/playground, and the Vite starter templates/vite-velinstyle.

GitHub →

Local preview: run npm run build in this repo, then npm run dev (port 4000). Open via http://localhost:4000 — file:// needs dist/ present.

@layer

8 ordered cascade layers for predictable specificity

CSS Nesting

Native nesting without Sass or PostCSS

Parent Selectors

CSS-only filtering & state detection

OKLCH Colors

Perceptually uniform, P3 gamut support

Container Queries

Components adapt to their container, not viewport

CSS Scope

Scoped styles without Shadow DOM

Anchor Positioning

Native tooltip/dropdown positioning, no Popper.js

Fluid Typography

Smooth scaling between mobile and desktop

Preview

Variants

Sizes

States

HTML

<button class="velin-btn velin-btn--primary">Primary</button> <button class="velin-btn velin-btn--success">Success</button> <button class="velin-btn velin-btn--outline">Outline</button> <button class="velin-btn velin-btn--primary velin-btn--sm">Small</button> <button class="velin-btn velin-btn--primary velin-btn--loading">Loading</button> <button class="velin-btn velin-btn--primary velin-btn--block">Block</button>

Preview

Default

Standard card with elevation and accessible structure.

Flat

velin-card--flat — minimal shadow.

Badge

Clickable + tint

velin-card--clickable with velin-bg-primary/10 wash.

Success surface

Semantic OKLCH color-mix on the card body.

Danger surface

velin-bg-danger/10 for error contexts.

HTML

<article class="velin-card">...</article>
<article class="velin-card velin-card--flat">...</article>
<article class="velin-card velin-card--clickable">...</article>
<article class="velin-card"><div class="velin-card__body velin-bg-success/10">...</div></article>

Preview

Default fields

Email We never share your email.

Password

Bio

Plan

Validation

Username At least 3 characters required.

Coupon Code applied.

HTML

<div class="velin-input-group">
  <label class="velin-input-group__label" for="email">Email</label>
  <input class="velin-input" type="email" id="email">
  <span class="velin-field-hint">Hint text</span>
</div>
<input class="velin-input" aria-invalid="true">
<span class="velin-field-error">Error message</span>

Preview

Success! Your changes have been saved.

Note: A new version is available.

Warning: This action cannot be undone.

Error: Something went wrong. Please try again.

HTML

<div class="velin-alert velin-alert--success" role="alert">...</div>
<div class="velin-alert velin-alert--info" role="alert">...</div>
<div class="velin-alert velin-alert--warning" role="alert">...</div>
<div class="velin-alert velin-alert--danger" role="alert">...</div>

Preview

Overlays

Tabs

36 canonical Web Components (38 lazy loaders) with keyboard support, ARIA, contracts, and focus trapping.

Works with React, Vue, Angular, or plain HTML.

Methods, events, and CSS parts for full customization.

HTML

<velin-modal id="my-modal" title="Hello">...</velin-modal>
<velin-drawer id="nav" title="Menu" side="start">...</velin-drawer>
<velin-toast id="toast"></velin-toast>
<velin-tabs>...</velin-tabs>

Preview

Built-in icons and six external providers via one attribute.

Sizes

HTML

<velin-icon name="check"></velin-icon>
<velin-icon name="heart" provider="lucide"></velin-icon>
<velin-icon name="star-fill" provider="bootstrap"></velin-icon>
velinstyle icons add lucide --icons heart,star,zap

Preview

Scoped preview — page theme unchanged. Chips set data-velin-theme on this box.

Badge

Card in theme

Tokens update instantly when you pick a preset.

HTML

<section id="preview" data-velin-theme="ocean">
  <button class="theme-swatch" data-velin-theme="neon">Neon</button>
  ...
</section>

Preview

Viewport: measuring…

Token	Min width	Example
base	0	`velin-block`
`sm`	36rem (576px)	`velin-sm:flex--row`
`md`	48rem (768px)	`velin-md:grid-cols-3`
`lg`	62rem (992px)	`velin-lg:hidden`
`xl`	80rem (1280px)	`velin-xl:p-8`

base sm+ md+ lg+ xl+

Visible from sm — velin-hidden velin-sm:block Mobile only — resize to see the switch.

HTML

<div class="velin-hidden velin-sm:block">Desktop / sm+</div>
<div class="velin-flex velin-flex--col velin-sm-flex--row velin-gap-3">...</div>

Preview

Pure CSS filters with :has() — no list JS.

HTML

<div class="velin-filter-group">
  <div class="velin-filter-controls">
    <input type="checkbox" class="velin-filter-check"
           data-velin-filter="a" id="f-a">
    <label class="velin-filter-label" for="f-a">Tag A</label>
  </div>
  <div class="velin-filter-list">
    <article class="velin-card velin-filter-target" data-velin-tags="a b">
      ...
    </article>
    <p class="velin-filter-empty">Nothing matches.</p>
  </div>
</div>

Preview

Design tokens compile to --velin-* variables — swap themes or override in scope.

--velin-color-primary

--velin-color-secondary

--velin-color-success

--velin-color-surface-bright

--velin-space-6

--velin-radius-lg

Aa Sans

--velin-font-sans

Mono

--velin-font-mono

HTML

:root {
  --velin-color-primary: oklch(55% 0.2 264);
  --velin-space-6: 1.5rem;
  --velin-radius-lg: 0.75rem;
}

Preview

primary

/10

/20

/30

solid

success

/10

/20

solid

danger

/10

/20

solid

HTML

<span class="velin-bg-primary/20 velin-text-primary">Tinted</span>
<div class="velin-bg-success/10">Wash</div>

Preview

Columns + gap

Auto-fit

Span

velin-col-2

velin-col-full

Container query

cols

flip

HTML

<div class="velin-grid velin-grid--cols-2 velin-grid--md-cols-4 velin-grid--gap-4">...</div>
<div class="velin-grid velin-grid--auto-fit" style="--velin-grid-min:12rem">...</div>
<div class="velin-grid velin-grid--cols-3"><div class="velin-col-2">...</div></div>

Preview

fade-invelin-animate-fade-in

slide-upvelin-animate-slide-up

scale-invelin-animate-scale-in

bouncevelin-animate-bounce

pulsevelin-animate-pulse

shakevelin-animate-shake

wigglevelin-animate-wiggle

spinvelin-animate-spin

heartbeatvelin-animate-heartbeat

pingvelin-animate-ping

spinner

HTML

<span class="velin-animate-fade-in">Enter</span>
<span class="velin-animate-pulse velin-animate--infinite">Live</span>
<span class="velin-animate-bounce velin-animate--infinite">Attention</span>

Preview

Flip

velin-animate-flip

Swing

velin-animate-swing

Drop in

velin-animate-drop-in

Tada

velin-animate-tada

HTML

<article class="velin-card velin-animate-flip">...</article>
<article class="velin-card velin-animate-swing">...</article>
<article class="velin-card velin-animate-drop-in">...</article>
<article class="velin-card velin-animate-tada">...</article>

Full split-view playground lives in the core repo: tools/playground — clone VelinStyle and open it locally.

Button

Default

Clean, balanced, professional.

Button

Sharp

Angular, editorial, zero radius.

Button

Soft

Rounded, warm, friendly.

Button

Brutalist

Raw, bold, hard shadows.

+ 9 more: Corporate, Elegant, Neon, Pastel, Retro, Glassmorphism, Nature, Monochrome, High Contrast

Explore All Themes →

Bootstrap since 2011

Modernness

Bundle
Components: ~25
Deps: jQuery / Popper

Tailwind since 2017

Modernness

Bundle: JIT (varies)
Components: 0 (utility only)
Deps: PostCSS + Node

VelinStyle v1.0.0 since 2025

Modernness

CSS bundle
JS bundle
Components: 35+ CSS · 36 WC
Deps: None

Feature	Bootstrap	Tailwind	VelinStyle
Components	~25	0 (utility only)	35+ CSS + 36 Web Components
Bundle Size	~230 KB (CSS+JS)	JIT (varies)	~46 KB CSS + ~111 KB JS
Accessibility	◐ Partial (ARIA in JS)	✕ None built-in	✓ WCAG 2.2 AAA · ready
Dark Mode	Manual Sass swap	`dark:` variant	Automatic token swap
Color System	HEX / RGB	HEX / RGB	OKLCH (perceptual)
JS Dependency	jQuery / Popper	PostCSS + Node	None (Web Components)
CSS Layers	✕	✕	✓ 8 ordered layers
Container Queries	✕	◐ v4 only	✓ First-class
RTL Support	Plugin	Plugin	Built-in (logical props)
Theme System	Sass variables	tailwind.config	✓ 13 presets, 1 attribute swap
Icon System	External (Bootstrap Icons)	External (Heroicons)	✓ Built-in + 6 providers
CLI Scanner	✕	✕	✓ A11y, Security, CSS
Security (XSS, CSP)	✕	✕	✓ Sanitization, Trusted Types
View Transitions	✕	✕	✓ CSS-only morph
Haptic Feedback	✕	✕	✓ 6 patterns
Form Persistence	✕	✕	✓ Zero-JS <velin-persist>
Fluid Typography	✕	◐ Manual	✓ clamp() engine
Motion & charts (0.8.0+)	✕	✕	✓ Sparkline, counter, FLIP-filter
VelinSearch & docs index (1.0.0)	✕	✕	✓ Fuzzy search + `search index`
Auto-generated API docs (1.0.0)	✕	✕	✓ `docs generate` Markdown
Velin-Meta (AI context) (1.0.0)	✕	✕	✓ `velin-agent.json`, `llms.txt`
PII & perf CLI (1.0.0)	✕	✕	✓ `scan --only pii`, `perf audit`

<!-- Add to <head> — that's it! -->
<link rel="stylesheet"
      href="dist/velinstyle.min.css">
<script type="module"
        src="dist/velinstyle-components.min.js"></script>

<!-- Start building -->
<div class="velin-container">
  <div class="velin-grid velin-grid--auto-fit">
    <article class="velin-card">
      <div class="velin-card__body">
        <h2 class="velin-card__title">Hello World</h2>
        <button class="velin-btn velin-btn--primary">Get Started</button>
      </div>
    </article>
  </div>
</div>

<!-- Option 1: Automatic (follows system preference) -->
<!-- Just use VelinStyle — it works automatically! -->

<!-- Option 2: Explicit toggle -->
<html data-velin-theme="dark">

<!-- Option 3: Use the toggle web component -->
<velin-theme-toggle></velin-theme-toggle>

<!-- That's it. All tokens swap automatically. -->
<!-- No extra CSS. No Sass variables. No rebuild. -->

<!-- Built-in themes: sharp | soft | brutalist -->
<html data-velin-theme="brutalist">

<!-- Or scope themes to sections -->
<section data-velin-theme="soft">
  <button class="velin-btn velin-btn--primary">Soft Button</button>
</section>

<!-- Create your own theme with CSS tokens -->
<style>
  [data-velin-theme="brand"] {
    --velin-color-primary: oklch(55% 0.2 160);
    --velin-radius-md: 1rem;
    --velin-font-heading: "Playfair Display", serif;
  }
</style>

// Open / close modal
const modal = document.querySelector('velin-modal');
modal.open();
modal.addEventListener('velin-close', () => console.log('closed'));

// Toast
document.querySelector('velin-toast').show({
  message: 'Saved successfully!',
  type: 'success',
  duration: 3000
});

// Confirm dialog (returns boolean)
const dialog = document.querySelector('velin-dialog');
const ok = await dialog.confirm('Delete item?', { title: 'Confirm', danger: true });

// Custom icon provider (VelinIcon global from bundle)
VelinIcon.registerProvider('myicons', 'https://cdn.example.com/{name}.svg');

# Project config + custom CSS bundle
$ npx velinstyle init
$ npx velinstyle build -o dist/app.css --minify

# HTML snippets (see blueprint list for all ids)
$ npx velinstyle blueprint list
#   modal, form-login, layout-dashboard, hero-section, …
$ npx velinstyle blueprint modal -o partials/modal.html
$ npx velinstyle tokens build --input tokens.json -o src/tokens.css

# Icons: multiple providers, then rebuild sprite (from repo root)
$ npx velinstyle icons add lucide --icons menu,search,check
$ npx velinstyle icons add heroicons --icons arrow-left --variant outline
$ npx velinstyle icons build

# Scanner: severity, dry-run, safe fixes
$ npx velinstyle scan ./src --severity warning
$ npx velinstyle scan --fix-dry-run
$ npx velinstyle scan --fix --fix-lang en

velin-modal

Focus-trapped, Escape to close, overlay dismiss

velin-drawer

Slide-in panel from any side

velin-tabs

Arrow-key navigation, ARIA tablist

velin-accordion

Expandable sections with animation

velin-toast

Stacking notifications with auto-dismiss

velin-countdown

Live timer with aria-live region

velin-progress-ring

Animated SVG circular progress

velin-lightbox

Fullscreen image viewer with swipe

View all 36 components →

Landing Page

Hero, features, pricing, testimonials

Dashboard

Stats, charts, sidebar navigation

Blog

Article layout, sidebar, comments

Portfolio

Project grid, about section, contact

Auth form with validation states

E-Commerce

Product grid, cart, filters

Chat

Message bubbles, sidebar, input

Kanban Board

Drag columns, task cards, labels

Start Building Today

One command. Zero config. Instant accessibility, dark mode, and 35+ components.

npm install @birdapi/velinstyle

Read the Docs Star on GitHub View on npm

VelinStyle

VelinStyle meets you where you are — then levels you up

Built Different from the Ground Up

Accessibility Built-in

Modern CSS Only

13 Themes + Dark Mode

Multi-Provider Icons

CLI: scaffold, audit, scan

Security Built-in

Motion runtime (1.0.0)

Search & highlight (1.0.0)

1.0.0 runtime in action

Stagger & reveals

Lazy in-view code

Agent-ready bundle

Search, motion, highlight, attributes & Velin-Meta

Agent context for Cursor & Copilot

VelinSearch

Motion

VelinHighlight

HTML attributes

<velin-search>

<velin-code-block>

Toolchain

Install & Go

Add the package

Load CSS

Optional: Web Components (ESM)

Markup

Drop in from a CDN

Use the official template

Or add to an existing Vite app

Generate a config

Build only the layers you need

Extras

Blueprint, tokens, and patterns

Scaffold & layout audit

Command-line reference

Pattern library

Validation layer

Local tooling

Modern CSS That Others Can't Match

@layer

CSS Nesting

Parent Selectors

OKLCH Colors

Container Queries

CSS Scope

Anchor Positioning

Fluid Typography

Interactive Playground

Default

Flat

Clickable + tint

Success surface

Danger surface

Card in theme

Tokens + UI

Guides

Blueprint

Flip

Swing

Drop in

Tada

Same HTML, Different Personality

Default

Sharp

Soft

Brutalist

VelinStyle vs. the Rest

Copy, Paste, Ship

Zero-Dependency Web Components

Sample Pages

Start Building Today