Contribute to the Catalog

Add a reusable block or component to the HyperFrames registry.

The Catalog is generated from the registry in the HyperFrames repository. You can contribute a visual idea or build an item that anyone can install.

Choose how to contribute

Suggest an idea

Open a GitHub issue with a visual reference and explain where the effect would be useful. A screen recording, Figma sketch, or example from another tool is enough to start.

Build an item

Ask your agent to use the /hyperframes-registry skill, or follow the same workflow below.

Choose the item type

Type	Use it for	Required files
Block	A standalone composition with fixed dimensions and duration	registry-item.json and the composition HTML
Component	A snippet installed into another composition	registry-item.json, the snippet HTML, and a standalone demo.html

Each item has its own directory under registry/blocks/ or registry/components/. Prefix every element ID with a short abbreviation of the item name so it cannot collide when installed as a sub-composition.

registry/blocks/my-block/
  my-block.html
  registry-item.json

registry/components/my-effect/
  my-effect.html
  demo.html
  registry-item.json

The Catalog preview generator skips a component without demo.html.

Define the manifest

registry-item.json follows the registry item schema. Blocks declare dimensions and duration; components must not.

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "my-block",
  "type": "hyperframes:block",
  "title": "My Block",
  "description": "What this block does in one sentence",
  "tags": ["category", "subcategory"],
  "dimensions": { "width": 1920, "height": 1080 },
  "duration": 5,
  "params": [
    {
      "key": "--accent",
      "label": "Accent",
      "type": "color",
      "default": "#ff4d4d"
    }
  ],
  "files": [
    {
      "path": "my-block.html",
      "target": "compositions/my-block.html",
      "type": "hyperframes:composition"
    }
  ]
}

Use params for the values someone should be able to change in Studio without editing HTML. Supported controls are color, text, number, and select.

Other useful optional fields include author, authorUrl, relatedSkill, registryDependencies, license, sourcePrompt, minCliVersion, and deprecated. The TypeScript registry types and existing manifests are the current authority. The published JSON schema validates the shared manifest fields but does not yet describe the block-only params field.

Build for reuse

Every registry item must:

• use a paused GSAP timeline registered on window.__timelines;
• match data-composition-id to the registered timeline ID;
• use prefixed element IDs;
• avoid Date.now(), unseeded Math.random(), and real-time animation loops;
• seek correctly at any frame;
• work after installation outside its source directory.

A one-off example belongs in Examples, not the Catalog.

Validate and preview

Lint the item the way a user receives it — mounted into a real project. A bare npx hyperframes lint cannot validate a registry directory, because the CLI looks for index.html and items ship as <name>.html or demo.html:

bun run lint:registry-items my-block

To exercise the full gate, install the item into a scratch project and run there:

npx hyperframes init scratch && cd scratch
npx hyperframes add my-block
npx hyperframes check

Generate the Catalog page and preview assets:

npx tsx scripts/generate-catalog-pages.ts
npx tsx scripts/generate-catalog-previews.ts --only my-block

These generators read the item directly from the working tree. The add command cannot install an unpublished local item by name: it resolves items from the registry URL in hyperframes.json. Test npx hyperframes add my-block from a clean project after the item is present in that registry manifest.

Do not hand-edit the generated item page. Fix its registry manifest or the generator and regenerate it.

Watch the preview at full speed. Passing check proves the composition is valid; it does not prove that the motion is readable or useful.

Review question	What good looks like
Is there one visual hero?	The eye knows where to look in the first second
Can the important text be read once?	Information lands, then holds before the cut
Does motion accelerate and settle?	It does not drift at constant speed like a slide
Can someone restyle it?	Brand-facing values are exposed as parameters
Is it meaningfully reusable?	It solves a repeated production problem

Open the pull request

Include:

• the item directory;
• the matching entry in registry/registry.json;
• regenerated Catalog output;
• a hyperframes.dev preview from npx hyperframes publish;
• when to use it, its useful duration range, and any known pitfalls.

External contributors should attach the preview MP4. A maintainer will publish the final Catalog media. HeyGen contributors can use scripts/upload-docs-images.sh after preview review.