django-studio

Category: Testing & Security | Uploader: danjac | Downloads: 0 | Version: v1.0（Latest）
Accessibility audit: WCAG 2.1 AA — forms, icons, HTMX, Alpine, semantic HTML
Changelog: Source: GitHub https://github.com/danjac/django-studio
Directory Structure

Current level: tree/main/template/.agents/skills/dj-a11y/
📁 resources/
- 📄 help.md 333 B
📄 SKILL.md 7.1 KB
SKILL.md

---
description: Accessibility audit: WCAG 2.1 AA — forms, icons, HTMX, Alpine, semantic HTML
---

Audit the codebase for accessibility violations.

Report findings in three groups: **VIOLATION** (clear WCAG 2.1 AA failure),
**WARNING** (likely issue; needs manual verification), and **ADVISORY** (best
practice gap below AA, or can only be confirmed by manual testing).

Work through each section below. Scan every template under `templates/` and every
Python file under `<package_name>/`. Do not skip sections because they seem unlikely
to have issues.

---

### 1. Forms

Check all templates for form field rendering. Any pattern that bypasses
`{{ field.as_field_group }}` or `{% for field in form %}{{ field.as_field_group }}{% endfor %}`
risks breaking the `<label>`–`<input>` association and `aria-describedby` on errors.

| Pattern | Severity |
|---|---|
| `{% render_field %}` without a label wrapper | VIOLATION |
| `{{ form.as_div }}` | WARNING — bypasses configured renderer |
| `{% include "forms/partials.html" %}` | VIOLATION — the include path is wrong; use `as_field_group` |
| Radio/checkbox group using `<label>` instead of `<fieldset>`+`<legend>` | WARNING |

---

### 2. Icons

Scan all templates for `{% heroicon_* %}` calls and inline `<svg>` elements.

| Pattern | Severity |
|---|---|
| `<button>` whose only content is an icon with no `aria-label` | VIOLATION |
| `<a>` whose only content is an icon with no `aria-label` or `aria-labelledby` | VIOLATION |
| Icon inside an element that has adjacent descriptive text, but `aria-hidden="true"` is absent | WARNING — screen reader reads icon name redundantly |
| Inline `<svg>` with no `aria-hidden="true"` and no `role`/`aria-label` | WARNING |

For each `<button>` or `<a>` that contains only an icon, flag it by template path and
line number. Provide the corrected markup in the finding.

---

### 3. Interactive Alpine components

Scan all templates for `x-data` attributes. For each Alpine component:

#### 3a. Dropdowns and menus

| Check | Severity if failing |
|---|---|
| Toggle button has `:aria-expanded="open"` (or equivalent) | VIOLATION |
| Menu closes on `Escape` (`@keydown.escape`) | VIOLATION |
| Menu items are keyboard-navigable (arrow keys or tab) | WARNING |

#### 3b. Modals and dialogs

| Check | Severity if failing |
|---|---|
| Dialog element has `role="dialog"` and `aria-modal="true"` | VIOLATION |
| Focus is trapped inside the modal while open | WARNING |
| Focus returns to the trigger element when the modal closes | WARNING |
| Modal can be closed with `Escape` | VIOLATION |

#### 3c. Loading states

| Check | Severity if failing |
|---|---|
| Containers that show a spinner or skeleton set `aria-busy="true"` during loading | ADVISORY |

---

### 4. HTMX

Scan all templates for `hx-swap`, `hx-get`, `hx-post`, and `hx-push-url` attributes.

| Check | Severity if failing |
|---|---|
| A region that is updated by HTMX in response to user action has no `aria-live` attribute | WARNING — screen readers will not announce the change |
| `hx-push-url` navigation does not update `<title>` | WARNING — screen readers announce the old page title after navigation |
| HTMX target element does not use `aria-busy` during requests | ADVISORY |

For `aria-live` checks: an `aria-live="polite"` wrapper on the swap target is
sufficient. `aria-live="assertive"` is only appropriate for urgent messages (errors).

---

### 5. Semantic HTML

Scan all templates for these patterns:

| Pattern | Severity |
|---|---|
| `<div>` or `<span>` with `@click` or `hx-get`/`hx-post` but no `role` or `tabindex` | VIOLATION — not keyboard-operable |
| `<div>` or `<span>` used as a button/link (has click handler, no semantic element) | VIOLATION |
| Heading levels that skip (e.g. `<h1>` → `<h3>`) | VIOLATION |
| Missing `<main>`, `<nav>`, `<header>`, `<footer>` landmarks on full-page templates | WARNING |
| `<table>` data cells with no `<th scope="col|row">` headers | VIOLATION |
| `<ul>` / `<ol>` items used for layout (no list semantics needed) | ADVISORY |

For heading hierarchy: read the base template first to find the `<h1>`, then trace
inherited heading levels in child templates.

---

### 6. Images

Scan all templates for `<img>` tags.

| Check | Severity if failing |
|---|---|
| `alt` attribute absent entirely | VIOLATION (WCAG 1.1.1) |
| Content image with `alt=""` (empty) | VIOLATION — empty alt means decorative; verify it is genuinely decorative |
| `alt` value is the filename or contains "image of" | WARNING |
| `width` attribute absent | WARNING — causes layout shift (CLS) |
| `height` attribute absent | WARNING — causes layout shift (CLS) |

---

### 7. Focus styles

Scan all CSS/Tailwind files (`static/`, `tailwind/`, templates with inline styles)
for focus style overrides.

| Pattern | Severity |
|---|---|
| `outline: none` or `outline: 0` without a `focus-visible:ring` replacement | VIOLATION |
| Tailwind `focus:outline-none` without `focus-visible:ring-*` | VIOLATION |
| `focus:outline-none focus-visible:ring-*` pair | OK — correct pattern |

Note: do not flag `focus:outline-none` if `focus-visible:ring-*` is present in the
same class list.

---

### 8. Colour and contrast

Static analysis cannot verify contrast ratios. Instead:

- Check for colour-only information patterns (e.g. status indicated by colour with no
  label, icon, or pattern).
- Flag as **WARNING** any element that conveys status or state via a colour class alone
  (e.g. `text-red-500` with no adjacent icon or text label explaining the state).

For contrast verification, direct the user to:

```
Lighthouse → Accessibility → Colour Contrast
```

or the axe-core browser extension.

---

### 9. Automated axe-core coverage

If `axe-playwright-python` is not already in `pyproject.toml`, install it:

```bash
uv add --dev axe-playwright-python
```

Check for a test file `tests/e2e/test_accessibility.py` and flag as
**ADVISORY** if it does not exist.

---

### Report format

```
VIOLATION (WCAG 2.1 AA failure — fix before going live):
  [icons] templates/base.html:42 — <button> contains only a trash icon with no aria-label
    Fix: <button type="button" aria-label="Delete post">
  [semantic] templates/search.html:18 — <div @click="..."> is not keyboard-operable
    Fix: replace with <button type="button">
  ...

WARNING (likely issue; verify manually):
  [htmx] templates/posts/list.html — swap target #results has no aria-live attribute
  [alpine] templates/nav.html — dropdown toggle missing :aria-expanded
  [images] templates/profile.html:8 — <img> missing width and height attributes
  ...

ADVISORY (best practice; address when time allows):
  [axe] axe-playwright-python not installed — automated axe-core coverage missing
  [loading] templates/search.html — hx-indicator target missing aria-busy
  ...

OK:
  All <button>-only icon elements have aria-label
  No outline:none without focus-visible:ring replacement found
  All <img> tags have alt attributes
  ...
```

After listing all findings, print a one-line summary:

```
X violations · Y warnings · Z advisory
```

If there are VIOLATION findings, recommend fixing them before any public deployment
and offer to fix each one. Wait for the user to confirm before making any changes.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
django-studio

Directory Structure

SKILL.md

Report

Notice
