Skip to main content
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

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.
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.
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:
To exercise the full gate, install the item into a scratch project and run there:
Generate the Catalog page and preview assets:
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.

​
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.