diff --git a/site/content/docs/components/buttons.md b/site/content/docs/components/buttons.md
index 811328b..e60921b 100644
--- a/site/content/docs/components/buttons.md
+++ b/site/content/docs/components/buttons.md
@@ -14,7 +14,7 @@ ai-provider: "Anthropic"
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px;display:flex;gap:0.75rem;flex-wrap:wrap;align-items:center">
+<div data-demo>
   <button>Primary</button>
   <button data-variant="secondary">Secondary</button>
   <button data-variant="danger">Danger</button>
diff --git a/site/content/docs/components/callouts.md b/site/content/docs/components/callouts.md
index de32e6e..2efc5cb 100644
--- a/site/content/docs/components/callouts.md
+++ b/site/content/docs/components/callouts.md
@@ -14,7 +14,7 @@ Add `data-callout="<type>"` to any block element to style it as a callout. Four
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px;display:flex;flex-direction:column;gap:1rem">
+<div data-demo>
   <div data-callout="note"><strong>Note</strong> — General information worth highlighting.</div>
   <div data-callout="tip"><strong>Tip</strong> — A helpful suggestion or best practice.</div>
   <div data-callout="warning"><strong>Warning</strong> — Something to watch out for.</div>
diff --git a/site/content/docs/components/dialog.md b/site/content/docs/components/dialog.md
index 1b2adc0..4c5ae7c 100644
--- a/site/content/docs/components/dialog.md
+++ b/site/content/docs/components/dialog.md
@@ -14,7 +14,7 @@ ASW styles the native `<dialog>` element — no JavaScript modal libraries requi
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
+<div data-demo>
   <button onclick="document.getElementById('demo-dialog').showModal()">Open dialog</button>
   <dialog id="demo-dialog">
     <article>
diff --git a/site/content/docs/components/forms.md b/site/content/docs/components/forms.md
index 2f3aac1..6801943 100644
--- a/site/content/docs/components/forms.md
+++ b/site/content/docs/components/forms.md
@@ -14,8 +14,8 @@ All standard form elements are styled out of the box. Labels, inputs, selects, a
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
-  <form style="display:flex;flex-direction:column;gap:1rem;max-width:28rem" onsubmit="return false">
+<div data-demo>
+  <form onsubmit="return false">
     <label>
       Name
       <input type="text" placeholder="Jane Smith">
diff --git a/site/content/docs/content/blockquotes.md b/site/content/docs/content/blockquotes.md
index d6f2fb4..266b97b 100644
--- a/site/content/docs/content/blockquotes.md
+++ b/site/content/docs/content/blockquotes.md
@@ -14,7 +14,7 @@ ai-provider: "Anthropic"
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
+<div data-demo>
   <blockquote>
     <p>Simplicity is the ultimate sophistication.</p>
     <footer>— Leonardo da Vinci</footer>
diff --git a/site/content/docs/content/figures.md b/site/content/docs/content/figures.md
index 114284a..253a486 100644
--- a/site/content/docs/content/figures.md
+++ b/site/content/docs/content/figures.md
@@ -14,9 +14,9 @@ ai-provider: "Anthropic"
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
+<div data-demo>
   <figure>
-    <div style="background:var(--surface-2,#f0f0f0);height:120px;display:flex;align-items:center;justify-content:center;border-radius:4px">
+    <div data-text="dim">
       <span data-text="dim">[ image placeholder ]</span>
     </div>
     <figcaption>Figure 1 — ASW renders figcaption below the content with muted styling.</figcaption>
diff --git a/site/content/docs/content/tables.md b/site/content/docs/content/tables.md
index d168e2a..8b1bf56 100644
--- a/site/content/docs/content/tables.md
+++ b/site/content/docs/content/tables.md
@@ -14,7 +14,7 @@ ai-provider: "Anthropic"
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px;overflow-x:auto">
+<div data-demo>
   <table>
     <thead>
       <tr><th>Element</th><th>Role</th><th>Class needed?</th></tr>
diff --git a/site/content/docs/getting-started/getting-started.md b/site/content/docs/getting-started/getting-started.md
index caf80a3..6cd21d8 100644
--- a/site/content/docs/getting-started/getting-started.md
+++ b/site/content/docs/getting-started/getting-started.md
@@ -14,8 +14,8 @@ Drop `asw.css` into your project, add one `<link>` tag, and write semantic HTML.
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
-  <nav style="margin-bottom:1rem">
+<div data-demo>
+  <nav>
     <a href="#">Home</a> ·
     <a href="#">Docs</a> ·
     <a href="#">About</a>
diff --git a/site/content/docs/reference/utilities.md b/site/content/docs/reference/utilities.md
index 06bd0d7..9701cbf 100644
--- a/site/content/docs/reference/utilities.md
+++ b/site/content/docs/reference/utilities.md
@@ -14,7 +14,7 @@ ASW provides a small set of utility attributes for inline adjustments. Rather th
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px;display:flex;flex-direction:column;gap:0.5rem">
+<div data-demo>
   <p><span data-text="mono">data-text="mono"</span> — monospace font</p>
   <p><span data-text="dim">data-text="dim"</span> — reduced opacity / muted</p>
   <p><span data-text="accent">data-text="accent"</span> — accent colour</p>
diff --git a/site/content/docs/reference/vocabulary.md b/site/content/docs/reference/vocabulary.md
index 7b29d17..7648ffb 100644
--- a/site/content/docs/reference/vocabulary.md
+++ b/site/content/docs/reference/vocabulary.md
@@ -14,7 +14,7 @@ Every `data-*` attribute that ASW recognises is listed here. This is the authori
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px;overflow-x:auto">
+<div data-demo>
   <table>
     <thead>
       <tr><th>Attribute</th><th>Values</th><th>Effect</th></tr>
diff --git a/site/content/docs/typography/code.md b/site/content/docs/typography/code.md
index c29a2eb..2e1af1f 100644
--- a/site/content/docs/typography/code.md
+++ b/site/content/docs/typography/code.md
@@ -14,7 +14,7 @@ Inline `<code>` uses a monospace font with a subtle background tint. Block-level
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
+<div data-demo>
   <p>Use <code>data-callout="tip"</code> to style a callout block, or <code>data-layout="docs"</code> for a sidebar layout.</p>
   <pre><code>/* Minimal ASW page */
 &lt;!doctype html&gt;
diff --git a/site/content/docs/typography/headings.md b/site/content/docs/typography/headings.md
index e95a82e..88654c6 100644
--- a/site/content/docs/typography/headings.md
+++ b/site/content/docs/typography/headings.md
@@ -14,7 +14,7 @@ Headings `h1` through `h6` are sized using a fluid scale derived from the token
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
+<div data-demo>
   <h1>Heading level 1</h1>
   <h2>Heading level 2</h2>
   <h3>Heading level 3</h3>
diff --git a/site/content/docs/typography/prose.md b/site/content/docs/typography/prose.md
index b316fb6..01b6904 100644
--- a/site/content/docs/typography/prose.md
+++ b/site/content/docs/typography/prose.md
@@ -14,7 +14,7 @@ ASW sets comfortable line-height, paragraph spacing, and list markers on prose e
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
+<div data-demo>
   <p>This is a body paragraph. ASW uses a fluid font size and generous line-height so long-form text remains comfortable to read on any screen width.</p>
   <ul>
     <li>First item in an unordered list</li>
diff --git a/site/content/docs/vault/status.md b/site/content/docs/vault/status.md
index d233e5f..45450fc 100644
--- a/site/content/docs/vault/status.md
+++ b/site/content/docs/vault/status.md
@@ -14,7 +14,7 @@ ai-provider: "Anthropic"
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px;display:flex;flex-direction:column;gap:0.5rem">
+<div data-demo>
   <p><span data-status="active">active</span> — currently running or in use</p>
   <p><span data-status="sleeping">sleeping</span> — paused or idle</p>
   <p><span data-status="blocked">blocked</span> — waiting on a dependency</p>
diff --git a/site/content/docs/vault/tasks.md b/site/content/docs/vault/tasks.md
index b48e184..32fcafd 100644
--- a/site/content/docs/vault/tasks.md
+++ b/site/content/docs/vault/tasks.md
@@ -14,8 +14,8 @@ Add `data-task="<state>"` to a `<li>` element to render it as a task item with a
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
-  <ul style="list-style:none;padding-left:0">
+<div data-demo>
+  <ul>
     <li data-task="done">Write the ASW reset layer</li>
     <li data-task="done">Publish initial token system</li>
     <li data-task="wip">Document all data-* attributes</li>
diff --git a/site/content/docs/vault/wikilinks.md b/site/content/docs/vault/wikilinks.md
index a21d125..d2017f6 100644
--- a/site/content/docs/vault/wikilinks.md
+++ b/site/content/docs/vault/wikilinks.md
@@ -14,7 +14,7 @@ ai-provider: "Anthropic"
 
 ## Inline Demo
 
-<div style="border:1px solid var(--border,#ccc);padding:1.5rem;border-radius:4px">
+<div data-demo>
   <p>
     See the <a href="#" data-wikilink>Getting Started</a> page, or cross-reference
     <a href="#" data-wikilink>Core Concepts</a> and <a href="#" data-wikilink>Token System</a>.
diff --git a/src/layers/07-data-attrs.css b/src/layers/07-data-attrs.css
index 8b5897c..38327b5 100644
--- a/src/layers/07-data-attrs.css
+++ b/src/layers/07-data-attrs.css
@@ -678,4 +678,16 @@ a[data-role="secondary"]:hover {
   gap: var(--space-5);
 }
 
+/* ── Demo block ────────────────────────────────────────────────────── */
+/* Inline demonstration area within docs pages.
+   Usage: <div data-demo>…live HTML example…</div> */
+
+[data-demo] {
+  border: var(--border-width) solid var(--border);
+  border-radius: var(--radius-md);
+  padding: var(--space-5);
+  background: var(--surface-1);
+  margin-block: var(--space-4);
+}
+
 } /* end @layer data-attrs */