MichaelScottsman--LiquidAss-Frame/docs/DESIGN.md

Glass Shell design spec

Goal: re-skin every surface and sub-menu of the Steam Frame's VR interface (Steam gamepadui as SteamVR overlays) into Apple's glass design language, with zero functional change.

• visionOS window glass for the window.
• Liquid Glass for the floating controls.

Source material is the project's design bible (../bible/, published at https://claude.ai/artifact/T4AqVM5FQrQzn3kW4UTYe9) and its rulebook ../.claude/skills/run-liquid-glass-frame/references/design-language.md. This spec translates them to CSS inside Steam's CEF.

1. What the platform allows

• Overlays have per-pixel alpha. Every surface is a quad composited over the room (passthrough, mono or colour) or over the running game.
  • Transparent pixels show the world.
  • Translucent pixels tint it.
• backdrop-filter only sees the page's own content, never the room. So:
  • Window glass over the room = translucent smoky tint + specular rim + sheen. It cannot blur the room, so the tint must carry legibility on its own (--lgs-window-alpha ≈ 0.72 by default; the user dial moves it from 0.60 to 0.84).
  • Liquid Glass over in-page content = backdrop-filter blur + saturation (+ lensing later). Examples: header capsules over scrolling library art, side menus and sheets over the window, context menus over a page.
• Each popup is its own quad.
  • The bar segments, bar popups, frame menus, tooltip, volume HUD, footer, toasts and keyboard float alone over the room. They use panel glass: tint + rim + sheen, no backdrop blur (there is nothing in-page behind them).
  • Their surroundings are transparent, so rounded corners are real.
• The Adreno GPU is shared with the compositor.
  • Steam's CEF runs GPU compositing and GPU raster (ANGLE on zink/Turnip). It repaints on change, so static decoration is nearly free.
  • Stock Steam already has about 100 elements with backdrop-filter on library home and scrolls at about 85 fps, so blur is affordable. It is still not free: blurred backdrops re-render while what's behind them moves.
  • Budget, measured: python glass.py perf main --route R scrolls the page with the theme off, then on. Themed must keep the same fps (within 5%) and add no long frames (>34 ms).
  • No animated filters, no infinite animations.

2. Materials (all defined in theme/00-tokens.nowrap.css)

Material	Use for	Recipe (copy these declarations)
Window glass	The dashboard window's root background, i.e. whatever paints the opaque page background today	background: var(--lgs-window-sheen), var(--lgs-window-bg); box-shadow: var(--lgs-window-rim); border-radius: var(--lgs-r-window);
Panel glass	Standalone overlays: bar segments, bar popups, frame menus, toasts, tooltip, HUDs, footer, keyboard	background: var(--lgs-panel-sheen), var(--lgs-panel-bg); box-shadow: var(--lgs-panel-rim); border-radius: var(--lgs-r-panel) (or --lgs-r-capsule / --lgs-r-menu by shape)
Liquid Glass (regular)	Floating controls over in-page content: header and search capsule, segmented tab bars, floating action capsules	background: var(--lgs-glass-bg); backdrop-filter: var(--lgs-glass-blur); box-shadow: var(--lgs-glass-rim), var(--lgs-glass-shadow); border-radius: var(--lgs-r-capsule);
Thick glass	Sheets, modals, side menus, context and dropdown menus inside the main window	background: var(--lgs-panel-sheen), var(--lgs-thick-bg); backdrop-filter: var(--lgs-thick-blur); box-shadow: var(--lgs-glass-rim), var(--lgs-glass-shadow); border-radius: var(--lgs-r-sheet) (menus --lgs-r-menu). Modal scrim: --lgs-scrim
Fills (content on glass)	Grouped settings sections, list rows at rest, input wells, chips, non-selected segments	--lgs-fill-1/2/3, --lgs-fill-sunken for wells; separators --lgs-separator. Never glass on glass: anything inside a glass container uses fills, not another blur

Rim and sheen are the Liquid Glass signature: a crisp bright top edge, faint side edges and a soft top-down sheen. Light comes from above, the same direction everywhere. Don't add outer drop shadows on standalone overlays, which have no room for them; inside the main window, floating glass may use --lgs-glass-shadow.

Content is not glass. Game art, capsules, screenshots, hero images, avatars and store pages stay opaque content.

• Round their corners to the concentric radius (--lgs-r-card for capsules, --lgs-r-small for small art).
• Never tint or blur them.

3. Interaction states (must stay unmistakable)

State	Treatment
Rest	Transparent, or --lgs-fill-1 for rows and grouped items; labels --lgs-text-1, secondary --lgs-text-2
Hover (laser)	--lgs-hover-fill, transition var(--lgs-t-fast) var(--lgs-ease)
Focus (.gpfocus, controller and laser focus)	background: var(--lgs-focus-fill); box-shadow: var(--lgs-focus-ring);. It "illuminates from within". Must be visible on every focusable control in every surface. For content like game capsules, use --lgs-focus-ring-outer around the art and keep Steam's scale-up if it has one
Selected (active tab, current nav item, chosen segment)	White fill --lgs-selected-fill + dark label --lgs-text-on-selected. Reserved: nothing else is white-filled
Pressed	Brighter fill; optional scale: var(--lgs-pressed-scale), using the independent property, never transform
Disabled	opacity: var(--lgs-disabled-opacity) on the control, or --lgs-text-disabled for labels
Primary action	Only the one primary action per screen is tinted: Play is --lgs-tint-play, a dialog's confirm is --lgs-tint-primary, destructive is --lgs-tint-danger. Tint goes into the whole capsule fill with a white label, never into thin text

4. Components

• Buttons (DialogButton family, bar small buttons): capsule (--lgs-r-capsule) for text buttons, circle for icon buttons.
  • Rest: --lgs-fill-2 with an inner top rim inset 0 1px 0 rgba(255,255,255,.18).
  • Focus: per §3.
  • Keep sizes; only round and recolour them.
• Toggles:
  • Track: capsule, off --lgs-fill-3, on --lgs-toggle-on (whole fill).
  • Knob: white with a soft shadow 0 1px 3px rgba(0,0,0,.3).
  • Focused toggle row gets the focus treatment.
• Sliders:
  • Track: --lgs-fill-3 capsule.
  • Fill: rgba(255,255,255,.92).
  • Knob: white, with a subtle ring.
  • Notches dim.
• Dropdown buttons look like capsule buttons. Opened dropdown menus are thick-glass menus.
• Text inputs / search: a sunken capsule well (--lgs-fill-sunken with inset 0 1px 2px rgba(0,0,0,.25)), white text, --lgs-text-3 placeholder. Focus: ring.
• Field rows (settings and dialogs): transparent rows inside a grouped section card (--lgs-fill-1, --lgs-r-card).
  • Separators --lgs-separator, inset from the left.
  • The focused row gets focus fill + ring with --lgs-r-row.
• Tabs / segmented controls: a Liquid Glass capsule holding the segments; the selected segment is the white pill.
  • Steam's home tabs (WHAT'S NEW / FRIENDS / RECOMMENDED) and library tabs map to this.
  • Keep their text case and size.
• Menus (context menus, dropdowns, bar popups, frame menus): thick or panel glass, --lgs-r-menu, 6–8 px inner padding.
  • Rows --lgs-r-row.
  • Headers in --lgs-text-2, small caps-free title case.
  • Separators as hairlines.
  • Materialize with animation: lgs-materialize var(--lgs-t) var(--lgs-spring) both;, only on the menu container and only if Steam doesn't already animate it with opacity/transform.
• Modals / sheets: thick glass, --lgs-r-sheet, scrim --lgs-scrim.
• Toasts and notifications: panel glass rounded rect, --lgs-r-panel; icon left, title --lgs-text-1, body --lgs-text-2.
• Scrollbars: thin capsule thumbs, rgba(255,255,255,.28), if Steam shows any.
• The dashboard bar (ornament):
  • Each BarSurface segment becomes a panel-glass capsule or rounded slab.
  • Icons are white.
  • The active tab gets a white-ish selected fill or an underglow dot.
  • The + and small buttons are circular glass hit areas with the focus treatment.
  • The clock uses --lgs-text-1.
  • The avatar has a rounded square.
• The keyboard: a panel-glass slab.
  • Keys are fills (--lgs-fill-2, --lgs-r-small) with white labels; special keys --lgs-fill-3.
  • The focused or touched key is bright white fill with a dark label (visionOS keyboard style).
  • Enter is tinted --lgs-tint-primary.

5. Type and colour

• Keep Steam's font (Motiva Sans) and its sizes. Don't change font sizes or weights in a way that can reflow and clip text; a +100 weight on small labels is fine where space allows.
• Labels are white at vibrancy levels: --lgs-text-1/2/3.
  • Map Steam's greys: near-white → --lgs-text-1, mid grey → --lgs-text-2, dim grey → --lgs-text-3.
  • Add text-shadow: var(--lgs-text-shadow) on text that sits directly on window or panel glass.
• Colour only in whole fills: the green Play capsule, the green toggle-on track, blue primary confirm, red destructive, badges.
• Keep Steam's semantic colours where they carry meaning (online green, in-game blue), but as fills or dots.

6. Shape

Concentric: inner radius = outer radius − padding.

Element	Radius
Window	32
Sheets	28
Panels	24
Menus	20
Cards and capsule art	16
Rows	12
Small	8
Controls	capsule

7. Motion

• Only on state changes, never at rest.
• Hover and focus fills transition over 140 ms.
• Popups and menus materialize in 220 ms with a spring.
• No shimmer, no pulsing, no oscillation.
• prefers-reduced-motion sets the durations to 1 ms.

8. Functionality guardrails (from docs/LAB.md, repeated because they matter most)

Never:

• hide, collapse, zero-opacity or disable pointer events on Steam elements;
• change layout geometry (position, size, overflow, flex/grid) of containers;
• override transforms Steam uses for positioning, carousels or virtualization;
• cover controls with pseudo-elements that take pointer events.

Run python glass.py audit SURF --route R on every screen you style. It must report 0 GONE / HIDDEN / SHRUNK / UNCLICKABLE and 0 CONTRAST.

Every focusable control must show the focus state in screenshots taken with that control focused (.gpfocus).

9. SteamVR's own pages

SteamVR draws a few pieces of the Frame UI itself; see LAB.md, "SteamVR's own pages". They follow the same language:

Piece	Treatment
Window grab bar under the dashboard window	A Liquid Glass pill: a translucent white fill with a rim, brighter on hover or focus
Resize corners	Thin white strokes at --lgs-text-2
Frame controls (keyboard, pop-out, recenter, more)	Panel-glass capsule segments, white icons, circular hit areas, obvious focus and hover. They sit as their own quads over the room
Controller status	A panel-glass card. Battery levels as whole-fill colour (green, orange, red)
Now Playing	Window glass like the dashboard. The game art is content. Resume Game is the one tinted primary (--lgs-tint-play); the other actions are fill capsules; Exit Game gets a destructive tint only on focus
Controller bindings / SteamVR settings pages	Window glass with the same primitives look as Steam's settings: fills, capsules, white selected, focus ring
Message overlays and toasts	Panel glass, like Steam's toasts

systemui is an atlas page: everything outside the panels is transparent, and each panel becomes its own quad. Don't paint the page or vsg-app backgrounds.

10. File ownership

File	Owner
theme/00-tokens.nowrap.css, theme/defs.svg	Foundation (changes go through it)
theme/10-primitives.css	Foundation: generic Steam components used everywhere (DialogButton, gamepaddialog fields, toggles, sliders, dropdowns, text inputs, context menus, modals, generic focus)
theme/20-shell.css	Window chrome: root window glass, header and search, side menus, page transitions, in-window footer
theme/30-bar.css	Dashboard bar, bar popups, frame menus
theme/35-hud.css	Tooltip, volume HUD, floating footer, notification toasts, keyboard
theme/40-library.css	Library home, library tabs, collections, capsules, search results
theme/50-appdetails.css	Game pages, play bar, game menus, properties, running-app overview
theme/60-settings.css	Settings pages (layout-level styling; controls come from primitives)
theme/70-social.css	Friends and chat, profile, notifications, media, downloads, store chrome, power menu, other routes
theme/vr/*.css	SteamVR's own pages: systemui (frame controls, grab bar, Now Playing, settings panels), controller bindings, overlays

Area files may refine primitives inside their own containers. Generic primitive changes belong in 10-primitives.css.