Liquid Metal Border

Proximity Reflections

Pass only explicit refs to neighbouring elements:

import { useRef } from "react";

const chipRef = useRef<HTMLButtonElement>(null);

<>
  <button ref={chipRef}>Tools</button>
  <MetalFx variant="circle" reflectionTargets={[chipRef]}>
    <button aria-label="Send">↑</button>
  </MetalFx>
</>

Omit reflectionTargets to disable reflection work. In light mode, reflections are skipped automatically.

Accessibility and Motion

• Preserve native button, a, and form semantics inside the wrapper.
• Keep active state in aria-pressed, aria-selected, checked state, or current-route state.
• Do not rely on hue or animation alone. Retain text, icon, position, weight, or a static edge change.
• Be careful with normalizeHostStyles. Its default removes the child's outline; set it to false and define transparent chrome plus :focus-visible when the control needs its own focus ring.
• Set paused for reduced motion. Also disable the wandering glow when its movement is unnecessary.
• Keep the effect pointer-transparent and verify the child remains clickable and keyboard-operable.
• Retain a plain CSS border or surface treatment for WebGL failure.

Performance

metal-fx reuses one shared WebGL context, one compiled shader, and one animation loop across mounted instances. It also pauses offscreen copies with IntersectionObserver and debounces resize work through animation frames.

Still keep the effect selective:

• Mount it on primary or stateful surfaces, not whole grids of idle controls.
• Pause non-active instances.
• Omit reflections unless they add visible depth.
• Do not animate the wrapped element's dimensions continuously.
• Prefer disableGlow for restrained cards and dense toolbars.

Verification

Run the project's lint, typecheck, production build, tests, and git diff --check. Then verify in the Codex browser:

1. Confirm the package is present in the manifest and lockfile.
2. Confirm one .metal-fx-root wraps one semantic host.
3. Test hover, pointer-down, selected, keyboard focus, and disabled states.
4. Confirm the active state is exposed semantically and remains clear with the effect hidden.
5. Confirm the focus ring is visible when normalizeHostStyles is enabled or disabled.
6. Check the measured size and radius at every responsive breakpoint.
7. Test the app's real light and dark themes; do not assume auto matches a manual toggle.
8. Enable reduced motion and confirm the shader stops moving.
9. Scroll the control offscreen and back; confirm the effect resumes without a blank frame.
10. Check console output for WebGL, hydration, resize, or ref errors.
11. Confirm neighbouring controls receive reflections only when explicitly targeted in dark mode.

Failure Diagnosis

• The ring is covered: the child has an opaque background above the canvas. Use default normalization or make the child transparent and style the wrapper.
• The focus ring disappeared: normalizeHostStyles removed the child outline. Set it to false and reset only background, border, and shadow in project CSS.
• The radius is wrong: use a real computed radius on the child or pass borderRadius explicitly.
• A circle looks soft or thin: use variant="circle" and explicit square dimensions before increasing ringCssPx.
• The pattern is too busy: lower strength, disable glow, or use silver; do not immediately thicken the ring.
• Reflections are missing in light mode: expected behavior; reflections are dark-mode only.
• The effect is the wrong physical size after zooming: set scale to the UI scale instead of tuning each pixel constant independently.
• The page crashes in a server component: move the usage behind the framework's client-component boundary.
• The border is blank on unsupported hardware: keep the semantic control and CSS fallback complete; treat the WebGL ring as enhancement.

Handoff

Report the installed metal-fx version, wrapped control, active-state source, preset, theme strategy, fallback border, reduced-motion behavior, build/test results, and Codex-browser verification. Distinguish local readiness from a deployed result.