Communitygithub.com

author-anim

Créez un « anim », un module YAML unique qui anime les paroles et les temps d'une chanson dans le navigateur (canvas2d, SVG, DOM ou three.js), à partir d'un court brief. À utiliser pour créer, porter, restyler ou corriger un anim / visualiseur de paroles / module d'animation de paroles.

Qu'est-ce que author-anim ?

Ce skill permet de créer un « anim », un fichier YAML autonome qui anime les paroles et les beats d'une chanson dans le navigateur. Il est conçu pour les développeurs travaillant avec des agents IA (Claude Code, Cursor, Codex) sur des projets de visualisation musicale ou de lyric video. Le skill met l'accent sur la pureté des frames (fonction déterministe du temps de lecture), la séparation entre logique pure et rendu navigateur, et l'utilisation des API `G.*` pour la gestion des événements et des données de la chanson. Il supporte les backend canvas2d, SVG, DOM et three.js, et inclut des règles strictes sur l'accessibilité (légibilité, taux de flash) et le thème clair/sombre. Un workflow outillé (scaffolding, validation, check, preview) est fourni, ainsi qu'un mode sans outils pour les modèles de chat. Le résultat final est un unique fichier YAML contenant le JavaScript, le CSS et le HTML/SVG de l'animation.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/prjctg/animr-skill/tree/HEAD/skill

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Créer un anim

Un anim est un fichier unique, <nom-kebab>@<majeur>.<mineur>.yaml, avec exactement quatre clés : t (le littéral c), j (un module ES), s (CSS), h (HTML/SVG). Un lecteur hôte l'exécute avec une API globale G qui fournit les syllabes, mots, lignes, sections et temps de la chanson. Votre tâche : transformer un brief en un tel fichier qui soit correct en cas de seek/pause/redimensionnement/changement de thème, lisible et beau. Les chemins ci-dessous sont relatifs à ce répertoire skill/.

Les règles les plus importantes

  1. Une frame est une fonction pure du temps de lecture. render(t) doit dessiner la même image que la lecture ait atteint t ou que l'utilisateur y ait cherché. Pas de Math.random, Date.now, d'intégration accumulée ou d'état « ce qui s'est passé dans la frame précédente » qu'un seek pourrait sauter. Dérivez tout des données de la chanson, de la graine et de t.
  2. Deux moitiés. Une moitié pure exportée, sans DOM (buildPlan, frameAt, helpers ; testable unitairement) au-dessus d'un commentaire de séparation, puis une moitié navigateur fine (export default function (G, shadowRoot, config)) qui ne fait que câbler et dessiner. Voir guides/architecture.md.
  3. Enregistrer dans default, lire les données de la chanson dans INIT. G.on / G.off / G.onFrame uniquement à l'intérieur de default. G.map / forEach / lookup / iterator / relayout uniquement après que INIT a été déclenché (un gestionnaire INIT, ou des callbacks ultérieurs comme render), jamais dans default lui-même. Abonnez-vous G.on(G.TYPE.TICK, render) pour la lecture ; G.onFrame({ render, reset }) couvre SEEK/PLAY/PAUSE/RESIZE et UNINIT.
  4. Nettoyer avec G.dispose / G.listen. Une fonction retournée par default est ignorée. Libérez WebGL (forceContextLoss), les écouteurs, les timers, la caméra.
  5. Les couleurs vivent dans le CSS, pas dans c.v. Valeurs claires sur :host, surcharges sombres dans [data-bs-theme=dark] { } ; le canvas les relit avec g-lib cssColors. Les deux thèmes doivent être intentionnels.
  6. Ne jamais réinventer ce que g-lib a (clamp, lerp, easing, RNG basé sur graine, ajustement du canvas, ressorts, disposition du texte, pools...). Importez depuis l'épingle exact-tag ; consultez pitfalls/dont-hand-roll.md et spec/g-lib.md avant d'écrire un helper.
  7. La lisibilité prime sur l'effet. La syllabe active est lisible en clair et en sombre, sur téléphone et ordinateur portable, pour les longues lignes, le CJK, le RTL et le birman. Les flashs amples restent sous 3 Hz (guides/accessibility.md).
  8. Peu d'options typées. c et cSchema sont des littéraux simples ; chaque option fait quelque chose de visible.

Workflow (avec les outils du dépôt)

  1. Brief. Rédigez le brief de conception à partir de guides/design-brief.md : une image physique forte ; le mécanisme ; quels événements déclenchent quoi (la carte de synchronisation) ; la structure (couplet/refrain/beat) ; le plan de lisibilité ; les options ; les pièges. Choisissez le backend avec sa table de sélection. Rejetez les idées qui ne peuvent pas rester lisibles.
  2. Scaffolding. npm run new -- <nom> --backend canvas2d|svg|dom|three (ou copiez templates/<backend>.yaml à la main et remplacez __NAME__).
  3. Lire une fois : spec/module-format.md, pitfalls/general.md, la section de votre backend dans pitfalls/backends.md, pitfalls/dont-hand-roll.md. N'ouvrez autre chose que via la table de routage ci-dessous.
  4. Implémentez d'abord la moitié pure (du temps à l'état), puis la moitié navigateur fine.
  5. Validez. npm run validate -- anims/<fichier>.yaml. Corrigez chaque erreur ; justifiez chaque avertissement dans le docblock ou corrigez-le.
  6. Vérifiez. npm run check -- anims/<fichier>.yaml monte 13 chansons aux cas limites en mode headless, note la table de conformité et écrit des PNG dans out/<nom>/. Ouvrez les PNG (téléphone/ordinateur portable, clair/sombre). Un tableau vert sur une image moche ou illisible est un échec. Un AVERTISSEMENT sur une ligne de pureté du seek signifie que l'image dépend de l'historique : corrigez-le ou justifiez-le dans le docblock (une simulation délibérée).
  7. Prévisualisation (optionnelle). npm run preview -- anims/<fichier>.yaml pour jouer, scruter, changer de thème et ajuster les options.
  8. Revue selon guides/quality-rubric.md (20 questions), puis fournissez le seul fichier YAML et un court rapport (nom du fichier, tableau final de vérification, décisions laissées ouvertes par le brief, ce que vous avez délibérément omis de faire). N'envoyez pas out/ ou le harnais.

Mode sans outils (modèles de chat, pas de shell)

Sautez les étapes 2, 5-7. Partez du texte du modèle correspondant, rédigez le brief de conception dans votre raisonnement, puis passez en revue pitfalls/general.md, la section du backend et la grille des 20 questions ligne par ligne par rapport à votre propre code avant de répondre. Produisez uniquement le fichier YAML dans un bloc délimité, et mentionnez quels éléments de la grille vous n'avez pas pu vérifier sans l'exécuter (pureté du seek, changement de thème, redimensionnement).

Table de routage : ouvrir un document seulement lorsque son déclencheur s'applique

Quand vous êtes sur le point de...Lisez
décider quoi construire ; choisir un backendguides/design-brief.md
organiser le fichier ; nommer les étapes ; écrire le docblockguides/architecture.md
utiliser un appel G.*, une option d'événement ou une plage d'IDspec/events.md, spec/event-shapes.md, spec/g.d.ts
ajouter des options, des couleurs, du thèmespec/config.md
utiliser des utilitaires de temps, de mesure de texte, des helpers canvas, le cycle de viespec/utilities.md
diviser des lignes en lignes d'affichage, envelopper le textespec/relayout.md, guides/patterns-text.md
déclencher des choses sur des syllabes/lignes/beats ; pré-générer ; pause ; ressortsguides/patterns-timing.md
ajuster, mettre en évidence ou styliser du texte ; écritures non latinesguides/patterns-text.md
écrire du code de rendu (DOM, SVG, canvas, three, simulation, couches)guides/patterns-render.md, pitfalls/backends.md
caméra, terrain, essaims, conditionnement, 3D procéduralguides/techniques.md, pitfalls/techniques.md
utiliser une photo ou une caméraspec/image-input.md
construire un jeu (autoPlay false, score, états)guides/games.md
utiliser un helper g-libspec/g-lib.md
ne pas être sûr des flashs, du mouvement, du contrasteguides/accessibility.md
terminerguides/quality-rubric.md

Forme minimale (ne pas livrer ceci ; partir d'un modèle)

"t": |-
  c
"j": |
  import { hash01 } from 'https://cdn.jsdelivr.net/gh/prjctg/[email protected]/index.js';
  /* [email protected]: <une ligne>
   * 1. <revendication de conception numérotée : le mécanisme et la tentation erronée qu'il rejette> */
  export function frameAt(plan, t) { /* pure */ }
  /* Moitié navigateur. Tout ce qui est au-dessus de cette ligne est intentionnellement sans DOM. */
  export default function (G, shadowRoot, config) {
    const cfg = G.cfg(config, { canal: G.cfg.int(0) });
    let ready = false;
    const render = (t) => { if (!ready) return; /* dessiner frameAt(plan, t) */ };
    G.on(G.TYPE.INIT, () => { ready = true; /* G.map(...) est valide ici */ });
    G.on(G.TYPE.TICK, render);
    G.onFrame({ render, reset() { ready = false; } });
  }
  export const c = { v: { fadeMs: 150 }, m: [{ s: 'fadeMs', t: 'fadeMs' }] };
  export const cSchema = [{ i: 'fadeMs', n: 'Fondu (ms)', t: 'int', mn: 0, mx: 2000 }];
"s": |
  :host { display: block; --ink: var(--inkColor, #111); }
  [data-bs-theme=dark] { --ink: var(--inkColor, #eee); }
"h": |
  <canvas id="c"></canvas>

j, s, h contiennent du texte brut (jamais entouré de backticks ou de guillemets). t utilise |-. Le nom du fichier porte la version ; ne modifiez jamais une version publiée sur place.

Skills associés