---
## ✨ What is GlassKit?
GlassKit is a complete **CSS component library** with glassmorphism aesthetics – inspired by **iOS 26 Liquid Glass** and visionOS. Apple fundamentally redefined glass design with iOS 26: deeper blur effects, luminous borders, and dynamic light reflections on surfaces. GlassKit brings exactly this look to the web – for apps and UIs that feel modern and native.
**One CSS file. No build tools. No dependencies.**
GlassKit is the **CSS foundation** of a three-layer family: [GlassKit Elements](https://glasskit-elements.jungherz.com) builds web components for application UIs on top of it, and [GlassKit Web](https://glasskit-web.jungherz.com) is the official Astro template for complete websites – three layers, one design language.
### Why GlassKit?
- 🎨 **Pure CSS** – no JavaScript framework required
- 🌗 **Dark & Light Mode** – toggle with a single attribute
- 🎛️ **Design Tokens** – all values controlled via CSS Custom Properties
- 📱 **Mobile-first** – optimized for touch devices and `safe-area-inset`
- 🔌 **Framework-agnostic** – works with React, Vue, Svelte, plain HTML, or any other stack
- 🧩 **Shadow DOM ready** – Constructable Stylesheet for Web Components included
- 🪶 **Lightweight** – 51 KB raw / 39 KB minified / 6.5 KB gzipped, no external dependencies
- 🎯 **BEM-like naming convention** – `glass-*` prefix, no conflicts with existing CSS
- 🤖 **AI-ready** – ships with [`SKILL.md`](SKILL.md), a structured reference for LLMs & AI copilots
---
## 📥 Installation
GlassKit can be included in several ways – choose the one that best fits your project:
### CDN (recommended for quick start)
No download, no build tool – just include and go:
```html
```
> **Tip:** Replace `@1.6` with `@latest` for the newest version – or pin to a specific version for maximum stability.
### npm / yarn / pnpm
For projects with a build pipeline:
```bash
# npm
npm install @jungherz-de/glasskit
# yarn
yarn add @jungherz-de/glasskit
# pnpm
pnpm add @jungherz-de/glasskit
```
Then import in your CSS or build tool:
```css
/* In your CSS file */
@import '@jungherz-de/glasskit/glasskit.css';
```
```js
// Or in JS (Webpack, Vite, etc.)
import '@jungherz-de/glasskit/glasskit.css';
```
### Direct Download
Download the files directly from the [GitHub Release](https://github.com/JUNGHERZ/GlassKit/releases/latest):
```html
```
---
## 🚀 Quick Start
### 1. Set the theme
```html
```
### 2. Start building
```html
Hello World
This is GlassKit.
```
---
## 📦 Components
### Navigation & Layout
| Component | Class | Description |
|---|---|---|
| **Background** | `.glass-bg` | Aurora gradient with light effects |
| **Nav Bar** | `.glass-nav` | Transparent navigation |
| **Pill Button** | `.glass-pill` | Round glass icon button (46×46) |
| **Tab Bar** | `.glass-tab-bar` | Fixed bottom navigation |
| **Tab Bar – Floating** | `.glass-tab-bar--floating` + `.glass-tab-bar-dock` | Pill-shaped Liquid-Glass tab bar with optional `.glass-tab-bar__accessory` capsule |
| **Accordion** | `.glass-accordion` | Collapsible content sections |
| **Divider** | `.glass-divider` | Fading separator line |
### Content
| Component | Class | Description |
|---|---|---|
| **Title** | `.glass-title` | Page title with text shadow |
| **Card** | `.glass-card` | Glass container for content |
| **Card (Glow)** | `.glass-card--glow` | Card with light-to-milky gradient |
| **Badge** | `.glass-badge` | Tags & labels |
| **Avatar** | `.glass-avatar` | Glass circle (sm/md/lg) |
| **Status** | `.glass-status` | Notice card with icon |
| **List** | `.glass-list` | iOS-style grouped settings list with auto dividers |
### Actions & Feedback
| Component | Class | Description |
|---|---|---|
| **Button (Primary)** | `.glass-btn--primary` | Colored gradient – primary action |
| **Button (Secondary)** | `.glass-btn--secondary` | Milky white – secondary action |
| **Button (Tertiary)** | `.glass-btn--tertiary` | Subtle glass – tertiary action |
| **Modal** | `.glass-modal` | Centered dialog with blur overlay |
| **Toast** | `.glass-toast` | Temporary notification |
| **Popover** | `.glass-popover` | Anchored dropdown / menu with fade & scale animation |
### Form Elements
| Component | Class | Description |
|---|---|---|
| **Input** | `.glass-input` | Text field with glass background |
| **Textarea** | `.glass-textarea` | Multi-line input |
| **Select** | `.glass-select` | Dropdown with custom chevron |
| **Search** | `.glass-search` | Input with search icon |
| **Toggle** | `.glass-toggle` | iOS-style switch |
| **Checkbox** | `.glass-checkbox` | Animated checkmark |
| **Radio** | `.glass-radio` | Animated dot |
| **Range Slider** | `.glass-range` | Slider with gradient thumb |
| **Progress Bar** | `.glass-progress` | Progress bar with shimmer |
---
## 🌗 Theming
### Dark / Light Mode
GlassKit supports two themes out of the box. Toggle via the `data-theme` attribute:
```js
// Toggle
function toggleTheme() {
const html = document.documentElement;
const current = html.getAttribute('data-theme');
html.setAttribute('data-theme', current === 'dark' ? 'light' : 'dark');
}
```
There's also a ready-made **Theme Toggle component**:
```html
```
### Custom Brand Colors
Create a `theme-override.css` and load it **after** the base library:
```css
/* theme-override.css */
:root {
--gl-color-primary: #007AFF;
--gl-color-primary-dark: #0055CC;
}
```
Since **1.11.0** that is the whole job. The gradient midpoint, the warm rim, the focus
ring, the glow under the primary button and the range slider thumb are all mixed from
those two — before 1.11.0 they were fixed amber, so a re-branded button came with an
orange halo and an amber focus ring. Declare the brand on `:root`: a custom property is
substituted where it is *declared*, so a brand set on a subtree does not re-derive the
tokens inherited from `:root`. Every derived token is still a plain default and loses to
a later declaration if you want to bend one.
The `theme-override.css` template comes with **4 example themes**:
- 🔵 Ocean Blue
- 🟢 Emerald Green
- 🌹 Rose
- 🎨 Custom (empty, ready to fill)
---
## 🎛️ Design Tokens
All visual values are controlled via CSS Custom Properties:
```css
/* Colors */
--gl-color-primary /* Primary color */
--gl-color-text /* Text color */
--gl-color-text-muted /* Secondary text */
/* Glass surfaces (gradations) */
--gl-surface-1 … --gl-surface-5
/* Blur */
--gl-blur /* 24px – default */
--gl-blur-light /* 16px */
--gl-blur-heavy /* 40px */
/* Radii */
--gl-radius-card /* 24px */
--gl-radius-btn /* 16px */
--gl-radius-input /* 14px */
/* Spacing */
--gl-space-xs … --gl-space-4xl
/* Shadows & Insets */
--gl-shadow-card
--gl-inset-strong
```
The full token reference can be found in the [Documentation](docs.html).
---
## 🛠️ Utility Classes
```css
/* Flex Layout */
.gl-stack /* Vertical stack */
.gl-stack--sm /* Gap: 12px */
.gl-row /* Horizontal row */
.gl-row--sm /* Gap: 12px */
/* Spacing */
.gl-mt-md /* Margin-top: 16px */
.gl-mb-lg /* Margin-bottom: 20px */
.gl-px /* Horizontal padding */
/* Text */
.gl-text-center
.gl-text-muted
.gl-text-sm
/* Layout */
.gl-w-full
.gl-flex-1
```
---
## 🧩 Web Components / Shadow DOM
The Shadow DOM encapsulates styles – external stylesheets like `glasskit.css` are not automatically inherited into the shadow tree. GlassKit therefore ships a ready-made **Constructable Stylesheet** that you can use directly in Web Components.
### The Problem
- CSS classes (`.glass-card`, `.glass-btn`, etc.) do **not** work inside the Shadow DOM
- Only **CSS Custom Properties** (`--gl-*`) penetrate the shadow boundary automatically
- Without a solution, each component would need to load and parse the CSS itself
### The Solution: `glasskit-styles.js`
GlassKit provides an ES module that exports the minified CSS as a [Constructable Stylesheet](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/CSSStyleSheet). The stylesheet is held **once** in memory and can be shared across any number of shadow roots – without duplicate parsing.
```js
import { glassSheet } from '@jungherz-de/glasskit/glasskit-styles.js';
// In a Web Component:
class MyCard extends HTMLElement {
constructor() {
super();
const shadow = this.attachShadow({ mode: 'open' });
shadow.adoptedStyleSheets = [glassSheet];
shadow.innerHTML = `
`;
}
}
customElements.define('my-card', MyCard);
```
### Example: Hybrids.js
GlassKit works great with lightweight Web Component frameworks like [Hybrids](https://hybrids.js.org/):
```js
import { define, html } from 'hybrids';
import { glassSheet } from '@jungherz-de/glasskit/glasskit-styles.js';
define({
tag: 'my-card',
render: () => html`
`.css(glassSheet),
});
```
### Example: Lit
```js
import { LitElement, html } from 'lit';
import { glassSheet } from '@jungherz-de/glasskit/glasskit-styles.js';
class MyCard extends LitElement {
static styles = [glassSheet];
render() {
return html`
`;
}
}
customElements.define('my-card', MyCard);
```
### Exports
| Export | Type | Description |
|---|---|---|
| `glassSheet` | `CSSStyleSheet` | Ready-made Constructable Stylesheet – use directly with `adoptedStyleSheets` |
| `css` | `string` | CSS as string – fallback for environments without Constructable Stylesheet support |
### Theming in the Shadow DOM
Since CSS Custom Properties penetrate the shadow boundary, **theme switching works automatically**. Set `data-theme` on the `` element as usual – all GlassKit tokens will be updated across all shadow roots:
```js
// Works globally – including all Web Components
document.documentElement.setAttribute('data-theme', 'light');
```
> **Tip:** For maximum performance with many component instances, import `glassSheet` once and share it across all components. The browser keeps the stylesheet in memory only once.
---
## 📁 Project Structure
```
glasskit/
├── glasskit.css # Core library (all components + tokens)
├── glasskit.min.css # Minified version (auto-generated on release)
├── glasskit-styles.js # Constructable Stylesheet for Shadow DOM (auto-generated)
├── theme-override.css # Template for custom themes
├── build-styles-js.mjs # Build script for glasskit-styles.js
├── package.json # npm package definition
├── index.html # Landing page with iPhone wireframe
├── showcase.html # Interactive showcase of all components
├── docs.html # Full documentation
├── de/ # German translations (index, docs, showcase)
├── SKILL.md # AI-optimized component reference (for LLMs & copilots)
├── LICENSE # MIT License
└── README.md # This file
```
---
## 📖 Documentation
The full documentation with **live previews**, **copy-paste code blocks**, and **class reference tables** is available in `docs.html`:
- Sidebar navigation to all 24 components
- Live previews on a real glassmorphism background
- Design token reference
- Theming guide
- Complete class overview at the end
Live pages:
- 🌐 Home: https://glasskit.jungherz.com/
- 📖 Docs: https://glasskit.jungherz.com/docs.html
- 🧪 Showcase: https://glasskit.jungherz.com/showcase.html
## 🧩 The GlassKit Family
GlassKit is the CSS foundation of a three-layer family – three layers, one design language.
### GlassKit Elements – the app layer
If you want to use GlassKit through **drop-in Web Components** instead of writing the full HTML structure yourself, take a look at **GlassKit Elements**.
GlassKit Elements builds on top of GlassKit CSS and provides a set of vanilla JavaScript custom elements like `glk-button`, `glk-card`, or `glk-input`.
Useful links:
- GitHub: https://github.com/JUNGHERZ/GlassKit-Elements
- Live Demo: https://glasskit-elements.jungherz.com/
- Docs: https://glasskit-elements.jungherz.com/docs.html
### GlassKit Web – the website layer
If you want to build a **complete website** rather than assemble components yourself, **GlassKit Web** is the intended path: the official Astro template with sections, i18n, SEO, and tests on top of the GlassKit foundation.
Useful links:
- GitHub: https://github.com/JUNGHERZ/GlassKit-Web
- Website: https://glasskit-web.jungherz.com/
---
## 🤖 AI / LLM Reference (`SKILL.md`)
GlassKit ships with an **AI-optimized component reference** in [`SKILL.md`](SKILL.md). This file is designed for LLMs, AI copilots, and code-generation tools to produce correct GlassKit markup without parsing `docs.html`.
### What it provides
- **Copy-paste-ready HTML** for all 24 components with exact nesting rules
- **Complete design token tables** (colors, surfaces, blur, radii, spacing, shadows, typography)
- **State class reference** – which class goes where (`is-active`, `is-open`, `is-visible`, `:checked`)
- **6 composition patterns** – full page layouts (Login, Dashboard, Form, Modal, Settings, Progress)
- **Common mistakes & corrections** – prevents the most frequent AI-generated errors
- **Quick reference table** – all components with their modifiers at a glance
### Usage with AI assistants
Attach or reference `SKILL.md` when asking an AI to generate GlassKit HTML. It provides the structured context needed for production-ready output – correct BEM hierarchy, proper modifier usage, and idiomatic component composition.
> **Tip:** While `docs.html` is built for humans browsing with live previews, `SKILL.md` is built for machines generating code. Both are kept in sync.
---
## 🌐 Browser Compatibility
GlassKit uses `backdrop-filter` for glass effects. Support:
| Browser | Support |
|---|---|
| Safari (iOS/macOS) | ✅ Full |
| Chrome / Edge | ✅ Full |
| Firefox | ✅ From version 103 |
| Samsung Internet | ✅ Full |
> **Note:** In browsers without `backdrop-filter` support, elements will be rendered with the defined background colors – the UI remains usable, just without the blur effect.
---
## 📋 States & Modifiers – Cheat Sheet
```
Interactive States:
.is-active → Tab Bar item, Modal Overlay
.is-open → Accordion item, Popover
.is-visible → Toast
:checked → Toggle, Checkbox, Radio
:focus → Input, Textarea, Select, Range
:disabled → Input
Button Modifiers:
.glass-btn--primary / --secondary / --tertiary
.glass-btn--sm / --lg / --auto
Card Modifiers:
.glass-card--glow
Progress Modifiers:
.glass-progress--sm / --lg
.glass-progress--success / --error
Badge Modifiers:
.glass-badge--primary / --success / --error
Avatar Modifiers:
.glass-avatar--sm / --lg
Toast Modifiers:
.glass-toast--success / --error / --warning
Modal Action Modifiers:
.glass-modal__action--primary / --danger
List Modifiers:
.glass-list--flush / --bare
.glass-list__item--interactive / --center
Popover Modifiers:
.glass-popover--top / --start / --end
Background Modifiers:
.glass-bg--has-tab-bar
.glass-bg--has-tab-bar-floating
Tab Bar – Floating:
.glass-tab-bar-dock
.glass-tab-bar--floating
.glass-tab-bar__accessory
.glass-tab-bar__accessory--accent / --success / --error
```
---
## 🤝 Contributing
Contributions are welcome! Here's how you can help:
1. **Fork** the repository
2. Create a **feature branch** (`git checkout -b feature/my-idea`)
3. **Commit** your changes (`git commit -m 'feat: New component XY'`)
4. **Push** the branch (`git push origin feature/my-idea`)
5. Open a **Pull Request**
### Guidelines
- Follow the **BEM-like naming convention** (`glass-*` prefix)
- Use existing **Design Tokens** instead of hard-coded values
- Make sure new components work in **both Dark and Light Mode**
- Test on **mobile** (touch targets at least 44px)
---
## 📄 License
GlassKit is released under the **MIT License**. See [LICENSE](LICENSE) for details.
Free to use for personal and commercial projects.
---
## 📋 Changelog
All changes, bugfixes, and design decisions are documented in the **[CHANGELOG.md](CHANGELOG.md)**.
---
## 🏢 Credits
Developed by **[Jungherz GmbH](https://www.jungherz.com)**
---
