From 7c4d3358531c4248a0f22d8855e3b4c32ea1a88c Mon Sep 17 00:00:00 2001
From: Ali Hamza <ali.hamzaaa6296@gmail.com>
Date: Mon, 20 Apr 2026 15:10:03 +0500
Subject: [PATCH 1/2] feat: add design system , theme.json, reusable
 components, docs

Adds theme.json global tokens, reusable LowerThird and Outro components,
and documentation for style inheritance. Addresses issue #340.
---
 docs/design-system.md                | 29 ++++++++++++++++++
 templates/components/LowerThird.html | 44 ++++++++++++++++++++++++++++
 templates/components/Outro.html      | 30 +++++++++++++++++++
 templates/theme.json                 | 37 +++++++++++++++++++++++
 4 files changed, 140 insertions(+)
 create mode 100644 docs/design-system.md
 create mode 100644 templates/components/LowerThird.html
 create mode 100644 templates/components/Outro.html
 create mode 100644 templates/theme.json

diff --git a/docs/design-system.md b/docs/design-system.md
new file mode 100644
index 000000000..af4c1f9dd
--- /dev/null
+++ b/docs/design-system.md
@@ -0,0 +1,29 @@
+# Design System & Reusable Components
+
+Hyperframes supports a global design system via `theme.json` and reusable HTML components.
+
+## 1. Global Theme (`templates/theme.json`)
+
+Define your brand's colors, typography, and spacing once:
+
+```json
+{
+  "colors": { "accent": "#FF5733" },
+  "typography": { "heading": { "fontSize": "72px" } }
+}
+```
+
+All CSS variables are auto-injected at render time with the prefix `--hf-*`:
+- `--hf-color-accent`
+- `--hf-font-family`
+- `--hf-heading-size`
+- `--hf-spacing-margin`
+
+## 2. Reusable Components (`templates/components/`)
+
+Pre-built components live in `templates/components/`. Copy any into your composition:
+
+- `LowerThird.html` — name + title overlay
+- `Outro.html` — branded end card
+
+## 3. Style Inheritance Order
\ No newline at end of file
diff --git a/templates/components/LowerThird.html b/templates/components/LowerThird.html
new file mode 100644
index 000000000..ccb226ce5
--- /dev/null
+++ b/templates/components/LowerThird.html
@@ -0,0 +1,44 @@
+<!--
+  @component LowerThird
+  @props title, subtitle
+  @description Reusable lower-third name/title overlay.
+  Inherits colors and typography from theme.json.
+  Usage: copy this block into your composition and fill in data-title / data-subtitle.
+-->
+<div
+  id="lower-third"
+  class="clip"
+  data-start="2"
+  data-duration="4"
+  data-track-index="3"
+  data-title="Your Name"
+  data-subtitle="Your Title"
+  style="
+    position: absolute;
+    bottom: var(--hf-spacing-margin, 48px);
+    left: var(--hf-spacing-margin, 48px);
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  "
+>
+  <span
+    style="
+      font-family: var(--hf-font-family, &quot;Inter, sans-serif&quot;);
+      font-size: var(--hf-heading-size, 48px);
+      font-weight: 700;
+      color: var(--hf-color-primary, #ffffff);
+    "
+    data-bind="title"
+  ></span>
+
+  <span
+    style="
+      font-family: var(--hf-font-family, &quot;Inter, sans-serif&quot;);
+      font-size: var(--hf-body-size, 28px);
+      font-weight: 400;
+      color: var(--hf-color-accent, #ff5733);
+    "
+    data-bind="subtitle"
+  ></span>
+</div>
diff --git a/templates/components/Outro.html b/templates/components/Outro.html
new file mode 100644
index 000000000..9b488de62
--- /dev/null
+++ b/templates/components/Outro.html
@@ -0,0 +1,30 @@
+<!--
+  @component Outro
+  @description Reusable branded end card. Inherits from theme.json.
+-->
+<div
+  id="outro"
+  class="clip"
+  data-start="0"
+  data-duration="5"
+  data-track-index="0"
+  style="
+    width: 100%;
+    height: 100%;
+    background: var(--hf-color-background, #0f0f0f);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  "
+>
+  <h1
+    style="
+      font-family: var(--hf-font-family, &quot;Inter, sans-serif&quot;);
+      font-size: var(--hf-heading-size, 72px);
+      font-weight: 700;
+      color: var(--hf-color-primary, #ffffff);
+    "
+  >
+    Thanks for watching.
+  </h1>
+</div>
diff --git a/templates/theme.json b/templates/theme.json
new file mode 100644
index 000000000..d51ee95ec
--- /dev/null
+++ b/templates/theme.json
@@ -0,0 +1,37 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schemas/theme.json",
+  "name": "default",
+  "version": "1.0.0",
+  "colors": {
+    "background": "#0F0F0F",
+    "primary": "#FFFFFF",
+    "accent": "#FF5733",
+    "muted": "#888888"
+  },
+  "typography": {
+    "fontFamily": "Inter, sans-serif",
+    "heading": {
+      "fontSize": "72px",
+      "fontWeight": "700",
+      "lineHeight": "1.1"
+    },
+    "body": {
+      "fontSize": "32px",
+      "fontWeight": "400",
+      "lineHeight": "1.5"
+    },
+    "caption": {
+      "fontSize": "24px",
+      "fontWeight": "400"
+    }
+  },
+  "spacing": {
+    "margin": "48px",
+    "gap": "24px",
+    "padding": "32px"
+  },
+  "composition": {
+    "width": 1920,
+    "height": 1080
+  }
+}

From ed10031a99ed2b7d6c3045dd9cb118424735fda8 Mon Sep 17 00:00:00 2001
From: Ali Hamza <ali.hamzaaa6296@gmail.com>
Date: Tue, 21 Apr 2026 12:42:15 +0500
Subject: [PATCH 2/2] fix: correct font-family fallback syntax and remove
 unimplemented data-bind

---
 templates/components/LowerThird.html | 12 ++++++------
 templates/components/Outro.html      |  2 +-
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/templates/components/LowerThird.html b/templates/components/LowerThird.html
index ccb226ce5..22f9c5e37 100644
--- a/templates/components/LowerThird.html
+++ b/templates/components/LowerThird.html
@@ -11,8 +11,6 @@
   data-start="2"
   data-duration="4"
   data-track-index="3"
-  data-title="Your Name"
-  data-subtitle="Your Title"
   style="
     position: absolute;
     bottom: var(--hf-spacing-margin, 48px);
@@ -24,21 +22,23 @@
 >
   <span
     style="
-      font-family: var(--hf-font-family, &quot;Inter, sans-serif&quot;);
+      font-family: var(--hf-font-family, &quot;Inter&quot;), sans-serif;
       font-size: var(--hf-heading-size, 48px);
       font-weight: 700;
       color: var(--hf-color-primary, #ffffff);
     "
     data-bind="title"
-  ></span>
+    >Your Name</span
+  >
 
   <span
     style="
-      font-family: var(--hf-font-family, &quot;Inter, sans-serif&quot;);
+      font-family: var(--hf-font-family, &quot;Inter&quot;), sans-serif;
       font-size: var(--hf-body-size, 28px);
       font-weight: 400;
       color: var(--hf-color-accent, #ff5733);
     "
     data-bind="subtitle"
-  ></span>
+    >Your Title</span
+  >
 </div>
diff --git a/templates/components/Outro.html b/templates/components/Outro.html
index 9b488de62..4027a4158 100644
--- a/templates/components/Outro.html
+++ b/templates/components/Outro.html
@@ -19,7 +19,7 @@
 >
   <h1
     style="
-      font-family: var(--hf-font-family, &quot;Inter, sans-serif&quot;);
+      font-family: var(--hf-font-family, &quot;Inter&quot;), sans-serif;
       font-size: var(--hf-heading-size, 72px);
       font-weight: 700;
       color: var(--hf-color-primary, #ffffff);