--- name: glasskit-css description: GlassKit is a pure CSS glassmorphism component library (v1.19.1) with 34 components, Dark & Light mode, design tokens, and BEM-like naming. Use this reference whenever generating HTML that uses GlassKit classes to ensure correct structure, nesting, modifiers, and token usage. --- # GlassKit CSS – AI Component Reference > **Purpose:** This document is an AI-optimized reference for generating correct GlassKit HTML markup. > It replaces the need to parse `docs.html` and provides copy-paste-ready structures, rules, and composition patterns. --- ## 1. Setup & Boilerplate ### Including the Library ```html ``` ### Minimal Template ```html
``` ### Naming Convention - **Prefix:** All components use `glass-` (e.g. `glass-card`, `glass-btn`) - **Utilities:** Use `gl-` (e.g. `gl-stack`, `gl-row`, `gl-mt-md`) - **BEM logic:** `glass-component__element--modifier` - Element: `glass-card__text`, `glass-modal__header` - Modifier: `glass-btn--primary`, `glass-avatar--lg` - **State classes:** `is-active`, `is-open`, `is-visible` (standalone, not BEM) ### Theming The theme is controlled via `data-theme` on ``: ```html ``` Both theme blocks also set `color-scheme` (`dark` / `light`), which is how the *browser* is told which scheme to paint its own widgets in — date and time pickers, number spinners, ` Optional help text ``` Error state: ```html
Please enter a valid email address
``` Disabled: ```html ``` Date and time fields (`type="date"`, `time`, `datetime-local`, `month`) take the same class. Since 1.17.0 they drop the native appearance, so iOS keeps them at the column width with the value at the start, like every other field; the native picker still opens. ```html ``` | Class | Description | |---|---| | `.glass-input-group` | Wrapper for label + input + hint | | `.glass-label` | Label (small, muted, uppercase) | | `.glass-input` | Text input (glass background) | | `.glass-input--error` | Red border for error state | | `.glass-hint` | Help text below input | | `.glass-hint--error` | Red help text | --- ### 3.15 Textarea Multi-line text field. ```html ``` | Class | Description | |---|---| | `.glass-textarea` | Multi-line glass input | --- ### 3.16 Select Dropdown with glass styling and custom chevron. ```html ``` | Class | Description | |---|---| | `.glass-select` | Styled dropdown | --- ### 3.17 Search Search field with embedded search icon. ```html
``` | Class | Description | |---|---| | `.glass-search` | Wrapper (position: relative) | | `.glass-search__icon` | Positioned search icon (left) | **Important:** The input inside `.glass-search` uses the regular `.glass-input` class. --- ### 3.18 Toggle Switch iOS-style switch. ```html ``` | Class | Description | |---|---| | `.glass-toggle` | Outer label (flex container) | | `.glass-toggle__input` | Hidden checkbox input | | `.glass-toggle__track` | Visible track | | `.glass-toggle__thumb` | Movable thumb | | `.glass-toggle__label` | Text label | **State:** `:checked` on the input activates the toggle visually. --- ### 3.19 Checkbox Animated checkbox with checkmark SVG. ```html ``` | Class | Description | |---|---| | `.glass-checkbox` | Outer label | | `.glass-checkbox__input` | Hidden checkbox input | | `.glass-checkbox__box` | Visible box with checkmark SVG | | `.glass-checkbox__label` | Text label | > **Multi-line labels (since 1.11.0).** The box lines up with the **first line** of the > label, not with the middle of the text block — a consent label runs over several lines > and a centred box points at nothing. Same for `.glass-radio` and `.glass-toggle`. > Single-line labels are unaffected. Nothing to set; it is the default. --- ### 3.20 Radio Button Animated radio button with dot. ```html ``` | Class | Description | |---|---| | `.glass-radio` | Outer label | | `.glass-radio__input` | Hidden radio input | | `.glass-radio__circle` | Visible circle | | `.glass-radio__dot` | Inner dot (visible on :checked) | | `.glass-radio__label` | Text label | **Important:** Radio buttons in the same group need the same `name` attribute value. --- ### 3.21 Range Slider Slider with gradient thumb. Used in a group with header and value display. ```html
75%
``` | Class | Description | |---|---| | `.glass-range-group` | Wrapper | | `.glass-range-header` | Flex container for label + value | | `.glass-range-value` | Value display (right) | | `.glass-range` | The actual slider | --- ### 3.22 Progress Bar Progress bar with optional shimmer effect. ```html
Upload 68%
``` | Class | Description | |---|---| | `.glass-progress` | Base container | | `.glass-progress--sm` | Narrow track (4px) | | `.glass-progress--lg` | Wide track (12px) | | `.glass-progress--success` | Green bar | | `.glass-progress--error` | Red bar | | `.glass-progress__header` | Flex container for label + value | | `.glass-progress__label` | Label (left) | | `.glass-progress__value` | Percentage value (right) | | `.glass-progress__track` | Background track | | `.glass-progress__fill` | Filled area (width via `style="width: X%"`) | **Important:** Progress width is controlled via inline `style="width: X%"` on `.glass-progress__fill`. --- ### 3.23 Accordion Collapsible content sections. Controlled via `is-open` on items. ```html
The answer to question one.
The answer to question two.
``` | Class | Description | |---|---| | `.glass-accordion` | Container | | `.glass-accordion__item` | Individual item | | `.glass-accordion__item.is-open` | Expanded item | | `.glass-accordion__trigger` | Clickable header button | | `.glass-accordion__trigger-icon` | Chevron icon (rotates on open) | | `.glass-accordion__content` | Wrapper for animated height | | `.glass-accordion__body` | Actual content | --- ### 3.24 List iOS-style grouped settings list. Items can carry a leading icon, a title with optional subtitle, and a trailing element (chevron, value, button). Dividers between items are drawn automatically via `::after` — **never add divider markup manually**. ```html ``` ```html ``` ```html
Recommendations
``` | Class | Description | |---|---| | `.glass-list` | Grouped surface container | | `.glass-list--flush` | Edge-to-edge variant (no side margin / radius). Assumes parent has `--gl-space-lg` horizontal padding. | | `.glass-list--bare` | Strips background, border & shadow — for embedding inside `.glass-popover` or `.glass-card`. | | `.glass-list__section-header` | Section label above a `.glass-list` — uppercase, small, muted | | `.glass-list__item` | List row (use `
  • `, ``, or `
    • Share
    • Duplicate
    • Delete
    ``` | Class | Description | |---|---| | `.glass-popover-anchor` | Positioning context — wraps trigger + popover | | `.glass-popover` | Floating glass surface, hidden until `.is-open` | | `.glass-popover.is-open` | Visible state — fade + scale animation | | `.glass-popover--top` | Opens upward (above the trigger) | | `.glass-popover--start` | Aligns left edge with trigger | | `.glass-popover--end` | Aligns right edge with trigger | **Note:** name your toggle function anything except `togglePopover` — that name collides with the native `HTMLElement.togglePopover()` method (HTML Popover API) and inline `onclick` handlers will throw `NotSupportedError`. Use a prefix like `gkTogglePopover` or `myToggle`. --- ### 3.26 Skeleton Loading placeholder — shimmer lines standing in for text that has not arrived (since 1.14.0). Set each line's width inline; the shimmer follows the theme and holds still under `prefers-reduced-motion`. Mark the region `aria-busy="true"`. ```html
    ``` | Class | Description | |---|---| | `.glass-skeleton` | Stack of lines, 10px apart | | `.glass-skeleton__line` | One shimmer line (12px); width via inline style | | `.glass-skeleton__line--title` | Taller line (18px) standing in for a heading | --- ### 3.27 Table A plain `` on glass (since 1.14.0): hairline rows, a muted header, numbers right-aligned in tabular figures. Wrap it in `.glass-table-wrap` to scroll sideways where the columns do not fit. ```html
    DateItemAmount
    2026-09-18Invoice #10421,240.00
    2026-09-20Pending–
    ``` | Class | Description | |---|---| | `.glass-table-wrap` | Optional horizontal scroll container | | `.glass-table` | The table: hairline rows, hover highlight on body rows | | `.glass-table__num` | Right-aligned, tabular figures — on `th` and `td` | | `.glass-table__muted` | Secondary text colour on a cell | > **Document-level by design.** From a shadow root, `::slotted()` matches only the slotted `` itself, never its cells — so there is no ``, and a wrapper element could not style the rows. Put the class on the table in the light DOM. --- ### 3.28 Prose Running text the app did not write by hand (since 1.14.0) — rendered Markdown, help and info pages. One class on the container styles `h1`–`h3`, `p`, `ul`/`ol`, `a`, `code`, `pre`, `blockquote`, `img`, `hr` and `table`. Links are underlined, because colour alone does not mark a link in running text. First and last children lose their outer margins, so the block sits flush inside a card. ```html

    Getting started

    Include glasskit.css and set data-theme — see the tokens.

    • Dark mode is the default
    The glass effect needs a coloured background.
    ``` > **Document-level by design**, for the same reason as the table: the content is light DOM, and `::slotted()` stops at the first level. Render Markdown into the document and put `.glass-prose` on the container. --- ### 3.29 Segmented A small, exclusive choice as one control (since 1.15.0) — traffic light, morning / afternoon, mode. Buttons inside a `role="group"`; the chosen one carries `aria-pressed="true"`, and the styling hangs on that attribute, so state and semantics cannot drift apart. Script only toggles `aria-pressed`; GlassKit Elements ships it as ``. ```html
    ``` More options than fit — seven areas on a phone: without a modifier the row stays one line and runs past the edge. `--scroll` keeps one row and lets it scroll sideways (scrollbar hidden, as on the date strip); `--wrap` breaks it into lines. Both combine with `--full`; use one or the other. ```html
    ``` | Class | Description | |---|---| | `.glass-segmented` | The group: inset glass track, buttons inside | | `.glass-segmented--full` | Buttons share the width | | `.glass-segmented--scroll` | One row that scrolls sideways when the options do not fit, scrollbar hidden (since 1.17.0) | | `.glass-segmented--wrap` | Breaks the row into lines when the options do not fit (since 1.17.0) | | `.glass-segmented__item` | One option; `aria-pressed="true"` marks the chosen one, `disabled` dims it | | `.glass-segmented__item--success` / `--warning` / `--error` | Tone: sets `--gl-segmented-tone` for the dot | | `.glass-segmented__dot` | The dot before the label, in the tone colour | --- ### 3.30 Steps Progress through a short flow (since 1.15.0): numbered circles joined by hairlines, done ones on the success surface with an SVG check, the current one in primary and marked `aria-current="step"`. The list is a size container: narrower than 360 px only the current step keeps its label; before that, labels shorten with an ellipsis. Keyed to the block's own width — inside a flex row give it a width, size containment leaves it none. ```html
    1. Day
    2. 2Slot
    3. 3Confirm
    ``` | Class | Description | |---|---| | `.glass-steps` | The list, a size container | | `.glass-steps__item`, `--done`, `--current` | One step and its states | | `.glass-steps__num` | The circle: number, or an SVG check when done | | `.glass-steps__label` | Label; hidden below 360 px except on the current step | | `.glass-steps__line` | Hairline connector | --- ### 3.31 Sheet The bottom sheet (since 1.15.0) — the mobile sibling of the modal: `.glass-sheet-overlay` fades, `.glass-sheet` rises from the bottom edge, only the top corners rounded, grip, safe-area padding. Its own block rather than a modal modifier because layout, entry motion and gesture differ. `[hidden]` beats `display: flex`, so the overlay leaves the layout when closed; `prefers-reduced-motion: reduce` drops the transitions. `--inline` embeds the panel in the flow without an overlay. ```html ``` Show: remove `hidden`, force a reflow (`void overlay.offsetHeight`), add `.is-active` on the next animation frame. Hide: remove `.is-active`, set `hidden` after `transitionend` on the panel (fallback 400 ms), immediately under reduced motion. Close on scrim click and Escape. `` in GlassKit Elements does all of this. | Class | Description | |---|---| | `.glass-sheet-overlay` | Fixed overlay: scrim, blur, panel at the bottom; starts at opacity 0 | | `.glass-sheet-overlay.is-active` | Overlay visible, panel risen | | `.glass-sheet` | The panel: milky glass, top corners rounded, bottom safe-area padding | | `.glass-sheet--inline` | In the flow, no overlay, all corners rounded | | `.glass-sheet__grip`, `__title`, `__body`, `__actions` | Grip bar, heading, body, action column | --- ### 3.32 Empty state For empty lists and result pages (since 1.15.0): a centred column with a round icon plate, a title, a short muted text and room for one action. ```html
    …

    No bookings yet

    Pick a day and a dog — the team is looking forward to it.

    ``` | Class | Description | |---|---| | `.glass-empty` | Centred column | | `.glass-empty__icon` | 48 px round plate, 24 px stroked icon inside (`::slotted(svg)` twin) | | `.glass-empty__title`, `__text` | Heading and muted text (max 38 ch) | | `.glass-empty__action` | Room for one action or several: side by side with 8 px between them, wrapping and centred when narrow (since 1.17.0) | ### 3.33 Date strip A row of day chips that scrolls sideways (since 1.16.0) — a booking horizon, the days around today. Chips are buttons in a `role="group"`; the chosen one carries `aria-pressed="true"` (as in the segmented control), `--today` underlines the number, `:disabled` / `aria-disabled="true"` dim a day that cannot be chosen. The dot beneath the number lights up with a tone modifier; without one it is transparent, so all chips are the same height. Give each button an `aria-label` with the full date — the visible "Tu 22" is no name. The scrollbar is hidden; the strip pads itself 4 px so its own overflow does not clip the focus ring. `` in GlassKit Elements builds this from dates. ```html
    ``` | Class | Description | |---|---| | `.glass-date-strip` | Scrolling row, hidden scrollbar, 4 px padding | | `.glass-date-strip__day` | Chip button, 44 px minimum; `[aria-pressed="true"]` chosen on the primary surface; `:disabled` / `[aria-disabled="true"]` dimmed | | `.glass-date-strip__day--today` | Underlines the number | | `.glass-date-strip__wd`, `__num` | Weekday in small caps, day number | | `.glass-date-strip__mark` | 6 px dot, transparent without a tone | | `.glass-date-strip__mark--primary`, `--success`, `--warning`, `--error` | Tone via `--gl-date-strip-tone`; on the chosen chip every tone becomes the ink on primary (`--gl-date-strip-ink`) | --- ### 3.34 Calendar One month (since 1.16.0): a title between two round nav buttons, a weekday row and 42 square day buttons with up to three dots beneath the number. The chosen day carries `aria-pressed="true"`, `--today` draws a warm border, `--other` dims a day of the neighbouring month, `:disabled` / `aria-disabled="true"` dim a day outside the allowed range — the second keeps it focusable for arrow keys. The days are a `role="group"` of buttons named with their full date, not a `role="grid"` (a grid demands rows and cells with `aria-selected`). The nav buttons take an SVG chevron. `` in GlassKit Elements builds it, with keyboard navigation and `Intl` names. ```html
    September 2026
    ``` | Class | Description | |---|---| | `.glass-calendar` | Block | | `.glass-calendar__head`, `__title`, `__nav` | Head row; title (ellipsis when tight); 32 px round nav buttons with an SVG chevron | | `.glass-calendar__grid` | Seven columns, 4 px gap | | `.glass-calendar__wd` | Weekday header cell, muted small caps | | `.glass-calendar__day` | Square day button; `[aria-pressed="true"]` chosen; `--today` warm border; `--other` dimmed; `:disabled` / `[aria-disabled="true"]` dimmed and unpickable | | `.glass-calendar__marks`, `__mark` | 5 px dots beneath the number, up to three; `__mark--primary` / `--success` / `--warning` / `--error` via `--gl-calendar-tone`, the ink on the chosen day via `--gl-calendar-ink` | --- ### 3.35 Image picker Choosing one image with a preview (since 1.16.0): a 72 px plate — the picture with `object-fit: cover`, or a placeholder icon — and a column with the label, a hint and the actions, which are ordinary `.glass-btn` buttons (`--secondary --sm --auto` to choose, `--tertiary --sm --auto` to remove); the block brings no button look of its own. `--round` makes the plate a circle for avatars; the column yields and the label wraps, so a long label never squeezes the plate. Any image, not only photos — hence the name. `` in GlassKit Elements adds the file dialog, EXIF rotation and resizing. ```html
    Profile photo JPG or PNG
    ``` | Class | Description | |---|---| | `.glass-image-picker` | Row: plate left, column right, 14 px gap | | `.glass-image-picker__preview` | 72 px plate; `img` covers it, `svg` is the 28 px placeholder in the muted icon colour | | `.glass-image-picker__preview--round` | Circle, for avatars | | `.glass-image-picker__meta` | Column that yields (`min-width: 0`) | | `.glass-image-picker__label`, `__hint` | Label in the look of `.glass-label`, wraps anywhere; small muted hint | | `.glass-image-picker__actions` | Wrapping row of `.glass-btn` buttons | --- ## 4. Utility Classes ### Stack (Vertical) Flexbox column with gap. ```html
    Item 1
    Item 2
    ``` | Class | Gap | |---|---| | `.gl-stack` | Default | | `.gl-stack--2xs` | 4px | | `.gl-stack--xs` | 8px | | `.gl-stack--sm` | 12px | | `.gl-stack--md` | 16px | | `.gl-stack--lg` | 20px | | `.gl-stack--xl` | 24px | ### Row (Horizontal) Flexbox row with gap. ```html
    Tag 1 Tag 2
    ``` | Class | Gap | |---|---| | `.gl-row` | Default | | `.gl-row--xs` | 8px | | `.gl-row--sm` | 12px | | `.gl-row--md` | 16px | ### Margin | Class | Value | |---|---| | `.gl-mt-sm` | margin-top: 12px | | `.gl-mt-md` | margin-top: 16px | | `.gl-mt-lg` | margin-top: 20px | | `.gl-mt-xl` | margin-top: 24px | | `.gl-mb-sm` | margin-bottom: 12px | | `.gl-mb-md` | margin-bottom: 16px | | `.gl-mb-lg` | margin-bottom: 20px | | `.gl-mb-xl` | margin-bottom: 24px | ### Text | Class | Description | |---|---| | `.gl-text-center` | text-align: center | | `.gl-text-muted` | Muted text color | | `.gl-text-sm` | Smaller font size | ### Layout | Class | Description | |---|---| | `.gl-px` | Horizontal padding | | `.gl-w-full` | width: 100% | | `.gl-flex-1` | flex: 1 | --- ## 5. State Classes Overview | State Class | Used on | Description | |---|---|---| | `.is-active` | `.glass-modal-overlay`, `.glass-tab-bar__item` | Element is active/visible | | `.is-open` | `.glass-accordion__item`, `.glass-popover` | Accordion item expanded / popover visible | | `.is-visible` | `.glass-toast` | Toast is visible | | `:checked` | Toggle, Checkbox, Radio (on the input) | Native checked state | | `:focus` | Input, Textarea, Select, Range | Focus ring | | `:disabled` | `.glass-input` | Disabled input | --- ## 6. Composition Patterns ### Login Screen ```html

    Sign In

    ``` ### Dashboard with Cards ```html

    Capture and upload documents.

    Manage and archive contracts.

    ``` ### Form Page ```html

    New Contract

    ``` ### Delete Confirmation (Modal) ```html

    Delete contract?

    Do you want to permanently delete this contract? This action cannot be undone.

    ``` ### Settings Page ```html

    Settings

    100%
    Advanced options go here…
    ``` ### iOS-style Settings Screen (List + Popover) A grouped settings screen using `glass-list` for the rows and `glass-popover` for an inline action menu. Reproduces the layout of native iOS Settings screens. ```html
    Account
    • Marcel Jungherz
      marcel@jungherz.com
    • Subscriptions
      $34.94
    Notifications
    • Push notifications
      On
    • Email digest
      Weekly
    • Reset to defaults
    ``` Key points in this composition: - **Two grouped sections** — labeled by `.glass-list__section-header` above each list, matching iOS settings. - **Auto-dividers** — no `
    ` between rows; the `::after` pseudo-element handles them. - **Mixed trailing types** — chevron, value text, value + chevron, all in the same list. - **Centered destructive action** — last item uses `--center` for a "Reset to defaults" style row, gets a full-width divider above (no leading icon → standard padding inset). - **Popover in nav** — `glass-popover--end` aligns the menu to the right edge of the trigger so it doesn't overflow the viewport. - **Bare list inside popover** — `glass-list--bare` strips the inner glass surface so the popover stays the only glass layer. --- ### Progress + Toast ```html
    Upload 100%
    Upload successful!
    ``` --- ## 7. Rules & Common Mistakes ### ✅ Always follow 1. **`glass-bg` as outermost container** – Without the background wrapper, the aurora background is missing and glass effects won't render correctly. 2. **`glass-bg--has-tab-bar`** – When a tab bar is present, this modifier must be set on `glass-bg`, otherwise the tab bar covers the bottom content. 3. **Buttons are full-width** – `glass-btn` has `width: 100%`. Always add `glass-btn--auto` for inline buttons. 4. **Wrap inputs in `glass-input-group`** – For correct label/hint spacing. 5. **Place state classes correctly:** - `is-active` → on `.glass-modal-overlay` (not on `.glass-modal`) - `is-active` → on `.glass-tab-bar__item` - `is-open` → on `.glass-accordion__item` - `is-open` → on `.glass-popover` (not on the trigger or anchor) - `is-visible` → on `.glass-toast` 6. **SVG icons** – GlassKit uses inline SVGs (stroke-based, not fill). Typical attributes: `viewBox="0 0 24 24"`, stroke via `currentColor`. 7. **`data-theme`** – Always set on ``, never on `` or deeper elements. 8. **List dividers are automatic** – Never add a `
    ` or divider element between `.glass-list__item`s. The divider is rendered via `::after` and respects `:has(.glass-list__leading)` for the inset. 9. **Popover toggle naming** – Never name your popover toggle JS function `togglePopover`. It collides with the native `HTMLElement.togglePopover()` method. Use a prefix like `gkTogglePopover`. ### ❌ Common Mistakes | Mistake | Correction | |---|---| | `is-active` on `.glass-modal` instead of `.glass-modal-overlay` | Set `is-active` on the overlay | | `glass-btn` without variant (`--primary` etc.) | Always specify a variant | | Inputs without `glass-input-group` wrapper | Wrap in `glass-input-group` | | `glass-tab-bar` without `glass-bg--has-tab-bar` | Add modifier to the background container | | `data-theme` on `` | Set on `` | | Progress width via class instead of inline style | Use `style="width: X%"` on `.glass-progress__fill` | | Toggle without `__track > __thumb` nesting | Follow correct BEM hierarchy | | Manually adding `
    ` or divider element between `.glass-list__item`s | Remove it — dividers are automatic via `::after` | | Putting `glass-list` inside `glass-popover` without `--bare` | Add `.glass-list--bare` to strip the double glass surface | | JS function named `togglePopover()` | Rename to `gkTogglePopover()` or similar to avoid native API clash | | Putting `.is-open` on the trigger button instead of `.glass-popover` | The state class belongs on the popover element | --- ## 8. Quick Class Reference | Component | Base Class | Modifiers / States | |---|---|---| | Background | `.glass-bg` | `--has-tab-bar` | | Navigation | `.glass-nav` | – | | Pill Button | `.glass-pill` | – | | Theme Toggle | `.glass-theme-toggle` | – | | Title | `.glass-title` | – | | Card | `.glass-card` | `--glow` | | Button | `.glass-btn` | `--primary`, `--secondary`, `--tertiary`, `--sm`, `--lg`, `--auto` | | Badge | `.glass-badge` | `--primary`, `--success`, `--warning`, `--error`, `--interactive`, `--selected` | | Avatar | `.glass-avatar` | `--sm`, `--lg` | | Divider | `.glass-divider` | – | | Status | `.glass-status` | – | | Input | `.glass-input` | `--error`, `:disabled` | | Input Group | `.glass-input-group` | – | | Label | `.glass-label` | – | | Hint | `.glass-hint` | `--error` | | Textarea | `.glass-textarea` | – | | Select | `.glass-select` | – | | Search | `.glass-search` | – | | Toggle | `.glass-toggle` | `:checked` | | Checkbox | `.glass-checkbox` | `:checked` | | Radio | `.glass-radio` | `:checked` | | Range | `.glass-range` | – | | Progress | `.glass-progress` | `--sm`, `--lg`, `--success`, `--error` | | Modal | `.glass-modal-overlay` | `.is-active` | | Toast | `.glass-toast` | `--success`, `--error`, `--warning`, `.is-visible`, `__action`, `__close` | | Tab Bar | `.glass-tab-bar` | `.is-active` on items | | Accordion | `.glass-accordion` | `.is-open` on items | | List | `.glass-list` | `--flush`, `--bare`, `__item--interactive`, `__item--center`, `__item--danger`, `__item--accent`, `__leading--lg`, `__subtitle--wrap`, `__value`, `__section-header` | | Popover | `.glass-popover` | `--top`, `--start`, `--end`, `.is-open` | | Skeleton | `.glass-skeleton` | `__line`, `__line--title` | | Table | `.glass-table` | `-wrap`, `__num`, `__muted` | | Prose | `.glass-prose` | – | | Segmented | `.glass-segmented` | `--full`, `--scroll`, `--wrap`, `__item`, `__item--success`/`--warning`/`--error`, `__dot`, `[aria-pressed]` | | Steps | `.glass-steps` | `__item`, `__item--done`, `__item--current`, `__num`, `__label`, `__line` | | Sheet | `.glass-sheet-overlay` + `.glass-sheet` | `.is-active`, `--inline`, `__grip`, `__title`, `__body`, `__actions` | | Empty state | `.glass-empty` | `__icon`, `__title`, `__text`, `__action` | | Date strip | `.glass-date-strip` | `__day`, `__day--today`, `__wd`, `__num`, `__mark`, `__mark--primary`/`--success`/`--warning`/`--error`, `[aria-pressed]`, `:disabled` | | Calendar | `.glass-calendar` | `__head`, `__title`, `__nav`, `__grid`, `__wd`, `__day`, `__day--today`, `__day--other`, `__marks`, `__mark--primary`/`--success`/`--warning`/`--error`, `[aria-pressed]`, `[aria-disabled]` | | Image picker | `.glass-image-picker` | `__preview`, `__preview--round`, `__meta`, `__label`, `__hint`, `__actions` | --- ## 9. Web Components / Shadow DOM GlassKit ships a Constructable Stylesheet for Shadow DOM usage: ```js import { glassSheet } from '@jungherz-de/glasskit/glasskit-styles.js'; class MyCard extends HTMLElement { constructor() { super(); const shadow = this.attachShadow({ mode: 'open' }); shadow.adoptedStyleSheets = [glassSheet]; shadow.innerHTML = `

    `; } } customElements.define('my-card', MyCard); ``` | Export | Type | Description | |---|---|---| | `glassSheet` | `CSSStyleSheet` | Full sheet — rules **and** token declarations | | `css` | `string` | The same, as a string | | `componentsSheet` | `CSSStyleSheet` | Component rules only, no token declarations (since 1.9.0) | | `componentsCss` | `string` | The same, as a string | | `tokensSheet` | `CSSStyleSheet` | Only the two `[data-theme]` blocks that declare `--gl-*` (since 1.9.0) | | `tokensCss` | `string` | The same, as a string | CSS Custom Properties (`--gl-*`) cross the shadow boundary by inheritance, so the example above picks up whatever the document defines and theme switching works globally. > **Pitfall: do not put `data-theme` inside the shadow root while adopting `glassSheet`.** > The full sheet contains `:root, [data-theme="dark"] { … }`. If your shadow root holds an > element carrying `data-theme`, that selector matches it and re-declares every token > locally — and a matching rule always beats an inherited value. A project's > `:root { --gl-color-primary: … }` then silently stops arriving inside your component. > > If you need a themed element inside the shadow root, adopt `componentsSheet` instead > and make sure the tokens are present on the document: > > ```js > shadow.adoptedStyleSheets = [componentsSheet]; > > // once per page, if the document does not already link glasskit.css: > const defaults = new CSSStyleSheet(); > defaults.replaceSync(`@layer glasskit-defaults { ${tokensCss} }`); > document.adoptedStyleSheets = [...document.adoptedStyleSheets, defaults]; > ``` > > The cascade layer keeps an ordinary brand stylesheet winning over the defaults. This is > what GlassKit Elements does since 1.9.0. > **Pitfall: a descendant selector cannot reach a slotted icon.** `.glass-btn svg` only > matches real descendants. An icon passed in from outside stays in the light DOM, so the > rule never applies to it. Since 1.10.0 every icon rule that sits above a slot has a > `::slotted()` twin, so passing an icon in works: > > ```html > …Save > ``` > > `::slotted()` matches only the assigned node, never inside it — an icon wrapped in a > container (``) stays unstyled and has to be sized by > the project. Pass the `` directly. --- ## 10. Custom Theming Load custom brand colors via `theme-override.css` after the base library: ```css :root { --gl-color-primary: #007AFF; --gl-color-primary-dark: #0055CC; } ``` Since 1.11.0 those two declarations are the whole job. The gradient midpoint, the warm rim (`--gl-border-warm`), the focus ring (`--gl-border-focus`, `--gl-shadow-focus`), the glow under the primary button and the range slider thumb are all mixed from them. Before 1.11.0 they held fixed amber values, so a re-branded button came with an orange halo and an amber focus ring. Two things worth knowing: - **Declare the brand on `:root`.** A custom property is substituted where it is *declared*, so the derived tokens read the primary of the element they sit on. Setting `--gl-color-primary` on a subtree re-colors what that subtree paints directly, but does not re-derive the tokens inherited from `:root`. - **Override any derived token individually** if you want to bend one — the derivations are plain defaults and lose to a later declaration. ```css :root { /* only if you want a different midpoint than the mix */ --gl-color-primary-mid: #0066E0; /* Ink on the primary fill – defaults to #ffffff. Set a dark ink here if your brand color is light and you need WCAG AA on filled surfaces. */ --gl-color-on-primary: #ffffff; } ``` Overriding `--gl-color-success` / `--gl-color-error` is enough on its own: fill, border, text and glow of every state component are derived from those tokens. Only if you want a different ink than the derived one do you need to touch `--gl-color-{state}-on-surface`. Included theme templates in `theme-override.css`: - 🔵 Ocean Blue - 🟢 Emerald Green - 🌹 Rose - 🎨 Custom (empty, ready to fill)