From 4bda5b4397471bf60d733bd710426ded061e5f43 Mon Sep 17 00:00:00 2001
From: Francis Secada <francis.secada@gmail.com>
Date: Wed, 29 Jul 2026 12:25:47 -0400
Subject: [PATCH 1/3] fix(a11y): dialog semantics, focus management,
 server-rendered tab state (#21)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three gaps that predate 0.1.0, flagged in the #6 review and deferred so a
theme PR would not widen into an accessibility PR. Fixed against both shipped
themes now, because every pattern here is one the three themes in the
expansion epic will copy — landing it after would mean writing it five times
instead of two.

Modal: role="dialog" + aria-modal, named by its header via aria-labelledby or
by a new `label` prop when there is none, focus moved in on open, restored to
the trigger on close, trapped while open, Escape to close. It stays a <div>;
showModal() would give all of this for free but would make cfModal branch per
theme, and the identical cross-theme Alpine contract is what the theme work
protects. The whole implementation is in cf_ui_alpine.js, so a new theme
inherits it by writing markup. Recorded in docs/accessibility.md.

Tabs: `active` is now a prop, server-rendering the theme's active class plus
aria-selected, aria-controls and a roving tabindex. The Alpine binding stays
on top — server state is the initial value, not a replacement. Arrow/Home/End
move focus, Enter/Space activates; automatic activation would fire an HTMX
request on every arrow press.

Panel: `open` was declared but never rendered, so an open panel still emitted
x-cloak and stayed hidden without JS. Now server-rendered, with initPanel()
seeding Alpine from it, and a real <button type="button"> carrying
aria-controls and aria-expanded. Takes a new `id` prop for the aria-controls
target.

Server state crosses into Alpine through data- attributes read in x-init,
never an interpolated x-data="cfTabs('{{ active }}')" — the value is
request-controlled and a template engine cannot escape JavaScript source.

Tests split along the line #21 draws: markup claims (roles, aria values,
server-rendered classes) in tests/unit/test_accessibility.py across all four
template sets; behavioral claims (where focus lands, that Tab cannot leave)
in E2E over js_on/js_off. The old `expect(first_tab).to_be_attached()` js_off
assertion is replaced with "exactly one tab carries the active class".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NhqNRBg83czKfr8L6FF5xf
---
 CHANGELOG.md                                  |  49 ++
 README.md                                     |  13 +-
 docs/accessibility.md                         | 154 +++++++
 src/cf_ui/static/cf_ui/cf_ui_alpine.js        | 170 ++++++-
 .../templates/cotton/_themes/bulma/modal.html |   7 +-
 .../templates/cotton/_themes/bulma/panel.html |  17 +-
 .../templates/cotton/_themes/bulma/tabs.html  |  22 +-
 .../templates/cotton/_themes/daisy/modal.html |   8 +-
 .../templates/cotton/_themes/daisy/panel.html |  12 +-
 .../templates/cotton/_themes/daisy/tabs.html  |  17 +-
 src/cf_ui/templates/cotton/cf/modal.html      |   2 +-
 src/cf_ui/templates/cotton/cf/panel.html      |   2 +-
 src/cf_ui/templates/cotton/cf/tabs.html       |   2 +-
 src/cf_ui/templates/jinja/bulma/Modal.jinja   |  10 +-
 src/cf_ui/templates/jinja/bulma/Panel.jinja   |  23 +-
 src/cf_ui/templates/jinja/bulma/Tabs.jinja    |  25 +-
 src/cf_ui/templates/jinja/daisy/Modal.jinja   |  11 +-
 src/cf_ui/templates/jinja/daisy/Panel.jinja   |  16 +-
 src/cf_ui/templates/jinja/daisy/Tabs.jinja    |  20 +-
 tests/e2e/test_bulma_cotton.py                |  40 ++
 tests/e2e/test_bulma_jinja.py                 | 162 +++++++
 tests/e2e/test_daisy.py                       | 143 +++++-
 .../templates/cotton_gallery/panel.html       |   3 +
 .../templates/cotton_gallery/tabs.html        |   3 +
 tests/integration/cotton_app/urls.py          |   2 +
 tests/integration/cotton_app/views.py         |  15 +
 tests/integration/jinja_app/main.py           |  31 +-
 tests/unit/test_accessibility.py              | 436 ++++++++++++++++++
 28 files changed, 1354 insertions(+), 61 deletions(-)
 create mode 100644 docs/accessibility.md
 create mode 100644 tests/integration/cotton_app/templates/cotton_gallery/panel.html
 create mode 100644 tests/integration/cotton_app/templates/cotton_gallery/tabs.html
 create mode 100644 tests/unit/test_accessibility.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9e700bd..10a806d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,55 @@
 
 ## [Unreleased]
 
+### Fixed — accessibility (#21)
+
+Three gaps that predate 0.1.0 and were flagged during the #6 review, fixed
+against both shipped themes before the theme-expansion epic copies the patterns
+into three more.
+
+- **The modal had no dialog semantics and no focus management.** It rendered a
+  plain `<div>`: a screen reader had no way to know a dialog opened, and
+  keyboard focus stayed behind it. It now carries `role="dialog"` and
+  `aria-modal="true"`, is named by its header via `aria-labelledby` (or by a new
+  `label` prop, defaulting to `"Dialog"`, when there is no header), moves focus
+  into itself on open, returns focus to whatever opened it on close, traps `Tab`
+  and `Shift+Tab` while open, and closes on `Escape`.
+
+  It stays a `<div>` rather than becoming a native `<dialog>`. `showModal()`
+  would give all of the above for free, but only where a theme's CSS is built
+  around it — it would make `cfModal` branch per theme, and the identical
+  cross-theme Alpine contract is what the theme work exists to protect. The
+  whole implementation is in `cf_ui_alpine.js`, once, so a new theme inherits it
+  by writing markup. See [`docs/accessibility.md`](docs/accessibility.md).
+
+- **Tabs showed no active tab without JavaScript.** The active marker existed
+  only as an Alpine binding, so a JS-less page rendered every tab identically —
+  navigation worked (tabs are HTMX-driven), but nothing said which one you were
+  on. `CfTabs` / `<c-cf.tabs>` now take an `active` prop and server-render the
+  active class, `aria-selected`, `aria-controls`, and a roving `tabindex` from
+  it. The Alpine binding stays on top: the server value is the initial state,
+  not a replacement. Keyboard support follows the ARIA tabs pattern with manual
+  activation — arrows move focus, `Enter`/`Space` activates — because automatic
+  activation would fire an HTMX request on every arrow press.
+
+- **`CfPanel`'s `open` prop was declared but never rendered.** An open panel
+  still emitted `x-cloak`, so with Alpine off it was hidden permanently. The
+  panel now renders its open state server-side, seeds Alpine from it rather than
+  resetting to closed, and its toggle is a real `<button type="button">` with
+  `aria-controls` and `aria-expanded`.
+
+  **New prop:** `CfPanel` takes an `id` (default `"panel"`), used for
+  `aria-controls="{id}-body"`. Two panels on one page need distinct `id`s or
+  they will emit duplicate element ids.
+
+- Tabs and Panel receive their server state through `data-` attributes read in
+  `x-init`, never through an interpolated `x-data="cfTabs('{{ active }}')"`. The
+  value is request-controlled, and a template engine escapes an attribute
+  correctly but has no idea it is writing JavaScript source.
+
+- `docs/accessibility.md` records the `<div>`-over-`<dialog>` decision and its
+  reasoning, so it is not relitigated per theme.
+
 ### Changed — BREAKING (#20)
 
 The axis layer stated four properties it did not enforce. Enforcing them is
diff --git a/README.md b/README.md
index ec73091..090a775 100644
--- a/README.md
+++ b/README.md
@@ -235,10 +235,10 @@ which is the exact failure it exists to prevent.
 `{% cf_ui_body %}` loads `cf_ui_alpine.js` (before the Alpine CDN) which registers:
 
 **Named components** — use `x-data="cfModal"` to bind from outside:
-- `cfModal` — `open`, `toggle()`, `close()`, `initModal()`
+- `cfModal` — `open`, `show()`, `toggle()`, `close()`, `initModal()`
 - `cfNavbar` — `menuOpen`, `toggle()`
-- `cfPanel` — `open`, `toggle()`
-- `cfTabs` — `active`, `setActive(id)`
+- `cfPanel` — `open`, `toggle()`, `initPanel()`
+- `cfTabs` — `active`, `setActive(id)`, `initTabs()`, `onKeydown(e)`
 
 **`$cf` global store** — cross-component messaging from any template:
 ```html
@@ -251,6 +251,13 @@ Opt out entirely:
 {% cf_ui_body alpine=False %}
 ```
 
+This file is also where the interactive components' accessibility lives — modal
+focus trapping and restoration, `Escape` to close, the tabs roving tabindex. A
+theme partial supplies classes and ARIA state; it never implements behavior, so
+a new theme inherits all of it.
+
+→ Full guide: [`docs/accessibility.md`](docs/accessibility.md)
+
 ---
 
 ## Escape Hatch
diff --git a/docs/accessibility.md b/docs/accessibility.md
new file mode 100644
index 0000000..b26ab21
--- /dev/null
+++ b/docs/accessibility.md
@@ -0,0 +1,154 @@
+# Accessibility
+
+What cf-ui guarantees about its interactive components, and — more usefully —
+*where* those guarantees live, so a new theme inherits them instead of
+reimplementing them.
+
+The rule: **behavior is in `cf_ui_alpine.js`, state is in the template.** A
+theme partial decides which classes express "selected" or "open". It never
+decides what happens when you press `Tab`.
+
+---
+
+## Modal
+
+### It is a `<div>`, on purpose
+
+DaisyUI's canonical modal is a native `<dialog>`, and `showModal()` would hand
+us focus trapping, `Escape`, the top layer, and the backdrop for free. cf-ui
+uses a `<div>` with `role="dialog"` anyway.
+
+The reason is not that `<dialog>` is worse — it is that Bulma has no `<dialog>`
+convention, and the three themes in the expansion epic will not agree either.
+Adopting it would make `cfModal` branch per theme, and the identical
+cross-theme Alpine contract is exactly what the theme work protects. One
+implementation covers every theme, present and future; that is the same trade
+the composition axes make.
+
+So everything `<dialog>` would have provided is implemented once, in
+`cf_ui_alpine.js`:
+
+| Guarantee | Where |
+|---|---|
+| `role="dialog"`, `aria-modal="true"` | theme partial (static markup) |
+| Focus moves into the dialog on open | `cfModal.$watch('open')` → `_focusFirst()` |
+| Focus returns to the trigger on close | `cfModal.close()` |
+| Focus cannot leave while open | `cfModal._trapTab()` |
+| `Escape` closes | `initModal()` keydown handler |
+
+The trigger is **captured**, not declared: `show()` records
+`document.activeElement`. Any opener works — a button, a link, a keyboard
+shortcut, `Alpine.store('cf').modal.open(id)` — and no template has to name it.
+
+### Labelling, and the `label` fallback
+
+A dialog needs an accessible name. cf-ui picks one of two, never both:
+
+* **With a header** — `aria-labelledby="{id}-title"`, pointing at the element
+  that renders the header slot.
+* **Without a header** — `aria-label="{label}"`, where `label` is a prop that
+  defaults to `"Dialog"`.
+
+An `aria-labelledby` aimed at an empty element is worse than no labelling: the
+name resolves to the empty string and the reader announces nothing. That is why
+the fallback exists and why the two are mutually exclusive.
+
+```html
+<!-- named by its header -->
+<c-cf.modal id="confirm">
+  <c-slot name="header">Delete this file?</c-slot>
+  This cannot be undone.
+</c-cf.modal>
+
+<!-- no header: name it explicitly -->
+<c-cf.modal id="prefs" label="Preferences">…</c-cf.modal>
+```
+
+```python
+catalog.render("Cf:Modal", id="prefs", label="Preferences")
+```
+
+---
+
+## Tabs
+
+`active` is a **server-rendered** prop, not just an Alpine variable. Without it
+— which is how cf-ui shipped through 0.1.x — a JS-less page rendered every tab
+identically: navigation still worked (tabs are HTMX-driven), but nothing told
+you which one you were on.
+
+```html
+<c-cf.tabs :tabs="tabs" active="overview" hx_target="tab-content" />
+```
+
+```python
+catalog.render("Cf:Tabs", tabs=tabs, active="overview", hx_target="tab-content")
+```
+
+Server-rendered from that one prop: the theme's active class, `aria-selected`,
+`aria-controls`, and the roving `tabindex`. The Alpine binding stays on top of
+all four — the server value is the *initial* state, not a replacement for
+client-side switching.
+
+### Keyboard
+
+Roving tabindex, **manual activation**: exactly one tab is in the page's tab
+order; arrows move focus between tabs; `Enter` / `Space` activates. Automatic
+activation (arrow = select) would fire an HTMX request on every arrow press.
+
+| Key | Effect |
+|---|---|
+| `←` `→` `↑` `↓` | Move focus, wrapping at both ends |
+| `Home` / `End` | First / last tab |
+| `Enter` / `Space` | Activate the focused tab |
+
+With no `active` prop, the **first** tab holds `tabindex="0"`. It has to: these
+anchors carry no `href`, so `tabindex` is the only thing making them focusable
+at all, and a widget where every tab is `-1` is unreachable by keyboard.
+
+---
+
+## Panel
+
+`open` is server-rendered too. An open panel emits no `x-cloak`, so it is
+readable with Alpine off; `initPanel()` then seeds Alpine from the same state
+rather than resetting to closed.
+
+The toggle is a real `<button type="button">` carrying `aria-controls` and a
+server-rendered `aria-expanded`, with `:aria-expanded="open"` layered on top.
+`aria-controls` points at `{id}-body` — which is why `CfPanel` takes an `id`,
+and why two panels on one page need distinct ones.
+
+A **closed** panel still cannot be opened without JS. Making that work needs
+`<details>`/`<summary>`, which is a different component shape; it is tracked
+separately rather than smuggled in here.
+
+---
+
+## Passing state into Alpine
+
+New state crosses into Alpine through `data-` attributes, read in an `x-init`
+hook — `data-cf-active` → `initTabs()`, `data-cf-open` → `initPanel()` — rather
+than through an interpolated `x-data="cfTabs('{{ active }}')"`.
+
+The value is request-controlled. A template engine escapes an *attribute*
+correctly; it has no idea it is writing JavaScript source, so a single
+apostrophe in `active` breaks out of the expression. The data-attribute route
+has no such seam.
+
+---
+
+## Testing
+
+Split deliberately, because #21 exists as a ticket largely because the earlier
+tests could not have caught what they claimed to:
+
+* `tests/unit/test_accessibility.py` — claims that *are* markup: a role, an
+  `aria-*` value, a server-rendered class. All four template sets, every case.
+* `tests/e2e/` — claims that are behavior: where focus lands after open, where
+  it lands after close, that `Tab` cannot leave the dialog. Parameterized over
+  `js_on` / `js_off`.
+
+`expect(role_is_dialog)` proves nothing about focus, and
+`expect(tab).to_be_attached()` passes against markup nobody can use. Assert the
+behavior.
diff --git a/src/cf_ui/static/cf_ui/cf_ui_alpine.js b/src/cf_ui/static/cf_ui/cf_ui_alpine.js
index 81eb9fe..fbab126 100644
--- a/src/cf_ui/static/cf_ui/cf_ui_alpine.js
+++ b/src/cf_ui/static/cf_ui/cf_ui_alpine.js
@@ -6,20 +6,122 @@
 
 let _notifId = 0;
 
+// Tabbable elements. `[tabindex="-1"]` is excluded on purpose: it is
+// programmatically focusable but not part of the tab sequence, so a focus trap
+// that included it would wrap in the wrong place.
+const CF_FOCUSABLE = [
+    'a[href]',
+    'area[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    'iframe',
+    'audio[controls]',
+    'video[controls]',
+    '[contenteditable]:not([contenteditable="false"])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+/**
+ * Tabbable descendants of `root` that are actually rendered.
+ *
+ * `getClientRects()` forces a layout flush, which is why the modal can call
+ * this straight out of `$nextTick`: by the time the list comes back, the
+ * class that reveals the dialog has been applied and `focus()` will take.
+ */
+function cfFocusable(root) {
+    return Array.from(root.querySelectorAll(CF_FOCUSABLE)).filter(
+        (el) => el.getClientRects().length > 0
+    );
+}
+
 document.addEventListener('alpine:init', () => {
     // ── Named components ──────────────────────────────────────────────────────
 
+    // Deliberately driven from a <div>, not a native <dialog>. See
+    // docs/accessibility.md — one Alpine implementation covers every theme,
+    // where showModal() would make this component branch per theme. Everything
+    // <dialog> would have given for free is implemented below, once.
     Alpine.data('cfModal', () => ({
         open: false,
+        // Where focus returns on close. Captured when the dialog opens rather
+        // than declared by the template, so any trigger works — a button, a
+        // link, a keyboard shortcut — without the markup knowing about it.
+        _returnFocusTo: null,
+
         toggle() {
-            this.open = !this.open;
+            if (this.open) {
+                this.close();
+            } else {
+                this.show();
+            }
         },
+
+        show() {
+            if (this.open) return;
+            this._returnFocusTo = document.activeElement;
+            this.open = true;
+        },
+
         close() {
+            if (!this.open) return;
             this.open = false;
+            const target = this._returnFocusTo;
+            this._returnFocusTo = null;
+            if (target && typeof target.focus === 'function' && target.isConnected) {
+                target.focus();
+            }
+        },
+
+        _focusFirst() {
+            const targets = cfFocusable(this.$el);
+            if (targets.length) {
+                targets[0].focus();
+                return;
+            }
+            // A dialog with nothing tabbable in it still has to take focus, or
+            // the reader stays behind it and the trap has nothing to hold.
+            this.$el.setAttribute('tabindex', '-1');
+            this.$el.focus();
+        },
+
+        _trapTab(event) {
+            const targets = cfFocusable(this.$el);
+            if (!targets.length) {
+                event.preventDefault();
+                return;
+            }
+            const first = targets[0];
+            const last = targets[targets.length - 1];
+            const inside = this.$el.contains(document.activeElement);
+            if (event.shiftKey) {
+                if (!inside || document.activeElement === first) {
+                    event.preventDefault();
+                    last.focus();
+                }
+            } else if (!inside || document.activeElement === last) {
+                event.preventDefault();
+                first.focus();
+            }
         },
+
         initModal() {
-            this.$el.addEventListener('cf-modal-open', () => { this.open = true; });
-            this.$el.addEventListener('cf-modal-close', () => { this.open = false; });
+            this.$el.addEventListener('cf-modal-open', () => this.show());
+            this.$el.addEventListener('cf-modal-close', () => this.close());
+            this.$el.addEventListener('keydown', (event) => {
+                if (event.key === 'Escape') {
+                    event.preventDefault();
+                    this.close();
+                } else if (event.key === 'Tab') {
+                    this._trapTab(event);
+                }
+            });
+            // Watched rather than folded into show(), so a consumer that sets
+            // `open` directly still gets focus management.
+            this.$watch('open', (isOpen) => {
+                if (isOpen) this.$nextTick(() => this._focusFirst());
+            });
         },
     }));
 
@@ -32,6 +134,11 @@ document.addEventListener('alpine:init', () => {
 
     Alpine.data('cfPanel', () => ({
         open: false,
+        initPanel() {
+            // Seeded from the server-rendered state so the Alpine binding
+            // continues the initial value rather than resetting it to closed.
+            this.open = this.$el.dataset.cfOpen === 'true';
+        },
         toggle() {
             this.open = !this.open;
         },
@@ -39,9 +146,66 @@ document.addEventListener('alpine:init', () => {
 
     Alpine.data('cfTabs', () => ({
         active: null,
+
+        initTabs() {
+            // Read from a data attribute rather than an interpolated
+            // `x-data="cfTabs('{{ active }}')"`. The value is request-controlled,
+            // and a template engine escapes an attribute correctly but has no
+            // way to escape JavaScript source text.
+            this.active = this.$el.dataset.cfActive || null;
+        },
+
         setActive(id) {
             this.active = id;
         },
+
+        _tabs() {
+            return Array.from(this.$el.querySelectorAll('[role="tab"]'));
+        },
+
+        // Roving tabindex. With no tab selected the first one holds the 0 —
+        // otherwise the whole widget drops out of the tab order, since these
+        // anchors carry no href and tabindex is all that makes them focusable.
+        tabIndexFor(id) {
+            if (this.active) return this.active === id ? 0 : -1;
+            const tabs = this._tabs();
+            return tabs.length && tabs[0].dataset.cfTab === id ? 0 : -1;
+        },
+
+        // Manual activation: arrows move focus, Enter/Space activates. Automatic
+        // activation would fire an HTMX request on every arrow press.
+        onKeydown(event) {
+            const tabs = this._tabs();
+            if (!tabs.length) return;
+            const current = tabs.indexOf(document.activeElement);
+            let next;
+            switch (event.key) {
+                case 'ArrowRight':
+                case 'ArrowDown':
+                    next = tabs[(current + 1) % tabs.length];
+                    break;
+                case 'ArrowLeft':
+                case 'ArrowUp':
+                    next = tabs[(current - 1 + tabs.length) % tabs.length];
+                    break;
+                case 'Home':
+                    next = tabs[0];
+                    break;
+                case 'End':
+                    next = tabs[tabs.length - 1];
+                    break;
+                case 'Enter':
+                case ' ':
+                    if (current < 0) return;
+                    event.preventDefault();
+                    tabs[current].click();
+                    return;
+                default:
+                    return;
+            }
+            event.preventDefault();
+            (current < 0 ? tabs[0] : next).focus();
+        },
     }));
 
     // ── $cf global store ──────────────────────────────────────────────────────
diff --git a/src/cf_ui/templates/cotton/_themes/bulma/modal.html b/src/cf_ui/templates/cotton/_themes/bulma/modal.html
index 18a3387..ae69c51 100644
--- a/src/cf_ui/templates/cotton/_themes/bulma/modal.html
+++ b/src/cf_ui/templates/cotton/_themes/bulma/modal.html
@@ -1,13 +1,16 @@
 <div id="{{ id }}"
      class="modal {{ class }}"
+     role="dialog"
+     aria-modal="true"
+     {% if header %}aria-labelledby="{{ id }}-title"{% else %}aria-label="{{ label|default:'Dialog' }}"{% endif %}
      x-data="cfModal"
      x-init="initModal()"
      :class="{ 'is-active': open }">
   <div class="modal-background" @click="close()"></div>
   <div class="modal-card">
     <header class="modal-card-head">
-      <p class="modal-card-title">{{ header }}</p>
-      <button class="delete" aria-label="close" @click="close()"></button>
+      <p class="modal-card-title" id="{{ id }}-title">{{ header }}</p>
+      <button type="button" class="delete" aria-label="close" @click="close()"></button>
     </header>
     <section class="modal-card-body">
       {{ slot }}
diff --git a/src/cf_ui/templates/cotton/_themes/bulma/panel.html b/src/cf_ui/templates/cotton/_themes/bulma/panel.html
index 57b7d5f..31048eb 100644
--- a/src/cf_ui/templates/cotton/_themes/bulma/panel.html
+++ b/src/cf_ui/templates/cotton/_themes/bulma/panel.html
@@ -1,14 +1,25 @@
-<div class="card {{ class }}" x-data="cfPanel">
+<div class="card {{ class }}"
+     x-data="cfPanel"
+     x-init="initPanel()"
+     data-cf-open="{% if open and open != 'false' %}true{% else %}false{% endif %}">
   <header class="card-header" style="cursor:pointer" @click="toggle()">
     <p class="card-header-title">{{ title }}</p>
-    <button class="card-header-icon" aria-label="toggle panel">
+    <button type="button"
+            class="card-header-icon"
+            aria-label="toggle panel"
+            aria-controls="{{ id }}-body"
+            aria-expanded="{% if open and open != 'false' %}true{% else %}false{% endif %}"
+            :aria-expanded="open">
       <span class="icon">
         <span :style="open ? 'transform:rotate(90deg)' : ''"
               style="display:inline-block;transition:transform 200ms">▶</span>
       </span>
     </button>
   </header>
-  <div class="card-content" x-show="open" x-cloak>
+  <div id="{{ id }}-body"
+       class="card-content"
+       x-show="open"
+       {% if not open or open == 'false' %}x-cloak{% endif %}>
     {{ slot }}
   </div>
 </div>
diff --git a/src/cf_ui/templates/cotton/_themes/bulma/tabs.html b/src/cf_ui/templates/cotton/_themes/bulma/tabs.html
index 7deb0b4..dc9f4e0 100644
--- a/src/cf_ui/templates/cotton/_themes/bulma/tabs.html
+++ b/src/cf_ui/templates/cotton/_themes/bulma/tabs.html
@@ -1,14 +1,26 @@
-<div class="{{ class }}" x-data="cfTabs">
+<div class="{{ class }}"
+     x-data="cfTabs"
+     x-init="initTabs()"
+     data-cf-active="{{ active }}">
   <div class="tabs">
-    <ul>
+    <ul role="tablist" @keydown="onKeydown($event)">
       {% for tab in tabs %}
-      <li :class="{ 'is-active': active === '{{ tab.id }}' }">
-        <a @click.prevent="setActive('{{ tab.id }}')"
+      <li role="presentation"
+          class="{% if tab.id == active %}is-active{% endif %}"
+          :class="{ 'is-active': active === '{{ tab.id }}' }">
+        <a role="tab"
+           data-cf-tab="{{ tab.id }}"
+           aria-controls="{{ hx_target }}"
+           aria-selected="{% if tab.id == active %}true{% else %}false{% endif %}"
+           tabindex="{% if tab.id == active or not active and forloop.first %}0{% else %}-1{% endif %}"
+           :aria-selected="active === '{{ tab.id }}'"
+           :tabindex="tabIndexFor('{{ tab.id }}')"
+           @click.prevent="setActive('{{ tab.id }}')"
            hx-get="{{ tab.url }}"
            hx-target="#{{ hx_target }}">{{ tab.id }}</a>
       </li>
       {% endfor %}
     </ul>
   </div>
-  <div id="{{ hx_target }}">{{ slot }}</div>
+  <div id="{{ hx_target }}" role="tabpanel">{{ slot }}</div>
 </div>
diff --git a/src/cf_ui/templates/cotton/_themes/daisy/modal.html b/src/cf_ui/templates/cotton/_themes/daisy/modal.html
index bf0ad41..1635884 100644
--- a/src/cf_ui/templates/cotton/_themes/daisy/modal.html
+++ b/src/cf_ui/templates/cotton/_themes/daisy/modal.html
@@ -1,13 +1,17 @@
 <div id="{{ id }}"
      class="modal {{ class }}"
+     role="dialog"
+     aria-modal="true"
+     {% if header %}aria-labelledby="{{ id }}-title"{% else %}aria-label="{{ label|default:'Dialog' }}"{% endif %}
      x-data="cfModal"
      x-init="initModal()"
      :class="{ 'modal-open': open }">
   <div class="modal-box">
-    <button class="btn btn-sm btn-circle btn-ghost absolute right-2 top-2"
+    <button type="button"
+            class="btn btn-sm btn-circle btn-ghost absolute right-2 top-2"
             aria-label="close"
             @click="close()">&times;</button>
-    {% if header %}<h3 class="text-lg font-bold">{{ header }}</h3>{% endif %}
+    {% if header %}<h3 class="text-lg font-bold" id="{{ id }}-title">{{ header }}</h3>{% endif %}
     <div class="py-4">{{ slot }}</div>
     {% if footer %}
     <div class="modal-action">{{ footer }}</div>
diff --git a/src/cf_ui/templates/cotton/_themes/daisy/panel.html b/src/cf_ui/templates/cotton/_themes/daisy/panel.html
index 2608638..f66302c 100644
--- a/src/cf_ui/templates/cotton/_themes/daisy/panel.html
+++ b/src/cf_ui/templates/cotton/_themes/daisy/panel.html
@@ -1,13 +1,21 @@
-<div class="card bg-base-100 shadow-xl {{ class }}" x-data="cfPanel">
+<div class="card bg-base-100 shadow-xl {{ class }}"
+     x-data="cfPanel"
+     x-init="initPanel()"
+     data-cf-open="{% if open and open != 'false' %}true{% else %}false{% endif %}">
   <button type="button"
           class="btn btn-ghost justify-between w-full"
+          aria-controls="{{ id }}-body"
+          aria-expanded="{% if open and open != 'false' %}true{% else %}false{% endif %}"
           :aria-expanded="open"
           @click="toggle()">
     <span class="card-title text-base">{{ title }}</span>
     <span :style="open ? 'transform:rotate(90deg)' : ''"
           style="display:inline-block;transition:transform 200ms">&#9654;</span>
   </button>
-  <div class="card-body pt-0" x-show="open" x-cloak>
+  <div id="{{ id }}-body"
+       class="card-body pt-0"
+       x-show="open"
+       {% if not open or open == 'false' %}x-cloak{% endif %}>
     {{ slot }}
   </div>
 </div>
diff --git a/src/cf_ui/templates/cotton/_themes/daisy/tabs.html b/src/cf_ui/templates/cotton/_themes/daisy/tabs.html
index b7f2271..142bcb5 100644
--- a/src/cf_ui/templates/cotton/_themes/daisy/tabs.html
+++ b/src/cf_ui/templates/cotton/_themes/daisy/tabs.html
@@ -1,13 +1,22 @@
-<div class="{{ class }}" x-data="cfTabs">
-  <div role="tablist" class="tabs tabs-bordered">
+<div class="{{ class }}"
+     x-data="cfTabs"
+     x-init="initTabs()"
+     data-cf-active="{{ active }}">
+  <div role="tablist" class="tabs tabs-bordered" @keydown="onKeydown($event)">
     {% for tab in tabs %}
     <a role="tab"
-       class="tab"
+       data-cf-tab="{{ tab.id }}"
+       class="tab {% if tab.id == active %}tab-active{% endif %}"
+       aria-controls="{{ hx_target }}"
+       aria-selected="{% if tab.id == active %}true{% else %}false{% endif %}"
+       tabindex="{% if tab.id == active or not active and forloop.first %}0{% else %}-1{% endif %}"
        :class="{ 'tab-active': active === '{{ tab.id }}' }"
+       :aria-selected="active === '{{ tab.id }}'"
+       :tabindex="tabIndexFor('{{ tab.id }}')"
        @click.prevent="setActive('{{ tab.id }}')"
        hx-get="{{ tab.url }}"
        hx-target="#{{ hx_target }}">{{ tab.id }}</a>
     {% endfor %}
   </div>
-  <div id="{{ hx_target }}">{{ slot }}</div>
+  <div id="{{ hx_target }}" role="tabpanel">{{ slot }}</div>
 </div>
diff --git a/src/cf_ui/templates/cotton/cf/modal.html b/src/cf_ui/templates/cotton/cf/modal.html
index 3326396..4624a6b 100644
--- a/src/cf_ui/templates/cotton/cf/modal.html
+++ b/src/cf_ui/templates/cotton/cf/modal.html
@@ -1,2 +1,2 @@
-<c-vars id="modal" header="" footer="" class="" />
+<c-vars id="modal" header="" footer="" label="Dialog" class="" />
 {% load cf_ui %}{% cf_ui_theme_path "modal" as cf_ui_partial %}{% include cf_ui_partial %}
diff --git a/src/cf_ui/templates/cotton/cf/panel.html b/src/cf_ui/templates/cotton/cf/panel.html
index 5c264c6..8acff58 100644
--- a/src/cf_ui/templates/cotton/cf/panel.html
+++ b/src/cf_ui/templates/cotton/cf/panel.html
@@ -1,2 +1,2 @@
-<c-vars title class="" />
+<c-vars title id="panel" open="" class="" />
 {% load cf_ui %}{% cf_ui_theme_path "panel" as cf_ui_partial %}{% include cf_ui_partial %}
diff --git a/src/cf_ui/templates/cotton/cf/tabs.html b/src/cf_ui/templates/cotton/cf/tabs.html
index fe69836..f6ed9fc 100644
--- a/src/cf_ui/templates/cotton/cf/tabs.html
+++ b/src/cf_ui/templates/cotton/cf/tabs.html
@@ -1,2 +1,2 @@
-<c-vars hx_target="tab-content" tabs="[]" class="" />
+<c-vars hx_target="tab-content" tabs="[]" active="" class="" />
 {% load cf_ui %}{% cf_ui_theme_path "tabs" as cf_ui_partial %}{% include cf_ui_partial %}
diff --git a/src/cf_ui/templates/jinja/bulma/Modal.jinja b/src/cf_ui/templates/jinja/bulma/Modal.jinja
index 0bcee5a..ec79c9f 100644
--- a/src/cf_ui/templates/jinja/bulma/Modal.jinja
+++ b/src/cf_ui/templates/jinja/bulma/Modal.jinja
@@ -1,17 +1,21 @@
-{#def id="modal", header="", content="", footer="", extra_class="" #}
+{#def id="modal", header="", content="", footer="", label="Dialog", extra_class="" #}
 {% set header = header if header is defined else "" %}
 {% set content = content if content is defined else "" %}
 {% set footer = footer if footer is defined else "" %}
+{% set label = label if label is defined and label else "Dialog" %}
 <div id="{{ id }}"
      class="modal {{ extra_class }}"
+     role="dialog"
+     aria-modal="true"
+     {% if header %}aria-labelledby="{{ id }}-title"{% else %}aria-label="{{ label }}"{% endif %}
      x-data="cfModal"
      x-init="initModal()"
      :class="{ 'is-active': open }">
   <div class="modal-background" @click="close()"></div>
   <div class="modal-card">
     <header class="modal-card-head">
-      <p class="modal-card-title">{{ header }}</p>
-      <button class="delete" aria-label="close" @click="close()"></button>
+      <p class="modal-card-title" id="{{ id }}-title">{{ header }}</p>
+      <button type="button" class="delete" aria-label="close" @click="close()"></button>
     </header>
     <section class="modal-card-body">
       {{ content }}
diff --git a/src/cf_ui/templates/jinja/bulma/Panel.jinja b/src/cf_ui/templates/jinja/bulma/Panel.jinja
index 00dcde0..cf8bbc1 100644
--- a/src/cf_ui/templates/jinja/bulma/Panel.jinja
+++ b/src/cf_ui/templates/jinja/bulma/Panel.jinja
@@ -1,16 +1,29 @@
-{#def title, content="", open=false, extra_class="" #}
+{#def title, id="panel", content="", open=false, extra_class="" #}
 {% set content = content if content is defined else "" %}
-<div class="card {{ extra_class }}" x-data="cfPanel">
-  <header class="card-header" style="cursor:pointer" @click="open = !open">
+{% set id = id if id is defined else "panel" %}
+{% set open = open if open is defined else false %}
+<div class="card {{ extra_class }}"
+     x-data="cfPanel"
+     x-init="initPanel()"
+     data-cf-open="{% if open %}true{% else %}false{% endif %}">
+  <header class="card-header" style="cursor:pointer" @click="toggle()">
     <p class="card-header-title">{{ title }}</p>
-    <button class="card-header-icon" aria-label="toggle panel">
+    <button type="button"
+            class="card-header-icon"
+            aria-label="toggle panel"
+            aria-controls="{{ id }}-body"
+            aria-expanded="{% if open %}true{% else %}false{% endif %}"
+            :aria-expanded="open">
       <span class="icon">
         <span :style="open ? 'transform:rotate(90deg)' : 'transform:rotate(0deg)'"
               style="display:inline-block;transition:transform 200ms">▶</span>
       </span>
     </button>
   </header>
-  <div class="card-content" x-show="open" x-cloak>
+  <div id="{{ id }}-body"
+       class="card-content"
+       x-show="open"
+       {% if not open %}x-cloak{% endif %}>
     {{ content }}
   </div>
 </div>
diff --git a/src/cf_ui/templates/jinja/bulma/Tabs.jinja b/src/cf_ui/templates/jinja/bulma/Tabs.jinja
index 669f3af..29eaf88 100644
--- a/src/cf_ui/templates/jinja/bulma/Tabs.jinja
+++ b/src/cf_ui/templates/jinja/bulma/Tabs.jinja
@@ -1,18 +1,31 @@
-{#def tabs=[], hx_target="tab-content", content="", extra_class="" #}
+{#def tabs=[], hx_target="tab-content", active="", content="", extra_class="" #}
 {% set tabs = tabs if tabs is defined else [] %}
 {% set content = content if content is defined else "" %}
+{% set active = active if active is defined else "" %}
 {% set hx_target = hx_target if hx_target is defined else "tab-content" %}
-<div class="{{ extra_class }}" x-data="cfTabs">
+<div class="{{ extra_class }}"
+     x-data="cfTabs"
+     x-init="initTabs()"
+     data-cf-active="{{ active }}">
   <div class="tabs">
-    <ul>
+    <ul role="tablist" @keydown="onKeydown($event)">
       {% for tab in tabs %}
-      <li :class="{ 'is-active': active === '{{ tab.id }}' }">
-        <a @click.prevent="setActive('{{ tab.id }}')"
+      <li role="presentation"
+          class="{% if tab.id == active %}is-active{% endif %}"
+          :class="{ 'is-active': active === '{{ tab.id }}' }">
+        <a role="tab"
+           data-cf-tab="{{ tab.id }}"
+           aria-controls="{{ hx_target }}"
+           aria-selected="{% if tab.id == active %}true{% else %}false{% endif %}"
+           tabindex="{% if tab.id == active or (not active and loop.first) %}0{% else %}-1{% endif %}"
+           :aria-selected="active === '{{ tab.id }}'"
+           :tabindex="tabIndexFor('{{ tab.id }}')"
+           @click.prevent="setActive('{{ tab.id }}')"
            hx-get="{{ tab.url }}"
            hx-target="#{{ hx_target }}">{{ tab.id }}</a>
       </li>
       {% endfor %}
     </ul>
   </div>
-  <div id="{{ hx_target }}">{{ content }}</div>
+  <div id="{{ hx_target }}" role="tabpanel">{{ content }}</div>
 </div>
diff --git a/src/cf_ui/templates/jinja/daisy/Modal.jinja b/src/cf_ui/templates/jinja/daisy/Modal.jinja
index 2ecb46d..e8df511 100644
--- a/src/cf_ui/templates/jinja/daisy/Modal.jinja
+++ b/src/cf_ui/templates/jinja/daisy/Modal.jinja
@@ -1,19 +1,24 @@
-{#def id="modal", header="", content="", footer="", extra_class="" #}
+{#def id="modal", header="", content="", footer="", label="Dialog", extra_class="" #}
 {% set id = id if id is defined else "modal" %}
 {% set header = header if header is defined else "" %}
 {% set content = content if content is defined else "" %}
 {% set footer = footer if footer is defined else "" %}
+{% set label = label if label is defined and label else "Dialog" %}
 {% set extra_class = extra_class if extra_class is defined else "" %}
 <div id="{{ id }}"
      class="modal {{ extra_class }}"
+     role="dialog"
+     aria-modal="true"
+     {% if header %}aria-labelledby="{{ id }}-title"{% else %}aria-label="{{ label }}"{% endif %}
      x-data="cfModal"
      x-init="initModal()"
      :class="{ 'modal-open': open }">
   <div class="modal-box">
-    <button class="btn btn-sm btn-circle btn-ghost absolute right-2 top-2"
+    <button type="button"
+            class="btn btn-sm btn-circle btn-ghost absolute right-2 top-2"
             aria-label="close"
             @click="close()">&times;</button>
-    {% if header %}<h3 class="text-lg font-bold">{{ header }}</h3>{% endif %}
+    {% if header %}<h3 class="text-lg font-bold" id="{{ id }}-title">{{ header }}</h3>{% endif %}
     <div class="py-4">{{ content }}</div>
     {% if footer %}
     <div class="modal-action">{{ footer }}</div>
diff --git a/src/cf_ui/templates/jinja/daisy/Panel.jinja b/src/cf_ui/templates/jinja/daisy/Panel.jinja
index efcad7c..6fb5db0 100644
--- a/src/cf_ui/templates/jinja/daisy/Panel.jinja
+++ b/src/cf_ui/templates/jinja/daisy/Panel.jinja
@@ -1,16 +1,26 @@
-{#def title, content="", open=false, extra_class="" #}
+{#def title, id="panel", content="", open=false, extra_class="" #}
 {% set content = content if content is defined else "" %}
+{% set id = id if id is defined else "panel" %}
+{% set open = open if open is defined else false %}
 {% set extra_class = extra_class if extra_class is defined else "" %}
-<div class="card bg-base-100 shadow-xl {{ extra_class }}" x-data="cfPanel">
+<div class="card bg-base-100 shadow-xl {{ extra_class }}"
+     x-data="cfPanel"
+     x-init="initPanel()"
+     data-cf-open="{% if open %}true{% else %}false{% endif %}">
   <button type="button"
           class="btn btn-ghost justify-between w-full"
+          aria-controls="{{ id }}-body"
+          aria-expanded="{% if open %}true{% else %}false{% endif %}"
           :aria-expanded="open"
           @click="toggle()">
     <span class="card-title text-base">{{ title }}</span>
     <span :style="open ? 'transform:rotate(90deg)' : 'transform:rotate(0deg)'"
           style="display:inline-block;transition:transform 200ms">&#9654;</span>
   </button>
-  <div class="card-body pt-0" x-show="open" x-cloak>
+  <div id="{{ id }}-body"
+       class="card-body pt-0"
+       x-show="open"
+       {% if not open %}x-cloak{% endif %}>
     {{ content }}
   </div>
 </div>
diff --git a/src/cf_ui/templates/jinja/daisy/Tabs.jinja b/src/cf_ui/templates/jinja/daisy/Tabs.jinja
index 6d55128..a7a7773 100644
--- a/src/cf_ui/templates/jinja/daisy/Tabs.jinja
+++ b/src/cf_ui/templates/jinja/daisy/Tabs.jinja
@@ -1,18 +1,28 @@
-{#def tabs=[], hx_target="tab-content", content="", extra_class="" #}
+{#def tabs=[], hx_target="tab-content", active="", content="", extra_class="" #}
 {% set tabs = tabs if tabs is defined else [] %}
 {% set content = content if content is defined else "" %}
+{% set active = active if active is defined else "" %}
 {% set hx_target = hx_target if hx_target is defined else "tab-content" %}
 {% set extra_class = extra_class if extra_class is defined else "" %}
-<div class="{{ extra_class }}" x-data="cfTabs">
-  <div role="tablist" class="tabs tabs-bordered">
+<div class="{{ extra_class }}"
+     x-data="cfTabs"
+     x-init="initTabs()"
+     data-cf-active="{{ active }}">
+  <div role="tablist" class="tabs tabs-bordered" @keydown="onKeydown($event)">
     {% for tab in tabs %}
     <a role="tab"
-       class="tab"
+       data-cf-tab="{{ tab.id }}"
+       class="tab {% if tab.id == active %}tab-active{% endif %}"
+       aria-controls="{{ hx_target }}"
+       aria-selected="{% if tab.id == active %}true{% else %}false{% endif %}"
+       tabindex="{% if tab.id == active or (not active and loop.first) %}0{% else %}-1{% endif %}"
        :class="{ 'tab-active': active === '{{ tab.id }}' }"
+       :aria-selected="active === '{{ tab.id }}'"
+       :tabindex="tabIndexFor('{{ tab.id }}')"
        @click.prevent="setActive('{{ tab.id }}')"
        hx-get="{{ tab.url }}"
        hx-target="#{{ hx_target }}">{{ tab.id }}</a>
     {% endfor %}
   </div>
-  <div id="{{ hx_target }}">{{ content }}</div>
+  <div id="{{ hx_target }}" role="tabpanel">{{ content }}</div>
 </div>
diff --git a/tests/e2e/test_bulma_cotton.py b/tests/e2e/test_bulma_cotton.py
index a2a4951..3a6f225 100644
--- a/tests/e2e/test_bulma_cotton.py
+++ b/tests/e2e/test_bulma_cotton.py
@@ -23,3 +23,43 @@ def test_card_cotton_renders(cotton_page, cotton_server_url):
     expect(page.locator(".card")).to_be_visible()
     expect(page.locator(".card-header-title")).to_have_text("Card Title")
     expect(page.locator(".card-footer-item")).to_have_text("Card Footer")
+
+
+# --- Accessibility through the real cotton compiler (#21) ------------------
+#
+# These pages carry no Alpine: the E2E Django server is a bare WSGIHandler and
+# serves no static files. That is fine for what this half is for — proving the
+# new props survive <c-vars>, which the unit tier cannot do because
+# render_to_string bypasses the compiler entirely. Focus behavior is asserted
+# on the JinjaX galleries, where cf_ui_alpine.js actually loads.
+
+
+def test_modal_cotton_declares_dialog_semantics(cotton_page, cotton_server_url):
+    page, _ = cotton_page
+    page.goto(f"{cotton_server_url}/modal/")
+    modal = page.locator("#test-modal")
+    expect(modal).to_have_attribute("role", "dialog")
+    expect(modal).to_have_attribute("aria-modal", "true")
+    expect(modal).to_have_attribute("aria-labelledby", "test-modal-title")
+    expect(page.locator("#test-modal-title")).to_have_text("Test Modal")
+
+
+def test_tabs_cotton_render_the_active_tab(cotton_page, cotton_server_url):
+    page, _ = cotton_page
+    page.goto(f"{cotton_server_url}/tabs/")
+    expect(page.locator("li.is-active")).to_have_count(1)
+    expect(page.locator("li.is-active [role='tab']")).to_have_text("tab1")
+    expect(page.locator("[role='tab'][aria-selected='true']")).to_have_count(1)
+    expect(page.locator("[role='tab'][tabindex='0']")).to_have_count(1)
+
+
+def test_panel_cotton_honors_its_open_prop(cotton_page, cotton_server_url):
+    page, _ = cotton_page
+    page.goto(f"{cotton_server_url}/panel/")
+    expect(page.locator("#open-panel-body")).not_to_have_attribute("x-cloak", "")
+    expect(page.locator('button[aria-controls="open-panel-body"]')).to_have_attribute(
+        "aria-expanded", "true"
+    )
+    expect(page.locator('button[aria-controls="closed-panel-body"]')).to_have_attribute(
+        "aria-expanded", "false"
+    )
diff --git a/tests/e2e/test_bulma_jinja.py b/tests/e2e/test_bulma_jinja.py
index ac7c5de..607c055 100644
--- a/tests/e2e/test_bulma_jinja.py
+++ b/tests/e2e/test_bulma_jinja.py
@@ -32,6 +32,91 @@ def test_modal_opens_and_closes(jinja_page, jinja_server_url):
         expect(modal).to_be_attached()
 
 
+# --- Dialog semantics and focus management (#21) ---------------------------
+#
+# Everything below asserts where focus *is*, not which attributes are present.
+# Attribute presence is covered by tests/unit/test_accessibility.py; a modal
+# can carry role="dialog" and still strand the keyboard user behind it.
+
+
+def test_modal_declares_dialog_semantics(jinja_page, jinja_server_url):
+    """Runs in both modes — the semantics are server-rendered, not scripted."""
+    page, _ = jinja_page
+    page.goto(f"{jinja_server_url}/gallery")
+    modal = page.locator("#e2e-modal")
+    expect(modal).to_have_attribute("role", "dialog")
+    expect(modal).to_have_attribute("aria-modal", "true")
+    expect(modal).to_have_attribute("aria-labelledby", "e2e-modal-title")
+    expect(page.locator("#e2e-modal-title")).to_have_text("E2E Dialog")
+
+
+def test_modal_moves_focus_into_the_dialog(jinja_page, jinja_server_url):
+    page, js_mode = jinja_page
+    if js_mode != "js_on":
+        pytest.skip("focus management requires JS")
+    page.goto(f"{jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    page.locator("#open-modal").click()
+    expect(page.locator("#e2e-modal")).to_have_class(re.compile(r"is-active"))
+    assert page.evaluate(
+        "() => document.getElementById('e2e-modal').contains(document.activeElement)"
+    ), "focus stayed behind the dialog"
+
+
+def test_modal_restores_focus_to_its_trigger(jinja_page, jinja_server_url):
+    page, js_mode = jinja_page
+    if js_mode != "js_on":
+        pytest.skip("focus management requires JS")
+    page.goto(f"{jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    page.locator("#open-modal").click()
+    page.locator("#e2e-modal .delete").click()
+    expect(page.locator("#e2e-modal")).not_to_have_class(re.compile(r"is-active"))
+    assert page.evaluate("() => document.activeElement.id") == "open-modal"
+
+
+def test_escape_closes_the_modal(jinja_page, jinja_server_url):
+    page, js_mode = jinja_page
+    if js_mode != "js_on":
+        pytest.skip("focus management requires JS")
+    page.goto(f"{jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    page.locator("#open-modal").click()
+    expect(page.locator("#e2e-modal")).to_have_class(re.compile(r"is-active"))
+    page.keyboard.press("Escape")
+    expect(page.locator("#e2e-modal")).not_to_have_class(re.compile(r"is-active"))
+    assert page.evaluate("() => document.activeElement.id") == "open-modal"
+
+
+def test_tab_does_not_escape_the_open_modal(jinja_page, jinja_server_url):
+    """Tab past the last focusable element must wrap, not leave the dialog.
+
+    The gallery modal has two stops (close, OK), so the loop below crosses the
+    wrap point several times rather than merely staying put.
+    """
+    page, js_mode = jinja_page
+    if js_mode != "js_on":
+        pytest.skip("focus management requires JS")
+    page.goto(f"{jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    page.locator("#open-modal").click()
+    inside = "() => document.getElementById('e2e-modal').contains(document.activeElement)"
+    seen = set()
+    for _ in range(6):
+        page.keyboard.press("Tab")
+        assert page.evaluate(inside), "focus escaped the dialog on Tab"
+        seen.add(page.evaluate("() => document.activeElement.className"))
+    assert len(seen) > 1, "focus never moved — the trap is pinning, not cycling"
+
+    for _ in range(6):
+        page.keyboard.press("Shift+Tab")
+        assert page.evaluate(inside), "focus escaped the dialog on Shift+Tab"
+
+
 def test_notification_dismisses(jinja_page, jinja_server_url):
     page, js_mode = jinja_page
     page.goto(f"{jinja_server_url}/gallery")
@@ -80,6 +165,83 @@ def test_navbar_burger_toggles_menu(jinja_page, jinja_server_url):
         expect(page.locator(".navbar")).to_be_visible()
 
 
+def test_open_panel_is_readable_without_js(jinja_page, jinja_server_url):
+    """`open` is server-rendered, so x-cloak must not hide an open panel.
+
+    Runs in both modes: with JS, initPanel() has to keep it open rather than
+    resetting to closed; without JS, the absence of x-cloak is what shows it.
+    """
+    page, js_mode = jinja_page
+    page.goto(f"{jinja_server_url}/gallery")
+    if js_mode == "js_on":
+        _wait_for_alpine(page)
+    expect(page.locator("#e2e-panel-open-body")).to_be_visible()
+    expect(page.locator("#e2e-panel-open-body")).to_contain_text("Visible content")
+
+
+def test_panel_toggle_reports_its_state(jinja_page, jinja_server_url):
+    page, js_mode = jinja_page
+    page.goto(f"{jinja_server_url}/gallery")
+    closed = page.locator('button[aria-controls="e2e-panel-body"]')
+    opened = page.locator('button[aria-controls="e2e-panel-open-body"]')
+    if js_mode == "js_on":
+        _wait_for_alpine(page)
+    expect(closed).to_have_attribute("aria-expanded", "false")
+    expect(opened).to_have_attribute("aria-expanded", "true")
+
+
+# --- Tabs: server-rendered active state (#21) ------------------------------
+
+
+def test_exactly_one_tab_is_marked_active(jinja_page, jinja_server_url):
+    """The js_off half is the point: without JS every tab used to look alike."""
+    page, js_mode = jinja_page
+    page.goto(f"{jinja_server_url}/gallery")
+    if js_mode == "js_on":
+        _wait_for_alpine(page)
+    expect(page.locator("li.is-active")).to_have_count(1)
+    expect(page.locator("li.is-active [role='tab']")).to_have_text("tab1")
+    expect(page.locator("[role='tab'][aria-selected='true']")).to_have_count(1)
+
+
+def test_tabs_switch_the_active_marker_on_click(jinja_page, jinja_server_url):
+    page, js_mode = jinja_page
+    if js_mode != "js_on":
+        pytest.skip("client-side switching requires JS")
+    page.goto(f"{jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    page.locator("[role='tab']").nth(1).click()
+    expect(page.locator("li.is-active")).to_have_count(1)
+    expect(page.locator("li.is-active [role='tab']")).to_have_text("tab2")
+
+
+def test_arrow_keys_rove_focus_across_the_tablist(jinja_page, jinja_server_url):
+    page, js_mode = jinja_page
+    if js_mode != "js_on":
+        pytest.skip("roving tabindex requires JS")
+    page.goto(f"{jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    tabs = page.locator("[role='tab']")
+    tabs.first.focus()
+    page.keyboard.press("ArrowRight")
+    assert page.evaluate("() => document.activeElement.dataset.cfTab") == "tab2"
+    # Wraps rather than dead-ending at the edge.
+    page.keyboard.press("ArrowRight")
+    assert page.evaluate("() => document.activeElement.dataset.cfTab") == "tab1"
+    page.keyboard.press("End")
+    assert page.evaluate("() => document.activeElement.dataset.cfTab") == "tab2"
+
+
+def test_only_the_active_tab_is_in_the_tab_order(jinja_page, jinja_server_url):
+    page, js_mode = jinja_page
+    page.goto(f"{jinja_server_url}/gallery")
+    if js_mode == "js_on":
+        _wait_for_alpine(page)
+    expect(page.locator("[role='tab'][tabindex='0']")).to_have_count(1)
+
+
 def test_form_field_renders(jinja_page, jinja_server_url):
     page, js_mode = jinja_page
     page.goto(f"{jinja_server_url}/form-field")
diff --git a/tests/e2e/test_daisy.py b/tests/e2e/test_daisy.py
index 4d08883..34703cf 100644
--- a/tests/e2e/test_daisy.py
+++ b/tests/e2e/test_daisy.py
@@ -142,17 +142,148 @@ def test_jinja_navbar_burger_toggles_menu(daisy_jinja_page, daisy_jinja_server_u
 
 
 def test_jinja_tabs_activate(daisy_jinja_page, daisy_jinja_server_url):
+    """Clicking a tab moves the marker; the server-rendered one is the start.
+
+    Was: assert the first tab is *not* active, click it, assert it is. That
+    only held because no tab was ever active to begin with — the js_off half
+    of the same test could do no better than `to_be_attached()`. The gallery
+    now ships `active="tab1"`, so this asserts a move rather than a first
+    appearance, and js_off has something real to check (see below).
+    """
     page, js_mode = daisy_jinja_page
+    if js_mode != "js_on":
+        pytest.skip("covered without JS by test_jinja_exactly_one_tab_is_active")
     page.goto(f"{daisy_jinja_server_url}/gallery")
-    first_tab = page.locator("[role='tab']").first
+    _wait_for_alpine(page)
 
+    tabs = page.locator("[role='tab']")
+    expect(tabs.nth(0)).to_have_class(re.compile(r"tab-active"))
+    tabs.nth(1).click()
+    expect(tabs.nth(1)).to_have_class(re.compile(r"tab-active"))
+    expect(tabs.nth(0)).not_to_have_class(re.compile(r"tab-active"))
+
+
+def test_jinja_exactly_one_tab_is_active(daisy_jinja_page, daisy_jinja_server_url):
+    """#21: `to_be_attached()` passed against markup that was unusable."""
+    page, js_mode = daisy_jinja_page
+    page.goto(f"{daisy_jinja_server_url}/gallery")
     if js_mode == "js_on":
         _wait_for_alpine(page)
-        expect(first_tab).not_to_have_class(re.compile(r"tab-active"))
-        first_tab.click()
-        expect(first_tab).to_have_class(re.compile(r"tab-active"))
-    else:
-        expect(first_tab).to_be_attached()
+    expect(page.locator("[role='tab'].tab-active")).to_have_count(1)
+    expect(page.locator("[role='tab'].tab-active")).to_have_text("tab1")
+    expect(page.locator("[role='tab'][aria-selected='true']")).to_have_count(1)
+    expect(page.locator("[role='tab'][tabindex='0']")).to_have_count(1)
+
+
+def test_jinja_arrow_keys_rove_focus_across_the_tablist(daisy_jinja_page, daisy_jinja_server_url):
+    page, js_mode = daisy_jinja_page
+    if js_mode != "js_on":
+        pytest.skip("roving tabindex requires JS")
+    page.goto(f"{daisy_jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    page.locator("[role='tab']").first.focus()
+    page.keyboard.press("ArrowRight")
+    assert page.evaluate("() => document.activeElement.dataset.cfTab") == "tab2"
+    page.keyboard.press("Home")
+    assert page.evaluate("() => document.activeElement.dataset.cfTab") == "tab1"
+
+
+# --- Dialog semantics and focus management (#21) ---------------------------
+
+
+def test_jinja_modal_declares_dialog_semantics(daisy_jinja_page, daisy_jinja_server_url):
+    page, _ = daisy_jinja_page
+    page.goto(f"{daisy_jinja_server_url}/gallery")
+    modal = page.locator("#e2e-modal")
+    expect(modal).to_have_attribute("role", "dialog")
+    expect(modal).to_have_attribute("aria-modal", "true")
+    expect(modal).to_have_attribute("aria-labelledby", "e2e-modal-title")
+
+
+def test_jinja_modal_manages_focus(daisy_jinja_page, daisy_jinja_server_url):
+    """Same Alpine contract as Bulma — the theme changes classes, not behavior."""
+    page, js_mode = daisy_jinja_page
+    if js_mode != "js_on":
+        pytest.skip("focus management requires JS")
+    page.goto(f"{daisy_jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    page.locator("#open-modal").click()
+    assert page.evaluate(
+        "() => document.getElementById('e2e-modal').contains(document.activeElement)"
+    ), "focus stayed behind the dialog"
+    page.keyboard.press("Escape")
+    expect(page.locator("#e2e-modal")).not_to_have_class(re.compile(r"modal-open"))
+    assert page.evaluate("() => document.activeElement.id") == "open-modal"
+
+
+def test_jinja_tab_does_not_escape_the_open_modal(daisy_jinja_page, daisy_jinja_server_url):
+    page, js_mode = daisy_jinja_page
+    if js_mode != "js_on":
+        pytest.skip("focus management requires JS")
+    page.goto(f"{daisy_jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    page.locator("#open-modal").click()
+    inside = "() => document.getElementById('e2e-modal').contains(document.activeElement)"
+    for _ in range(6):
+        page.keyboard.press("Tab")
+        assert page.evaluate(inside), "focus escaped the dialog on Tab"
+
+
+def test_jinja_open_panel_is_readable_without_js(daisy_jinja_page, daisy_jinja_server_url):
+    page, js_mode = daisy_jinja_page
+    page.goto(f"{daisy_jinja_server_url}/gallery")
+    if js_mode == "js_on":
+        _wait_for_alpine(page)
+    expect(page.locator("#e2e-panel-open-body")).to_be_visible()
+
+
+def test_jinja_panel_toggle_reports_its_state(daisy_jinja_page, daisy_jinja_server_url):
+    page, js_mode = daisy_jinja_page
+    page.goto(f"{daisy_jinja_server_url}/gallery")
+    if js_mode == "js_on":
+        _wait_for_alpine(page)
+    expect(page.locator('button[aria-controls="e2e-panel-body"]')).to_have_attribute(
+        "aria-expanded", "false"
+    )
+    expect(page.locator('button[aria-controls="e2e-panel-open-body"]')).to_have_attribute(
+        "aria-expanded", "true"
+    )
+
+
+# --- django-cotton: the same contract through the real compiler ------------
+
+
+def test_cotton_modal_declares_dialog_semantics(daisy_cotton_page, daisy_cotton_server_url):
+    page, _ = daisy_cotton_page
+    page.goto(f"{daisy_cotton_server_url}/modal/")
+    modal = page.locator("#test-modal")
+    expect(modal).to_have_attribute("role", "dialog")
+    expect(modal).to_have_attribute("aria-modal", "true")
+    expect(modal).to_have_attribute("aria-labelledby", "test-modal-title")
+
+
+def test_cotton_tabs_render_the_active_tab(daisy_cotton_page, daisy_cotton_server_url):
+    """`active` has to survive <c-vars> — unit tests bypass that compiler."""
+    page, _ = daisy_cotton_page
+    page.goto(f"{daisy_cotton_server_url}/tabs/")
+    expect(page.locator("[role='tab'].tab-active")).to_have_count(1)
+    expect(page.locator("[role='tab'].tab-active")).to_have_text("tab1")
+    expect(page.locator("[role='tab'][aria-selected='true']")).to_have_count(1)
+
+
+def test_cotton_panel_honors_its_open_prop(daisy_cotton_page, daisy_cotton_server_url):
+    page, _ = daisy_cotton_page
+    page.goto(f"{daisy_cotton_server_url}/panel/")
+    expect(page.locator("#open-panel-body")).not_to_have_attribute("x-cloak", "")
+    expect(page.locator('button[aria-controls="open-panel-body"]')).to_have_attribute(
+        "aria-expanded", "true"
+    )
+    expect(page.locator('button[aria-controls="closed-panel-body"]')).to_have_attribute(
+        "aria-expanded", "false"
+    )
 
 
 def test_jinja_form_field_renders(daisy_jinja_page, daisy_jinja_server_url):
diff --git a/tests/integration/cotton_app/templates/cotton_gallery/panel.html b/tests/integration/cotton_app/templates/cotton_gallery/panel.html
new file mode 100644
index 0000000..f5a7ec7
--- /dev/null
+++ b/tests/integration/cotton_app/templates/cotton_gallery/panel.html
@@ -0,0 +1,3 @@
+<style>[x-cloak] { display: none !important; }</style>
+<c-cf.panel id="closed-panel" title="Closed">Closed body</c-cf.panel>
+<c-cf.panel id="open-panel" title="Open" open="true">Open body</c-cf.panel>
diff --git a/tests/integration/cotton_app/templates/cotton_gallery/tabs.html b/tests/integration/cotton_app/templates/cotton_gallery/tabs.html
new file mode 100644
index 0000000..8675816
--- /dev/null
+++ b/tests/integration/cotton_app/templates/cotton_gallery/tabs.html
@@ -0,0 +1,3 @@
+<c-cf.tabs :tabs="tabs" hx_target="tab-content" active="{{ active }}">
+  Initial content
+</c-cf.tabs>
diff --git a/tests/integration/cotton_app/urls.py b/tests/integration/cotton_app/urls.py
index 0775d95..fb75daa 100644
--- a/tests/integration/cotton_app/urls.py
+++ b/tests/integration/cotton_app/urls.py
@@ -6,4 +6,6 @@
     path("form-field/", views.form_field_view),
     path("modal/", views.modal_view),
     path("card/", views.card_view),
+    path("tabs/", views.tabs_view),
+    path("panel/", views.panel_view),
 ]
diff --git a/tests/integration/cotton_app/views.py b/tests/integration/cotton_app/views.py
index bc49177..cd77199 100644
--- a/tests/integration/cotton_app/views.py
+++ b/tests/integration/cotton_app/views.py
@@ -22,3 +22,18 @@ def modal_view(request):
 
 def card_view(request):
     return render(request, "cotton_gallery/card.html", {})
+
+
+def tabs_view(request):
+    return render(
+        request,
+        "cotton_gallery/tabs.html",
+        {
+            "tabs": [{"id": "tab1", "url": "/tab/one/"}, {"id": "tab2", "url": "/tab/two/"}],
+            "active": "tab1",
+        },
+    )
+
+
+def panel_view(request):
+    return render(request, "cotton_gallery/panel.html", {})
diff --git a/tests/integration/jinja_app/main.py b/tests/integration/jinja_app/main.py
index ad881ea..a9c54f4 100644
--- a/tests/integration/jinja_app/main.py
+++ b/tests/integration/jinja_app/main.py
@@ -74,23 +74,47 @@ async def tabs():
             "Cf:Tabs",
             tabs=[{"id": "one", "url": "/tab/one/"}, {"id": "two", "url": "/tab/two/"}],
             hx_target="tab-content",
+            active="one",
             extra_class="",
         )
 
     @app.get("/gallery", response_class=HTMLResponse)
     async def gallery():
-        modal_html = catalog.render("Cf:Modal", id="e2e-modal", extra_class="")
+        # A header (so aria-labelledby has a target) and a focusable footer
+        # control (so the focus trap has more than one stop to wrap between).
+        modal_html = catalog.render(
+            "Cf:Modal",
+            id="e2e-modal",
+            header="E2E Dialog",
+            footer='<button type="button" id="modal-ok">OK</button>',
+            extra_class="",
+        )
         notification_html = catalog.render(
             "Cf:Notification", message="Hello!", type="info", dismissible=True, extra_class=""
         )
         navbar_html = catalog.render("Cf:Navbar", brand="Brand", start="", end="", extra_class="")
         panel_html = catalog.render(
-            "Cf:Panel", title="Accordion", _content="Hidden content", open=False, extra_class=""
+            "Cf:Panel",
+            id="e2e-panel",
+            title="Accordion",
+            _content="Hidden content",
+            open=False,
+            extra_class="",
+        )
+        # The no-JS case for `open`: this one must be readable with Alpine off.
+        panel_open_html = catalog.render(
+            "Cf:Panel",
+            id="e2e-panel-open",
+            title="Already open",
+            _content="Visible content",
+            open=True,
+            extra_class="",
         )
         tabs_html = catalog.render(
             "Cf:Tabs",
             tabs=[{"id": "tab1", "url": "/tab/one/"}, {"id": "tab2", "url": "/tab/two/"}],
             hx_target="tab-content",
+            active="tab1",
             _content="Initial content",
             extra_class="",
         )
@@ -104,10 +128,11 @@ async def gallery():
 <body>
   <section class="section">
     {navbar_html}
-    <button id="open-modal">Open Modal</button>
+    <button id="open-modal" x-data @click="$store.cf.modal.open('e2e-modal')">Open Modal</button>
     {modal_html}
     {notification_html}
     {panel_html}
+    {panel_open_html}
     {tabs_html}
   </section>
   <script src="/static/cf_ui/cf_ui_alpine.js" defer></script>
diff --git a/tests/unit/test_accessibility.py b/tests/unit/test_accessibility.py
new file mode 100644
index 0000000..7e03557
--- /dev/null
+++ b/tests/unit/test_accessibility.py
@@ -0,0 +1,436 @@
+"""Accessibility contract for the interactive components (issue #21).
+
+Scope split, deliberately:
+
+* **Here** live the claims that *are* markup — a role, an ``aria-*`` value, a
+  server-rendered class. Asserting those against the rendered string is not a
+  proxy for anything; it is the thing itself.
+* **In ``tests/e2e/``** live the claims that are behavior — where focus lands,
+  whether it can escape, whether Escape closes. Issue #21 is explicit that a
+  test asserting ``role="dialog"`` is present proves nothing about focus, so
+  no test in this module pretends otherwise.
+
+Every case runs against all four template sets (2 engines x 2 themes). The
+point of the phase is a pattern the three themes in the expansion epic copy;
+a fix that landed in one set and not the others would be worse than none.
+"""
+
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape
+
+TEMPLATES_DIR = Path(__file__).parent.parent.parent / "src" / "cf_ui" / "templates"
+JINJA_DIR = TEMPLATES_DIR / "jinja"
+
+THEMES = ["bulma", "daisy"]
+
+#: The class each theme puts on the *selected* tab, and the element it sits on.
+#: Bulma marks the ``<li>``; DaisyUI marks the ``<a role="tab">`` itself.
+ACTIVE_TAB_CLASS = {"bulma": "is-active", "daisy": "tab-active"}
+
+
+@pytest.fixture(params=THEMES)
+def theme(request) -> str:
+    return request.param
+
+
+@pytest.fixture
+def jinja_render(theme: str) -> Callable[..., str]:
+    """Render a JinjaX component file through plain Jinja2, for one theme.
+
+    Plain Jinja2 with ``StrictUndefined`` rather than a JinjaX ``Catalog``,
+    for the same reason the rest of ``tests/unit/jinja`` does: it is the
+    harsher environment. ``{#def}`` defaults do not apply here, so every
+    template has to carry its own ``is defined`` guards to pass.
+    """
+    env = Environment(
+        loader=FileSystemLoader(JINJA_DIR / theme),
+        autoescape=select_autoescape(["html", "jinja"]),
+        undefined=StrictUndefined,
+    )
+
+    def _render(template_name: str, **ctx: object) -> str:
+        return env.get_template(template_name).render(**ctx)
+
+    return _render
+
+
+@pytest.fixture
+def cotton_render(settings, theme: str) -> Callable[..., str]:
+    """Render a public cotton wrapper with ``CF_UI_THEME`` set to ``theme``.
+
+    ``render_to_string`` bypasses the django-cotton compiler, so ``<c-vars>``
+    defaults never apply — props are passed explicitly here and the E2E tier
+    is what exercises real ``<c-vars>`` resolution.
+    """
+    from django.template.loader import render_to_string
+
+    settings.CF_UI_THEME = theme
+
+    def _render(stem: str, **props: object) -> str:
+        return render_to_string(f"cotton/cf/{stem}.html", props)
+
+    return _render
+
+
+def _attrs(html: str, tag_marker: str) -> str:
+    """Return the opening tag containing ``tag_marker``, attributes included."""
+    for match in re.finditer(r"<[a-zA-Z][^>]*>", html, re.DOTALL):
+        if tag_marker in match.group(0):
+            return match.group(0)
+    raise AssertionError(f"no opening tag containing {tag_marker!r} in:\n{html}")
+
+
+# ── 1. Modal: dialog semantics ────────────────────────────────────────────
+
+
+def test_jinja_modal_declares_dialog_semantics(jinja_render):
+    html = jinja_render("Modal.jinja", id="m", header="", footer="", content="", extra_class="")
+    root = _attrs(html, 'id="m"')
+    assert 'role="dialog"' in root
+    assert 'aria-modal="true"' in root
+
+
+def test_cotton_modal_declares_dialog_semantics(cotton_render):
+    html = cotton_render("modal", id="m", header="", footer="", label="", **{"class": ""})
+    root = _attrs(html, 'id="m"')
+    assert 'role="dialog"' in root
+    assert 'aria-modal="true"' in root
+
+
+def test_jinja_modal_labels_itself_by_its_header(jinja_render):
+    html = jinja_render(
+        "Modal.jinja", id="m", header="Delete file", footer="", content="", extra_class=""
+    )
+    assert 'aria-labelledby="m-title"' in _attrs(html, 'id="m"')
+    assert 'id="m-title"' in html, "nothing carries the id aria-labelledby points at"
+
+
+def test_cotton_modal_labels_itself_by_its_header(cotton_render):
+    html = cotton_render(
+        "modal", id="m", header="Delete file", footer="", label="", **{"class": ""}
+    )
+    assert 'aria-labelledby="m-title"' in _attrs(html, 'id="m"')
+    assert 'id="m-title"' in html, "nothing carries the id aria-labelledby points at"
+
+
+def test_jinja_modal_falls_back_to_aria_label_without_a_header(jinja_render):
+    """An empty aria-labelledby target is worse than no labelling at all."""
+    html = jinja_render(
+        "Modal.jinja", id="m", header="", footer="", content="", label="Settings", extra_class=""
+    )
+    root = _attrs(html, 'id="m"')
+    assert 'aria-label="Settings"' in root
+    assert "aria-labelledby" not in root
+
+
+def test_cotton_modal_falls_back_to_aria_label_without_a_header(cotton_render):
+    html = cotton_render("modal", id="m", header="", footer="", label="Settings", **{"class": ""})
+    root = _attrs(html, 'id="m"')
+    assert 'aria-label="Settings"' in root
+    assert "aria-labelledby" not in root
+
+
+def test_jinja_modal_aria_label_has_a_default(jinja_render):
+    """No header and no label must still leave the dialog named."""
+    html = jinja_render("Modal.jinja", id="m", header="", footer="", content="", extra_class="")
+    assert re.search(r'aria-label="[^"]+"', _attrs(html, 'id="m"'))
+
+
+def test_cotton_modal_aria_label_has_a_default(cotton_render):
+    html = cotton_render("modal", id="m", header="", footer="", **{"class": ""})
+    assert re.search(r'aria-label="[^"]+"', _attrs(html, 'id="m"'))
+
+
+def test_cotton_modal_wrapper_declares_the_label_prop():
+    """The fallback is only reachable if <c-vars> lets a consumer pass it."""
+    source = (TEMPLATES_DIR / "cotton" / "cf" / "modal.html").read_text(encoding="utf-8")
+    assert "label" in source.split("/>")[0]
+
+
+@pytest.mark.parametrize("theme", THEMES)
+def test_no_modal_template_implements_focus_itself(theme):
+    """#21: all focus behavior in cf_ui_alpine.js, not per template.
+
+    Five themes copying five slightly-different focus traps is the failure
+    mode this checks for.
+    """
+    sources = [
+        (JINJA_DIR / theme / "Modal.jinja").read_text(encoding="utf-8"),
+        (TEMPLATES_DIR / "cotton" / "_themes" / theme / "modal.html").read_text(encoding="utf-8"),
+    ]
+    for source in sources:
+        assert ".focus()" not in source
+        assert "keydown" not in source
+
+
+# ── 2. Tabs: server-rendered state ────────────────────────────────────────
+
+TABS = [{"id": "one", "url": "/one/"}, {"id": "two", "url": "/two/"}]
+
+
+def _tab_tags(html: str) -> list[str]:
+    return re.findall(r'<a[^>]*role="tab"[^>]*>', html)
+
+
+def test_jinja_tabs_render_the_active_tab_without_js(jinja_render, theme):
+    html = jinja_render(
+        "Tabs.jinja", tabs=TABS, hx_target="tc", active="two", content="", extra_class=""
+    )
+    marker = ACTIVE_TAB_CLASS[theme]
+    assert html.count(marker) >= 1, "no tab carries the active class server-side"
+    # Exactly one, in the static markup — Alpine is not running here.
+    static_classes = re.findall(r'\sclass="([^"]*)"', html)
+    assert sum(1 for c in static_classes if marker in c.split()) == 1
+
+
+def test_cotton_tabs_render_the_active_tab_without_js(cotton_render, theme):
+    html = cotton_render("tabs", tabs=TABS, hx_target="tc", active="two", **{"class": ""})
+    marker = ACTIVE_TAB_CLASS[theme]
+    static_classes = re.findall(r'\sclass="([^"]*)"', html)
+    assert sum(1 for c in static_classes if marker in c.split()) == 1
+
+
+def test_jinja_tabs_mark_no_tab_active_when_no_active_prop(jinja_render, theme):
+    html = jinja_render(
+        "Tabs.jinja", tabs=TABS, hx_target="tc", active="", content="", extra_class=""
+    )
+    marker = ACTIVE_TAB_CLASS[theme]
+    static_classes = re.findall(r'\sclass="([^"]*)"', html)
+    assert not [c for c in static_classes if marker in c.split()]
+
+
+def test_jinja_tabs_keep_the_alpine_binding(jinja_render, theme):
+    """Server state is the initial value, not a replacement (#21)."""
+    html = jinja_render(
+        "Tabs.jinja", tabs=TABS, hx_target="tc", active="two", content="", extra_class=""
+    )
+    assert ":class=" in html
+    assert "cfTabs" in html
+
+
+def test_cotton_tabs_keep_the_alpine_binding(cotton_render):
+    html = cotton_render("tabs", tabs=TABS, hx_target="tc", active="two", **{"class": ""})
+    assert ":class=" in html
+    assert "cfTabs" in html
+
+
+def test_jinja_tabs_seed_alpine_from_a_data_attribute(jinja_render):
+    """The initial value crosses into Alpine as data, never as expression text.
+
+    ``x-data="cfTabs('{{ active }}')"`` would splice a request-controlled
+    string into an evaluated expression; an apostrophe alone breaks out of it.
+    A ``data-`` attribute is escaped by the template engine like any other.
+    """
+    html = jinja_render(
+        "Tabs.jinja", tabs=TABS, hx_target="tc", active="two", content="", extra_class=""
+    )
+    assert 'data-cf-active="two"' in html
+    assert "cfTabs(" not in html
+
+
+def test_cotton_tabs_seed_alpine_from_a_data_attribute(cotton_render):
+    html = cotton_render("tabs", tabs=TABS, hx_target="tc", active="two", **{"class": ""})
+    assert 'data-cf-active="two"' in html
+    assert "cfTabs(" not in html
+
+
+def test_jinja_tabs_escape_a_hostile_active_value(jinja_render):
+    html = jinja_render(
+        "Tabs.jinja",
+        tabs=TABS,
+        hx_target="tc",
+        active="' + alert(1) + '",
+        content="",
+        extra_class="",
+    )
+    value = re.search(r'data-cf-active="([^"]*)"', html)
+    assert value, "no data-cf-active attribute to escape into"
+    assert "'" not in value.group(1), "a raw apostrophe survived into the attribute"
+
+
+def test_jinja_tabs_expose_the_tablist_roles(jinja_render):
+    html = jinja_render(
+        "Tabs.jinja", tabs=TABS, hx_target="tc", active="one", content="", extra_class=""
+    )
+    assert 'role="tablist"' in html
+    assert len(_tab_tags(html)) == len(TABS)
+    assert 'role="tabpanel"' in html
+
+
+def test_cotton_tabs_expose_the_tablist_roles(cotton_render):
+    html = cotton_render("tabs", tabs=TABS, hx_target="tc", active="one", **{"class": ""})
+    assert 'role="tablist"' in html
+    assert len(_tab_tags(html)) == len(TABS)
+    assert 'role="tabpanel"' in html
+
+
+def test_jinja_tabs_render_aria_selected_server_side(jinja_render):
+    html = jinja_render(
+        "Tabs.jinja", tabs=TABS, hx_target="tc", active="two", content="", extra_class=""
+    )
+    tags = _tab_tags(html)
+    assert 'aria-selected="false"' in tags[0]
+    assert 'aria-selected="true"' in tags[1]
+
+
+def test_cotton_tabs_render_aria_selected_server_side(cotton_render):
+    html = cotton_render("tabs", tabs=TABS, hx_target="tc", active="two", **{"class": ""})
+    tags = _tab_tags(html)
+    assert 'aria-selected="false"' in tags[0]
+    assert 'aria-selected="true"' in tags[1]
+
+
+def test_jinja_tabs_point_aria_controls_at_the_panel(jinja_render):
+    html = jinja_render(
+        "Tabs.jinja", tabs=TABS, hx_target="tc", active="one", content="", extra_class=""
+    )
+    for tag in _tab_tags(html):
+        assert 'aria-controls="tc"' in tag
+    assert 'id="tc"' in html, "aria-controls points at an id nothing carries"
+
+
+def test_cotton_tabs_point_aria_controls_at_the_panel(cotton_render):
+    html = cotton_render("tabs", tabs=TABS, hx_target="tc", active="one", **{"class": ""})
+    for tag in _tab_tags(html):
+        assert 'aria-controls="tc"' in tag
+    assert 'id="tc"' in html
+
+
+def test_jinja_tabs_use_a_roving_tabindex(jinja_render):
+    html = jinja_render(
+        "Tabs.jinja", tabs=TABS, hx_target="tc", active="two", content="", extra_class=""
+    )
+    tags = _tab_tags(html)
+    assert 'tabindex="-1"' in tags[0]
+    assert 'tabindex="0"' in tags[1]
+
+
+def test_cotton_tabs_use_a_roving_tabindex(cotton_render):
+    html = cotton_render("tabs", tabs=TABS, hx_target="tc", active="two", **{"class": ""})
+    tags = _tab_tags(html)
+    assert 'tabindex="-1"' in tags[0]
+    assert 'tabindex="0"' in tags[1]
+
+
+def test_jinja_tabs_stay_keyboard_reachable_with_no_active_tab(jinja_render):
+    """A roving tabindex with nothing at 0 removes the whole widget from the
+    tab order. These anchors have no href, so tabindex is the only thing
+    making them focusable at all."""
+    html = jinja_render(
+        "Tabs.jinja", tabs=TABS, hx_target="tc", active="", content="", extra_class=""
+    )
+    tags = _tab_tags(html)
+    assert 'tabindex="0"' in tags[0]
+    assert 'tabindex="-1"' in tags[1]
+
+
+def test_cotton_tabs_stay_keyboard_reachable_with_no_active_tab(cotton_render):
+    html = cotton_render("tabs", tabs=TABS, hx_target="tc", active="", **{"class": ""})
+    tags = _tab_tags(html)
+    assert 'tabindex="0"' in tags[0]
+    assert 'tabindex="-1"' in tags[1]
+
+
+def test_cotton_tabs_wrapper_declares_the_active_prop():
+    source = (TEMPLATES_DIR / "cotton" / "cf" / "tabs.html").read_text(encoding="utf-8")
+    assert "active" in source.split("/>")[0]
+
+
+@pytest.mark.parametrize("theme", THEMES)
+def test_tab_keyboard_handling_lives_in_alpine(theme):
+    """Roving-tabindex arrow keys belong in cf_ui_alpine.js, same as the modal."""
+    for source in (
+        (JINJA_DIR / theme / "Tabs.jinja").read_text(encoding="utf-8"),
+        (TEMPLATES_DIR / "cotton" / "_themes" / theme / "tabs.html").read_text(encoding="utf-8"),
+    ):
+        assert "onKeydown($event)" in source
+        assert "ArrowRight" not in source
+
+
+# ── 3. Panel: server-rendered open state ──────────────────────────────────
+
+
+def test_jinja_panel_renders_its_body_visible_when_open(jinja_render):
+    """x-cloak on a server-open panel hides it forever without JS."""
+    html = jinja_render("Panel.jinja", id="p", title="T", content="Body", open=True, extra_class="")
+    assert "x-cloak" not in html
+
+
+def test_jinja_panel_cloaks_its_body_when_closed(jinja_render):
+    html = jinja_render(
+        "Panel.jinja", id="p", title="T", content="Body", open=False, extra_class=""
+    )
+    assert "x-cloak" in html
+
+
+def test_cotton_panel_renders_its_body_visible_when_open(cotton_render):
+    html = cotton_render("panel", id="p", title="T", open="true", **{"class": ""})
+    assert "x-cloak" not in html
+
+
+def test_cotton_panel_cloaks_its_body_when_closed(cotton_render):
+    html = cotton_render("panel", id="p", title="T", open="", **{"class": ""})
+    assert "x-cloak" in html
+
+
+def test_jinja_panel_seeds_alpine_from_a_data_attribute(jinja_render):
+    html = jinja_render("Panel.jinja", id="p", title="T", content="Body", open=True, extra_class="")
+    assert 'data-cf-open="true"' in html
+    assert "cfPanel(" not in html
+
+
+def test_cotton_panel_seeds_alpine_from_a_data_attribute(cotton_render):
+    html = cotton_render("panel", id="p", title="T", open="true", **{"class": ""})
+    assert 'data-cf-open="true"' in html
+    assert "cfPanel(" not in html
+
+
+def test_jinja_panel_toggle_declares_aria_expanded_and_controls(jinja_render):
+    html = jinja_render(
+        "Panel.jinja", id="p", title="T", content="Body", open=False, extra_class=""
+    )
+    toggle = _attrs(html, "aria-controls=")
+    assert 'aria-controls="p-body"' in toggle
+    assert 'aria-expanded="false"' in toggle
+    assert ':aria-expanded="open"' in toggle, "the Alpine binding must survive"
+    assert 'id="p-body"' in html, "aria-controls points at an id nothing carries"
+
+
+def test_cotton_panel_toggle_declares_aria_expanded_and_controls(cotton_render):
+    html = cotton_render("panel", id="p", title="T", open="", **{"class": ""})
+    toggle = _attrs(html, "aria-controls=")
+    assert 'aria-controls="p-body"' in toggle
+    assert 'aria-expanded="false"' in toggle
+    assert ':aria-expanded="open"' in toggle
+    assert 'id="p-body"' in html
+
+
+def test_jinja_panel_reports_expanded_when_server_open(jinja_render):
+    html = jinja_render("Panel.jinja", id="p", title="T", content="Body", open=True, extra_class="")
+    assert 'aria-expanded="true"' in _attrs(html, "aria-controls=")
+
+
+def test_cotton_panel_reports_expanded_when_server_open(cotton_render):
+    html = cotton_render("panel", id="p", title="T", open="true", **{"class": ""})
+    assert 'aria-expanded="true"' in _attrs(html, "aria-controls=")
+
+
+def test_cotton_panel_wrapper_declares_id_and_open():
+    source = (TEMPLATES_DIR / "cotton" / "cf" / "panel.html").read_text(encoding="utf-8")
+    header = source.split("/>")[0]
+    assert "id" in header
+    assert "open" in header
+
+
+@pytest.mark.parametrize("theme", THEMES)
+def test_panel_toggle_is_a_real_button(theme):
+    """A div with a click handler is not reachable by keyboard."""
+    for source in (
+        (JINJA_DIR / theme / "Panel.jinja").read_text(encoding="utf-8"),
+        (TEMPLATES_DIR / "cotton" / "_themes" / theme / "panel.html").read_text(encoding="utf-8"),
+    ):
+        assert 'type="button"' in source

From 99dc44cab67171fa86323ed8aef989c023a46fc6 Mon Sep 17 00:00:00 2001
From: Francis Secada <francis.secada@gmail.com>
Date: Wed, 29 Jul 2026 12:40:08 -0400
Subject: [PATCH 2/3] fix(a11y): retry modal focus until the dialog is actually
 revealed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`focus()` on an element that is not rendered yet is a silent no-op — on the
first tabbable child and on the `$el` fallback alike. Alpine does not order the
`:class` effect that reveals the dialog against the `open` watcher's
`$nextTick`, so focus was being attempted while `display: none` still applied
and nothing retried. Focus stayed on `<body>`, Escape never reached the dialog,
and the trap had nothing to hold.

`_focusFirst()` now verifies the result and retries per animation frame,
bounded by `CF_FOCUS_ATTEMPTS`, bailing out if the dialog closed in the
meantime. This also covers a theme that reveals behind a transition.

Caught by CI, which failed three `js_on` E2E tests that passed locally on
every run. The new regression test makes the race deterministic: it pins the
dialog hidden with a rule outranking `is-active`, opens it, and lifts the rule
two frames later. Verified non-vacuous — disabling the retry fails it with the
same symptom CI reported.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NhqNRBg83czKfr8L6FF5xf
---
 docs/accessibility.md                  | 17 +++++++++
 src/cf_ui/static/cf_ui/cf_ui_alpine.js | 39 ++++++++++++-------
 tests/e2e/test_bulma_jinja.py          | 52 ++++++++++++++++++++++++++
 3 files changed, 94 insertions(+), 14 deletions(-)

diff --git a/docs/accessibility.md b/docs/accessibility.md
index b26ab21..3bc49df 100644
--- a/docs/accessibility.md
+++ b/docs/accessibility.md
@@ -40,6 +40,23 @@ The trigger is **captured**, not declared: `show()` records
 `document.activeElement`. Any opener works — a button, a link, a keyboard
 shortcut, `Alpine.store('cf').modal.open(id)` — and no template has to name it.
 
+#### Why `_focusFirst()` retries
+
+`focus()` on an element that is not rendered yet is a silent no-op — on the
+first tabbable child *and* on the `$el` fallback. So focus can only be taken
+once the class that reveals the dialog has actually been committed, and nothing
+guarantees that has happened by the time the watcher's `$nextTick` runs: Alpine
+does not order the `:class` effect against it, and a theme is free to reveal
+behind a transition. `_focusFirst()` therefore verifies the result and retries
+per animation frame, bounded by `CF_FOCUS_ATTEMPTS`, rather than trusting one
+flush's ordering. A retry that finds the dialog closed again bails out instead
+of yanking focus back in.
+
+This was not theoretical: it passed locally every run and failed on CI. The
+regression test (`test_modal_takes_focus_even_when_the_reveal_is_late`) pins the
+dialog hidden with a rule that outranks the reveal class, opens it, and lifts
+the rule a couple of frames later — the race made deterministic.
+
 ### Labelling, and the `label` fallback
 
 A dialog needs an accessible name. cf-ui picks one of two, never both:
diff --git a/src/cf_ui/static/cf_ui/cf_ui_alpine.js b/src/cf_ui/static/cf_ui/cf_ui_alpine.js
index fbab126..7fd2053 100644
--- a/src/cf_ui/static/cf_ui/cf_ui_alpine.js
+++ b/src/cf_ui/static/cf_ui/cf_ui_alpine.js
@@ -23,19 +23,18 @@ const CF_FOCUSABLE = [
     '[tabindex]:not([tabindex="-1"])',
 ].join(',');
 
-/**
- * Tabbable descendants of `root` that are actually rendered.
- *
- * `getClientRects()` forces a layout flush, which is why the modal can call
- * this straight out of `$nextTick`: by the time the list comes back, the
- * class that reveals the dialog has been applied and `focus()` will take.
- */
+/** Tabbable descendants of `root` that are actually rendered. */
 function cfFocusable(root) {
     return Array.from(root.querySelectorAll(CF_FOCUSABLE)).filter(
         (el) => el.getClientRects().length > 0
     );
 }
 
+// Frames `_focusFirst` will keep retrying for before giving up. ~10 frames is
+// well past any reveal transition and still bounded, so a dialog that never
+// becomes visible cannot spin forever.
+const CF_FOCUS_ATTEMPTS = 10;
+
 document.addEventListener('alpine:init', () => {
     // ── Named components ──────────────────────────────────────────────────────
 
@@ -74,16 +73,28 @@ document.addEventListener('alpine:init', () => {
             }
         },
 
-        _focusFirst() {
+        _focusFirst(attempt = 0) {
+            // A retry scheduled before the dialog was closed again must not
+            // yank focus back into it.
+            if (!this.open) return;
+
             const targets = cfFocusable(this.$el);
-            if (targets.length) {
-                targets[0].focus();
-                return;
-            }
             // A dialog with nothing tabbable in it still has to take focus, or
             // the reader stays behind it and the trap has nothing to hold.
-            this.$el.setAttribute('tabindex', '-1');
-            this.$el.focus();
+            if (!targets.length) this.$el.setAttribute('tabindex', '-1');
+            (targets[0] || this.$el).focus();
+
+            // `focus()` on an element that is not rendered yet is a silent
+            // no-op — on both the child and the $el fallback. Nothing
+            // guarantees the class that reveals the dialog has been committed
+            // by the time this runs: Alpine does not order the `:class` effect
+            // against a $watch's $nextTick, and a theme may reveal behind a
+            // transition. So verify and retry per frame rather than trusting
+            // one flush's ordering. CI caught exactly this; it passed locally
+            // every time.
+            if (!this.$el.contains(document.activeElement) && attempt < CF_FOCUS_ATTEMPTS) {
+                requestAnimationFrame(() => this._focusFirst(attempt + 1));
+            }
         },
 
         _trapTab(event) {
diff --git a/tests/e2e/test_bulma_jinja.py b/tests/e2e/test_bulma_jinja.py
index 607c055..4d9f8bc 100644
--- a/tests/e2e/test_bulma_jinja.py
+++ b/tests/e2e/test_bulma_jinja.py
@@ -64,6 +64,58 @@ def test_modal_moves_focus_into_the_dialog(jinja_page, jinja_server_url):
     ), "focus stayed behind the dialog"
 
 
+def test_modal_takes_focus_even_when_the_reveal_is_late(jinja_page, jinja_server_url):
+    """Regression: CI failed here while every local run passed.
+
+    `focus()` on an element that is not rendered yet is a silent no-op — on the
+    first tabbable child *and* on the `$el` fallback — so if the class that
+    reveals the dialog has not been committed when focus is attempted, focus
+    stays on `<body>` and the dialog is unusable. Nothing orders Alpine's
+    `:class` effect against a `$watch`'s `$nextTick`, so this is a race, and a
+    theme revealing behind a transition would hit it deterministically.
+
+    Rather than reproduce the timing, this pins the dialog hidden with a rule
+    that outranks `is-active`, opens it, and lifts the rule a couple of frames
+    later. It runs entirely in the page so the reveal lands inside the retry
+    window instead of racing the test harness's round trips.
+    """
+    page, js_mode = jinja_page
+    if js_mode != "js_on":
+        pytest.skip("focus management requires JS")
+    page.goto(f"{jinja_server_url}/gallery")
+    _wait_for_alpine(page)
+
+    result = page.evaluate("""
+        async () => {
+            const frame = () => new Promise((r) => requestAnimationFrame(r));
+            const inside = () =>
+                document.getElementById('e2e-modal').contains(document.activeElement);
+
+            const style = document.createElement('style');
+            style.textContent = '#e2e-modal { display: none !important; }';
+            document.head.appendChild(style);
+
+            document.getElementById('open-modal').click();
+            await frame();
+            await frame();
+            const whilePinned = inside();
+
+            style.remove();
+            for (let i = 0; i < 30; i++) {
+                await frame();
+                if (inside()) return { whilePinned, recovered: true };
+            }
+            return { whilePinned, recovered: false };
+        }
+    """)
+
+    assert not result["whilePinned"], (
+        "the dialog took focus while pinned hidden — the reveal was never "
+        "actually blocked, so this test proves nothing"
+    )
+    assert result["recovered"], "focus never reached the revealed dialog"
+
+
 def test_modal_restores_focus_to_its_trigger(jinja_page, jinja_server_url):
     page, js_mode = jinja_page
     if js_mode != "js_on":

From 7d160996257bd4975b919d58ae6461c03c9d665d Mon Sep 17 00:00:00 2001
From: Francis Secada <francis.secada@gmail.com>
Date: Wed, 29 Jul 2026 12:44:51 -0400
Subject: [PATCH 3/3] test(a11y): wait for modal focus instead of sampling it
 once
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The retry landed in 99dc44c but CI still failed the same three tests, and the
log showed why: the dialog was already `class="modal is-active"` — revealed —
with focus still outside. So the reveal was not the problem; the assertion was.

`_focusFirst()` retries across animation frames, so reading
`document.activeElement` once, immediately after `to_have_class` returns, races
that loop. A fast machine wins the race every time; a loaded CI runner loses it.
`test_escape_closes_the_modal` failed downstream of the same thing — Escape is
handled on the dialog, so a keypress sent while focus is still on <body> never
reaches the handler and the modal stays open.

Both suites now wait via `_wait_for_modal_focus()` before asserting focus or
pressing a key the dialog handles. The retry remains necessary: without it focus
never lands at all, so waiting alone would not help either.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NhqNRBg83czKfr8L6FF5xf
---
 docs/accessibility.md         |  6 ++++++
 tests/e2e/test_bulma_jinja.py | 23 ++++++++++++++++++++---
 tests/e2e/test_daisy.py       | 18 +++++++++++++++---
 3 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/docs/accessibility.md b/docs/accessibility.md
index 3bc49df..1a42d59 100644
--- a/docs/accessibility.md
+++ b/docs/accessibility.md
@@ -169,3 +169,9 @@ tests could not have caught what they claimed to:
 `expect(role_is_dialog)` proves nothing about focus, and
 `expect(tab).to_be_attached()` passes against markup nobody can use. Assert the
 behavior.
+
+One caveat that cost a CI cycle: a focus assertion has to **wait**, not sample.
+`document.activeElement` read once, immediately after the reveal class lands,
+races `_focusFirst()`'s retry loop — a fast machine wins it every time and a
+loaded CI runner does not. Use `_wait_for_modal_focus(page)`, and press keys
+that the dialog handles only after it returns.
diff --git a/tests/e2e/test_bulma_jinja.py b/tests/e2e/test_bulma_jinja.py
index 4d9f8bc..97dd3b5 100644
--- a/tests/e2e/test_bulma_jinja.py
+++ b/tests/e2e/test_bulma_jinja.py
@@ -12,6 +12,20 @@ def _wait_for_alpine(page) -> None:
     )
 
 
+def _wait_for_modal_focus(page) -> None:
+    """Wait for the dialog to actually hold focus.
+
+    `_focusFirst` retries across animation frames until the reveal has been
+    committed, so sampling `document.activeElement` once — right after the
+    reveal class lands — is a race that is only lost on a slow machine. CI lost
+    it on all three Python versions while every local run won it.
+    """
+    page.wait_for_function(
+        "() => document.getElementById('e2e-modal').contains(document.activeElement)",
+        timeout=5000,
+    )
+
+
 def test_modal_opens_and_closes(jinja_page, jinja_server_url):
     page, js_mode = jinja_page
     page.goto(f"{jinja_server_url}/gallery")
@@ -59,9 +73,7 @@ def test_modal_moves_focus_into_the_dialog(jinja_page, jinja_server_url):
 
     page.locator("#open-modal").click()
     expect(page.locator("#e2e-modal")).to_have_class(re.compile(r"is-active"))
-    assert page.evaluate(
-        "() => document.getElementById('e2e-modal').contains(document.activeElement)"
-    ), "focus stayed behind the dialog"
+    _wait_for_modal_focus(page)
 
 
 def test_modal_takes_focus_even_when_the_reveal_is_late(jinja_page, jinja_server_url):
@@ -124,6 +136,7 @@ def test_modal_restores_focus_to_its_trigger(jinja_page, jinja_server_url):
     _wait_for_alpine(page)
 
     page.locator("#open-modal").click()
+    _wait_for_modal_focus(page)
     page.locator("#e2e-modal .delete").click()
     expect(page.locator("#e2e-modal")).not_to_have_class(re.compile(r"is-active"))
     assert page.evaluate("() => document.activeElement.id") == "open-modal"
@@ -138,6 +151,9 @@ def test_escape_closes_the_modal(jinja_page, jinja_server_url):
 
     page.locator("#open-modal").click()
     expect(page.locator("#e2e-modal")).to_have_class(re.compile(r"is-active"))
+    # Escape is handled on the dialog itself, so it only reaches the handler
+    # once focus is inside — press it earlier and the key goes to <body>.
+    _wait_for_modal_focus(page)
     page.keyboard.press("Escape")
     expect(page.locator("#e2e-modal")).not_to_have_class(re.compile(r"is-active"))
     assert page.evaluate("() => document.activeElement.id") == "open-modal"
@@ -156,6 +172,7 @@ def test_tab_does_not_escape_the_open_modal(jinja_page, jinja_server_url):
     _wait_for_alpine(page)
 
     page.locator("#open-modal").click()
+    _wait_for_modal_focus(page)
     inside = "() => document.getElementById('e2e-modal').contains(document.activeElement)"
     seen = set()
     for _ in range(6):
diff --git a/tests/e2e/test_daisy.py b/tests/e2e/test_daisy.py
index 34703cf..7003f17 100644
--- a/tests/e2e/test_daisy.py
+++ b/tests/e2e/test_daisy.py
@@ -20,6 +20,19 @@ def _wait_for_alpine(page) -> None:
     )
 
 
+def _wait_for_modal_focus(page) -> None:
+    """Wait for the dialog to actually hold focus — see the Bulma suite.
+
+    `_focusFirst` retries across animation frames, so a one-shot read of
+    `document.activeElement` right after the reveal is a race that only a slow
+    machine loses.
+    """
+    page.wait_for_function(
+        "() => document.getElementById('e2e-modal').contains(document.activeElement)",
+        timeout=5000,
+    )
+
+
 # --- django-cotton: one setting, no consumer template edits ----------------
 
 
@@ -210,9 +223,7 @@ def test_jinja_modal_manages_focus(daisy_jinja_page, daisy_jinja_server_url):
     _wait_for_alpine(page)
 
     page.locator("#open-modal").click()
-    assert page.evaluate(
-        "() => document.getElementById('e2e-modal').contains(document.activeElement)"
-    ), "focus stayed behind the dialog"
+    _wait_for_modal_focus(page)
     page.keyboard.press("Escape")
     expect(page.locator("#e2e-modal")).not_to_have_class(re.compile(r"modal-open"))
     assert page.evaluate("() => document.activeElement.id") == "open-modal"
@@ -226,6 +237,7 @@ def test_jinja_tab_does_not_escape_the_open_modal(daisy_jinja_page, daisy_jinja_
     _wait_for_alpine(page)
 
     page.locator("#open-modal").click()
+    _wait_for_modal_focus(page)
     inside = "() => document.getElementById('e2e-modal').contains(document.activeElement)"
     for _ in range(6):
         page.keyboard.press("Tab")