diff --git a/docs/public/videos/README.md b/docs/public/videos/README.md
new file mode 100644
index 0000000000..2eb1af5d33
--- /dev/null
+++ b/docs/public/videos/README.md
@@ -0,0 +1,47 @@
+# Videos Directory
+
+This directory contains video files used in the documentation.
+
+## Usage
+
+Place video files here and reference them in documentation using the Video component:
+
+```mdx
+import Video from '@components/Video.astro';
+
+<Video src="/gh-aw/videos/your-video.mp4" caption="Video Title" />
+```
+
+## Supported Formats
+
+- MP4 (`.mp4`) - **Recommended** for best browser compatibility
+- WebM (`.webm`) - Modern, open format
+- OGG (`.ogg`) - Open format, older browsers
+- MOV (`.mov`) - QuickTime format
+- AVI (`.avi`) - Legacy format
+- MKV (`.mkv`) - Matroska format
+
+## Best Practices
+
+- Keep file sizes reasonable for web delivery (< 50MB recommended)
+- Use MP4 with H.264 codec for widest browser support
+- Provide meaningful filenames (e.g., `workflow-demo.mp4`)
+- Consider adding poster images (thumbnails) for better UX
+- Compress videos appropriately for web use
+
+## Example
+
+To add a new video to the documentation:
+
+1. Place the video file in this directory: `docs/public/videos/demo.mp4`
+2. Reference it in your MDX file:
+
+```mdx
+import Video from '@components/Video.astro';
+
+<Video 
+  src="/gh-aw/videos/demo.mp4" 
+  caption="Workflow Demo"
+  thumbnail="/gh-aw/images/demo-thumbnail.png"
+/>
+```
diff --git a/docs/src/components/Video.astro b/docs/src/components/Video.astro
new file mode 100644
index 0000000000..ebe09e515f
--- /dev/null
+++ b/docs/src/components/Video.astro
@@ -0,0 +1,72 @@
+---
+interface Props {
+    src: string
+    caption?: string
+    aspectRatio?: '16:9' | '4:3' | '1:1' | 'auto'
+    showControls?: boolean
+    autoStart?: boolean
+    repeat?: boolean
+    silenced?: boolean
+    thumbnail?: string
+    maxWidth?: string
+}
+
+const { 
+    src, 
+    caption, 
+    aspectRatio = 'auto',
+    showControls = true,
+    autoStart = false,
+    repeat = false,
+    silenced = false,
+    thumbnail,
+    maxWidth = '100%'
+} = Astro.props
+
+// Extract file extension and determine content type
+const fileExtension = src.split('.').pop()?.toLowerCase() || ''
+const videoFormats: Record<string, string> = {
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    ogg: 'video/ogg',
+    ogv: 'video/ogg',
+    mov: 'video/quicktime',
+    avi: 'video/x-msvideo',
+    mkv: 'video/x-matroska',
+    m4v: 'video/x-m4v'
+}
+const contentType = videoFormats[fileExtension] || 'video/mp4'
+
+// Calculate aspect ratio padding
+const ratioMap: Record<string, string> = {
+    '16:9': '56.25%',
+    '4:3': '75%',
+    '1:1': '100%',
+    'auto': '0'
+}
+const paddingBottom = ratioMap[aspectRatio]
+---
+
+<div class="gh-aw-video-wrapper" style={`max-width: ${maxWidth};`}>
+    <div class={`gh-aw-video-container ${aspectRatio !== 'auto' ? 'has-aspect-ratio' : ''}`} 
+         style={aspectRatio !== 'auto' ? `padding-bottom: ${paddingBottom};` : ''}>
+        <video 
+            class="gh-aw-video-element"
+            controls={showControls}
+            autoplay={autoStart}
+            loop={repeat}
+            muted={silenced}
+            poster={thumbnail}
+            preload="metadata"
+            aria-label={caption}
+        >
+            <source src={src} type={contentType} />
+            <p>Your browser doesn't support HTML5 video. Download the video <a href={src}>here</a>.</p>
+        </video>
+    </div>
+    {caption && (
+        <div class="gh-aw-video-caption" role="note">
+            {caption}
+        </div>
+    )}
+</div>
diff --git a/docs/src/styles/custom.css b/docs/src/styles/custom.css
index f21ec851db..52621fcaaa 100644
--- a/docs/src/styles/custom.css
+++ b/docs/src/styles/custom.css
@@ -1622,3 +1622,90 @@ main,
     justify-content: center !important;
   }
 }
+
+/* Video Component Styles */
+.gh-aw-video-wrapper {
+    margin: 2rem auto;
+    width: 100%;
+}
+
+.gh-aw-video-container {
+    position: relative;
+    width: 100%;
+    background: linear-gradient(135deg, #1a1a1a 0%, #0d0d0d 100%);
+    border-radius: 12px;
+    overflow: hidden;
+    box-shadow: 
+        0 8px 16px rgba(0, 0, 0, 0.4),
+        0 0 0 1px rgba(255, 255, 255, 0.05);
+    transition: box-shadow 0.3s ease;
+}
+
+.gh-aw-video-container:hover {
+    box-shadow: 
+        0 12px 24px rgba(0, 0, 0, 0.5),
+        0 0 0 1px rgba(139, 92, 246, 0.3);
+}
+
+.gh-aw-video-container.has-aspect-ratio {
+    height: 0;
+    padding-bottom: 56.25%;
+}
+
+.gh-aw-video-element {
+    width: 100%;
+    height: 100%;
+    display: block;
+    background-color: #000;
+}
+
+.has-aspect-ratio .gh-aw-video-element {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+}
+
+.gh-aw-video-caption {
+    margin-top: 0.75rem;
+    padding: 0.5rem 1rem;
+    font-size: 0.9rem;
+    color: var(--sl-color-gray-3);
+    text-align: center;
+    background: var(--sl-color-gray-6);
+    border-left: 3px solid var(--sl-color-purple);
+    border-radius: 0 6px 6px 0;
+    font-style: italic;
+}
+
+[data-theme='light'] .gh-aw-video-container {
+    background: linear-gradient(135deg, #f5f5f5 0%, #e8e8e8 100%);
+    box-shadow: 
+        0 8px 16px rgba(0, 0, 0, 0.15),
+        0 0 0 1px rgba(0, 0, 0, 0.08);
+}
+
+[data-theme='light'] .gh-aw-video-container:hover {
+    box-shadow: 
+        0 12px 24px rgba(0, 0, 0, 0.2),
+        0 0 0 1px rgba(102, 57, 186, 0.3);
+}
+
+[data-theme='light'] .gh-aw-video-caption {
+    color: var(--sl-color-gray-2);
+    background: var(--sl-color-gray-7);
+}
+
+@media (max-width: 768px) {
+    .gh-aw-video-wrapper {
+        margin: 1.5rem auto;
+    }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .gh-aw-video-container {
+        transition: none;
+    }
+}