mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
James Russo
4bde66f532
## What
New skill `hyperframes-registry` that teaches AI coding agents how to install and wire registry blocks and components into HyperFrames compositions.
### Skill structure
```
skills/hyperframes-registry/
SKILL.md — triggers, overview, quick reference
references/
install-locations.md — default paths, hyperframes.json config
wiring-blocks.md — iframe inclusion, data attributes, positioning
wiring-components.md — snippet merging (HTML, CSS, JS, timeline)
discovery.md — manifest reading, item fields, available items table
demo-html-pattern.md — why components ship demo.html, structure conventions
examples/
add-block.md — worked example: data-chart block install + wiring
add-component.md — worked example: shimmer-sweep component install + wiring
```
## Why
Phase B of the catalog plan (PR 10). Without this skill, agents using `hyperframes add` have to guess how to wire installed items into compositions. The skill encodes the iframe/snippet patterns so agents get it right on the first attempt.
## How
- SKILL.md frontmatter triggers on: `hyperframes add`, "block", "component", `hyperframes.json`
- References cover every step: discovery, install, wiring blocks (iframe), wiring components (snippet merge), and the demo.html convention
- Two worked examples walk through complete install-to-preview workflows
- Updated CLAUDE.md skills table + trigger rules, README.md skills table, docs/packages/cli.mdx
## Test plan
- [x] `scripts/lint-skills.ts` passes (checked 4 skill files, no issues)
- [x] `oxfmt --check` passes on all markdown files
- [x] SKILL.md frontmatter has valid `name` and `description`
- [x] All reference links in SKILL.md resolve to existing files
- [x] CLAUDE.md, README.md, and docs CLI page updated with new skill
55 lines
1.8 KiB
Markdown
55 lines
1.8 KiB
Markdown
# The demo.html Convention
|
|
|
|
## Why components ship demo.html
|
|
|
|
Every component in the registry ships a companion `demo.html` file alongside its snippet. The demo serves two purposes:
|
|
|
|
1. **Preview fixture** — the CI preview pipeline renders the demo to generate thumbnail images and preview videos for the catalog docs page.
|
|
|
|
2. **Usage example** — the demo shows the component effect applied to representative content, serving as a working reference.
|
|
|
|
## Demo structure
|
|
|
|
A demo is a complete, standalone HTML composition:
|
|
|
|
```html
|
|
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8" />
|
|
<meta name="viewport" content="width=1920, height=1080" />
|
|
<title>Component Name — Demo</title>
|
|
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
|
|
<style>
|
|
/* reset + canvas size */
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div data-composition-id="<name>-demo" data-width="1920" data-height="1080" data-duration="N">
|
|
<!-- Demo content showing the effect -->
|
|
<!-- Component snippet inlined here -->
|
|
</div>
|
|
<script>
|
|
// GSAP timeline demonstrating the effect
|
|
window.__timelines = window.__timelines || {};
|
|
window.__timelines["<name>-demo"] = tl;
|
|
</script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
Key conventions:
|
|
|
|
- `data-composition-id` is `<component-name>-demo` to avoid collisions
|
|
- The demo is self-contained — all CSS and JS from the snippet is inlined
|
|
- The GSAP timeline is registered on `window.__timelines`
|
|
- Duration should be long enough to showcase the effect (typically 5-8 seconds)
|
|
|
|
## Blocks don't need demo.html
|
|
|
|
Blocks are already standalone compositions that can be rendered directly. Only components need the demo wrapper.
|
|
|
|
## Demos are not installed
|
|
|
|
The `demo.html` is NOT installed by `hyperframes add` — it exists only in the registry for preview generation and as a reference.
|