astro-liquid-glass

v0.1.0

Published

a month ago

Liquid Glass design system for Astro - Apple WWDC 2025 inspired glassmorphism with Swiss minimalism

Downloads

119

0High
0Medium
0Low

jawadicus

astro astro-integration liquid-glass glassmorphism apple wwdc design-system css ui

Astro Liquid Glass

A design system for Astro inspired by Apple's WWDC 2025 Liquid Glass aesthetic. Features glassmorphism effects, motion-responsive highlights, and iOS-style interactive components.

Features

Apple HIG Compliant - Full adherence to Apple Human Interface Guidelines
Liquid Glass Effects - Backdrop blur, lensing, and specular highlights
Glass Morphing - Dynamic blur/opacity/saturation changes during drag interactions
Motion-Responsive Highlights - DeviceOrientation API for mobile tilt effects
iOS-Style Components - Toggle, Slider, Sheet, Segmented Control, Stepper, and more
Dynamic Light Adaptation - Background color sampling for adaptive glass tints
Animated Mesh Gradients - Beautiful animated gradient backgrounds
Dark Mode Support - Automatic adaptation to color scheme
Accessibility - Respects prefers-reduced-motion, prefers-reduced-transparency, and prefers-contrast
Battery Saver Mode - Reduced effects when battery is low
TypeScript - Full type support

Installation

npm install astro-liquid-glass

Component Library Demo

A comprehensive component library page is included at demo/ComponentLibrary.astro. To use it in your Astro project:

---
// src/pages/components.astro
import ComponentLibrary from 'astro-liquid-glass/demo/ComponentLibrary.astro';
---

<ComponentLibrary title="My Component Library" />

This provides a shadcn/ui-style documentation page with:

Sidebar navigation for all component categories
Interactive demos for every component
Props documentation
CSS class reference
Copy-pasteable code examples

Quick Start

1. Import the Styles

In your layout or page:

---
// src/layouts/Layout.astro
import 'astro-liquid-glass/styles';
---

<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <slot />
  </body>
</html>

2. Add the Script

<script>
  import 'astro-liquid-glass/scripts/liquid-glass.js';
</script>

3. Use the Components

---
import Toggle from 'astro-liquid-glass/components/Toggle.astro';
import Sheet from 'astro-liquid-glass/components/Sheet.astro';
import Button from 'astro-liquid-glass/components/Button.astro';
import Card from 'astro-liquid-glass/components/Card.astro';
---

<Button variant="primary">Get Started</Button>

<Toggle id="notifications" label="Enable Notifications" />

<Card variant="glass" hover>
  <h2>Glass Card</h2>
  <p>Beautiful glassmorphism effects.</p>
</Card>

<Sheet id="settings" title="Settings" size="medium">
  <p>Sheet content here</p>
</Sheet>

Sheet Component

The Sheet component provides a draggable bottom sheet with glass morphing:

---
import Sheet from 'astro-liquid-glass/components/Sheet.astro';
---

<Sheet
  id="mySheet"
  title="Sheet Title"
  size="medium"
  showHandle={true}
  showClose={true}
>
  <p>Content goes here</p>
</Sheet>

<button onclick="window.sheet_mySheet.open()">Open Sheet</button>

Sizes: small (40vh), medium (60vh), large (80vh), full

JavaScript API:

window.sheet_mySheet.open();
window.sheet_mySheet.close();
window.sheet_mySheet.toggle();

Glass Morphing: When dragging the sheet handle, the glass material dynamically changes:

Blur increases with height (20px to 50px)
Opacity increases (0.25 to 0.50)
Saturation increases (150% to 200%)
Border radius decreases (32px to 16px)

Apple HIG Compliance

This design system follows Apple Human Interface Guidelines for Liquid Glass:

Depth System (0-30 scale)

.glass-depth-5   /* Minimal blur - 4px */
.glass-depth-10  /* Subtle blur - 8px */
.glass-depth-15  /* Light blur - 12px */
.glass-depth-20  /* Default for controls - 16px */
.glass-depth-25  /* Medium blur - 20px */
.glass-depth-30  /* Heavy blur - 24px (max recommended) */

Frost Levels (10-25 for accessibility)

.glass-frost-10  /* Very transparent - 0.25 opacity */
.glass-frost-15  /* Light frost - 0.35 opacity */
.glass-frost-20  /* Default frost - 0.45 opacity */
.glass-frost-25  /* Heavy frost - 0.55 opacity */

Concentric Shapes

Nested elements automatically calculate proper border-radius:

<div class="glass glass-concentric">
  <div class="nested-content">
    <!-- Border radius automatically adjusted -->
  </div>
</div>

Motion-Responsive Highlights

Add motion response to glass elements:

<div class="glass glass-motion">
  <!-- Highlight responds to device orientation on mobile -->
  <!-- Falls back to mouse movement on desktop -->
</div>

Dynamic Light Adaptation

Glass elements can adapt to their background:

<div class="glass glass-adaptive">
  <!-- Automatically adjusts tint based on background color -->
</div>

Specular Highlights

Add animated specular highlights:

<div class="glass glass-specular">
  <!-- Subtle ambient highlight animation -->
</div>

Scroll Edge Effects

Two modes per Apple HIG:

<!-- Soft edges (iOS style) -->
<div class="scroll-edge-soft">
  <div class="scrollable-content">...</div>
</div>

<!-- Hard edges (macOS style) -->
<div class="scroll-edge-hard">
  <div class="scrollable-content">...</div>
</div>

Text Legibility on Glass

.glass-text             /* Subtle shadow for contrast */
.glass-text-bold        /* Heavier weight + shadow */
.glass-text-high-contrast /* Maximum legibility */

JavaScript API

Configuration

import liquidGlass from 'astro-liquid-glass/scripts/liquid-glass';

liquidGlass({
  maxGlassLayers: 4,        // Max compositing layers (warns if exceeded)
  highlightAmplitude: 4,    // Motion highlight amplitude (Apple HIG: max 6px)
  enableMotionResponse: true,
  enableBackgroundSampling: true,
  debugMode: false,         // Enable debug warnings and outlines
});

WCAG Contrast Verification

import { verifyAllGlassContrast, calculateContrastRatio } from 'astro-liquid-glass/scripts/liquid-glass';

// Verify all glass elements on page
const results = verifyAllGlassContrast();
results.forEach((result, element) => {
  console.log(`Ratio: ${result.ratio}, Passes AA: ${result.passesAA}`);
});

Battery Saver Detection

Automatically reduces effects when battery is low (<20% and not charging):

Reduces blur intensity
Disables animations
Simplifies effects

Components

Layout Components

BaseLayout - Base HTML layout with mesh gradient
BookLayout - Layout with sidebar TOC for documentation
ReferenceLayout - Layout with right sidebar

Navigation Components

Header - Floating glass navigation header
TabBar - Floating glass tab bar with scroll minimization
Sidebar - Inset floating sidebar with glass treatment
Toolbar - Auto-grouped toolbar items with glass

Interactive Controls

Toggle - Glass toggle/switch with enlarging nub
Slider - Glass slider with responsive thumb
SegmentedControl - Animated segment selector
Chip - Pill-shaped filter tags

Presentation Components

Sheet - Bottom sheet with morphing heights
Alert - Alert dialog with left-aligned typography
ActionSheet - iOS-style action sheet
ContextMenu - Right-click/long-press menu
Toast - Floating notification snackbar

Feedback Components

Progress - Linear, circular, and dots progress indicators
Badge - Notification badges with glass variant

Content Components

Hero - Full-bleed hero with glass overlay options
GlassCard - Versatile glass card component
ChapterCard - Card for chapter/section links
GlossaryTerm - Term definition card
ReferenceItem - Academic reference card
ExpertCard - Expert quote card
FAQ - Accordion FAQ component

Utility Components

TableOfContents - Sticky TOC with scroll highlighting
SearchInput - Glass search input
MeshGradient - Animated gradient background
Footer - Glass footer with navigation groups

CSS Classes

Glass Materials

.glass - Primary glass material
.glass-nav - Navigation glass
.glass-card - Card glass
.glass-modal - Modal glass
.glass-subtle - Subtle glass

Depth Variants

.glass-depth-5 through .glass-depth-30
.glass-frost-10 through .glass-frost-25

Special Effects

.glass-motion - Motion-responsive highlights
.glass-adaptive - Background-adaptive tinting
.glass-specular - Animated specular highlight
.glass-concentric - Concentric shape system

Interactive Controls

.lg-toggle - Toggle/switch control
.lg-slider - Slider control
.lg-segmented - Segmented control
.lg-stepper - Stepper control
.lg-chip - Chip/tag element
.lg-badge - Badge element
.lg-progress - Progress bar
.lg-spinner - Loading spinner
.lg-activity - Activity indicator (dots)

Navigation

.lg-tab-bar - Floating tab bar
.lg-sidebar - Floating sidebar
.lg-toolbar - Toolbar
.lg-navbar - Navigation bar

Presentations

.lg-sheet - Bottom sheet
.lg-alert - Alert dialog
.lg-action-sheet - Action sheet
.lg-context-menu - Context menu
.lg-popover - Popover
.lg-toast - Toast notification
.lg-dimming - Dimming overlay

Hero & Media

.lg-hero - Hero section
.lg-media-controls - Media player controls

Selection

.lg-selection-list - Selection list
.lg-selection-item - Selection item

Typography

.text-large-title - 44pt bold
.text-title-1 - 34pt bold
.text-title-2 - 28pt semibold
.text-title-3 - 24pt semibold
.text-headline - 17pt semibold
.text-body - 17pt regular
.text-callout - 20pt regular
.text-subheadline - 13pt regular
.text-footnote - 11pt regular
.text-caption - 11pt caps
.glass-text - Text on glass surfaces
.glass-text-bold - Bold text on glass
.glass-text-high-contrast - Maximum legibility

Layout

.container - Max 1200px centered
.container-narrow - Max 720px
.container-wide - Max 1440px
.grid-2, .grid-3, .grid-4 - Grid columns
.section, .section-sm, .section-lg - Section padding

Backgrounds

.mesh-gradient - Static mesh gradient
.mesh-gradient-animated - Animated gradient with orbs
.section-gradient - Subtle section gradient

Scroll Effects

.scroll-edge-soft - iOS-style soft scroll edges
.scroll-edge-hard - macOS-style hard scroll edges

Buttons

.btn - Base button
.btn-primary - Primary action
.btn-secondary - Secondary action
.btn-ghost - Ghost button
.btn-sm, .btn-lg - Size variants

Animations

.spring-in, .spring-out - Spring scale animations
.spring-up, .spring-down - Spring slide animations
.morph-expand, .morph-collapse - Shape morphing
.morph-thick, .morph-thin - Material thickness
.touch-press, .touch-press-deep - Touch feedback
.touch-ripple - Ripple effect
.bounce-top, .bounce-bottom - Elastic bounce
.sheet-appear, .sheet-dismiss - Sheet transitions

Utilities

Full set of flexbox, spacing, and responsive utilities

CSS Variables

All design tokens are exposed as CSS variables:

:root {
  /* Glass Depth System (Apple HIG 0-30) */
  --glass-depth-0 through --glass-depth-30

  /* Glass Frost Levels (Apple HIG 10-25) */
  --glass-frost-10 through --glass-frost-25

  /* Motion Response */
  --glass-motion-x, --glass-motion-y
  --glass-tilt-x, --glass-tilt-y
  --glass-highlight-amplitude: 4px /* Max 6px per Apple HIG */

  /* Dynamic Tint */
  --glass-tint, --glass-tint-opacity

  /* Glass Base */
  --glass-bg, --glass-blur, --glass-border, --glass-highlight

  /* Concentric Shapes */
  --radius-inset-sm, --radius-inset-md, --radius-inset-lg
  --radius-lg-nested, --radius-xl-nested, --radius-md-nested

  /* Colors */
  --color-primary, --color-secondary, --color-success, --color-warning, --color-danger

  /* Typography */
  --font-system, --font-text, --font-mono, --font-swiss
  --text-xs through --text-4xl

  /* Spacing */
  --space-1 through --space-24

  /* Radius */
  --radius-sm, --radius-md, --radius-lg, --radius-xl, --radius-pill
}

Accessibility

Reduced Motion

Respects prefers-reduced-motion: reduce:

Disables parallax effects
Removes scroll animations
Simplifies transitions

Reduced Transparency

Respects prefers-reduced-transparency: reduce:

Uses solid backgrounds instead of glass
Removes backdrop blur
Increases opacity

High Contrast

Respects prefers-contrast: more:

Increases border visibility
Uses bolder text weights
Enhances color contrast

WCAG Compliance

Built-in contrast verification utility
Text rendering optimized for glass surfaces
Minimum 4.5:1 contrast ratio enforcement (AA)
Debug mode highlights failing elements

Performance

Compositing Layer Limits

Apple HIG recommends max 4 glass layers per screen. The library warns when exceeded:

// In debug mode, excess layers are highlighted
liquidGlass({ debugMode: true });

Battery Saver

Automatically detects low battery and reduces effects:

Blur reduced to 8px
Animations disabled
Orb movement stopped

Browser Support

Chrome/Edge 76+
Firefox 103+
Safari 14+

Includes fallbacks for browsers without backdrop-filter support.

License

MIT

Author

Jawad Yaqub

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Astro Liquid Glass

Features

Installation

Component Library Demo

Quick Start

1. Import the Styles

2. Add the Script

3. Use the Components

Sheet Component

Apple HIG Compliance

Depth System (0-30 scale)

Frost Levels (10-25 for accessibility)

Concentric Shapes

Motion-Responsive Highlights

Dynamic Light Adaptation

Specular Highlights

Scroll Edge Effects

Text Legibility on Glass

JavaScript API

Configuration

WCAG Contrast Verification

Battery Saver Detection

Components

Layout Components

Navigation Components

Interactive Controls

Presentation Components

Feedback Components

Content Components

Utility Components

CSS Classes

Glass Materials

Depth Variants

Special Effects

Interactive Controls

Navigation

Presentations

Hero & Media

Selection

Typography

Layout

Backgrounds

Scroll Effects

Buttons

Animations

Utilities

CSS Variables

Accessibility

Reduced Motion

Reduced Transparency

High Contrast

WCAG Compliance

Performance

Compositing Layer Limits

Battery Saver

Browser Support

License

Author