Skip to content

đŸŽ„ Make videos programmatically with React

Skills: Simplify Element contribution workflow (#10517)

Igor Samokhovets2ec795a924ea
diff --git a/.agents/skills/accept-element/SKILL.md b/.agents/skills/accept-element/SKILL.md
deleted file mode 100644
index 7be097605d..0000000000
--- a/.agents/skills/accept-element/SKILL.md
+++ /dev/null
@@ -1,93 +0,0 @@
----
-name: accept-element
-description: Accept an external Remotion Element contribution by verifying its committed previews, uploading them to R2, removing the temporary assets, and preparing the pull request for review.
----
-
-# Accept a Remotion Element
-
-This is a maintainer-only workflow for contributions that used the external path in the [`submit-element` skill](../submit-element/SKILL.md). Do not use it for a repository writer's direct submission, which already has public preview URLs and no committed preview assets. Read the [Element contribution guide](../../../packages/docs/elements/contributing.mdx), the [`scaffold-element` skill](../scaffold-element/SKILL.md), and the `submit-element` skill completely before making changes.
-
-Run this workflow on the external contributor's pull request branch. Do not force push. For a pull request from a fork, confirm that “Allow edits from maintainers” is enabled. If the branch cannot be updated, upload only after approval and ask the contributor to apply the URL and asset cleanup described below.
-
-## 1. Confirm the contribution is reviewable
-
-Identify the single submitted `<category>/<slug>` and confirm that:
-
-- The implementation, page, central definition, and sidebar registration are in the pull request.
-- The page frontmatter and central definition use `/elements/<category>-<slug>-preview.png` and `.mp4` review URLs.
-- The matching files are committed at `packages/docs/static/elements/<category>-<slug>-preview.png` and `.mp4`.
-- The contributor explicitly reviewed the Element in Studio and approved both committed preview assets.
-- The pull request has passed code review against the Element contribution guide.
-
-Do not accept an Element whose metadata already points to a missing `https://remotion.media` asset or whose review assets are available only outside the pull request.
-
-## 2. Verify the committed assets against the final code
-
-Run the focused test, then render the Element again from the final pull request source:
-
-```bash
-cd packages/docs
-bun test src/test/elements.test.ts
-bun run render-element-previews --element=<category>/<slug>
-cd ../..
-```
-
-Give the maintainer these committed asset paths:
-
-- `packages/docs/static/elements/<category>-<slug>-preview.png`
-- `packages/docs/static/elements/<category>-<slug>-preview.mp4`
-
-Also give them the fresh render paths:
-
-- `packages/docs/.element-previews/<category>/<slug>/preview.png`
-- `packages/docs/.element-previews/<category>/<slug>/preview.mp4`
-
-Ask the maintainer to visually compare the committed assets with the fresh render and confirm that they represent the same poster frame and animation. Stop and wait for explicit approval of the final source and both committed assets before uploading. Do not infer approval from the agent's own inspection. If the maintainer rejects them, return the contribution to the submission workflow.
-
-## 3. Upload the exact approved files
-
-With maintainer R2 credentials in `packages/docs/.env`, run:
-
-```bash
-cd packages/docs
-bun run upload-element-preview \
- --element=<category>/<slug> \
- --source=submission
-cd ../..
-```
-
-Running the command from `packages/docs` makes Bun load `packages/docs/.env`. Element preview uploads do not use `packages/remotion-media/.env`; do not use the generic `upload-r2` or `offload-r2` skills for them.
-
-This command uploads the exact files from `packages/docs/static/elements`; it does not rerender or delete them. The explicit submission source validates that the assets are committed and unmodified, then checks the local paths, signatures, combined size, uploaded sizes, public HTTP responses, and content types. Do not continue unless both uploads are verified.
-
-The command prints the public URLs:
-
-- `https://remotion.media/elements/<category>-<slug>-preview.png`
-- `https://remotion.media/elements/<category>-<slug>-preview.mp4`
-
-## 4. Convert the contribution to its published state
-
-Only after the upload succeeds:
-
-1. Replace the local `posterUrl` and `videoUrl` in `packages/docs/src/components/Elements/element-definitions.ts` with the printed `https://remotion.media` URLs.
-2. Replace the local `image` URL in `packages/docs/elements/<category>/<slug>/index.mdx` with the public poster URL.
-3. Delete the two files from `packages/docs/static/elements`.
-4. Remove `packages/docs/static/elements` if it is empty.
-
-Do not change the slug or flat asset names between upload and cleanup.
-
-## 5. Validate and update the pull request
-
-```bash
-cd packages/docs
-bun test src/test/elements.test.ts
-cd ../..
-bun run build
-bun run stylecheck
-git diff --check
-git status --short
-```
-
-The focused test now validates that the metadata contains the exact public URLs and that no matching local review assets remain.
-
-Inspect the final diff. It should contain the Element source, page, definition, gallery registration, and public URLs, but not the PNG or MP4. Commit the acceptance cleanup normally to the same pull request branch and push without force. Then stop and report that the pull request is ready for review.
diff --git a/.agents/skills/offload-r2/SKILL.md b/.agents/skills/offload-r2/SKILL.md
index 4431b80245..48ee75f7be 100644
--- a/.agents/skills/offload-r2/SKILL.md
+++ b/.agents/skills/offload-r2/SKILL.md
@@ -1,13 +1,12 @@
---
name: offload-r2
-description: Upload Remotion repository media assets to the Cloudflare R2 bucket behind remotion.media, switch source code to hosted URLs, and retain ignored local working copies. Use when binaries should remain available locally for editing or previewing but must not be committed to Git. Do not use for Remotion Element previews.
+description: Upload Remotion repository media assets to the Cloudflare R2 bucket behind remotion.media, switch source code to hosted URLs, and retain ignored local working copies. Use when binaries should remain available locally for editing or previewing but must not be committed to Git.
---
# Offload R2 Asset
Host media on `https://remotion.media/` while preserving the original file in the worktree as an ignored local copy.
-Do not use this skill for Remotion Element previews. Follow the `submit-element` or `accept-element` skill instead; the dedicated uploader runs from `packages/docs` and loads `packages/docs/.env`.
## Workflow
diff --git a/.agents/skills/pr/SKILL.md b/.agents/skills/pr/SKILL.md
index a226d6ffc6..0374adfb3a 100644
--- a/.agents/skills/pr/SKILL.md
+++ b/.agents/skills/pr/SKILL.md
@@ -6,6 +6,8 @@ description: Open a pull request for the current feature
Ensure we are not on the main branch, make a branch if necessary.
Check whether a PR already exists for the current branch with `gh pr status` or `gh pr view`. If one exists, update it with local changes.
+If the changes add a Remotion Element, read the [Element contribution guide](../../../packages/docs/elements/contributing.mdx) before continuing.
+
Run Oxfmt on the files or package directories affected by the current change. Pass their actual paths; do not assume that the repository root has a `src` directory. Include relevant root-level files, and do not format unrelated packages or the whole repository.
For example:
diff --git a/.agents/skills/scaffold-element/SKILL.md b/.agents/skills/scaffold-element/SKILL.md
index 9eba6e48df..05ecbe1108 100644
--- a/.agents/skills/scaffold-element/SKILL.md
+++ b/.agents/skills/scaffold-element/SKILL.md
@@ -1,83 +1,17 @@
---
name: scaffold-element
-description: Scaffold a new Remotion Element with a correctly configured preview composition for development in the docs Remotion Studio.
+description: Scaffold a new Remotion Element for development in the docs Remotion Studio.
---
# Scaffold a Remotion Element
-The source of truth for design and quality criteria is the [Element contribution guide](../../../packages/docs/elements/contributing.mdx). Read it completely before making changes. If this skill and the guide diverge on acceptance criteria, follow the guide.
+The [Element contribution guide](../../../packages/docs/elements/contributing.mdx) is the source of truth for Element development. Read it completely, then follow its [Develop the Element](../../../packages/docs/elements/contributing.mdx#1-develop-the-element) section.
-This skill owns the technical scaffolding workflow. Use the [`submit-element` skill](../submit-element/SKILL.md) when the Element is ready for the gallery.
-
-## 1. Plan the preview
-
-Choose an existing category and a kebab-case slug. Before creating files, determine the initial preview metadata needed for development:
-
-- Composition width, height, fps, and preview duration
-- Installed Element duration
-- Element width and height
-- Installation mode
-- External source dependencies
-- Preview padding, which affects only the docs preview and not the Element bounds
-- A provisional poster frame
-- Explicit local poster and video review URLs using the flat asset convention:
- - `/elements/<category>-<slug>-preview.png`
- - `/elements/<category>-<slug>-preview.mp4`
-
-The files do not exist during scaffolding and are not needed by the development composition. The [`submit-element` skill](../submit-element/SKILL.md) renders them and either uploads them directly for a repository writer or adds them to an external contribution for review. Preview videos are always opaque MP4 files for broad browser, social-card, and embed compatibility. Elements that are transparent in a composition are composited onto the standard preview background for these assets.
-
-Inspect `packages/docs/elements-template/` and at least one existing Element in the same category. Do not create a new category unless the task explicitly requires one.
-
-## 2. Scaffold the files
-
-From the repository root, replace the placeholders and run:
+After scaffolding, suggest opening Docs Studio to preview the Element. If the user agrees, start it without opening a browser automatically:
```bash
-cp -R packages/docs/elements-template \
- packages/docs/elements/<category>/<slug>
-mv packages/docs/elements/<category>/<slug>/element.tsx \
- packages/docs/elements/<category>/<slug>/<slug>.tsx
-```
-
-Adapt the copied `index.mdx` to the production pattern: import `elementDefinitions`, use its `'<category>/<slug>'` entry, and set `sourceFile="./<slug>.tsx"`.
-
-Implement only enough of the component in the generated `<slug>.tsx` file to provide a visible starting point in the intended bounds. Follow the Element contribution guide for the component itself. When using Studio-editable controls, also follow the [interactivity best practices skill](../interactivity-best-practices/SKILL.md).
-
-## 3. Register the development composition
-
-Import and register the component in `packages/docs/src/components/Elements/element-definitions.ts` using the planned preview metadata. Set `installationMode` explicitly and use the same `durationInFrames` for the preview and installed Element. Add the explicit `preview` object next to the render metadata, including the local `posterUrl` and `videoUrl`. Keep the matching local poster URL in the MDX page frontmatter. The submission workflow replaces these paths with public `https://remotion.media` URLs after a direct member upload, or the acceptance workflow replaces them after an external contribution is approved.
-
-Do not edit `packages/docs/src/remotion/Root.tsx`. It automatically creates a composition for every central definition using the same sizing and wrapper used by published Elements.
-
-If the component imports a package that is not available to `packages/docs`, add it to `packages/docs/package.json`, run `bun install`, and include `bun.lock`.
-
-## 4. Check the scaffold
-
-Format the changed TypeScript and TSX files, then run the focused test:
-
-```bash
-bunx oxfmt \
- packages/docs/elements/<category>/<slug>/<slug>.tsx \
- packages/docs/src/components/Elements/element-definitions.ts \
- --write
-
cd packages/docs
-bun test src/test/elements.test.ts
-cd ../..
+bunx remotion studio --no-open
```
-Do not add the category-index or sidebar entries and do not render preview assets yet. Those belong to the submission workflow.
-
-## 5. Hand off development
-
-Do not launch the Studio from this skill. Tell the developer to run:
-
-```bash
-bun run build
-cd packages/docs
-bun run remotion
-```
-
-Then tell them to open the `elements` folder and select `element-<category>-<slug>`. Development should start in that composition so the Element is always evaluated with its configured dimensions, duration, padding, and preview background.
-
-Report the created files, composition ID, focused test result, and that the next step after development is the [`submit-element` skill](../submit-element/SKILL.md).
+Read the URL from the command output and open that URL in the available browser.
diff --git a/.agents/skills/submit-element/SKILL.md b/.agents/skills/submit-element/SKILL.md
deleted file mode 100644
index 8d17d0b6ef..0000000000
--- a/.agents/skills/submit-element/SKILL.md
+++ /dev/null
@@ -1,171 +0,0 @@
----
-name: submit-element
-description: Finalize a developed Remotion Element, add it to the docs gallery, and prepare either a direct member submission or an externally reviewable contribution.
----
-
-# Submit a Remotion Element
-
-The source of truth for design and quality criteria is the [Element contribution guide](../../../packages/docs/elements/contributing.mdx). Read it completely before making changes. If this skill and the guide diverge on acceptance criteria, follow the guide.
-
-This skill owns the contributor submission workflow. It starts with an Element created by the [`scaffold-element` skill](../scaffold-element/SKILL.md). Repository writers upload reviewed previews directly. Other contributors commit temporary review assets that a maintainer later processes with the [`accept-element` skill](../accept-element/SKILL.md).
-
-## 1. Confirm the Element is ready
-
-Confirm these files and the matching entry in `packages/docs/src/components/Elements/element-definitions.ts` already exist:
-
-- `packages/docs/elements/<category>/<slug>/index.mdx`
-- `packages/docs/elements/<category>/<slug>/<slug>.tsx`
-
-Do not launch the Studio from this skill. Before continuing, require the developer to explicitly confirm that they visually reviewed `element-<category>-<slug>` in the docs Remotion Studio and that it looks correct. Do not infer approval from completed tests or from the agent's own inspection. If the developer has not approved it or more visual development is needed, give them these commands and stop the submission workflow:
-
-```bash
-bun run build
-cd packages/docs
-bun run remotion
-```
-
-## 2. Select the submission path
-
-Determine the authenticated GitHub account's permission on the canonical repository. Do not infer membership from Git remotes, branch names, or commit email.
-
-```bash
-login=$(gh api user --jq '.login' 2>/dev/null || true)
-permission=$(
- if [ -n "$login" ]; then
- gh api "repos/remotion-dev/remotion/collaborators/$login/permission" \
- --jq '.permission' 2>/dev/null || true
- fi
-)
-printf 'GitHub user: %s\nRepository permission: %s\n' \
- "${login:-unknown}" "${permission:-unknown}"
-```
-
-Use the **direct member path** only when `permission` is `write`, `maintain`, or `admin`. Before continuing on that path, verify without printing their values that Bun can read both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`:
-
-```bash
-(
- cd packages/docs
- bun -e 'process.exit(Bun.env.AWS_ACCESS_KEY_ID && Bun.env.AWS_SECRET_ACCESS_KEY ? 0 : 1)'
-)
-```
-
-The subshell is intentional: Bun loads `packages/docs/.env` because the working directory is `packages/docs`. Element preview uploads do not use `packages/remotion-media/.env`; do not use the generic `upload-r2` or `offload-r2` skills for them.
-
-If a repository writer is missing either credential, stop and report that direct preview upload credentials are required. Do not silently commit temporary assets for them.
-
-Use the **external contribution path** when the permission is `read`, `triage`, `none`, unknown, or the GitHub lookup fails. This path does not require upload credentials.
-
-## 3. Perform the submission review
-
-Review the finished source, MDX page, and central definition against the Element contribution guide and the technical requirements in the [`scaffold-element` skill](../scaffold-element/SKILL.md). Resolve placeholder content and finalize the description, display name, contributors, dimensions, duration, `installationMode`, declared dependencies, preview padding, and poster frame.
-
-Keep the local review URLs in place while rendering and reviewing:
-
-- `posterUrl: '/elements/<category>-<slug>-preview.png'`
-- `videoUrl: '/elements/<category>-<slug>-preview.mp4'`
-- `image: /elements/<category>-<slug>-preview.png` in the page frontmatter
-
-Preview assets are composited onto the standard background and use MP4 for broad browser, social-card, and embed compatibility, even when the Element itself supports transparency.
-
-When the Element has Studio-editable controls, also review it using the [interactivity best practices skill](../interactivity-best-practices/SKILL.md).
-
-If the Element imports a package that is not available to `packages/docs`, add it to `packages/docs/package.json`, run `bun install`, and include `bun.lock`.
-
-## 4. Add it to the gallery
-
-- Confirm that the entry in `packages/docs/src/components/Elements/element-definitions.ts` places the Element in the generated overview and category library.
-- Add `'<category>/<slug>/index'` to the matching category in `packages/docs/elements-sidebars.ts`.
-
-Preserve the ordering used by the sidebar. Do not add a manual link to the category index: the visual and raw Markdown libraries are generated from the central definitions. If the task explicitly introduces a new category, create an index that renders the filtered `ElementLibrary` and add its sidebar group as part of this step.
-
-Before considering gallery registration complete, verify that the Element appears on the overview page, its category page, and the generated raw Markdown routes.
-
-Do not edit `packages/docs/src/remotion/Root.tsx`; Element compositions are derived from the central definitions.
-
-## 5. Render and inspect the previews
-
-Render only the submitted Element:
-
-```bash
-cd packages/docs
-bun run render-element-previews --element=<category>/<slug>
-cd ../..
-```
-
-Do not run `render-element-previews` without an Element filter, because that renders every Element and clears the complete preview output.
-
-Inspect these files and give both paths to the developer for visual review:
-
-- `packages/docs/.element-previews/<category>/<slug>/preview.png`
-- `packages/docs/.element-previews/<category>/<slug>/preview.mp4`
-
-Stop and wait for the developer to explicitly confirm that both previews look correct. Do not upload or copy the assets until that approval is received.
-
-## 6A. Direct member path: Upload the render
-
-Do not copy the previews into `packages/docs/static/elements` and do not add them to Git. Upload the exact reviewed render:
-
-```bash
-cd packages/docs
-bun run upload-element-preview \
- --element=<category>/<slug> \
- --source=render
-cd ../..
-```
-
-The uploader validates the local URLs, signatures, combined size, uploaded sizes, public HTTP responses, and content types. Running it from `packages/docs` makes Bun load `packages/docs/.env`. Do not continue unless both uploads are verified.
-
-Then:
-
-1. Replace the local `posterUrl` and `videoUrl` in `packages/docs/src/components/Elements/element-definitions.ts` with the printed `https://remotion.media` URLs.
-2. Replace the local `image` URL in `packages/docs/elements/<category>/<slug>/index.mdx` with the public poster URL.
-3. Confirm that no matching files exist under `packages/docs/static/elements`.
-
-If the Element changes visually after this upload, restore the local URLs, render and review it again, rerun the direct upload, and only then restore the public URLs.
-
-## 6B. External contribution path: Add review assets
-
-Do not upload to R2 or replace the local URLs. Copy the exact reviewed files to their flat review paths:
-
-```bash
-mkdir -p packages/docs/static/elements
-cp packages/docs/.element-previews/<category>/<slug>/preview.png \
- packages/docs/static/elements/<category>-<slug>-preview.png
-cp packages/docs/.element-previews/<category>/<slug>/preview.mp4 \
- packages/docs/static/elements/<category>-<slug>-preview.mp4
-```
-
-The PNG and MP4 must total no more than 10 MiB. Do not add the ignored `.element-previews` directory. The two files under `packages/docs/static/elements` are intentionally tracked and must be included in the pull request so the contributor and reviewers do not get 404 responses.
-
-The [`accept-element` skill](../accept-element/SKILL.md) uploads the approved assets and replaces the local URLs after review.
-
-## 7. Format and test
-
-Format the changed TypeScript and TSX files only. For the usual files:
-
-```bash
-bunx oxfmt \
- packages/docs/elements/<category>/<slug>/<slug>.tsx \
- packages/docs/src/components/Elements/element-definitions.ts \
- packages/docs/elements-sidebars.ts \
- --write
-
-cd packages/docs
-bun test src/test/elements.test.ts
-cd ../..
-```
-
-For direct member submissions, the focused test validates the exact public URLs and the absence of local review assets. For external contributions, it validates the local URLs, flat review assets, file signatures, and combined contribution size.
-
-## 8. Run final repository checks
-
-```bash
-bun run build
-bun run stylecheck
-git diff --check
-git status --short
-```
-
-Before finishing, verify that the page is listed in the generated overview and category library, the generated raw Markdown, and the sidebar; all checks pass; and only intended files are part of the change.
-
-For the direct member path, report the two verified public preview URLs and confirm that no preview assets are tracked. For the external path, report the two tracked review assets and keep “Allow edits from maintainers” enabled if a pull request is opened. In both cases, stop after preparing the contribution for review.
diff --git a/.agents/skills/upload-element-previews/SKILL.md b/.agents/skills/upload-element-previews/SKILL.md
new file mode 100644
index 0000000000..efbece8c06
--- /dev/null
+++ b/.agents/skills/upload-element-previews/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: upload-element-previews
+description: Upload a Remotion Element's preview assets to remotion.media and replace local preview URLs. Use when given an Element slug, or when exactly one Element's preview assets are present in the current worktree.
+---
+
+# Upload Element Previews
+
+1. Identify the Element slug. Ask if it is ambiguous.
+2. Choose the source:
+ - Use `render` for fresh files in `.element-previews`.
+ - Use `submission` for committed files in `static/elements`.
+3. Upload the previews:
+
+```bash
+cd packages/docs
+bun run upload-element-preview \
+ --element=<category>/<slug> \
+ --source=<render|submission>
+```
+
+4. Replace `image`, `posterUrl`, and `videoUrl` with the printed `remotion.media` URLs.
+5. If using `submission`, delete the local review assets. If using `render`, leave `.element-previews` uncommitted.
+6. Commit and push when the work belongs on a branch.
diff --git a/.agents/skills/upload-r2/SKILL.md b/.agents/skills/upload-r2/SKILL.md
index c3f4d297ae..86469cf850 100644
--- a/.agents/skills/upload-r2/SKILL.md
+++ b/.agents/skills/upload-r2/SKILL.md
@@ -1,13 +1,12 @@
---
name: upload-r2
-description: Upload large Remotion repository assets to the Cloudflare R2 bucket behind remotion.media and replace local public/ assets with hosted URLs. Use when a file is too large for Git or when a PR should avoid committing media binaries by hosting them on remotion.media. Do not use for Remotion Element previews.
+description: Upload large Remotion repository assets to the Cloudflare R2 bucket behind remotion.media and replace local public/ assets with hosted URLs. Use when a file is too large for Git or when a PR should avoid committing media binaries by hosting them on remotion.media.
---
# Upload R2 Asset
Use this for large media assets that should be hosted on `https://remotion.media/` instead of committed to Git.
-Do not use this skill for Remotion Element previews. Follow the `submit-element` or `accept-element` skill instead; the dedicated uploader runs from `packages/docs` and loads `packages/docs/.env`.
## Workflow
diff --git a/packages/docs/elements/contributing.mdx b/packages/docs/elements/contributing.mdx
index 4f730ec88d..3ba2fc1add 100644
--- a/packages/docs/elements/contributing.mdx
+++ b/packages/docs/elements/contributing.mdx
@@ -8,33 +8,50 @@ description: Create and submit a Remotion Element for the Elements gallery.
Have a small, remixable Remotion Element? We'd like to see it.
-## Develop the Element
+## 1. Develop the Element
1. Copy `packages/docs/elements-template` to `packages/docs/elements/<category>/<slug>`. The template includes a component and an `index.mdx` documentation page.
-2. Add its metadata to `packages/docs/src/components/Elements/element-definitions.ts` to register its Studio composition.
+2. Add its metadata to `packages/docs/src/components/Elements/element-definitions.ts` to register its Studio composition, and add its page to `packages/docs/elements-sidebars.ts`.
3. Build and preview the Element in Studio:
```bash title="Terminal"
cd packages/docs && bun remotion
```
-The following [Agent Skills](https://agentskills.io/) support the contribution workflow:
+The **scaffold-element skill** is an [Agent Skill](https://agentskills.io/) that can set up the template and Studio composition.
-- The **scaffold-element skill** copies the template and registers the development composition.
-- The **submit-element skill** adds the Element to the gallery and prepares it for review.
+## 2. Prepare previews
-## Open the pull request
+Render and visually review the Element and its previews:
-Before opening a pull request, visually review the Element in Studio.
+```bash title="Terminal"
+cd packages/docs
+bun run render-element-previews --element=<category>/<slug>
+bun test src/test/elements.test.ts
+```
+
+To make previews visible in the pull request deployment:
+
+1. Copy the rendered preview assets to `packages/docs/static/elements` and commit them.
+2. Set `image`, `posterUrl`, and `videoUrl` to `/elements/<category>-<slug>-preview.png` and `/elements/<category>-<slug>-preview.mp4`, matching those files.
+
+{/*
+Preview workflows:
+
+- External contributors render previews, commit them to static/elements, and use local URLs so the pull request deployment can show them.
+- Maintainers can use the upload-element-previews skill after rendering locally (source=render) or from a contributor's committed assets (source=submission). The uploader verifies the assets, publishes them to remotion.media, and prints the replacement URLs. Delete the static review assets after a submission upload.
+*/}
+
+## 3. Open the pull request
Include:
- The implementation, page, and gallery registration
- What makes it useful
-- A working PNG and MP4 preview, committed directly to the pull request
+- A working PNG and MP4 preview
- Links to inspiration, if any
-Preview assets let reviewers see the Element in the pull request deployment. After approval, a repository maintainer uploads them to static storage. Keep “Allow edits from maintainers” enabled on the pull request.
+Keep “Allow edits from maintainers” enabled on the pull request. After approval, a repository maintainer uploads the assets to static storage.
## Element Guidelines
@@ -89,4 +106,4 @@ Follow the [interactivity best practices](/docs/studio/interactivity-best-practi
Choose a poster frame that clearly shows the Element. The video preview should cover the Element's full duration and, when applicable, include its entrance and exit animations.
-When ready, [open a pull request](#open-the-pull-request).
+When ready, [open a pull request](#3-open-the-pull-request).
diff --git a/packages/docs/upload-element-preview.ts b/packages/docs/upload-element-preview.ts
index cea450efc8..694fc11e63 100644
--- a/packages/docs/upload-element-preview.ts
+++ b/packages/docs/upload-element-preview.ts
@@ -3,6 +3,15 @@ import path from 'path';
import {S3Client} from 'bun';
import {elementDefinitions} from './src/components/Elements/element-definitions';
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+ console.log(`Usage:
+ bun run upload-element-preview --element=<category>/<slug> --source=render
+ bun run upload-element-preview --element=<category>/<slug> --source=submission
+
+Use render to upload files from .element-previews. Use submission to upload committed files from static/elements. The command prints the hosted URLs and any cleanup required after a verified upload.`);
+ process.exit(0);
+}
+
const elementArguments = process.argv.filter((argument) =>
argument.startsWith('--element='),
);