liquid-glass-skills

Agent skills for building with Liquid Glass and native motion on Apple platforms (iOS 26+ / macOS 26 Tahoe through the iOS 27 betas), for Claude Code and any tool speaking the open Agent Skills format:

Skill Owns
liquid-glass The material: variants, containers and sampling, toolbars and scroll-edge, UIKit (UIGlassEffect), AppKit (NSGlassEffectView, Tahoe window chrome), accessibility, pre-26 fallbacks and migration, version-pinned bugs, a diff-checkable review checklist
liquid-glass-motion Motion: morphing (glassEffectID/glassEffectUnion/glassEffectTransition), animation fundamentals, phase/keyframe animators, scroll-driven effects, Reduce Motion gating, Metal shaders with/under/instead-of glass, and an Instruments (xctrace) profiling workflow
apple-motion-feel Choosing the values: which spring, which damping, which duration — and why most "feels off" bugs are category errors rather than timing bugs. Gesture handoff, momentum projection, interruptibility, consistency. Not glass-specific; applies to any Apple-platform animation

Every rule carries an availability floor and a confidence tag ([verified], [apple], [multi], [single], [version-pinned]). Each SKILL.md is a router; references load per-topic on demand, so context stays small.

Research findings

Claims in these skills were settled against developer.apple.com (DocC) and the SDK's .swiftinterface annotations rather than write-ups. That verification pass surfaced findings that, to our knowledge, had not been reported:

  • Apple's Xcode-bundled LLM-facing documentation contains a fabricated API. scrollExtensionMode(.underSidebar) appears there with a plausible full code sample; it does not exist in any SDK or DocC path. The real API (backgroundExtensionEffect()) is absent from the same document.
  • Apple's reference page for phaseAnimator(_:trigger:) describes the wrong semantics (one-phase-per-trigger). The real behavior — confirmed against WWDC23 session 10157 and multiple independent references — is a full burst per trigger change.
  • toolbarMinimizeBehavior was renamed toolbarMinimizationBehavior(_:for:) at iOS 27 beta 4; Apple's own SwiftUI updates page still shows the old name.
  • .interactive() is not iOS-only. It is iOS 26.0 + macOS 26.0, pointer-optimized on Mac — a widely-repeated myth says otherwise.
  • glassEffectID does not match across an if / else branch replacement. Two mutually exclusive branches sharing one ID satisfy every documented morph precondition and still do nothing, because at no frame do both shapes exist to match against. Measured with a harness logging every Shape.path(in:) call. The working pattern for a collapsed↔expanded swap is one surface that is never inserted or removed, whose frame and corner radius interpolate.
  • glassEffect samples a hosted CAMetalLayer; SwiftUI Material does not. A Material over a MTKView resolves against the window background and reads as nothing — glass over the same canvas refracts the real rendered content.
  • 14 hallucinated or misnamed APIs that recur across blogs, skills, and LLM output, collected in liquid-glass/references/review-checklist.md, plus availability corrections (appearsActive is iOS 18+; UIDesignRequiresCompatibility was never removed; ScrollEdgeEffectStyle cases are .hard/.soft, not .sharp/.subtle).

Install

npx skills add YordiLorenzo/liquid-glass-skills
# or manually:
git clone https://github.com/YordiLorenzo/liquid-glass-skills
cp -R liquid-glass-skills/liquid-glass \
      liquid-glass-skills/liquid-glass-motion \
      liquid-glass-skills/apple-motion-feel ~/.claude/skills/

Install liquid-glass and liquid-glass-motion together — they cross-reference each other and split the topic deliberately (material vs motion) to keep context loading small. apple-motion-feel stands alone and is useful without either, but the two motion skills cross-reference: it defers Reduce Motion detail to liquid-glass-motion, which defers value selection to it.

Scope and caveats

  • SwiftUI first; UIKit and AppKit covered. visionOS is a per-symbol split (most glass APIs are SDK-annotated unavailable there); watchOS/tvOS are out of scope.
  • Version-pinned bug workarounds are dated and marked — recheck them on new OS releases.
  • Verified facts were checked against the iOS/macOS 26.2 SDK and iOS 27 beta 4 documentation in August 2026.

License

MIT.