diff --git a/public/css/sub-pages.css b/public/css/sub-pages.css
index 2cfcaf6cd..4d843b1bf 100644
--- a/public/css/sub-pages.css
+++ b/public/css/sub-pages.css
@@ -1042,7 +1042,9 @@ main#main {
   display: flex;
   align-items: center;
   justify-content: center;
-  padding: var(--spacing-md);
+  /* No padding: demos that fill the container (overdrive) need full
+     bleed, and demos with smaller content (polish, bolder) already
+     center themselves via flex. */
 }
 
 .split-after {
@@ -1107,10 +1109,41 @@ main#main {
    SKILL DETAIL
    ============================================ */
 
-.skill-detail-header {
+/* Editorial hero: on wide viewports, text header on the left and the
+   before/after demo floats to the right as a hero module. On narrow
+   viewports everything stacks. */
+.skill-detail-hero {
   margin-bottom: clamp(2.5rem, 5vw, 3.5rem);
 }
 
+@media (min-width: 1100px) {
+  .skill-detail-hero--has-demo {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: clamp(var(--spacing-lg), 4vw, var(--spacing-2xl));
+    align-items: start;
+  }
+
+  .skill-detail-hero--has-demo .skill-detail-header {
+    margin-bottom: 0;
+    align-self: center;
+  }
+
+  .skill-detail-hero--has-demo .skill-demo {
+    /* 500px visible container + 64px padding buffer stays 564px total.
+       Keep the eyebrow and labels vertically centered with the title.
+       Cancel the narrow-viewport stacking margin. */
+    align-self: center;
+    margin-top: 0;
+  }
+}
+
+/* Stacked spacing between header and demo on narrow viewports; overridden
+   by the grid gap when the hero switches to two columns at >=1100px. */
+.skill-detail-hero--has-demo .skill-demo {
+  margin-top: clamp(2rem, 4vw, 2.5rem);
+}
+
 .skill-detail-eyebrow {
   font-family: var(--font-mono);
   font-size: 0.75rem;
diff --git a/scripts/build-sub-pages.js b/scripts/build-sub-pages.js
index 3b5c8d192..fa1f724f9 100644
--- a/scripts/build-sub-pages.js
+++ b/scripts/build-sub-pages.js
@@ -114,16 +114,19 @@ ${refBody}
   ${skill.argumentHint ? `<span class="skill-meta-chip skill-meta-args">${escapeHtml(skill.argumentHint)}</span>` : ''}
 </div>`;
 
+  const hasDemo = demoHtml.trim().length > 0;
+
   return `
 <article class="skill-detail">
-  <header class="skill-detail-header">
-    <p class="skill-detail-eyebrow"><a href="/skills">Skills</a> / ${escapeHtml(categoryLabel)}</p>
-    <h1 class="skill-detail-title"><span class="skill-detail-title-slash">/</span>${escapeHtml(skill.id)}</h1>
-    <p class="skill-detail-tagline">${escapeHtml(tagline)}</p>
-    ${metaStrip}
-  </header>
-
-  ${demoHtml}
+  <div class="skill-detail-hero${hasDemo ? ' skill-detail-hero--has-demo' : ''}">
+    <header class="skill-detail-header">
+      <p class="skill-detail-eyebrow"><a href="/skills">Skills</a> / ${escapeHtml(categoryLabel)}</p>
+      <h1 class="skill-detail-title"><span class="skill-detail-title-slash">/</span>${escapeHtml(skill.id)}</h1>
+      <p class="skill-detail-tagline">${escapeHtml(tagline)}</p>
+      ${metaStrip}
+    </header>
+    ${demoHtml}
+  </div>
 
   ${editorialHtml ? `<section class="skill-detail-editorial prose">\n${editorialHtml}\n</section>` : ''}