# Liquid Glass Studio 2.2.0 Materials and components for functional UI controls. ## Quick start 1. GET /api/v2/manifest.json. 2. GET /api/v2/components/.json and /api/v2/presets.json. 3. Validate material config against /schemas/v2/config.schema.json. Resolver applies defaults; JSON Schema does not apply them. 4. generateCode({ component, preset, ... }) with the ESM SDK; or node tools/cli.mjs generate request.json ./output. 5. Serve the generated directory over HTTP. Test keyboard, resize and fallback. ## Source model material = optics; component = anatomy, size, state and behavior; recipe = responsive composition; template = complete screen with all 12 components. preview dimensions are demonstration geometry and must not become layout defaults. DTCG 2025.10 tokens are separate from component usage/behavior contracts. Dimension values are { value: 44, unit: 'px' }. Token aliases resolve within the token file. ## Runtime import { mount } from '/releases/2.2.0/sdk/runtime/index.js'; const instance = mount(root, request); instance.update({ config: { blur: 24 } }); instance.destroy(); update accepts optics (config, preset, size, theme, quality, preferences). To change component, recipe or state, render and mount a new instance. Use one independent instance per root. Each surface has a unique SVG feDisplacementMap filter; ResizeObserver updates geometry. The neutral map center preserves content; edge channels bend the background. url(#filter) follows blur/saturate. CSS.supports is only a parser check. ## Exports HTML/CSS/runtime bundle is the complete responsive implementation. CSS alone has no dynamic SVG lens or JavaScript keyboard behavior. Tailwind uses the same required CSS/runtime. SwiftUI exports a native material wrapper, not pixel-identical web optics or a full native component library. JSON exports a versioned request; tokens export DTCG. The SDK is usable without DOM; DOM runtime is separate. The agent ZIP includes a local CLI and SDK. Install the skill by copying agent-skill/liquid-glass into your agent's supported skill folder. AGENTS.md in this repository applies to maintaining this repository. ## Accessibility and rendering Text contrast must be verified against rendered backgrounds and every relevant state. A valid config is not a WCAG audit. Use opaque fallback for unpredictable content; media/custom backgrounds cannot have guaranteed contrast based on tokens alone. Native controls retain labels and keyboard operation. Follow system reduced motion/transparency, increased contrast and forced colors. full = blur + rim + refraction where visually confirmed; reduced = blur + rim; solid = opaque background + border. Chromium/WebKit/Firefox baseline support and measured results are listed in /api/v2/compatibility.json. ## Performance Maps are cached by geometry, resize updates batch per animation frame, translation does not rebuild maps. destroy disconnects observers and removes filters. An advisory warning above eight surfaces is a conservative project heuristic, not a measured device limit. Profile actual devices before setting a production budget. ## Compatibility 54 old presets remain available at /api/presets.json for existing consumers; the modern library has 24 materials (neutral, tinted, light and optical). Old #g= configurations preserve validated material values; removed preset names migrate to custom values over Graphite. v1 local storage migrates when no v2 setting exists. New #v2= links encode versioned requests locally; no external shortener. ## Components ### button: Button A labelled action Anatomy: label, leadingIcon, trailingIcon. States: default, hover, pressed, focus-visible, disabled, loading. Keyboard: Enter/Space activates; native disabled prevents activation. Contract: /api/v2/components/button.json Example: /examples/button/ References: /examples/button/light.png and dark.png ### icon-button: Icon button A compact action with an accessible name Anatomy: icon, accessibleName. States: default, hover, pressed, focus-visible, disabled. Keyboard: Requires aria-label when no visible text. Enter/Space activates. Contract: /api/v2/components/icon-button.json Example: /examples/icon-button/ References: /examples/icon-button/light.png and dark.png ### toolbar: Toolbar Related actions on one functional surface Anatomy: group, action, separator. States: default, focus-visible. Keyboard: Native buttons use Tab. Use role=group; toolbar role only with roving focus. Contract: /api/v2/components/toolbar.json Example: /examples/toolbar/ References: /examples/toolbar/light.png and dark.png ### searchfield: Search field Search with a label, clear action and result feedback Anatomy: label, input, clear, status. States: default, hover, focus-visible, disabled, empty, error. Keyboard: Enter submits, Escape clears; label required, status announced politely. Contract: /api/v2/components/searchfield.json Example: /examples/searchfield/ References: /examples/searchfield/light.png and dark.png ### tabs: Tabs Switch between related content panels Anatomy: tablist, tab, tabpanel. States: default, hover, focus-visible, selected, disabled. Keyboard: Left/Right/Home/End moves focus and selects. Tab enters active tab, then panel. Contract: /api/v2/components/tabs.json Example: /examples/tabs/ References: /examples/tabs/light.png and dark.png ### segmented-control: Segmented control Choose one value from a small set Anatomy: legend, radio, label. States: default, hover, focus-visible, selected, disabled. Keyboard: Native radios: arrow keys change value. Tab enters selected radio. Contract: /api/v2/components/segmented-control.json Example: /examples/segmented-control/ References: /examples/segmented-control/light.png and dark.png ### switch: Switch Turn a setting on or off Anatomy: input, track, thumb, label. States: default, hover, focus-visible, selected, disabled. Keyboard: Native checkbox with role=switch; Space toggles. Visible label required. Contract: /api/v2/components/switch.json Example: /examples/switch/ References: /examples/switch/light.png and dark.png ### slider: Slider Choose a numeric value with a visible label Anatomy: label, input, output. States: default, hover, focus-visible, disabled. Keyboard: Native range. Arrow keys adjust; Home/End select bounds. min/max/step required. Contract: /api/v2/components/slider.json Example: /examples/slider/ References: /examples/slider/light.png and dark.png ### popover: Popover Contextual settings next to an action Anatomy: trigger, panel, heading, close. States: default, hover, focus-visible, open. Keyboard: Native popover; Escape closes and focus returns to trigger. Non-modal, Tab follows document. Contract: /api/v2/components/popover.json Example: /examples/popover/ References: /examples/popover/light.png and dark.png ### menu: Menu A short menu of related commands Anatomy: trigger, menu, menuitem. States: default, hover, focus-visible, open, disabled. Keyboard: Trigger Enter/Space/Down opens. Up/Down/Home/End moves. Escape closes and returns focus. Contract: /api/v2/components/menu.json Example: /examples/menu/ References: /examples/menu/light.png and dark.png ### dialog: Dialog A modal decision with a clear heading Anatomy: trigger, title, description, actions. States: default, focus-visible, open. Keyboard: Native showModal traps focus; Escape closes, focus returns to trigger. aria-labelledby/description. Contract: /api/v2/components/dialog.json Example: /examples/dialog/ References: /examples/dialog/light.png and dark.png ### media-controls: Media controls Compact controls floating over media Anatomy: play, progress, time, mute. States: default, hover, pressed, focus-visible, selected, disabled. Keyboard: Native buttons and range. Controls have names; seek value announced; no autoplay. Contract: /api/v2/components/media-controls.json Example: /examples/media-controls/ References: /examples/media-controls/light.png and dark.png ## Recipes - media-toolbar: Media toolbar — Video controls over a detailed backdrop. Components: media-controls, icon-button. Preset: clear. - search-navigation: Search & navigation — Search and tabs over ordinary content. Components: searchfield, tabs. Preset: smoke. - settings-panel: Actions & settings — A panel with a switch, a slider and an action. Components: switch, slider, button. Preset: spacegray. ## Screen templates ### workspace: Workspace Projects, activity overview, navigation and quick actions. Page: https://liquid-glass.weblocally.com/templates/workspace/ Contract: /api/v2/templates/workspace.json Example: /examples/templates/workspace/ Preview: /examples/templates/workspace/preview.png Request: {"template":"workspace","preset":"graphite","quality":"reduced","lang":"en"} Components: button, icon-button, toolbar, searchfield, tabs, segmented-control, switch, slider, popover, menu, dialog, media-controls. ### media-studio: Media studio An asset library, a media preview and production controls. Page: https://liquid-glass.weblocally.com/templates/media-studio/ Contract: /api/v2/templates/media-studio.json Example: /examples/templates/media-studio/ Preview: /examples/templates/media-studio/preview.png Request: {"template":"media-studio","preset":"midnight","quality":"reduced","lang":"en"} Components: button, icon-button, toolbar, searchfield, tabs, segmented-control, switch, slider, popover, menu, dialog, media-controls. ### preferences: App preferences Profile, notifications, media preferences and workspace settings. Page: https://liquid-glass.weblocally.com/templates/preferences/ Contract: /api/v2/templates/preferences.json Example: /examples/templates/preferences/ Preview: /examples/templates/preferences/preview.png Request: {"template":"preferences","preset":"spacegray","quality":"reduced","lang":"en"} Components: button, icon-button, toolbar, searchfield, tabs, segmented-control, switch, slider, popover, menu, dialog, media-controls. ### ui-kit: Complete UI kit All 12 components on one screen: actions, navigation, inputs and overlays. Page: https://liquid-glass.weblocally.com/templates/ui-kit/ Contract: /api/v2/templates/ui-kit.json Example: /examples/templates/ui-kit/ Preview: /examples/templates/ui-kit/preview.png Request: {"template":"ui-kit","preset":"obsidian","quality":"reduced","lang":"en"} Components: button, icon-button, toolbar, searchfield, tabs, segmented-control, switch, slider, popover, menu, dialog, media-controls. Templates default to reduced optics for many surfaces. All sample data must be replaced; project actions require application handlers, search reports a query, media controls toggle demo state and do not play real video. Run generateCode({template:'workspace',preset:'graphite',lang:'en'}) or CLI generate with request.json. Plain template URLs include contract/source links in initial HTML for agents without browser tools. #v2 fragments contain versioned configuration; decode with decodeConfig(decodeURIComponent(url.hash.slice(4))). ## Browser agent tools WebMCP is a progressive adapter over the same core. Detect document.modelContext or the implementation's navigator.modelContext. Tools: list_presets, get_preset, list_components, get_component, get_recipe, list_templates, get_template, validate_config, generate_code. Registration is not proof of successful browser-agent execution; check the compatibility status. JSON/SDK/CLI are the stable path. ## Sources https://www.designtokens.org/tr/2025.10/format/ https://webmachinelearning.github.io/webmcp/ https://developer.apple.com/design/human-interface-guidelines/materials This is a web interpretation inspired by Liquid Glass, not a native Apple rendering engine. Distribution retains the existing repository assets. npm registry publication is not part of this release.