@anvpx/motion-templates 0.0.0-stage → 0.1.1

package/templates/explain/blueprints/architecture.json

@@ -0,0 +1,76 @@
+{
+  "id": "architecture",
+  "purpose": "Show how a system fits together: a node-and-arrow diagram, up to four notes, one optional number, a close.",
+  "discover": {
+    "useCases": [
+      "Show how a system works: its components and how data flows between them.",
+      "Walk a new teammate through an architecture in under a minute.",
+      "Give a reviewer a quick map of the parts and their links before a design talk."
+    ],
+    "audience": ["engineers", "stakeholders", "new-hires"],
+    "goodFor": "A system of 2-8 parts with arrows between them and a few notes.",
+    "notFor": "Procedures (howto), persuasion (pitch), numeric analysis (datastory).",
+    "tags": ["explain", "architecture", "diagram", "dev", "process"],
+    "tone": ["technical", "calm"],
+    "aspects": ["16:9"],
+    "lengths": { "min": 40, "max": 90 }
+  },
+  "slots": {
+    "title": { "type": "text", "max": 60, "required": true },
+    "nodes": { "type": "text[]", "min": 2, "max": 8, "itemMax": 24, "required": true },
+    "edges": { "type": "text[]", "max": 12, "itemMax": 60, "optional": true },
+    "notes": { "type": "text[]", "max": 4, "itemMax": 70, "optional": true },
+    "stat": {
+      "type": "object",
+      "fields": { "value": "number", "unit": "text", "label": "text" },
+      "optional": true
+    },
+    "takeaway": { "type": "text", "max": 80, "optional": true },
+    "length": { "type": "enum", "values": ["short", "standard", "long"], "default": "standard" },
+    "style": { "type": "enum", "values": ["calm", "crisp"], "default": "calm" }
+  },
+  "example": {
+    "title": "How a request reaches the data",
+    "nodes": ["Client", "API gateway", "Auth service", "Database"],
+    "edges": [
+      "Client>API gateway|request",
+      "API gateway>Auth service|check token",
+      "API gateway>Database|query"
+    ],
+    "notes": ["The gateway is the only public entry", "Every request is authenticated first"],
+    "stat": { "value": 120, "unit": "ms", "label": "median response time" },
+    "takeaway": "One public door, checked every time"
+  },
+  "meta": { "title": { "$slot": "title" }, "lang": "en" },
+  "scenes": [
+    {
+      "id": "intro",
+      "type": "title",
+      "props": { "kicker": "Architecture", "title": { "$slot": "title" } }
+    },
+    {
+      "id": "diagram",
+      "type": "flow",
+      "props": {
+        "nodes": { "$slot": "nodes", "as": "flow-nodes" },
+        "edges": {
+          "$slot": "edges",
+          "as": "flow-edges",
+          "orElse": { "$slot": "nodes", "as": "flow-chain" }
+        }
+      }
+    },
+    {
+      "when": "notes",
+      "id": "notes",
+      "type": "bullets",
+      "props": { "title": "Design rules", "items": { "$slot": "notes" } }
+    },
+    { "when": "stat", "id": "number", "type": "stat", "props": { "$spread": "stat" } },
+    {
+      "id": "end",
+      "type": "outro",
+      "props": { "title": { "$slot": "takeaway", "orElse": { "$slot": "title" } } }
+    }
+  ]
+}

package/templates/explain/blueprints/concept.json

@@ -0,0 +1,89 @@
+{
+  "id": "concept",
+  "purpose": "Explain one concept in 30-60s: hook, one-line definition, 3-5 points, one number, one diagram, close.",
+  "discover": {
+    "useCases": [
+      "Explain one idea to people who did not build it.",
+      "Introduce a term or technology with one number and one diagram.",
+      "Give newcomers a short lesson with a single takeaway."
+    ],
+    "audience": ["stakeholders", "new-hires", "customers", "students"],
+    "goodFor": "A single concept with a hook, 3-5 points and an optional number.",
+    "notFor": "Step-by-step procedures (howto), numeric deep dives (datastory).",
+    "tags": ["explain", "concept", "lesson", "onboarding", "education"],
+    "tone": ["calm"],
+    "aspects": ["16:9"],
+    "lengths": { "min": 30, "max": 60 }
+  },
+  "slots": {
+    "title": { "type": "text", "max": 60, "required": true },
+    "hook": { "type": "text", "max": 90 },
+    "definition": { "type": "text", "max": 110, "optional": true },
+    "points": { "type": "text[]", "min": 3, "max": 5, "itemMax": 70 },
+    "stat": {
+      "type": "object",
+      "fields": { "value": "number", "unit": "text", "label": "text" },
+      "optional": true
+    },
+    "nodes": { "type": "text[]", "min": 2, "max": 6, "itemMax": 24, "optional": true },
+    "edges": { "type": "text[]", "max": 8, "itemMax": 60, "optional": true },
+    "takeaway": { "type": "text", "max": 80, "optional": true },
+    "length": { "type": "enum", "values": ["short", "standard", "long"], "default": "standard" },
+    "style": { "type": "enum", "values": ["calm", "crisp"], "default": "calm" }
+  },
+  "example": {
+    "title": "How caching works",
+    "hook": "Fast answers by remembering recent work",
+    "definition": "A [cache] keeps a copy of recent answers so repeat requests skip the slow path",
+    "points": [
+      "A miss fetches from the origin",
+      "The cache keeps a copy",
+      "A hit answers instantly"
+    ],
+    "stat": { "value": 90, "unit": "%", "label": "requests served from cache" },
+    "nodes": ["Client", "Cache", "Origin"],
+    "takeaway": "Remember work to skip work"
+  },
+  "meta": { "title": { "$slot": "title" }, "lang": "en" },
+  "scenes": [
+    {
+      "id": "intro",
+      "type": "title",
+      "props": {
+        "kicker": "Concept",
+        "title": { "$slot": "title" },
+        "subtitle": { "$slot": "hook" }
+      }
+    },
+    {
+      "when": "definition",
+      "id": "definition",
+      "type": "callout",
+      "props": { "kind": "definition", "label": "In short", "text": { "$slot": "definition" } }
+    },
+    {
+      "id": "points",
+      "type": "bullets",
+      "props": { "title": "How it works", "items": { "$slot": "points" } }
+    },
+    { "when": "stat", "id": "number", "type": "stat", "props": { "$spread": "stat" } },
+    {
+      "when": "nodes",
+      "id": "diagram",
+      "type": "flow",
+      "props": {
+        "nodes": { "$slot": "nodes", "as": "flow-nodes" },
+        "edges": {
+          "$slot": "edges",
+          "as": "flow-edges",
+          "orElse": { "$slot": "nodes", "as": "flow-chain" }
+        }
+      }
+    },
+    {
+      "id": "end",
+      "type": "outro",
+      "props": { "title": { "$slot": "takeaway", "orElse": { "$slot": "title" } } }
+    }
+  ]
+}

package/templates/explain/blueprints/howto.json

@@ -0,0 +1,56 @@
+{
+  "id": "howto",
+  "purpose": "Teach a procedure: an animated path of 3-6 steps with a detail under each, then the outcome.",
+  "discover": {
+    "useCases": [
+      "Teach a procedure in 3-6 numbered steps.",
+      "Give a quick how-to with a stated outcome.",
+      "Show newcomers the order in which a routine task is done."
+    ],
+    "audience": ["new-hires", "customers", "students"],
+    "goodFor": "A procedure with 3-6 ordered steps and a clear outcome.",
+    "notFor": "Concept explanations (concept), system diagrams (architecture).",
+    "tags": ["howto", "tutorial", "steps", "explain", "onboarding", "process"],
+    "tone": ["calm"],
+    "aspects": ["16:9"],
+    "lengths": { "min": 15, "max": 50 }
+  },
+  "slots": {
+    "title": { "type": "text", "max": 60, "required": true },
+    "steps": {
+      "type": "object",
+      "fields": { "label": "text", "detail": "text" },
+      "list": true,
+      "min": 3,
+      "max": 6,
+      "required": true
+    },
+    "outcome": { "type": "text", "max": 90, "required": true },
+    "length": { "type": "enum", "values": ["short", "standard", "long"], "default": "standard" },
+    "style": { "type": "enum", "values": ["calm", "crisp"], "default": "calm" }
+  },
+  "example": {
+    "title": "Ship a change safely",
+    "steps": [
+      { "label": "Branch", "detail": "Start from main" },
+      { "label": "Test", "detail": "Write a failing test" },
+      { "label": "Review", "detail": "One teammate reads it" },
+      { "label": "Merge", "detail": "Squash and clean up" }
+    ],
+    "outcome": "A small change merged with confidence"
+  },
+  "meta": { "title": { "$slot": "title" }, "lang": "en" },
+  "scenes": [
+    {
+      "id": "intro",
+      "type": "title",
+      "props": { "kicker": "How to", "title": { "$slot": "title" } }
+    },
+    {
+      "id": "procedure",
+      "type": "steps",
+      "props": { "title": { "$slot": "title" }, "layout": "path", "steps": { "$slot": "steps" } }
+    },
+    { "id": "end", "type": "outro", "props": { "title": { "$slot": "outcome" } } }
+  ]
+}

package/templates/explain/blueprints/overview.json

@@ -0,0 +1,126 @@
+{
+  "id": "overview",
+  "purpose": "Stakeholder overview of a system: goal, what it is made of, how it works in 3 steps, key numbers, architecture flow, close.",
+  "discover": {
+    "useCases": [
+      "Give leadership a one-minute overview of a system or programme.",
+      "Introduce a platform to new stakeholders: goal, parts, process and headline numbers.",
+      "Brief a partner team on what something does and how it fits together."
+    ],
+    "audience": ["stakeholders", "new-hires", "customers"],
+    "goodFor": "A whole system or programme: a goal, 3-4 pillars, a 3-step flow and a few numbers.",
+    "notFor": "One narrow idea (concept), a procedure (howto), persuasion (pitch).",
+    "tags": ["explain", "architecture", "onboarding", "kpi", "diagram", "internal", "process"],
+    "tone": ["calm", "technical"],
+    "aspects": ["16:9"],
+    "lengths": { "min": 45, "max": 90 }
+  },
+  "slots": {
+    "title": { "type": "text", "max": 60, "required": true },
+    "goal": { "type": "text", "max": 110, "required": true },
+    "pillars": {
+      "type": "object",
+      "fields": { "icon": "text", "label": "text", "detail": "text" },
+      "list": true,
+      "min": 3,
+      "max": 4,
+      "required": true
+    },
+    "steps": {
+      "type": "object",
+      "fields": { "label": "text", "detail": "text" },
+      "list": true,
+      "min": 3,
+      "max": 3,
+      "required": true
+    },
+    "numbers": {
+      "type": "object",
+      "fields": { "value": "text", "label": "text" },
+      "list": true,
+      "min": 2,
+      "max": 4,
+      "optional": true
+    },
+    "nodes": { "type": "text[]", "min": 3, "max": 6, "itemMax": 24, "optional": true },
+    "edges": { "type": "text[]", "max": 8, "itemMax": 60, "optional": true },
+    "ask": { "type": "text", "max": 90, "optional": true },
+    "length": { "type": "enum", "values": ["short", "standard", "long"], "default": "standard" },
+    "style": { "type": "enum", "values": ["calm", "crisp"], "default": "calm" }
+  },
+  "example": {
+    "title": "Booking platform overview",
+    "goal": "Let customers book a slot in [under a minute] and let staff see it [instantly]",
+    "pillars": [
+      { "icon": "calendar", "label": "Scheduling", "detail": "Live availability" },
+      { "icon": "users", "label": "Accounts", "detail": "One profile each" },
+      { "icon": "shield", "label": "Security", "detail": "Encrypted data" },
+      { "icon": "chart-line", "label": "Reporting", "detail": "Daily usage" }
+    ],
+    "steps": [
+      { "label": "Choose", "detail": "Pick a service and time" },
+      { "label": "Confirm", "detail": "Pay and get a receipt" },
+      { "label": "Attend", "detail": "Staff see it on arrival" }
+    ],
+    "numbers": [
+      { "value": "40k", "label": "bookings a month" },
+      { "value": "99.9%", "label": "uptime" },
+      { "value": "52 s", "label": "median booking time" }
+    ],
+    "nodes": ["Web app", "API gateway", "Booking service", "Payments", "Database"],
+    "edges": [
+      "Web app>API gateway",
+      "API gateway>Booking service",
+      "API gateway>Payments",
+      "Booking service>Database"
+    ],
+    "ask": "Next step: pilot with two more sites"
+  },
+  "meta": { "title": { "$slot": "title" }, "lang": "en" },
+  "scenes": [
+    {
+      "id": "intro",
+      "type": "title",
+      "props": { "kicker": "Overview", "title": { "$slot": "title" } }
+    },
+    {
+      "id": "goal",
+      "type": "callout",
+      "props": { "kind": "statement", "label": "Goal", "text": { "$slot": "goal" } }
+    },
+    {
+      "id": "pillars",
+      "type": "icon-grid",
+      "props": { "title": "What it is made of", "items": { "$slot": "pillars" } }
+    },
+    {
+      "id": "how",
+      "type": "steps",
+      "props": { "title": "How it works", "layout": "path", "steps": { "$slot": "steps" } }
+    },
+    {
+      "when": "numbers",
+      "id": "numbers",
+      "type": "kpi-grid",
+      "props": { "title": "In numbers", "items": { "$slot": "numbers" } }
+    },
+    {
+      "when": "nodes",
+      "id": "diagram",
+      "type": "flow",
+      "props": {
+        "nodes": { "$slot": "nodes", "as": "flow-nodes" },
+        "edges": {
+          "$slot": "edges",
+          "as": "flow-edges",
+          "orElse": { "$slot": "nodes", "as": "flow-chain" }
+        }
+      }
+    },
+    {
+      "id": "end",
+      "type": "outro",
+      "props": { "title": { "$slot": "ask", "orElse": { "$slot": "title" } } }
+    }
+  ]
+}

package/templates/explain/copy.md

@@ -0,0 +1,19 @@
+# Explainer copy guide
+
+Tone: calm, direct, plain English. Explain, do not sell.
+
+Do
+- One idea per scene. Lead with the subject, then the verb.
+- Title: a topic or a question, at most 8 words.
+- Points and steps: parallel phrases of 3-8 words; no full stops.
+- Numbers: round them and say what they mean; one unit per number.
+- Diagram labels: nouns, 1-3 words ("API gateway", "Order service").
+- Branching diagrams: add `edges` as `from>to|label` items ("Gateway>Database|query"); without `edges` the nodes chain in order.
+- Close with the outcome or the next step, not a recap.
+
+Don't
+- No jargon without a short gloss; spell out acronyms once.
+- No more than 5 points, 8 nodes, 40 words per scene.
+- No exclamation marks, emoji, or marketing adjectives (seamless, powerful).
+
+Vocabulary: "service" not "microservice", "request" not "payload", "step" not "stage".

package/templates/explain/pacing.json

@@ -0,0 +1,19 @@
+{
+  "wordsPerSecond": 2.5,
+  "sceneSeconds": {
+    "title": { "short": 3, "standard": 4, "long": 5 },
+    "bullets": { "short": 6, "standard": 8, "long": 11 },
+    "stat": { "short": 4, "standard": 5, "long": 6 },
+    "flow": { "short": 4, "standard": 5, "long": 11 },
+    "callout": { "short": 4, "standard": 6, "long": 8 },
+    "steps": { "short": 6, "standard": 11, "long": 14 },
+    "icon-grid": { "short": 5, "standard": 7, "long": 10 },
+    "kpi-grid": { "short": 4, "standard": 6, "long": 8 },
+    "outro": { "short": 3, "standard": 4, "long": 5 }
+  },
+  "lengths": {
+    "short": { "scenes": [3, 6], "totalSec": [10, 40] },
+    "standard": { "scenes": [3, 8], "totalSec": [18, 60] },
+    "long": { "scenes": [4, 10], "totalSec": [30, 90] }
+  }
+}

package/templates/explain/styles/calm.json

@@ -0,0 +1,6 @@
+{
+  "id": "calm",
+  "theme": "calm-light",
+  "frame": { "width": 1920, "height": 1080, "fps": 30 },
+  "direction": { "shot": "medium", "move": "push-in", "ease": "out", "transition": "crossfade" }
+}

package/templates/explain/styles/crisp.json

@@ -0,0 +1,6 @@
+{
+  "id": "crisp",
+  "theme": "tech-dark",
+  "frame": { "width": 1920, "height": 1080, "fps": 30 },
+  "direction": { "shot": "close", "move": "static", "ease": "spring-snappy", "transition": "cut" }
+}

package/templates/explain/template.json

@@ -0,0 +1,64 @@
+{
+  "templateVersion": 1,
+  "id": "explain",
+  "version": "2.1.0",
+  "title": "Explainer",
+  "summary": "Concepts, architectures, how-tos and stakeholder overviews. 16:9, calm, diagram-led.",
+  "domains": ["tech", "architecture", "tutorial", "internal-comms"],
+  "discover": {
+    "useCases": [
+      "Explain a concept or technology to people outside the team.",
+      "Show how the components of a system connect.",
+      "Teach a short how-to in numbered steps.",
+      "Give leadership a one-minute overview of a system or programme."
+    ],
+    "audience": ["engineers", "stakeholders", "new-hires", "customers", "students"],
+    "goodFor": "One concept, system or process with 3-5 points and one diagram.",
+    "notFor": "Heavy numeric analysis (datastory), persuasion (pitch).",
+    "tags": [
+      "explain",
+      "concept",
+      "architecture",
+      "howto",
+      "tutorial",
+      "onboarding",
+      "diagram",
+      "internal"
+    ],
+    "tone": ["calm", "technical"],
+    "aspects": ["16:9"]
+  },
+  "requires": {
+    "storyboard": 1,
+    "scenes": [
+      "title",
+      "bullets",
+      "flow",
+      "stat",
+      "outro",
+      "callout",
+      "steps",
+      "icon-grid",
+      "kpi-grid"
+    ]
+  },
+  "themes": [
+    { "id": "calm-light", "file": "@shared/calm-light.json", "mode": "light", "pair": "calm-dark" },
+    { "id": "calm-dark", "file": "@shared/calm-dark.json", "mode": "dark", "pair": "calm-light" },
+    { "id": "tech-light", "file": "@shared/tech-light.json", "mode": "light", "pair": "tech-dark" },
+    { "id": "tech-dark", "file": "@shared/tech-dark.json", "mode": "dark", "pair": "tech-light" }
+  ],
+  "styles": [
+    { "id": "calm", "file": "styles/calm.json" },
+    { "id": "crisp", "file": "styles/crisp.json" }
+  ],
+  "blueprints": [
+    { "id": "concept", "file": "blueprints/concept.json" },
+    { "id": "architecture", "file": "blueprints/architecture.json" },
+    { "id": "howto", "file": "blueprints/howto.json" },
+    { "id": "overview", "file": "blueprints/overview.json" }
+  ],
+  "pacing": "pacing.json",
+  "copy": "copy.md",
+  "license": "Apache-2.0"
+}

package/templates/guide/blueprints/lesson.json

@@ -0,0 +1,173 @@
+{
+  "id": "lesson",
+  "purpose": "Teach one idea: objectives, a bold definition or rule, an optional code example, and a checked recap.",
+  "discover": {
+    "useCases": [
+      "Teach a lesson in four beats: objectives, concept, example and recap.",
+      "Make one definition, rule or formula memorable with a short worked example.",
+      "Close a course unit with a checklist of what learners can now do."
+    ],
+    "audience": ["learners", "students", "developers", "new-hires"],
+    "goodFor": "One concept with 2-4 objectives, a one-line definition and a recap.",
+    "notFor": "Ordered procedures (tutorial), product tours (onboarding), data stories (datastory).",
+    "tags": ["lesson", "education", "concept", "explain", "code", "tutorial"],
+    "tone": ["calm", "friendly"],
+    "aspects": ["16:9"],
+    "lengths": {
+      "min": 35,
+      "max": 90
+    }
+  },
+  "slots": {
+    "topic": {
+      "type": "text",
+      "max": 60,
+      "required": true
+    },
+    "objectives": {
+      "type": "text[]",
+      "min": 2,
+      "max": 4,
+      "itemMax": 45,
+      "required": true
+    },
+    "concept": {
+      "type": "text",
+      "max": 110,
+      "required": true
+    },
+    "label": {
+      "type": "text",
+      "max": 30,
+      "default": "Key idea"
+    },
+    "code": {
+      "type": "text[]",
+      "min": 1,
+      "max": 14,
+      "itemMax": 60,
+      "optional": true
+    },
+    "lang": {
+      "type": "enum",
+      "values": ["js", "ts", "json", "py", "sh", "plain"],
+      "default": "js"
+    },
+    "file": {
+      "type": "text",
+      "max": 40,
+      "optional": true
+    },
+    "recap": {
+      "type": "text[]",
+      "min": 2,
+      "max": 4,
+      "itemMax": 45,
+      "required": true
+    },
+    "next": {
+      "type": "text",
+      "max": 60,
+      "default": "Next lesson: put it to work"
+    },
+    "length": {
+      "type": "enum",
+      "values": ["short", "standard", "long"],
+      "default": "standard"
+    },
+    "style": {
+      "type": "enum",
+      "values": ["calm", "techdark", "friendly"],
+      "default": "calm"
+    }
+  },
+  "example": {
+    "topic": "What is a function",
+    "objectives": ["Name the parts of a function", "Call one with inputs", "Use the result"],
+    "concept": "A [function] takes [inputs], does one job and returns an [output].",
+    "label": "Key idea",
+    "code": ["function add(a, b) {", "  return a + b", "}", "add(2, 3)  // 5"],
+    "lang": "js",
+    "file": "example.js",
+    "recap": ["A function has a name", "Inputs go in brackets", "It returns one result"],
+    "next": "Next lesson: put it to work"
+  },
+  "meta": {
+    "title": {
+      "$slot": "topic"
+    },
+    "lang": "en"
+  },
+  "scenes": [
+    {
+      "id": "intro",
+      "type": "title",
+      "props": {
+        "kicker": "Lesson",
+        "title": {
+          "$slot": "topic"
+        }
+      }
+    },
+    {
+      "id": "goals",
+      "type": "bullets",
+      "props": {
+        "title": "You will learn to",
+        "items": {
+          "$slot": "objectives"
+        },
+        "marker": "dot"
+      }
+    },
+    {
+      "id": "idea",
+      "type": "callout",
+      "props": {
+        "text": {
+          "$slot": "concept"
+        },
+        "kind": "definition",
+        "label": {
+          "$slot": "label"
+        }
+      }
+    },
+    {
+      "when": "code",
+      "id": "example",
+      "type": "code",
+      "props": {
+        "lines": {
+          "$slot": "code"
+        },
+        "lang": {
+          "$slot": "lang"
+        },
+        "file": {
+          "$slot": "file"
+        }
+      }
+    },
+    {
+      "id": "recap",
+      "type": "bullets",
+      "props": {
+        "title": "Recap",
+        "items": {
+          "$slot": "recap"
+        },
+        "marker": "check"
+      }
+    },
+    {
+      "id": "end",
+      "type": "outro",
+      "props": {
+        "title": {
+          "$slot": "next"
+        }
+      }
+    }
+  ]
+}