SkillAgentSearch skills...

liquid-metal-border

Add and tune animated liquid-metal WebGL borders with the React `metal-fx` package

Install / Use

npx skills add MengTo/Skills --skill liquid-metal-border

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

93/100

Category

Legal

Supported Platforms

Universal

Our assessment of liquid-metal-border

liquid-metal-border scores 93/100 on our quality scale, 20th of 208 Legal skills we index (top 10%).

Its SKILL.md is 13 KB long, well organised into 19 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.

With 6,252 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
16/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so liquid-metal-border is actively maintained.
  • Our last check on 2026-10-26 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-27. Automated pattern scan on 2026-09-27. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

liquid-metal-border compared with similar skills

All 4 of these similar skills score higher than liquid-metal-border; compare them before choosing.

SkillScoreStarsUpdatedFormat
liquid-metal-border (this skill)by MengTo936.3k54d agoSKILL.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md
designby nextlevelbuilder100149.0k6d agoSKILL.md

Frequently asked questions

How do I install liquid-metal-border?
Run npx skills add MengTo/Skills --skill liquid-metal-border. The install tabs above show the steps for each supported agent.
Which AI agents does liquid-metal-border work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is liquid-metal-border safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is liquid-metal-border still maintained?
The repository was last updated about 2 months ago, so liquid-metal-border is actively maintained.

name: liquid-metal-border description: Add and tune animated liquid-metal WebGL borders with the React metal-fx package. Use when buttons, icon controls, chips, tabs, cards, or selected surfaces need a metallic active, selected, hover, focus, or premium border; when implementing the MetalFx component from metal.jakubantalik.com; or when troubleshooting its presets, themes, strength, glow, reflections, sizing, radius, animation, accessibility, SSR, or performance.

Liquid Metal Border

Core Contract

  1. Use metal-fx in React 18 or newer.
  2. Wrap exactly one real host element such as a button, a, div, or article.
  3. Keep the host semantic and interactive. MetalFx is visual framing, not the control.
  4. Reserve the animated border for active, selected, focused, hovered, or primary surfaces. Do not put it around every control.
  5. Keep a static CSS border or focus outline as the fallback. WebGL decoration must never carry essential state by itself.
  6. Pause non-active instances and reduced-motion experiences.
  7. Test light and dark modes independently. Reflections intentionally render only in dark mode.

Inspect Before Editing

  • Confirm the project uses React and has react and react-dom version 18 or newer.
  • Find the real control, its dimensions, radius, background, border, outline, shadow, active-state source, and theme source.
  • Decide whether the metal should be always visible or driven by active, selected, hover, or focus state.
  • Check whether the project has a manual theme toggle. Use that state instead of theme="auto" when it does not follow the OS.
  • Identify nearby elements that genuinely benefit from reflected light. Do not add reflections by default.
  • Check the installed metal-fx version before relying on the prop surface below.

Install and Import

Install with the project's package manager:

npm install metal-fx
# pnpm add metal-fx
# yarn add metal-fx
# bun add metal-fx

Import the named React component:

import { MetalFx } from "metal-fx";

Do not import a stylesheet. The package injects its component styles. It supports ESM and CommonJS builds, is SSR-safe, and mounts the WebGL pipeline after hydration. In a Next.js App Router project, render it from a Client Component because the component uses client-side React hooks.

Baseline Button

Start with a restrained border before adding reflections or custom shader geometry:

import { MetalFx } from "metal-fx";

export function UpgradeButton() {
  return (
    <MetalFx
      variant="button"
      preset="chromatic"
      theme="auto"
      strength={0.85}
    >
      <button type="button">Upgrade to Pro</button>
    </MetalFx>
  );
}

The wrapper measures the child, paints the metal ring on top, and keeps the child interactive. Size the child normally with CSS, Tailwind, or inline styles.

Active-State Pattern

Keep one mounted instance and drive its intensity from real component state. Use aria-pressed, aria-selected, or the native selected-state mechanism so the visual effect is not the only signal.

"use client";

import { useEffect, useState } from "react";
import { MetalFx } from "metal-fx";

function useReducedMotion() {
  const [reduced, setReduced] = useState(false);

  useEffect(() => {
    const query = window.matchMedia("(prefers-reduced-motion: reduce)");
    const sync = () => setReduced(query.matches);

    sync();
    query.addEventListener("change", sync);
    return () => query.removeEventListener("change", sync);
  }, []);

  return reduced;
}

export function LiquidMetalToggle({
  selected,
  onSelect,
}: {
  selected: boolean;
  onSelect: () => void;
}) {
  const [hovered, setHovered] = useState(false);
  const [focused, setFocused] = useState(false);
  const reducedMotion = useReducedMotion();
  const highlighted = selected || hovered || focused;

  return (
    <MetalFx
      className="liquid-metal-toggle"
      variant="button"
      preset="chromatic"
      strength={highlighted ? 0.9 : 0.14}
      paused={reducedMotion || !highlighted}
      disableGlow={reducedMotion || !highlighted}
      ringCssPx={selected ? 1.5 : 1}
      normalizeHostStyles={false}
    >
      <button
        type="button"
        className="liquid-metal-toggle__control"
        aria-pressed={selected}
        onClick={onSelect}
        onPointerEnter={() => setHovered(true)}
        onPointerLeave={() => setHovered(false)}
        onFocus={() => setFocused(true)}
        onBlur={() => setFocused(false)}
      >
        Auto
      </button>
    </MetalFx>
  );
}
.liquid-metal-toggle {
  background: #18181b;
  border-radius: 999px;
}

.liquid-metal-toggle__control {
  min-height: 40px;
  padding: 0 18px;
  color: #fafafa;
  background: transparent;
  border: 0;
  border-radius: 999px;
  box-shadow: none;
}

.liquid-metal-toggle__control:focus-visible {
  outline: 2px solid #ffffff;
  outline-offset: 3px;
}

Use paused to stop non-active canvas updates; it freezes the last frame without hiding the ring. strength changes rendered opacity from 0 to 1 but does not slow the shader.

Static Border and Card Pattern

Use the wrapper as the surface when the child must remain transparent:

<MetalFx
  variant="button"
  preset="silver"
  theme="dark"
  strength={0.55}
  borderRadius={24}
  ringCssPx={1}
  shaderScale={1.45}
  disableGlow
  normalizeHostStyles={false}
  style={{ background: "#111318" }}
>
  <article className="feature-card">
    <h3>Realtime review</h3>
    <p>Keep feedback attached to the work.</p>
  </article>
</MetalFx>

Keep the article background transparent so it does not cover the ring. Use the child for content layout and the MetalFx wrapper for the visible surface.

Complete Customization Surface

| Prop | Values and default | Use | | --- | --- | --- | | children | One React host element; required | Preserve the real button, link, chip, card, or icon control. | | variant | "button" default, "circle" | Choose a 1 px pill-style baseline at shader scale 1.6, or a 2 px compact-circle baseline at scale 1.3. The measured child still controls the rendered size. | | preset | "chromatic" default, "silver", "gold" | Choose iridescent rainbow, cool steel, or warm gold. Each includes dark and light tuning. | | theme | "auto" default, "dark", "light" | Follow live prefers-color-scheme changes or pin the effect to the app theme. SSR starts dark, then resolves on the client. | | strength | Number 0..1; default 1 | Scale canvas and glow opacity. Use lower values for idle states and stronger values for active states. | | paused | Boolean; default false | Freeze this instance on its current shader frame while keeping the silhouette visible. | | borderRadius | Number in CSS pixels; optional | Override the radius. When omitted, read the child's computed radius on resize. | | normalizeHostStyles | Boolean; default true | Remove the child's background, border, outline, and shadow so they do not fight the ring. Set false when preserving a custom focus outline or fallback border. | | reflectionTargets | Array of React element refs; optional | Cast a soft mirrored reflection onto selected neighbouring elements. Dark mode only. | | disableGlow | Boolean; default false | Remove the wandering halo while retaining the shader ring. | | shaderScale | Number; variant baseline by default | Increase to zoom into larger metal pattern features; decrease to zoom out. | | ringCssPx | Number; variant baseline by default | Override the visible ring thickness in CSS pixels. | | scale | Number; default 1 | Scale every absolute-pixel engine constant together for CSS zoom or deliberately enlarged UI systems. | | className | String; optional | Style the MetalFx wrapper, not the child. | | style | React CSS properties; optional | Size or style the wrapper surface directly. | | ref | React ref; optional | Access the forwarded wrapper HTMLDivElement. |

Other valid HTMLDivElement attributes are forwarded to the wrapper.

Tuning Defaults

  • Primary pill button: variant="button", strength={0.75}, ringCssPx={1}.
  • Selected tab or filter: idle strength 0.1–0.2, selected strength 0.75–0.9.
  • Icon button: variant="circle", explicit square child dimensions, strength={0.7}.
  • Large card: ringCssPx={1}, shaderScale={1.3–1.6}, disableGlow.
  • Premium CTA: start with chromatic; use silver for neutral UI and gold only for warm or luxury palettes.
  • Quiet active state: disable glow before reducing the ring below legibility.
  • Doubled design system: use scale={2} instead of independently doubling shader, ring, glow, and reflection values.

Keep strength <= 0.9 for routine controls. Full-strength chromatic metal can dominate labels and icons.

Sizing and Radius

Prefer sizing the child:

<MetalFx variant="circle">
  <button style={{ width: 36, height: 36 }} aria-label="Send">
    ↑
  </button>
</MetalFx>

To make the frame larger than the child, size the wrapper and stretch the child:

<MetalFx style={{ width: 44, height: 44 }} variant="circle">
  <button
    style={{ width: "100%", height: "100%" }}
    aria-label="Send"
  >
    ↑
  </button>
</MetalFx>

The wrapper uses display: inline-flex. Do not create cyclic percentage sizing where neither wrapper nor child has an intrinsic size.

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 t

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars6.3k
CategoryLegal
Updated1mo ago
Forks741

Languages

HTML

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions