Communitygithub.com

iPolloWork 组件开发规范

规范 iPolloWork Video 中地图、图表、排行等可复用视觉组件的开发与更新。涵盖组件编写规则、清单配置、可编辑变量、共用数据表单、继承设计主题、AI 编辑插槽和可 seek 的 HyperFrames 时间线。不用于生成完整视频、编写全项目模板或打包 DeepSeek 宿主插件。

¿Qué es iPolloWork 组件开发规范?

Este skill define las reglas y la estructura mínima para desarrollar o actualizar componentes visuales reutilizables dentro de iPolloWork Video, como mapas, gráficos, rankings, diagramas, aperturas y cierres. Su objetivo es garantizar que los componentes se integren perfectamente en el ecosistema iPolloWork, utilizando formularios compartidos para la edición de variables, heredando temas de diseño globales, exponiendo datos estructurados para la IA y operando dentro de la línea de tiempo de HyperFrames. El skill aplica a plataformas como Claude Code y Cursor, y detalla un flujo de trabajo que comienza con la revisión de convenios de código (`AGENTS.md`) y componentes de referencia, para luego construir un paquete mínimo (un `registry-item.json` y un archivo HTML). Los componentes deben exponer pocas variables útiles (a través de manifiestos), aceptar datos tipados (como `region-value`) y aprovechar los temas CSS existentes (`--ipw-color-bg`, etc.). La animación debe basarse en GSAP y ser controlada por HyperFrames, con slots de edición para IA (`data-ipw-ai-slot`) y una validación final que verifique la consistencia en la línea de tiempo, la independencia entre instancias y el correcto funcionamiento en múltiples temas. No se permite crear editores, paneles de parámetros o plugins de host separados.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Devin-AXIS/iPolloWork/tree/HEAD/.codex/skills/ipollowork-video-component-authoring

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Normas de desarrollo de componentes de iPolloWork Video

El resultado debe ser un componente que pueda colocarse en un video, ajustarse mediante formularios compartidos, seguir el tema del proyecto y ser procesado por IA. No cree un editor, panel de parámetros, renderizador o plugin de host separado para un componente.

1. Antes de empezar: Basarse en el convenio de código actual

Lea AGENTS.md y las normas de mantenimiento en la raíz del repositorio de iPolloWork. Primero busque componentes similares y luego decida si extender o crear uno nuevo. Las siguientes rutas son relativas a la raíz del repositorio:

  • vendor/hyperframes/registry/blocks/world-map/: Referencia para mapas, herencia de temas y datos estructurados.
  • vendor/hyperframes/registry/blocks/metric-signal/: Referencia para visualización de datos y recetas de animación opcionales.
  • vendor/hyperframes/packages/core/src/registry/types.ts: Clasificación de componentes y contrato del manifiesto.
  • vendor/hyperframes/packages/core/src/registry/componentData.ts: Estructuras de datos compartidas y reglas de análisis.
  • vendor/hyperframes/packages/core/schemas/registry-item.json, packages/types/src/hyperframes.ts: Esquemas de registro y contrato de validación del host.
  • vendor/hyperframes/packages/studio/src/utils/blockInstaller.ts: Método de instalación real, integración de temas y variables.

No copie estos esquemas ni cree otro protocolo de datos. Cuando las normas no coincidan con el código, verifique primero el consumidor actual, no use ejemplos antiguos para adivinar la interfaz.

2. Estructura de entrega mínima

Normalmente, solo necesita colocar en vendor/hyperframes/registry/blocks/<slug>/:

registry-item.json       # Metadatos, variables, categoría, archivos y declaración de capacidades
<slug>.html              # Imagen y animación

Si es realmente necesario, agregue imágenes locales, fuentes, datos o archivos de vista previa; todos los archivos necesarios para la instalación deben declararse en files, con rutas relativas al paquete. Regístrese en el vendor/hyperframes/registry/registry.json existente, no cree un servicio de directorio de componentes separado.

En el producto se denominan "componentes", pero el tipo subyacente debe ser preciso: los mapas, clasificaciones, etc., que tienen lienzo y duración independientes suelen ser hyperframes:block; los fragmentos que se inyectan en una imagen existente son hyperframes:component. Las plantillas de proyecto completo son otro tipo de entrega, no se mezclen.

3. Variables: Pocas y útiles, formularios compartidos

  • Declare en variables del manifiesto id estable, label comprensible, tipo y valor predeterminado, coherente con data-composition-variables del HTML.
  • Use los tipos existentes string / number / color / boolean / enum; para números, proporcione un rango razonable; para enumerados, opciones; para texto largo, restricciones de longitud. No agregue tipos de objeto arbitrariamente.
  • Exponga solo contenido, datos, resaltados y decisiones de diseño necesarias del usuario; no convierta cada valor CSS en un parámetro. Los colores predeterminados provienen del tema, el usuario no debe tener que configurar cada elemento para poder usarlo.
  • update: live solo para parámetros que puedan actualizarse instantáneamente; para cambios de estructura o animación, use rebuild / reload según el mecanismo existente, la declaración debe ser coherente con el comportamiento real.
  • Conecte al mecanismo de actualización de variables existente; después de la actualización, el DOM y la animación deben reflejar los nuevos valores y mantener la posición de reproducción actual del host. No cambie solo el texto mientras la línea de tiempo aún apunta al elemento antiguo.
  • Use formularios de variables y tablas de datos compartidos, no escriba un nuevo panel para un solo componente. Los campos de control del sistema como motionCueTimes, motionStyle no se tratan como parámetros de usuario comunes.

4. Datos: Estructura para IA, tabla para usuario

Los componentes de datos como mapas, rutas, gráficos, clasificaciones usan visualComponent.data, declarando columnas, semántica, identificador de fila, límite de filas y enlace. Use los tipos existentes category-value / region-value / point-value / route-value / series-value, eligiendo el que realmente coincida con los datos.

Los datos estándar para IA son:

{
  "version": 1,
  "kind": "region-value",
  "rows": [
    { "region": "China", "value": 96 },
    { "region": "Japón", "value": 77 }
  ]
}

Los nombres de columna los determina el columns del componente, no todos los componentes usan fijamente region. rowId debe ser estable y único, los números deben mantener el tipo numérico; declare unidades, precisión, resaltado y semántica de reemplazo/cobertura según el contrato existente.

binding.variable debe corresponder a una variable real. El nivel subyacente puede usar la codificación existente json / key-value-list / route-value-list / label-detail-list, pero la capa de adaptación compartida la transforma; no obligue al usuario a escribir comas, dos puntos, etc. No cree otro estado JSON no sincronizado. Para datos inválidos, proporcione mensajes claros, no ignore filas silenciosamente ni genere valores ficticios.

5. Tema y clasificación

  • Declare visualComponent.version: 1, themeMode: inherit, complete surfaces según capacidades; prefiera video, no afirme soporte para PPT o web hasta que esté verificado.
  • Use la clasificación actual VISUAL_COMPONENT_CATEGORIES, por ejemplo mapas maps, datos data, diagramas diagrams. Para aperturas y cierres, use también el librarySection existente; no cree otro árbol de clasificación.
  • Use las variables de tema existentes, por ejemplo --ipw-color-bg, --ipw-color-surface, --ipw-color-text, --ipw-color-primary, --ipw-color-border, --ipw-font-display, --ipw-font-body, --ipw-card-radius.
  • Proporcione valores de respaldo predeterminados para vista previa independiente, pero no sobrescriba el tema del host. Después de cambiar el tema, el fondo, el texto, los gráficos, los bordes y las fuentes deben cambiar coordinadamente; los colores semánticos de los datos son una excepción y requieren una justificación clara.
  • Mantenga una jerarquía clara, espaciado razonable y legibilidad en chino. Use degradados o efectos de vidrio esmerilado con moderación, no reemplace la expresión de información con efectos especiales.

6. Animación y línea de tiempo

  • Por defecto: HTML + CSS + GSAP; prefiera reutilizar gráficos existentes y SVG local. Solo considere Three.js cuando sea necesario un 3D real, no agregue dependencias pesadas para mapas simples.
  • Use el nodo raíz de composición, el tamaño, la duración y el mecanismo de instalación existentes; regístrese en la línea de tiempo GSAP pausada de window.__timelines[compositionId], controlada por HyperFrames para reproducción, pausa y seek.
  • Los selectores, estados y líneas de tiempo de cada instancia solo afectan a sí mismos. Al reconstruir, limpie las animaciones antiguas sin sobrescribir otras instancias.
  • En un momento dado, se debe obtener la misma imagen: no use temporizadores independientes, bucles de reproducción automática, números aleatorios no fijados o animaciones CSS autoejecutadas para contenido clave. Las imágenes reales, el audio y el video siguen el método de sincronización de medios existente.
  • La animación sirve al orden de explicación: aparición clara, énfasis, pausa, salida; deje suficiente tiempo de lectura para texto y datos. Evite que todos los componentes tengan la misma entrada, y evite el movimiento continuo solo por ostentación.
  • Los componentes normales no deben forzar la adición de motionRecipe. Solo cuando se necesite que la IA invoque recetas de animación según la narración, use el contrato de recetas existente; los eventos, enlaces de cue y elementos reales deben ser coherentes, la capacidad y las limitaciones de texto deben basarse en datos reales, no fabrique tiempo de voz.

7. Espacio de procesamiento de IA

Use visualComponent.ai.slots para declarar áreas editables estables y agregue data-ipw-ai-slot en las posiciones correspondientes del HTML. instructions debe explicar brevemente el propósito, las reglas de entrada y la estructura que debe conservarse.

La IA puede reemplazar contenido, ajustar el diseño, reducir el mapa y agregar explicaciones al lado, etc.; mantenga los IDs de variables, los enlaces de datos, la herencia de temas y la conexión de la línea de tiempo sin cambios. No obligue a que todo el procesamiento se convierta en parámetros de formulario, ni mantenga otra copia de la imagen para la IA.

El texto externo se trata como texto, no se incrusta en HTML ejecutable; no ejecute scripts en los datos de entrada, no incruste claves secretas. Para recursos como mapas, fuentes, imágenes, conserve la fuente y la licencia; cuando falten materiales, indíquelo claramente, no los reemplace silenciosamente en línea.

8. Aceptación y entrega

  1. El manifiesto, las variables HTML, los slots de IA, los enlaces de datos y las rutas de instalación son coherentes; pase las validaciones correspondientes del repositorio actual y las pruebas afectadas.
  2. Instale el componente en el Studio existente; el formulario compartido puede modificar la imagen real, la tabla de datos puede agregar, eliminar y editar filas válidas.
  3. Verifique los valores predeterminados, los límites, los valores nulos, el texto largo en chino, los datos incorrectos y los dos temas; las múltiples instancias no deben interferir entre sí.
  4. Verifique la reproducción desde el principio, seek intermedio, arrastre al inicio y seek después de la actualización de parámetros; la imagen y la línea de tiempo deben ser coherentes.
  5. Exporte un video corto con material real, confirme que la vista previa del navegador y la salida sean coherentes; no se puede aprobar solo con capturas de pantalla.
  6. Entregue los archivos del componente, los recursos necesarios con su origen, ejemplos de parámetros/datos, resultados de pruebas reales y elementos no verificados. No copie Studio, no modifique el comportamiento de las plantillas existentes, no deje implementaciones alternativas.

Esta norma solo guía el desarrollo de componentes. Publicar en npm, modificar plugins de host, enviar PR o cargar al mercado de componentes requiere seguir los permisos del usuario y los procesos de publicación existentes por separado.

Individual skills in this repo

This repo contains 17 individual skills — each has its own dedicated page.

Devin-AXIS/iPolloWork

Create deterministic animation and transitions for the active iPollo Video project.

Devin-AXIS/iPolloWork

Inspect, validate, preview, and render the active iPollo Video project with its bundled HyperFrames CLI.

Devin-AXIS/iPolloWork

Apply the core composition, timing, media, and determinism contract used by iPollo Video.

Devin-AXIS/iPolloWork

Plan visual direction, typography, pacing, audio, and composition for iPollo Video projects.

Devin-AXIS/iPolloWork

Build seek-safe keyframe animation for the active iPollo Video timeline.

Devin-AXIS/iPolloWork

Reuse approved HyperFrames blocks and components inside the active iPollo Video project.

Devin-AXIS/iPolloWork

Route video creation and editing through the active iPollo Video project and its built-in HyperFrames runtime.

Devin-AXIS/iPolloWork

Create or edit the active iPolloWork video's visual assets, installed recipes, editable composition and seek-safe motion; use for assembly or local picture/text/theme changes.

Devin-AXIS/iPolloWork

Add or revise music, sound effects and their mix in the active iPolloWork video, using authorized sources, real editable tracks and measured event cues.

Devin-AXIS/iPolloWork

Write or revise the active iPolloWork video's native STORYBOARD.md, with source coverage, content-led sequence and provisional timing; use for script-only work.

Devin-AXIS/iPolloWork

Route the active iPolloWork video request to its current storyboard, compose, voiceover or soundtrack work, preserving the client-owned delivery flow.

Devin-AXIS/iPolloWork

Add or revise scene-bound narration or speech-linked captions in the active iPolloWork video using actual voice settings, measured audio and alignment.

Devin-AXIS/iPolloWork

Create product launch and promotional videos through the active iPollo Video workflow.

Devin-AXIS/iPolloWork

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

Devin-AXIS/iPolloWork

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

Devin-AXIS/iPolloWork

Plan and create short videos using the installed short-video-studio workspace app. Manage its creative canvas, scripts, storyboards, characters and local assets, generate images or video through connected Work channels, and hand off editable tracks to Work Video Studio.

Devin-AXIS/iPolloWork

Find, generate, process, and reuse media through the active iPollo Video session's media services.

Skills relacionados