Documentation

`@vkcha/tw-glass` is a framework-agnostic Tailwind plugin + token system for “liquid glass” surfaces: translucency, blur, depth, soft highlights, and fluid motion-usable with pure HTML + Tailwind classes.

Installation

Install from npm and add to your Tailwind config.

npm install @vkcha/tw-glass

CommonJS:

// tailwind.config.js
const twGlass = require("@vkcha/tw-glass");

module.exports = {
  darkMode: ["class"],
  content: ["./**/*.html"],
  plugins: [twGlass]
};

ES Modules:

// tailwind.config.js
import twGlass from "@vkcha/tw-glass";

export default {
  darkMode: ["class"],
  content: ["./**/*.html"],
  plugins: [twGlass]
};

Core idea

Tokens are CSS variables (`:root` + `.dark`).
Primitives are composable classes (surface, depth, overlays, motion).
Components are just recipes (semantic HTML + classes).

Tokens

Tokens are CSS variables defined by the plugin (`:root` + `.dark`). You can override them globally or per container (e.g. on a `.dark` wrapper) using CSS custom properties.

Blur levels

`--lt-blur-xs` → `--lt-blur-xl`

Surface opacity scale

`bg-liquid-1` → `bg-liquid-5`

Radii + depth

`rounded-lt-soft/liquid` + `liquid-depth-*`

Classes (reference)

These are the main primitives shipped by the plugin. Treat them like LEGO: start with a surface, add depth, optionally add highlight/grain, then motion.

Surfaces

liquid-surface Glass panel primitive (bg + border + blur).

liquid-canvas Page/content scrim for stable readability.

bg-liquid-1..5 Opacity levels (works without blur).

border-liquid Consistent glass stroke.

backdrop-liquid-* Blur-only helpers (xs/sm/md/lg/xl).

<div class="liquid-surface liquid-depth-2 liquid-highlight">
  ...
</div>

Depth + overlays + motion

liquid-depth-1..5 Shadow layers (ambient + specular).

liquid-highlight Soft refraction overlay.

liquid-grain Optional grain overlay.

liquid-motion Transition defaults.

liquid-hover Subtle lift on hover.

liquid-press Gentle press scale on active.

liquid-focus Accessible focus ring (`:focus-visible`).

All motion respects prefers-reduced-motion.

Component recipes

Each “component” is just semantic HTML + these primitives. Copy/paste and adjust the classes as needed.

Glass card

Use article for semantic content blocks.

<article class="liquid-surface liquid-depth-2 liquid-highlight rounded-lt-liquid p-4">
  <h3 class="text-sm font-semibold">Card title</h3>
  <p class="mt-1 text-sm text-liquid-text-muted">Short description.</p>
</article>

Buttons

Prefer real button elements for accessibility.

<button class="liquid-surface liquid-depth-2 liquid-highlight liquid-motion liquid-hover liquid-press liquid-focus rounded-lt-soft px-4 py-2 text-sm font-semibold">
  Primary
</button>

Input / text field

Wrap inputs in label for a larger clickable area.

<label class="grid gap-1.5">
  <span class="text-xs font-medium">Email</span>
  <input class="liquid-surface liquid-depth-1 liquid-motion liquid-focus rounded-lt-soft px-3 py-2 text-sm" />
</label>

Modal (markup)

Use role="dialog" + aria-modal. For a production modal you’ll need JS for focus trap + open/close.

<div role="dialog" aria-modal="true" aria-labelledby="m-title" class="liquid-surface liquid-depth-4 liquid-highlight rounded-lt-liquid p-4">
  <h2 id="m-title" class="text-sm font-semibold">Modal title</h2>
  <p class="mt-1 text-sm text-liquid-text-muted">Description.</p>
  <div class="mt-4 flex justify-end gap-2">
    <button class="liquid-motion liquid-focus rounded-lt-soft border border-liquid bg-liquid-1 px-3 py-2 text-sm font-semibold hover:bg-liquid-2">Cancel</button>
    <button class="liquid-surface liquid-depth-2 liquid-highlight liquid-motion liquid-hover liquid-press liquid-focus rounded-lt-soft px-3 py-2 text-sm font-semibold">Confirm</button>
  </div>
</div>

Navigation bar

Use <nav> + a list of links for semantics.

Floating panel / dock

Make it a nav with icon buttons. Keep hit targets ≥ 44px.