BaseSurface

Usage

Modes

mode picks the material: refraction (the default), glass, acrylic, blur backdrop blur, mask translucent overlay, mica, pure solid (flat is an alias), or plain, which paints no material. Each material's pipeline and cost are in Surface 8-Material Taxonomy & Gatekeepers.

Advanced Lab

filter* props tune the filter layer, refraction* props the refraction layer, and preset="card" applies the card tuning.

Fake Mode

fake paints the background on a pseudo-element, matching the existing .fake-background layering; slot content sits above it naturally. Under pure (flat) that base is opaque and under mask it follows the mask opacity; under blur, acrylic, glass and refraction it sits beneath the material at opacity, so the page behind still shows through to be blurred and refracted; mica paints its own opaque base and plain paints nothing, so neither takes it.

Motion Fallback

When a surface moves with its element, backdrop-filter samples lag behind the element's position, and the filter layers drag a misaligned patch of backdrop along. With moving set, blur, glass and acrylic degrade to fallbackMode and recover smoothly when it stops; refraction keeps its mode and fades its filter layers out, then back in once it stops.

Raw vs BaseSurface

When the motion state isn't available, turn on autoDetect and the surface senses motion itself (see the next section).

Environment sensing

With autoDetect on, the surface combines five runtime signals: transforms on itself and its ancestors, the speed of a pressed pointer (above 1.2px/ms), window moves and resizes, a frame-budget probe, and power saving. The first three trigger the motion fallback, which starts to recover 140ms after the signal stops; under power saving or a reduced frame budget, refraction, glass and acrylic become blur, and under minimal they and blur become flat, returning to the declared material once the condition clears. How each signal is read is in Adaptive Surface Deduction & 120Hz Fallback.

A page receives no event when its window moves, so the host forwards one; a host that knows the power state can override the battery API's reading:

import { notifySurfaceWindowMotion, setSurfacePowerSaving } from '@talex-touch/tuffex'

// Once per BrowserWindow move (and will-move) event the main process relays to the renderer
notifySurfaceWindowMotion()

// From Electron's powerMonitor, say; null hands it back to the Battery Status API
setSurfacePowerSaving(true)

Flow light

flowLight lays a fixed brand-colour light (FlowLight) over the veil and under the edge, in any mode.

System backdrop

A transparent Electron window lets the desktop show through its own system material (vibrancy on macOS, Mica on Windows), and a page's backdrop-filter cannot reach that material: the filter samples only the surface's own veil and lays the copy over that veil, so a 75% veil stacked twice is all but opaque and the desktop no longer shows through. systemBackdrop runs no backdrop-filter on the surface: the glass layer doesn't render and the filter layer keeps only its tint, leaving the blur to the system; the veil, mask, flow light and rim draw as usual. With nothing sampled from the page, moving and autoDetect have no effect either.

<!-- core-app's CoreBox: a transparent window, its surface over the system material -->
<TxBaseSurface system-backdrop fake color="var(--tx-fill-color)" :opacity="0.75" />

Best Practices

• Prefer TxCard for product containers, since it owns container semantics and interaction; use TxBaseSurface only to tune material, fallback, or refraction directly.
• Pass moving when the parent owns the animation state; use autoDetect only for motion whose state you can't reach, or to switch to a lighter material under power saving and dropped frames.
• Keep fallbackMode="mask" so blur / glass / acrylic content stays readable in motion; use pure only when a flat color is acceptable.
• Tune refraction through refractionStrength, refractionProfile, and refractionTone; keep RGB channel offsets for visual experiments.
• Use refractionRenderer="css" only where its lower optical fidelity is acceptable.

API Reference

Props

Slots

CSS Variables

Environment API

Import from @talex-touch/tuffex.

Overview

• pure and flat render only the root background; mask renders a mask layer with opacity clamped to 0..1; acrylic is a filter layer blurring three times as wide under a tint whose alpha carries fractal noise; mica paints the root with an opaque base and two glows anchored to the viewport (background-attachment: fixed), reading no backdrop but repainting with every scroll of its container, so keep it off bases that scroll; plain keeps only the radius and the overflow clip.
• blur, glass and acrylic degrade while moving is set or autoDetect senses motion: fallbackMode="mask" prefers fallbackMaskOpacity, and pure and flat render no mask layer.
• refraction keeps its mode in motion: the glass / blur layers that lose their sampling fade out, a translucent motion cover holds the weight, and both cross-fade back on settle.
• Passing any of refractionStrength, refractionAngle, or refractionProfile switches to the derived refraction model; unset ones fall back to 62 / -24 / 'filmic'.
• autoDetect listens on the root and every ancestor for their own transform / translate transitions (transitionstart / transitionend / transitioncancel) and watches their inline style with a MutationObserver; the pointer, window, frame-probe and battery listeners are page-wide, shared by every surface with autoDetect, and removed when the last one unmounts.
• With systemBackdrop, the glass layer doesn't render and the filter layer's backdrop-filter is none, keeping its tint; neither the motion fallback nor environment sensing runs. The veil, mask, flow light and rim are unaffected.
• Under high contrast (triggers in Theming), every mode but plain paints only the opaque root background, like pure: the glass, blur, mask, motion-cover and refraction-edge layers don't render, and the fake base shows at full opacity; plain gets no fill even then.

Technologies

• Glass and refraction render through TxGlassSurface; fallback timing lives in base-surface-motion.ts, and the page-wide environment sensing and material degradation in surface-environment.ts.
• Source: packages/tuffex/packages/components/src/base-surface/.