# AGENTS.md — cool-web-fx

> **If you are an LLM or coding agent, this is the entry point.** It tells you
> what this site is, how to take an effect, and what attribution to keep.
> A longer walkthrough lives in [skill.md](/skill.md).

## Overview

[cool-web-fx](https://fx.statico.io) is a static gallery of small web
interaction effects — canvas backgrounds, text animations, 3D CSS, animated SVG,
WebGL shaders. Each one is recreated from scratch as a **single self-contained
HTML file** with all CSS and JavaScript inline.

The site is built with [Astro](https://astro.build), deployed on Vercel at
<https://fx.statico.io>, and generated with
[Claude Code](https://claude.com/claude-code). It is inspired by
[reactbits.dev](https://reactbits.dev).

## Setup

Nothing to install to *use* an effect — the files are plain HTML. To build the
site itself:

```bash
npm install
npm run dev      # astro dev on http://localhost:4321
npm run build    # static output to dist/, then generates the agent files
npm run thumbs   # regenerate gallery thumbnails with Playwright
```

## How to grab an effect

Every effect is served at:

```
https://fx.statico.io/effects/<slug>.html
```

That URL returns a complete, runnable `<!doctype html>` document. Fetch it and
copy it verbatim — **do not reconstruct an effect from a screenshot, from the
thumbnail, or from memory.** The same source is also printed inside each demo
page in a `<pre><code class="language-html">` block, so it can be scraped from
the rendered HTML without executing any JavaScript.

Every effect is dependency-free except `resend-cube`, which loads Three.js as a
pinned ES module from a CDN via an `<script type="importmap">`.

To embed one, either serve the whole file (or drop it in an `<iframe>`), or lift
its `<style>` and `<script>` blocks plus the small bit of markup into your own
page, renaming IDs if they clash.

Each effect file carries a metadata header block (title, description, canonical
URL, JSON-LD) added for machine readability. It is marked with
`a14y metadata` comments and is safe to delete when you copy the file.

## Conventions

| Path | What it holds |
|---|---|
| `public/effects/<slug>.html` | Canonical, runnable, copy-paste source of each effect |
| `src/demos/<slug>.json` | Metadata: title, source, credit, blurb, technique writeup |
| `src/pages/index.astro` | Gallery index |
| `src/pages/demos/[slug].astro` | Per-effect page — live iframe, code, writeup, credit |
| `src/pages/glossary.astro` | Definitions of the rendering terms used in writeups |
| `public/thumbs/<slug>.png` | Gallery thumbnails, generated by `scripts/take-screenshots.mjs` |
| `scripts/generate-agent-files.mjs` | Postbuild: sitemaps and Markdown mirrors |

To add an effect: write `public/effects/<new-slug>.html`, add
`src/demos/<new-slug>.json` copying the schema from any existing one, then run
`npm run thumbs`. The index and demo page generate themselves.

## Machine-readable index

| Resource | Purpose |
|---|---|
| [`/llms.txt`](/llms.txt) | Short index of every effect with its source site |
| [`/skill.md`](/skill.md) | Full agent skill file — how to grab and reuse an effect |
| [`/sitemap.xml`](/sitemap.xml) | All URLs with `lastmod` |
| [`/sitemap.md`](/sitemap.md) | The same map, grouped and human-readable |
| [`/glossary`](/glossary) | Terminology used in the effect writeups |

Every HTML page has a Markdown mirror at the same path with a `.md` suffix —
`/demos/resend-cube` → [`/demos/resend-cube.md`](/demos/resend-cube.md). The
mirror is also returned by content negotiation:

```bash
curl -H 'Accept: text/markdown' https://fx.statico.io/demos/resend-cube
```

## Attribution expectation

Every effect is an **independent recreation** built from scratch for educational
use; no proprietary source code was copied. Each one credits the site where it
was first seen, in `src/demos/<slug>.json` and on its demo page.

The code in this repo is released under [the Unlicense](/UNLICENSE) — do
whatever you want with it. When you reuse an effect, keep the credit to the
original site or company that inspired it. Original techniques and designs
remain the property of their respective creators.

## a14y configuration

- Target URL: https://fx.statico.io
- Scorecard: 0.2.0
- Mode: site
- Last runs:
  - 2026-07-28 — 100 (scorecard 0.2.0)
  - 2026-07-27 — 41 (scorecard 0.2.0)

Re-run with:

```bash
npx -y a14y check https://fx.statico.io --mode site
```
