diff --git a/test/e2e/regression/dialog.spec.mjs b/test/e2e/regression/dialog.spec.mjs
new file mode 100644
index 0000000..017c1dc
--- /dev/null
+++ b/test/e2e/regression/dialog.spec.mjs
@@ -0,0 +1,35 @@
+/**
+ * Functional regression template — dialog open/close behavior.
+ *
+ * This is NOT an axe test. It demonstrates the harness for behavioral tests.
+ * Copy this file to add more regression specs; replace selectors and assertions.
+ *
+ * Pattern notes:
+ *  - Use web-first assertions (toBeVisible/toBeHidden) — never fixed timeouts.
+ *  - Scope to [data-shadix-preview] to avoid touching unrelated page chrome.
+ *  - Use .first() when a selector can match multiple elements (Playwright strict mode).
+ *  - The LiveView JS bundle must be built (`mix assets.build`) for JS commands to fire.
+ */
+import { test, expect } from "@playwright/test";
+
+test("dialog: opens on trigger click and closes on Escape", async ({ page }) => {
+  await page.goto("/components/dialog");
+
+  // Wait for the LiveView preview region to mount before interacting.
+  const preview = page.locator("[data-shadix-preview]").first();
+  await preview.waitFor();
+
+  // The dialog content starts with `class="hidden"` (set by JS.hide); it carries
+  // role="dialog" and data-slot="dialog-content".
+  const dialog = preview.locator("[data-slot='dialog-content']").first();
+  await expect(dialog).toBeHidden();
+
+  // The trigger is a <span class="contents"> wrapping the demo button, wired to
+  // show_dialog via phx-click. Click the first button in the preview to open it.
+  await preview.getByRole("button").first().click();
+  await expect(dialog).toBeVisible();
+
+  // Escape closes via phx-window-keydown on the dialog-content element.
+  await page.keyboard.press("Escape");
+  await expect(dialog).toBeHidden();
+});