zooqueen
62bbc7766c
Every SKILL.md already declared the new name — name: frames, frames-cli, frames-core, and so on — but the directories were never moved, so the tree carried frames-* in content and hyperframes-* on disk. Everything that resolves a skill by path missed: the core-skill list, the plugin marketplace pin, and the docs the CLI reads at runtime. Eight tests failed on main because the files they open do not exist. The directories now match what the files say they are, and the guide the claude-design contract reads takes the name that contract already used.
5.2 KiB
name, description
| name | description |
|---|---|
| frames-registry | Install, discover, and wire registry blocks and components into Frames compositions. Use when running frames add or frames catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with frames.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR). |
Frames Registry
The registry provides reusable blocks and components installable via frames add <name>.
- Blocks — standalone sub-compositions (own dimensions, duration, timeline). Included via
data-composition-srcin a host composition. - Components — effect snippets (no own dimensions). Pasted directly into a host composition's HTML.
Quick reference
frames add data-chart # install a block
frames add grain-overlay # install a component
frames add captions # install every block tagged captions
frames add shimmer-sweep --dir . # target a specific project
frames add data-chart --json # machine-readable output
frames add data-chart --no-clipboard # skip clipboard (CI/headless)
After install, the CLI prints which files were written and a snippet to paste into your host composition. The snippet is a starting point — you'll need to add data-composition-id (must match the block's internal composition ID), data-start, and data-track-index attributes when wiring blocks.
The positional value is resolved as an exact item name first. If no item matches and the value is a tag, the command installs every block with that tag. Registry dependencies are installed before the requested item. frames add works only for blocks and components; for examples, use frames init <dir> --example <name> instead.
Install locations
Blocks install to compositions/<name>.html by default. Components install to compositions/components/<name>.html by default.
These paths are configurable in frames.json:
{
"registry": "https://raw.githubusercontent.com/hanzoai/frames/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
See install-locations.md for full details.
Wiring blocks
Blocks are standalone compositions — include them via data-composition-src in your host index.html:
<div
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-start="2"
data-duration="15"
data-track-index="1"
data-width="1920"
data-height="1080"
></div>
Key attributes:
data-composition-src— path to the block HTML filedata-composition-id— must match the block's internal IDdata-start— when the block appears in the host timeline (seconds)data-duration— how long the block playsdata-width/data-height— block canvas dimensionsdata-track-index— layer ordering (higher = in front)
See wiring-blocks.md for full details.
Wiring components
Components are snippets — paste their HTML into your composition's markup, their CSS into your style block, and their JS into your script (if any):
- Read the installed file (e.g.,
compositions/components/grain-overlay.html) - Copy the HTML elements into your composition's
<div data-composition-id="..."> - Copy the
<style>block into your composition's styles - Copy any
<script>content into your composition's script (before your timeline code) - If the component exposes GSAP timeline integration (see the comment block in the snippet), add those calls to your timeline
See wiring-components.md for full details.
Discovery
Use the CLI as the primary discovery surface:
npx @hanzo/frames catalog
npx @hanzo/frames catalog --type block
npx @hanzo/frames catalog --type component
npx @hanzo/frames catalog --type block --tag social
npx @hanzo/frames catalog --json
npx @hanzo/frames catalog --human-friendly
The normal table and --json modes only list matches; install a selected name with frames add <name>. --human-friendly opens an interactive picker and installs the selected item immediately. In CI or agent workflows, prefer --json followed by an explicit add.
If the CLI cannot reach the configured registry, inspect the raw manifest as a fallback:
curl -s https://raw.githubusercontent.com/hanzoai/frames/main/registry/registry.json
Each item's registry-item.json contains: name, type, title, description, tags, dimensions (blocks only), duration (blocks only), and file list.
See discovery.md for details on filtering by type and tags.
Contributing a new block or component
To author a NEW registry item (caption style, VFX block, transition, lower third, or a reusable component) and ship it as an upstream PR — not install an existing one — follow the full idea → scaffold → build → validate → preview → ship workflow in contributing.md. Copy-paste starter templates (caption / VFX / component / registry-item.json) are in templates.md.