Appllama loader button experiments

A dependency-free collection of 25 original loading button animations. The shared button surface, page background, and every loader motion system are authored as part of this Appllama experiment.

This repository holds two things:

packages/loader-buttons/	loader-buttons — the published npm package
index.html, styles.css, src/	The gallery site, which consumes the package

The gallery is the package's living test bed: it renders all 25 loaders through the same public API any consumer would use.

Using the package

npm install loader-buttons

import { LoaderButton } from "loader-buttons/react";
import "loader-buttons/styles.css";

<LoaderButton design="mercury-relay" label="Saving" loading={isSaving} />

See the package README for the headless runtime, the vanilla button, every customization option, and the design catalog.

Run locally

python3 -m http.server 4173

Then open http://127.0.0.1:4173. There is no build step — the gallery loads the package straight from source through an import map, so an edit in packages/loader-buttons/src/ shows up on refresh.

• http://127.0.0.1:4173/examples/react/ — the React component across sizes, variants, themes, and tokens
• http://127.0.0.1:4173/preview.html?design=16-mercury-relay — a single loader at actual size beside a 3× motion loupe. Append &t=<seconds> to freeze a deterministic still, or call window.__motionPreview.setTime(seconds) and .play() from the console.

The gallery shares one WebGL 2 context, mounts only within the visible scroll range, and renders visible Canvas/WebGL surfaces at up to 3× device pixel density. It still defaults to a resource-conscious 30fps. Each button can be clicked to reset its local cycle. Use ?fps=15 for an extra-light preview or ?fps=60 only when making a final capture.

Tests

node scripts/test.mjs

Static checks over the module graph, the design contract, the export surface, and the stylesheet/type/README coverage. Motion itself is verified in a browser.

Adding a loader

Each loader owns one file in packages/loader-buttons/src/designs/ and is registered in designs/index.js. The contract, including the constraints that keep motion legible at 30×30, is in designs/CONTRACT.md.

Deploy

For static hosting, leave the build command empty and publish this directory. The production URL is:

https://loader-buttons.appllama.io/

robots.txt, sitemap.xml, canonical metadata, social metadata, and JSON-LD are already configured for that hostname.