Hax Udl Audit

HAX UDL Audit (Read-Only Diagnostic)

Review an existing HAX site/page against the CAST UDL Guidelines 3.0 and emit a diagnostic + remediation report. This skill diagnoses and recommends only — it does not edit pages, mutate site.json, or insert components. It mirrors the hax-ubd-unit-audit and hax-content-chunking-audit pattern but operates through the UDL lens: does the page reach all learners through multiple means of engagement, representation, and action & expression?

The worldview in one paragraph

There is no "average" brain. Learner variability is predictable, so design for it up front rather than retrofitting accommodations. UDL 3.0 organizes that design around three principles — Engagement (the WHY of learning), Representation (the WHAT), and Action & Expression (the HOW) — each with three guidelines (G1–G9). The goal is learner agency: purposeful & reflective, resourceful & authentic, strategic & action-oriented. UDL is a set of design prompts, not a checklist — so this audit reports what is present, what is absent, and recommends only real HAX components for the gaps. The empirically-confirmed gap across the HAX training corpus (36 courses, 4,870 pages) is Action & Expression: courses are rich in media (Representation) and moderate in reflection/objectives (Engagement) but nearly devoid of interactive assessment and varied response methods. Bias the audit toward that gap.

When to Use

Trigger conditions:

• "Is this accessible to all learners" / "does this page reach everyone" / "audit for UDL"
• "My course is all reading and video with no interaction" / "add multiple means of expression"
• "Universal design" / "learner agency" / "multiple means of representation"
• even when the user does not say "UDL" — if they question whether a page reaches diverse learners or relies on a single medium/response type, this is the skill

When NOT to use (with redirect):

• Page readability / "wall of text" / chunking → hax-content-chunking-audit (page-scope cognitive load)
• Unit alignment / "are assessments aligned" / backward design → hax-ubd-unit-audit (UbD owns alignment)
• DDD/CSS compliance → hax-design-system
• Component accessibility audit (ARIA, keyboard) → hax-webcomponent-dev
• Cognitive level of an objective/assessment → grad-blooms

Scope: this skill is READ-ONLY

This skill diagnoses and recommends only. It produces a report. To apply remediation, hand off to the related skills and the hax CLI / hax-claudehax (see "Implementing the Recommendations" below). Never edit pages/*.html or site.json from within this skill.

Inputs

• a HAX site path: site.json (JOS tree) + pages/*.html, or a single page (JOS node / raw HTML / markdown)
• optional pageSlug to scope the audit to one page (else audit the page and report site-level patterns if a site path is given)
• optional unitSlug — if the unit has already been through hax-ubd-unit-audit, note it and apply the overlap rule (see below)

Methodology

1. Ingest structure. Locate the page(s) in the HAX project:
   • site.json (JSON Outline Schema) for the node tree + metadata
   • pages/<slug>.html for rendered page content (the canonical content source)
   • a JOS items export or markdown representation for offline review
2. Inventory blocks present. Parse every custom element on the page(s) and bucket each under the UDL guideline it supports, using references/udl-element-map.md as the single source of truth. Record counts per guideline.
3. Find the gaps. For each of the nine guidelines, mark Present / Thin / Absent:
   • Action & Expression (G4–G6): flag as Absent/Thin unless there is at least one interactive response block (multiple-choice, self-check, fill-in-the-blanks, short-answer-question, etc.) — this is the empirically-confirmed gap, so hold it to a higher bar.
   • Representation (G1–G3): usually Present in HAX courses (media-rich); flag only when a page is text-only with no alternate format, or when math/notation lacks lrn-math.
   • Engagement (G7–G9): flag when there is no visible goal/objective (oer-schema/stop-note), no reflection prompt (stop-note/self-check), or no relevance signal (simple-cta).
4. Map each gap to a real HAX remediation. Use references/udl-element-map.md. Never invent tag names and never recommend a legacy/third-party tag (instruction-card, lrndesign-sidenote, link-preview, model-viewer are excluded — use the documented gap handling).
5. Apply the UbD overlap rule. If the unit was already audited/designed with the UbD family, do NOT re-report Stage 2 alignment as a UDL finding — defer alignment to hax-ubd-unit-audit and limit the UDL report to the variety of means lens (multiple response methods? graduated practice? progress monitoring?).
6. Determine the overall rating: Accessible (all three principles represented) | Partial (one principle thin/absent) | Single-Path (Action & Expression absent — the common HAX-course failure mode).
7. Emit the report (format below), then an "Implementation handoff" block.

Expected Output Format

Format findings exactly like this structure (mirrors hax-ubd-unit-audit):

### 📊 UDL 3.0 Diagnostics
* **UDL Rating:** [Accessible / Partial / Single-Path]
* **Primary Gap:** [the worst offender — one sentence, e.g. "Action & Expression absent: no interactive response blocks on the page."]

### 🔍 Findings & HAX Remediation

* **{node / page / site-level} — {Principle: Guideline}**
  * **Status:** [Present / Thin / Absent]
  * **Issue:** [what is missing or thin, with the measured signal, e.g. "0 interactive response blocks; page is video + text only."]
  * **UDL Rationale:** [why this limits learner agency — cite the guideline]
  * **HAX Remediation:** [real component(s) + concrete placement, e.g. "Add a `multiple-choice` or `short-answer-question` check-in after the video; add `self-check` for progress monitoring (G6.4)."]

* **{node / page / site-level} — {Principle: Guideline}**
  * ...

### 🛠 Implementation handoff
* [one-line action per fix → skill/CLI, e.g. "Add a `short-answer-question` check-in to <page> via `/hax add a check-for-understanding section to <page>`."]

Worked example

Input — a HAX page that is a 14-minute video-player followed by 400 words of prose and a stop-note reflection prompt. No interactive blocks.

Output:

### 📊 UDL 3.0 Diagnostics
* **UDL Rating:** Single-Path
* **Primary Gap:** Action & Expression absent — the only learner action is reading/watching; there
  is no way to respond, practice, or monitor progress.

### 🔍 Findings & HAX Remediation

* **Page "efficient-deep-dive" — Action & Expression: G4 Interaction**
  * **Status:** Absent
  * **Issue:** 0 interactive response blocks. Page is `video-player` (14:30) + prose + one
    `stop-note`. No `multiple-choice`, `self-check`, `short-answer-question`, or `fill-in-the-blanks`.
  * **UDL Rationale:** G4.1 asks to vary and honor the methods for response. A single medium
    (watch + read) excludes learners who demonstrate understanding through response, and offers no
    retrieval practice.
  * **HAX Remediation:** Insert a `multiple-choice` or `short-answer-question` check-in after the
    video. Add a `self-check` for ungraded self-monitoring (G6.4).

* **Page "efficient-deep-dive" — Action & Expression: G5 Expression & Communication**
  * **Status:** Absent
  * **Issue:** No constructed-response or composition tool. The `stop-note` invites reflection but
    captures no learner artifact.
  * **UDL Rationale:** G5.2 asks for multiple tools for construction/composition. Reflection without
    a way to produce/record it limits expression to learners who process internally.
  * **HAX Remediation:** Pair the `stop-note` with a `simple-fields` constructed-response prompt so
    learners can record their reflection.

* **Page "efficient-deep-dive" — Representation: G1 Perception**
  * **Status:** Present (video + text). No concern — multiple media present.
  * **Issue:** None.
  * **UDL Rationale:** G1.2 satisfied via `video-player` + prose.
  * **HAX Remediation:** None.

* **Page "efficient-deep-dive" — Engagement: G9 Emotional Capacity**
  * **Status:** Present (thin). One `stop-note` reflection prompt exists.
  * **Issue:** Reflection is present but singular; no metacognitive self-assessment.
  * **UDL Rationale:** G9.3 asks for individual reflection; `self-check` would strengthen it.
  * **HAX Remediation:** Convert or add a `self-check` alongside the `stop-note`.

### 🛠 Implementation handoff
* G4: add a `short-answer-question` check-in after the video — `/hax add a check-for-understanding section to efficient-deep-dive using HAX web components, not plain HTML`.
* G5: pair the `stop-note` with a `simple-fields` reflection capture.
* G9: add a `self-check` for metacognitive self-assessment.
* Confirm the check-in's cognitive level via `grad-blooms`; apply DDD tokens via `hax-design-system`.