From ab401cf893477cdce268661e7f8d7697f19794ab Mon Sep 17 00:00:00 2001
From: Matt Hesketh <matt@heskethwebdesign.co.uk>
Date: Wed, 11 Feb 2026 17:15:36 +0000
Subject: [PATCH 1/2] feat(compiler): add compile-time accessibility (a11y)
 checking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a post-parse a11y analysis pass that checks template ASTs for
common accessibility violations and emits warnings. Integrated into
the compile() pipeline — warnings are returned in CompileResult.a11y.

10 rules implemented:
- img-alt: <img> must have alt attribute
- click-keyboard: non-interactive elements with @click need keyboard support
- anchor-content: <a> must have content or aria-label
- form-label: form elements need id/aria-label/aria-labelledby
- no-distracting: <marquee>/<blink> are forbidden
- heading-order: heading levels must not skip
- aria-role: role values must be valid WAI-ARIA 1.2
- no-positive-tabindex: tabindex should not be positive
- media-captions: <video>/<audio> should have <track>
- anchor-valid: <a> should have href

Configurable via CompileOptions.a11y (disable rules or turn off).
43 new tests covering all rules, edge cases, and integration.
---
 packages/compiler/src/a11y.test.ts | 307 ++++++++++++++++++++++++++++
 packages/compiler/src/a11y.ts      | 310 +++++++++++++++++++++++++++++
 packages/compiler/src/index.ts     |  19 +-
 3 files changed, 633 insertions(+), 3 deletions(-)
 create mode 100644 packages/compiler/src/a11y.test.ts
 create mode 100644 packages/compiler/src/a11y.ts

diff --git a/packages/compiler/src/a11y.test.ts b/packages/compiler/src/a11y.test.ts
new file mode 100644
index 0000000..7ca255e
--- /dev/null
+++ b/packages/compiler/src/a11y.test.ts
@@ -0,0 +1,307 @@
+// ============================================================================
+// a11y.test.ts — Tests for compile-time accessibility checking
+// ============================================================================
+
+import { describe, it, expect } from 'vitest';
+import { parseTemplate } from './template-compiler';
+import { checkA11y } from './a11y';
+import { compile } from './index';
+
+// Helper: parse and check in one call.
+function check(template: string, options?: { disable?: string[] }) {
+  const ast = parseTemplate(template);
+  return checkA11y(ast, options);
+}
+
+// ---------------------------------------------------------------------------
+// img-alt
+// ---------------------------------------------------------------------------
+
+describe('img-alt', () => {
+  it('warns on <img> without alt', () => {
+    const w = check('<img src="photo.jpg">');
+    expect(w).toHaveLength(1);
+    expect(w[0].rule).toBe('img-alt');
+  });
+
+  it('passes with static alt', () => {
+    expect(check('<img src="photo.jpg" alt="A photo">')).toHaveLength(0);
+  });
+
+  it('passes with bound :alt', () => {
+    expect(check('<img src="photo.jpg" :alt="desc">')).toHaveLength(0);
+  });
+
+  it('passes with aria-label', () => {
+    expect(check('<img src="photo.jpg" aria-label="Photo">')).toHaveLength(0);
+  });
+
+  it('passes with role="presentation" (decorative)', () => {
+    expect(check('<img src="bg.jpg" role="presentation">')).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// click-keyboard
+// ---------------------------------------------------------------------------
+
+describe('click-keyboard', () => {
+  it('warns on non-interactive element with @click but no keyboard handler', () => {
+    const w = check('<div @click="doThing">click me</div>');
+    expect(w.some((w) => w.rule === 'click-keyboard')).toBe(true);
+  });
+
+  it('does not warn on <button> with @click', () => {
+    const w = check('<button @click="doThing">click me</button>');
+    expect(w.filter((w) => w.rule === 'click-keyboard')).toHaveLength(0);
+  });
+
+  it('does not warn on <a> with @click', () => {
+    const w = check('<a href="/foo" @click="doThing">link</a>');
+    expect(w.filter((w) => w.rule === 'click-keyboard')).toHaveLength(0);
+  });
+
+  it('does not warn when @keydown is present', () => {
+    const w = check('<div @click="go" @keydown="go" tabindex="0">go</div>');
+    expect(w.filter((w) => w.rule === 'click-keyboard')).toHaveLength(0);
+  });
+
+  it('warns about missing tabindex on non-interactive element', () => {
+    const w = check('<div @click="go" @keydown="go">go</div>');
+    expect(w.some((w) => w.message.includes('tabindex'))).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// anchor-content
+// ---------------------------------------------------------------------------
+
+describe('anchor-content', () => {
+  it('warns on empty <a>', () => {
+    const w = check('<a href="/foo"></a>');
+    expect(w.some((w) => w.rule === 'anchor-content')).toBe(true);
+  });
+
+  it('passes with text content', () => {
+    const w = check('<a href="/foo">Home</a>');
+    expect(w.filter((w) => w.rule === 'anchor-content')).toHaveLength(0);
+  });
+
+  it('passes with aria-label', () => {
+    const w = check('<a href="/foo" aria-label="Home"></a>');
+    expect(w.filter((w) => w.rule === 'anchor-content')).toHaveLength(0);
+  });
+
+  it('passes with child elements', () => {
+    const w = check('<a href="/foo"><img src="icon.svg" alt="Home"></a>');
+    expect(w.filter((w) => w.rule === 'anchor-content')).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// form-label
+// ---------------------------------------------------------------------------
+
+describe('form-label', () => {
+  it('warns on <input> without id or aria-label', () => {
+    const w = check('<input type="text">');
+    expect(w.some((w) => w.rule === 'form-label')).toBe(true);
+  });
+
+  it('passes with id', () => {
+    const w = check('<input type="text" id="name">');
+    expect(w.filter((w) => w.rule === 'form-label')).toHaveLength(0);
+  });
+
+  it('passes with aria-label', () => {
+    const w = check('<input type="text" aria-label="Name">');
+    expect(w.filter((w) => w.rule === 'form-label')).toHaveLength(0);
+  });
+
+  it('does not warn on hidden inputs', () => {
+    const w = check('<input type="hidden" name="csrf">');
+    expect(w.filter((w) => w.rule === 'form-label')).toHaveLength(0);
+  });
+
+  it('warns on <select> without label', () => {
+    const w = check('<select><option>A</option></select>');
+    expect(w.some((w) => w.rule === 'form-label')).toBe(true);
+  });
+
+  it('warns on <textarea> without label', () => {
+    const w = check('<textarea></textarea>');
+    expect(w.some((w) => w.rule === 'form-label')).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// no-distracting
+// ---------------------------------------------------------------------------
+
+describe('no-distracting', () => {
+  it('warns on <marquee>', () => {
+    const w = check('<marquee>scrolling text</marquee>');
+    expect(w).toHaveLength(1);
+    expect(w[0].rule).toBe('no-distracting');
+  });
+
+  it('warns on <blink>', () => {
+    const w = check('<blink>blinking text</blink>');
+    expect(w).toHaveLength(1);
+    expect(w[0].rule).toBe('no-distracting');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// heading-order
+// ---------------------------------------------------------------------------
+
+describe('heading-order', () => {
+  it('warns when heading level is skipped', () => {
+    const w = check('<div><h1>Title</h1><h3>Subtitle</h3></div>');
+    expect(w.some((w) => w.rule === 'heading-order')).toBe(true);
+  });
+
+  it('does not warn on sequential headings', () => {
+    const w = check('<div><h1>Title</h1><h2>Subtitle</h2></div>');
+    expect(w.filter((w) => w.rule === 'heading-order')).toHaveLength(0);
+  });
+
+  it('does not warn on same-level headings', () => {
+    const w = check('<div><h2>A</h2><h2>B</h2></div>');
+    expect(w.filter((w) => w.rule === 'heading-order')).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// aria-role
+// ---------------------------------------------------------------------------
+
+describe('aria-role', () => {
+  it('warns on invalid role', () => {
+    const w = check('<div role="foobar">content</div>');
+    expect(w).toHaveLength(1);
+    expect(w[0].rule).toBe('aria-role');
+    expect(w[0].message).toContain('foobar');
+  });
+
+  it('passes on valid role', () => {
+    const w = check('<div role="button">content</div>');
+    expect(w.filter((w) => w.rule === 'aria-role')).toHaveLength(0);
+  });
+
+  it('passes on role="navigation"', () => {
+    const w = check('<nav role="navigation">nav</nav>');
+    expect(w.filter((w) => w.rule === 'aria-role')).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// no-positive-tabindex
+// ---------------------------------------------------------------------------
+
+describe('no-positive-tabindex', () => {
+  it('warns on positive tabindex', () => {
+    const w = check('<div tabindex="5">content</div>');
+    expect(w.some((w) => w.rule === 'no-positive-tabindex')).toBe(true);
+  });
+
+  it('does not warn on tabindex="0"', () => {
+    const w = check('<div tabindex="0">content</div>');
+    expect(w.filter((w) => w.rule === 'no-positive-tabindex')).toHaveLength(0);
+  });
+
+  it('does not warn on tabindex="-1"', () => {
+    const w = check('<div tabindex="-1">content</div>');
+    expect(w.filter((w) => w.rule === 'no-positive-tabindex')).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// media-captions
+// ---------------------------------------------------------------------------
+
+describe('media-captions', () => {
+  it('warns on <video> without <track>', () => {
+    const w = check('<video src="movie.mp4"></video>');
+    expect(w.some((w) => w.rule === 'media-captions')).toBe(true);
+  });
+
+  it('passes with <track> child', () => {
+    const w = check('<video src="movie.mp4"><track kind="captions" src="subs.vtt"></video>');
+    expect(w.filter((w) => w.rule === 'media-captions')).toHaveLength(0);
+  });
+
+  it('passes with aria-label', () => {
+    const w = check('<video src="movie.mp4" aria-label="Movie clip"></video>');
+    expect(w.filter((w) => w.rule === 'media-captions')).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// anchor-valid
+// ---------------------------------------------------------------------------
+
+describe('anchor-valid', () => {
+  it('warns on <a> without href', () => {
+    const w = check('<a>click</a>');
+    expect(w.some((w) => w.rule === 'anchor-valid')).toBe(true);
+  });
+
+  it('passes with href', () => {
+    const w = check('<a href="/page">click</a>');
+    expect(w.filter((w) => w.rule === 'anchor-valid')).toHaveLength(0);
+  });
+
+  it('passes with bound :href', () => {
+    const w = check('<a :href="url">click</a>');
+    expect(w.filter((w) => w.rule === 'anchor-valid')).toHaveLength(0);
+  });
+
+  it('passes with role="button"', () => {
+    const w = check('<a role="button" @click="go">click</a>');
+    expect(w.filter((w) => w.rule === 'anchor-valid')).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Options: disabling rules
+// ---------------------------------------------------------------------------
+
+describe('options', () => {
+  it('can disable specific rules', () => {
+    const w = check('<img src="photo.jpg">', { disable: ['img-alt'] });
+    expect(w).toHaveLength(0);
+  });
+
+  it('can disable multiple rules', () => {
+    const w = check('<img src="photo.jpg"><marquee>hi</marquee>', {
+      disable: ['img-alt', 'no-distracting'],
+    });
+    expect(w).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Integration: compile() includes a11y warnings
+// ---------------------------------------------------------------------------
+
+describe('compile() a11y integration', () => {
+  it('includes a11y warnings in compile result', () => {
+    const result = compile('<template><img src="photo.jpg"></template>');
+    expect(result.a11y).toHaveLength(1);
+    expect(result.a11y[0].rule).toBe('img-alt');
+  });
+
+  it('returns empty a11y array for accessible templates', () => {
+    const result = compile('<template><img src="photo.jpg" alt="A photo"></template>');
+    expect(result.a11y).toHaveLength(0);
+  });
+
+  it('can disable a11y checking via options', () => {
+    const result = compile('<template><img src="photo.jpg"></template>', {
+      a11y: false,
+    });
+    expect(result.a11y).toHaveLength(0);
+  });
+});
diff --git a/packages/compiler/src/a11y.ts b/packages/compiler/src/a11y.ts
new file mode 100644
index 0000000..6f6588d
--- /dev/null
+++ b/packages/compiler/src/a11y.ts
@@ -0,0 +1,310 @@
+// ============================================================================
+// @matthesketh/utopia-compiler — Compile-time accessibility (a11y) checking
+// ============================================================================
+//
+// Analyzes the template AST for common accessibility violations and emits
+// warnings. Runs as a post-parse pass before codegen.
+//
+// Rules implemented:
+//   1. img-alt          — <img> must have an alt attribute
+//   2. click-keyboard   — Elements with @click should have keyboard support
+//   3. anchor-content   — <a> must have content or aria-label
+//   4. form-label       — <input>/<select>/<textarea> should have id+label or aria-label
+//   5. no-distracting   — <marquee> and <blink> are forbidden
+//   6. heading-order    — Heading levels should not skip (h1 -> h3)
+//   7. aria-role        — aria role values must be valid
+//   8. no-positive-tabindex — tabindex should not be positive
+//   9. media-captions   — <video>/<audio> should have captions/accessible alternatives
+//  10. anchor-valid     — <a> should have an href
+// ============================================================================
+
+import type { TemplateNode, ElementNode, Attribute, Directive } from './template-compiler';
+import { NodeType } from './template-compiler';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface A11yWarning {
+  /** Rule ID (e.g. 'img-alt'). */
+  rule: string;
+  /** Human-readable message. */
+  message: string;
+  /** The element tag that triggered the warning. */
+  tag: string;
+}
+
+export interface A11yOptions {
+  /** Rules to disable (by rule ID). */
+  disable?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Valid ARIA roles (WAI-ARIA 1.2)
+// ---------------------------------------------------------------------------
+
+const VALID_ARIA_ROLES = new Set([
+  'alert', 'alertdialog', 'application', 'article', 'banner', 'button',
+  'cell', 'checkbox', 'columnheader', 'combobox', 'complementary',
+  'contentinfo', 'definition', 'dialog', 'directory', 'document',
+  'feed', 'figure', 'form', 'grid', 'gridcell', 'group', 'heading',
+  'img', 'link', 'list', 'listbox', 'listitem', 'log', 'main',
+  'marquee', 'math', 'menu', 'menubar', 'menuitem', 'menuitemcheckbox',
+  'menuitemradio', 'meter', 'navigation', 'none', 'note', 'option',
+  'presentation', 'progressbar', 'radio', 'radiogroup', 'region',
+  'row', 'rowgroup', 'rowheader', 'scrollbar', 'search', 'searchbox',
+  'separator', 'slider', 'spinbutton', 'status', 'switch', 'tab',
+  'table', 'tablist', 'tabpanel', 'term', 'textbox', 'timer',
+  'toolbar', 'tooltip', 'tree', 'treegrid', 'treeitem',
+]);
+
+// Elements that are natively interactive (have implicit keyboard support).
+const INTERACTIVE_ELEMENTS = new Set([
+  'a', 'button', 'input', 'select', 'textarea', 'details', 'summary',
+]);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getAttr(node: ElementNode, name: string): Attribute | undefined {
+  return node.attrs.find((a) => a.name === name);
+}
+
+function hasAttr(node: ElementNode, name: string): boolean {
+  return node.attrs.some((a) => a.name === name);
+}
+
+function hasDirective(node: ElementNode, kind: string, arg?: string): boolean {
+  return node.directives.some(
+    (d) => d.kind === kind && (arg === undefined || d.arg === arg),
+  );
+}
+
+function hasBoundAttr(node: ElementNode, name: string): boolean {
+  return node.directives.some((d) => d.kind === 'bind' && d.arg === name);
+}
+
+function hasTextContent(node: ElementNode): boolean {
+  return node.children.some(
+    (c) =>
+      (c.type === NodeType.Text && c.content.trim() !== '') ||
+      c.type === NodeType.Interpolation,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Rule implementations
+// ---------------------------------------------------------------------------
+
+type RuleCheck = (node: ElementNode, warnings: A11yWarning[], ctx: WalkContext) => void;
+
+interface WalkContext {
+  lastHeadingLevel: number;
+}
+
+const rules: Record<string, RuleCheck> = {
+  'img-alt'(node, warnings) {
+    if (node.tag !== 'img') return;
+    if (hasAttr(node, 'alt') || hasBoundAttr(node, 'alt')) return;
+    // aria-label or aria-labelledby are acceptable alternatives.
+    if (hasAttr(node, 'aria-label') || hasAttr(node, 'aria-labelledby')) return;
+    // Decorative images can use role="presentation" or role="none".
+    const role = getAttr(node, 'role');
+    if (role && (role.value === 'presentation' || role.value === 'none')) return;
+    warnings.push({
+      rule: 'img-alt',
+      message: '<img> element must have an alt attribute',
+      tag: node.tag,
+    });
+  },
+
+  'click-keyboard'(node, warnings) {
+    const hasClick = hasDirective(node, 'on', 'click');
+    if (!hasClick) return;
+    // Interactive elements already have keyboard support.
+    if (INTERACTIVE_ELEMENTS.has(node.tag)) return;
+    // Check for role="button" or explicit keyboard handlers.
+    const hasKeyboard =
+      hasDirective(node, 'on', 'keydown') ||
+      hasDirective(node, 'on', 'keyup') ||
+      hasDirective(node, 'on', 'keypress');
+    const role = getAttr(node, 'role');
+    const hasInteractiveRole = role && (role.value === 'button' || role.value === 'link');
+    if (!hasKeyboard && !hasInteractiveRole) {
+      warnings.push({
+        rule: 'click-keyboard',
+        message: `<${node.tag}> with @click handler should also have a keyboard event handler or role="button"`,
+        tag: node.tag,
+      });
+    }
+    // Also check for tabindex if non-interactive.
+    if (!hasAttr(node, 'tabindex') && !hasBoundAttr(node, 'tabindex')) {
+      warnings.push({
+        rule: 'click-keyboard',
+        message: `<${node.tag}> with @click handler should have tabindex="0" for keyboard accessibility`,
+        tag: node.tag,
+      });
+    }
+  },
+
+  'anchor-content'(node, warnings) {
+    if (node.tag !== 'a') return;
+    if (hasTextContent(node)) return;
+    if (hasAttr(node, 'aria-label') || hasAttr(node, 'aria-labelledby')) return;
+    // Check if it has child elements (could be an icon).
+    const hasChildElements = node.children.some(
+      (c) => c.type === NodeType.Element,
+    );
+    if (hasChildElements) return; // Assume child elements provide content.
+    warnings.push({
+      rule: 'anchor-content',
+      message: '<a> element must have content, aria-label, or aria-labelledby',
+      tag: node.tag,
+    });
+  },
+
+  'form-label'(node, warnings) {
+    const formElements = new Set(['input', 'select', 'textarea']);
+    if (!formElements.has(node.tag)) return;
+    // Hidden inputs don't need labels.
+    const type = getAttr(node, 'type');
+    if (type && type.value === 'hidden') return;
+    // Check for labelling mechanisms.
+    if (hasAttr(node, 'aria-label') || hasAttr(node, 'aria-labelledby')) return;
+    if (hasAttr(node, 'id')) return; // Assumes a matching <label for="..."> exists.
+    if (hasAttr(node, 'title')) return;
+    warnings.push({
+      rule: 'form-label',
+      message: `<${node.tag}> should have an id (with matching <label>), aria-label, or aria-labelledby`,
+      tag: node.tag,
+    });
+  },
+
+  'no-distracting'(node, warnings) {
+    if (node.tag === 'marquee' || node.tag === 'blink') {
+      warnings.push({
+        rule: 'no-distracting',
+        message: `<${node.tag}> is distracting and inaccessible — do not use`,
+        tag: node.tag,
+      });
+    }
+  },
+
+  'heading-order'(node, warnings, ctx) {
+    const match = node.tag.match(/^h([1-6])$/);
+    if (!match) return;
+    const level = parseInt(match[1], 10);
+    if (ctx.lastHeadingLevel > 0 && level > ctx.lastHeadingLevel + 1) {
+      warnings.push({
+        rule: 'heading-order',
+        message: `Heading level <${node.tag}> skips from <h${ctx.lastHeadingLevel}> — headings should not skip levels`,
+        tag: node.tag,
+      });
+    }
+    ctx.lastHeadingLevel = level;
+  },
+
+  'aria-role'(node, warnings) {
+    const role = getAttr(node, 'role');
+    if (!role || !role.value) return;
+    if (!VALID_ARIA_ROLES.has(role.value)) {
+      warnings.push({
+        rule: 'aria-role',
+        message: `Invalid ARIA role "${role.value}" on <${node.tag}>`,
+        tag: node.tag,
+      });
+    }
+  },
+
+  'no-positive-tabindex'(node, warnings) {
+    const tabindex = getAttr(node, 'tabindex');
+    if (!tabindex || !tabindex.value) return;
+    const val = parseInt(tabindex.value, 10);
+    if (!isNaN(val) && val > 0) {
+      warnings.push({
+        rule: 'no-positive-tabindex',
+        message: `Avoid positive tabindex="${tabindex.value}" — it disrupts natural tab order`,
+        tag: node.tag,
+      });
+    }
+  },
+
+  'media-captions'(node, warnings) {
+    if (node.tag !== 'video' && node.tag !== 'audio') return;
+    // Check for <track> child element.
+    const hasTrack = node.children.some(
+      (c) => c.type === NodeType.Element && (c as ElementNode).tag === 'track',
+    );
+    if (hasTrack) return;
+    if (hasAttr(node, 'aria-label') || hasAttr(node, 'aria-labelledby')) return;
+    warnings.push({
+      rule: 'media-captions',
+      message: `<${node.tag}> should have a <track> element for captions`,
+      tag: node.tag,
+    });
+  },
+
+  'anchor-valid'(node, warnings) {
+    if (node.tag !== 'a') return;
+    if (hasAttr(node, 'href') || hasBoundAttr(node, 'href')) return;
+    // Allow anchors that act as buttons via role.
+    const role = getAttr(node, 'role');
+    if (role && role.value === 'button') return;
+    warnings.push({
+      rule: 'anchor-valid',
+      message: '<a> element should have an href attribute',
+      tag: node.tag,
+    });
+  },
+};
+
+// ---------------------------------------------------------------------------
+// AST walker
+// ---------------------------------------------------------------------------
+
+function walkNodes(
+  nodes: TemplateNode[],
+  enabledRules: RuleCheck[],
+  warnings: A11yWarning[],
+  ctx: WalkContext,
+): void {
+  for (const node of nodes) {
+    if (node.type === NodeType.Element) {
+      for (const rule of enabledRules) {
+        rule(node, warnings, ctx);
+      }
+      walkNodes(node.children, enabledRules, warnings, ctx);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Check a parsed template AST for accessibility issues.
+ *
+ * Returns an array of warnings. An empty array means no issues found.
+ *
+ * ```ts
+ * const ast = parseTemplate('<img src="photo.jpg">');
+ * const warnings = checkA11y(ast);
+ * // [{ rule: 'img-alt', message: '...', tag: 'img' }]
+ * ```
+ */
+export function checkA11y(
+  ast: TemplateNode[],
+  options?: A11yOptions,
+): A11yWarning[] {
+  const disabled = new Set(options?.disable ?? []);
+  const enabledRules = Object.entries(rules)
+    .filter(([id]) => !disabled.has(id))
+    .map(([, fn]) => fn);
+
+  const warnings: A11yWarning[] = [];
+  const ctx: WalkContext = { lastHeadingLevel: 0 };
+  walkNodes(ast, enabledRules, warnings, ctx);
+  return warnings;
+}
diff --git a/packages/compiler/src/index.ts b/packages/compiler/src/index.ts
index 3ee00e6..33861aa 100644
--- a/packages/compiler/src/index.ts
+++ b/packages/compiler/src/index.ts
@@ -18,10 +18,12 @@ export {
   type StyleCompileOptions,
   type StyleCompileResult,
 } from './style-compiler';
+export { checkA11y, type A11yWarning, type A11yOptions } from './a11y';
 
 import { parse } from './parser';
-import { compileTemplate } from './template-compiler';
+import { compileTemplate, parseTemplate } from './template-compiler';
 import { compileStyle, generateScopeId } from './style-compiler';
+import { checkA11y, type A11yWarning, type A11yOptions } from './a11y';
 
 // ---- Public types ----------------------------------------------------------
 
@@ -30,6 +32,8 @@ export interface CompileOptions {
   filename?: string;
   /** Override the scope ID for testing. */
   scopeId?: string;
+  /** Accessibility checking options. Pass false to disable entirely. */
+  a11y?: A11yOptions | false;
 }
 
 export interface CompileResult {
@@ -39,6 +43,8 @@ export interface CompileResult {
   css: string;
   /** Source map (reserved for future use). */
   map?: unknown;
+  /** Accessibility warnings from template analysis. */
+  a11y: A11yWarning[];
 }
 
 // ---- Main compile function -------------------------------------------------
@@ -83,13 +89,20 @@ export function compile(source: string, options: CompileOptions = {}): CompileRe
     scopeId = styleResult.scopeId;
   }
 
-  // 3. Compile the template block.
+  // 3. Compile the template block and run a11y checks.
   let renderModule = '';
+  let a11yWarnings: A11yWarning[] = [];
   if (descriptor.template) {
     const templateResult = compileTemplate(descriptor.template.content, {
       scopeId: scopeId ?? undefined,
     });
     renderModule = templateResult.code;
+
+    // Run a11y checks unless explicitly disabled.
+    if (options.a11y !== false) {
+      const ast = parseTemplate(descriptor.template.content);
+      a11yWarnings = checkA11y(ast, options.a11y ?? undefined);
+    }
   }
 
   // 4. Assemble the final JavaScript module.
@@ -129,7 +142,7 @@ export function compile(source: string, options: CompileOptions = {}): CompileRe
 
   const code = parts.join('\n\n') + '\n';
 
-  return { code, css };
+  return { code, css, a11y: a11yWarnings };
 }
 
 // ---- Internal helpers -------------------------------------------------------

From 5343a743905fbb2c8d87b24e02338ea603ac5499 Mon Sep 17 00:00:00 2001
From: Matt Hesketh <matt@heskethwebdesign.co.uk>
Date: Wed, 11 Feb 2026 17:55:52 +0000
Subject: [PATCH 2/2] style: format with prettier

---
 packages/compiler/src/a11y.ts | 106 ++++++++++++++++++++++++++--------
 1 file changed, 81 insertions(+), 25 deletions(-)

diff --git a/packages/compiler/src/a11y.ts b/packages/compiler/src/a11y.ts
index 6f6588d..601cc50 100644
--- a/packages/compiler/src/a11y.ts
+++ b/packages/compiler/src/a11y.ts
@@ -44,23 +44,87 @@ export interface A11yOptions {
 // ---------------------------------------------------------------------------
 
 const VALID_ARIA_ROLES = new Set([
-  'alert', 'alertdialog', 'application', 'article', 'banner', 'button',
-  'cell', 'checkbox', 'columnheader', 'combobox', 'complementary',
-  'contentinfo', 'definition', 'dialog', 'directory', 'document',
-  'feed', 'figure', 'form', 'grid', 'gridcell', 'group', 'heading',
-  'img', 'link', 'list', 'listbox', 'listitem', 'log', 'main',
-  'marquee', 'math', 'menu', 'menubar', 'menuitem', 'menuitemcheckbox',
-  'menuitemradio', 'meter', 'navigation', 'none', 'note', 'option',
-  'presentation', 'progressbar', 'radio', 'radiogroup', 'region',
-  'row', 'rowgroup', 'rowheader', 'scrollbar', 'search', 'searchbox',
-  'separator', 'slider', 'spinbutton', 'status', 'switch', 'tab',
-  'table', 'tablist', 'tabpanel', 'term', 'textbox', 'timer',
-  'toolbar', 'tooltip', 'tree', 'treegrid', 'treeitem',
+  'alert',
+  'alertdialog',
+  'application',
+  'article',
+  'banner',
+  'button',
+  'cell',
+  'checkbox',
+  'columnheader',
+  'combobox',
+  'complementary',
+  'contentinfo',
+  'definition',
+  'dialog',
+  'directory',
+  'document',
+  'feed',
+  'figure',
+  'form',
+  'grid',
+  'gridcell',
+  'group',
+  'heading',
+  'img',
+  'link',
+  'list',
+  'listbox',
+  'listitem',
+  'log',
+  'main',
+  'marquee',
+  'math',
+  'menu',
+  'menubar',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'meter',
+  'navigation',
+  'none',
+  'note',
+  'option',
+  'presentation',
+  'progressbar',
+  'radio',
+  'radiogroup',
+  'region',
+  'row',
+  'rowgroup',
+  'rowheader',
+  'scrollbar',
+  'search',
+  'searchbox',
+  'separator',
+  'slider',
+  'spinbutton',
+  'status',
+  'switch',
+  'tab',
+  'table',
+  'tablist',
+  'tabpanel',
+  'term',
+  'textbox',
+  'timer',
+  'toolbar',
+  'tooltip',
+  'tree',
+  'treegrid',
+  'treeitem',
 ]);
 
 // Elements that are natively interactive (have implicit keyboard support).
 const INTERACTIVE_ELEMENTS = new Set([
-  'a', 'button', 'input', 'select', 'textarea', 'details', 'summary',
+  'a',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  'details',
+  'summary',
 ]);
 
 // ---------------------------------------------------------------------------
@@ -76,9 +140,7 @@ function hasAttr(node: ElementNode, name: string): boolean {
 }
 
 function hasDirective(node: ElementNode, kind: string, arg?: string): boolean {
-  return node.directives.some(
-    (d) => d.kind === kind && (arg === undefined || d.arg === arg),
-  );
+  return node.directives.some((d) => d.kind === kind && (arg === undefined || d.arg === arg));
 }
 
 function hasBoundAttr(node: ElementNode, name: string): boolean {
@@ -88,8 +150,7 @@ function hasBoundAttr(node: ElementNode, name: string): boolean {
 function hasTextContent(node: ElementNode): boolean {
   return node.children.some(
     (c) =>
-      (c.type === NodeType.Text && c.content.trim() !== '') ||
-      c.type === NodeType.Interpolation,
+      (c.type === NodeType.Text && c.content.trim() !== '') || c.type === NodeType.Interpolation,
   );
 }
 
@@ -153,9 +214,7 @@ const rules: Record<string, RuleCheck> = {
     if (hasTextContent(node)) return;
     if (hasAttr(node, 'aria-label') || hasAttr(node, 'aria-labelledby')) return;
     // Check if it has child elements (could be an icon).
-    const hasChildElements = node.children.some(
-      (c) => c.type === NodeType.Element,
-    );
+    const hasChildElements = node.children.some((c) => c.type === NodeType.Element);
     if (hasChildElements) return; // Assume child elements provide content.
     warnings.push({
       rule: 'anchor-content',
@@ -294,10 +353,7 @@ function walkNodes(
  * // [{ rule: 'img-alt', message: '...', tag: 'img' }]
  * ```
  */
-export function checkA11y(
-  ast: TemplateNode[],
-  options?: A11yOptions,
-): A11yWarning[] {
+export function checkA11y(ast: TemplateNode[], options?: A11yOptions): A11yWarning[] {
   const disabled = new Set(options?.disable ?? []);
   const enabledRules = Object.entries(rules)
     .filter(([id]) => !disabled.has(id))