From 9969adca7217018e0c69b8346c0d10e496795109 Mon Sep 17 00:00:00 2001
From: Josh Knapp <jknapp85@gmail.com>
Date: Sun, 12 Jul 2026 14:19:01 -0700
Subject: [PATCH] a11y: exported semantics (forms/rating/nav/iframe/icons)

- InputField/TextareaField/ContactForm: every control gets a
  deterministic id (slugId() in utils/escape.ts, derived from the
  field's name/label + index for ContactForm's looped fields -- no
  Math.random) with a matching <label for=>; fields with no visible
  label get an aria-label from the placeholder/name instead.
- StarRating: wrapped in role="img" aria-label="Rating: N out of M",
  individual star glyphs marked aria-hidden.
- Navbar: the mobile hamburger toggle gets aria-label="Toggle
  navigation menu", aria-controls="navbar-links", and aria-expanded
  wired to flip true/false in the inline onclick handler.
- VideoBlock and MapEmbed: every exported <iframe> gets a title
  (generic "Embedded video", or "Map of {address}" for MapEmbed).
- Decorative Font Awesome icons (ContentSlider arrows already covered
  in the prior commit; SocialLinks, SearchBar, Testimonials stars) are
  aria-hidden; SocialLinks' icon-only links get an aria-label naming
  the platform alongside the existing title tooltip.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../components/basic/Navbar.toHtml.test.ts    | 28 ++++++++++++++++++
 craft/src/components/basic/Navbar.tsx         |  9 ++++--
 .../components/basic/SearchBar.toHtml.test.ts | 13 +++++++++
 craft/src/components/basic/SearchBar.tsx      |  4 +--
 .../basic/SocialLinks.toHtml.test.ts          | 16 ++++++++++
 craft/src/components/basic/SocialLinks.tsx    |  6 +++-
 .../basic/StarRating.toHtml.test.ts           | 23 +++++++++++++++
 craft/src/components/basic/StarRating.tsx     | 11 ++++---
 .../forms/ContactForm.toHtml.test.ts          | 25 ++++++++++++++++
 craft/src/components/forms/ContactForm.tsx    | 15 ++++++----
 .../forms/InputField.toHtml.test.ts           | 29 +++++++++++++++++++
 craft/src/components/forms/InputField.tsx     | 12 ++++++--
 .../forms/TextareaField.toHtml.test.ts        | 21 ++++++++++++++
 craft/src/components/forms/TextareaField.tsx  | 12 ++++++--
 .../components/media/MapEmbed.toHtml.test.ts  | 16 ++++++++++
 craft/src/components/media/MapEmbed.tsx       |  2 +-
 .../media/VideoBlock.toHtml.test.ts           | 12 ++++++++
 craft/src/components/media/VideoBlock.tsx     |  4 +--
 .../sections/Testimonials.toHtml.test.ts      |  9 ++++++
 .../src/components/sections/Testimonials.tsx  |  4 +--
 craft/src/utils/escape.ts                     | 11 +++++++
 21 files changed, 255 insertions(+), 27 deletions(-)
 create mode 100644 craft/src/components/basic/Navbar.toHtml.test.ts
 create mode 100644 craft/src/components/basic/SearchBar.toHtml.test.ts
 create mode 100644 craft/src/components/basic/SocialLinks.toHtml.test.ts
 create mode 100644 craft/src/components/basic/StarRating.toHtml.test.ts
 create mode 100644 craft/src/components/forms/InputField.toHtml.test.ts
 create mode 100644 craft/src/components/forms/TextareaField.toHtml.test.ts
 create mode 100644 craft/src/components/media/MapEmbed.toHtml.test.ts

diff --git a/craft/src/components/basic/Navbar.toHtml.test.ts b/craft/src/components/basic/Navbar.toHtml.test.ts
new file mode 100644
index 0000000..ed46235
--- /dev/null
+++ b/craft/src/components/basic/Navbar.toHtml.test.ts
@@ -0,0 +1,28 @@
+import { describe, test, expect } from 'vitest';
+import { Navbar } from './Navbar';
+
+const toHtml = (Navbar as any).toHtml;
+
+describe('Navbar.toHtml hamburger accessibility (F2.3)', () => {
+  test('mobile toggle button has an accessible name, aria-expanded, and aria-controls', () => {
+    const { html } = toHtml({ showMobileMenu: true }, '');
+    expect(html).toMatch(/class="navbar-hamburger"[^>]*aria-label="Toggle navigation menu"/);
+    expect(html).toMatch(/aria-expanded="false"/);
+    expect(html).toMatch(/aria-controls="navbar-links"/);
+  });
+
+  test('aria-controls target id exists on the links container', () => {
+    const { html } = toHtml({ showMobileMenu: true }, '');
+    expect(html).toContain('id="navbar-links"');
+  });
+
+  test('toggle script flips aria-expanded on click', () => {
+    const { html } = toHtml({ showMobileMenu: true }, '');
+    expect(html).toMatch(/setAttribute\(['"]aria-expanded['"]/);
+  });
+
+  test('no mobile menu: no hamburger button emitted', () => {
+    const { html } = toHtml({ showMobileMenu: false }, '');
+    expect(html).not.toContain('navbar-hamburger');
+  });
+});
diff --git a/craft/src/components/basic/Navbar.tsx b/craft/src/components/basic/Navbar.tsx
index 77c1e49..17b510a 100644
--- a/craft/src/components/basic/Navbar.tsx
+++ b/craft/src/components/basic/Navbar.tsx
@@ -264,9 +264,12 @@ Navbar.craft = {
     return `<a href="${escapeAttr(safeUrl(link.href || "#"))}"${target}${linkStyle ? ` style="${linkStyle}"` : ''}>${escapeHtml(link.text)}</a>`;
   }).join('\n      ');
 
-  // Hamburger HTML for mobile
+  // Hamburger HTML for mobile. The toggle needs an accessible name (there's
+  // no visible text, just three bars) and must report its open/closed state
+  // via aria-expanded, kept in sync with the .navbar-open class by the
+  // inline onclick handler.
   const hamburgerHtml = mobile
-    ? `\n    <button class="navbar-hamburger" onclick="this.parentElement.querySelector('.navbar-links').classList.toggle('navbar-open')" style="display:none;background:none;border:none;cursor:pointer;padding:4px;flex-direction:column;gap:4px">
+    ? `\n    <button class="navbar-hamburger" aria-label="Toggle navigation menu" aria-expanded="false" aria-controls="navbar-links" onclick="var m=this.parentElement.querySelector('.navbar-links');var open=m.classList.toggle('navbar-open');this.setAttribute('aria-expanded', open ? 'true' : 'false');" style="display:none;background:none;border:none;cursor:pointer;padding:4px;flex-direction:column;gap:4px">
       <span style="display:block;width:24px;height:2px;background-color:${escapeAttr(textCol)}"></span>
       <span style="display:block;width:24px;height:2px;background-color:${escapeAttr(textCol)}"></span>
       <span style="display:block;width:24px;height:2px;background-color:${escapeAttr(textCol)}"></span>
@@ -305,7 +308,7 @@ Navbar.craft = {
     html: `${hoverCss}
 <nav${navStyle ? ` style="${navStyle}${mobile ? ';position:relative' : ''}"` : ''}>
   ${logoHtml}${hamburgerHtml}
-  <div class="navbar-links" style="display:flex;align-items:center;gap:24px">
+  <div class="navbar-links" id="navbar-links" style="display:flex;align-items:center;gap:24px">
       ${linksHtmlWithClass}
   </div>
 </nav>`,
diff --git a/craft/src/components/basic/SearchBar.toHtml.test.ts b/craft/src/components/basic/SearchBar.toHtml.test.ts
new file mode 100644
index 0000000..acf29a1
--- /dev/null
+++ b/craft/src/components/basic/SearchBar.toHtml.test.ts
@@ -0,0 +1,13 @@
+import { describe, test, expect } from 'vitest';
+import { SearchBar } from './SearchBar';
+
+const toHtml = (SearchBar as any).toHtml;
+
+describe('SearchBar.toHtml decorative icons (F2.5)', () => {
+  test('the input-adjacent search icon is aria-hidden', () => {
+    const { html } = toHtml({}, '');
+    const icons = html.match(/<i class="fa fa-search"[^>]*>/g) || [];
+    expect(icons.length).toBeGreaterThan(0);
+    icons.forEach((tag: string) => expect(tag).toContain('aria-hidden="true"'));
+  });
+});
diff --git a/craft/src/components/basic/SearchBar.tsx b/craft/src/components/basic/SearchBar.tsx
index 5000a20..78030a1 100644
--- a/craft/src/components/basic/SearchBar.tsx
+++ b/craft/src/components/basic/SearchBar.tsx
@@ -130,13 +130,13 @@ SearchBar.craft = {
   const inputStyleStr = `width:100%;padding:12px 16px 12px 40px;font-size:15px;font-family:Inter,sans-serif;border:1px solid #d1d5db;border-radius:${showButton ? '8px 0 0 8px' : '8px'};background-color:#ffffff;color:#1f2937;outline:none;box-sizing:border-box`;
 
   const btnHtml = showButton
-    ? `<button type="submit" style="padding:12px 20px;font-size:15px;font-weight:600;font-family:Inter,sans-serif;color:#ffffff;background-color:#3b82f6;border:none;border-radius:0 8px 8px 0;cursor:pointer;white-space:nowrap;display:flex;align-items:center;gap:6px"><i class="fa fa-search" style="font-size:13px"></i>${escapeHtml(buttonText)}</button>`
+    ? `<button type="submit" style="padding:12px 20px;font-size:15px;font-weight:600;font-family:Inter,sans-serif;color:#ffffff;background-color:#3b82f6;border:none;border-radius:0 8px 8px 0;cursor:pointer;white-space:nowrap;display:flex;align-items:center;gap:6px"><i class="fa fa-search" style="font-size:13px" aria-hidden="true"></i>${escapeHtml(buttonText)}</button>`
     : '';
 
   return {
     html: `<form role="search"${formStyle ? ` style="${formStyle}"` : ''}>
   <div style="position:relative;flex:1">
-    <i class="fa fa-search" style="position:absolute;left:14px;top:50%;transform:translateY(-50%);color:#9ca3af;font-size:14px;pointer-events:none"></i>
+    <i class="fa fa-search" style="position:absolute;left:14px;top:50%;transform:translateY(-50%);color:#9ca3af;font-size:14px;pointer-events:none" aria-hidden="true"></i>
     <input type="search" placeholder="${escapeAttr(placeholder)}" style="${inputStyleStr}" />
   </div>
   ${btnHtml}
diff --git a/craft/src/components/basic/SocialLinks.toHtml.test.ts b/craft/src/components/basic/SocialLinks.toHtml.test.ts
new file mode 100644
index 0000000..a415453
--- /dev/null
+++ b/craft/src/components/basic/SocialLinks.toHtml.test.ts
@@ -0,0 +1,16 @@
+import { describe, test, expect } from 'vitest';
+import { SocialLinks } from './SocialLinks';
+
+const toHtml = (SocialLinks as any).toHtml;
+
+describe('SocialLinks.toHtml accessibility (F2.5)', () => {
+  test('icon-only links get an aria-label naming the platform', () => {
+    const { html } = toHtml({ links: [{ platform: 'facebook', url: 'https://fb.example/x' }] }, '');
+    expect(html).toMatch(/<a[^>]*aria-label="Facebook"/);
+  });
+
+  test('the icon glyph itself is aria-hidden', () => {
+    const { html } = toHtml({ links: [{ platform: 'twitter', url: '#' }] }, '');
+    expect(html).toMatch(/<i class="fa fa-twitter"[^>]*aria-hidden="true"/);
+  });
+});
diff --git a/craft/src/components/basic/SocialLinks.tsx b/craft/src/components/basic/SocialLinks.tsx
index 61e7670..09cd212 100644
--- a/craft/src/components/basic/SocialLinks.tsx
+++ b/craft/src/components/basic/SocialLinks.tsx
@@ -204,7 +204,11 @@ SocialLinks.craft = {
     if (hasBg) {
       aStyle += `;${getShapeStr()}`;
     }
-    return `<a href="${escapeAttr(safeUrl(link.url || '#'))}" target="_blank" rel="noopener noreferrer" title="${escapeAttr(title)}" style="${aStyle}"><i class="fa ${escapeAttr(iconClass)}" style="font-size:${iconSize}"></i></a>`;
+    // The link's only content is the icon glyph, so the glyph itself is
+    // aria-hidden and the accessible name lives on the link (aria-label,
+    // mirroring the existing `title` tooltip since title support in
+    // screen readers is inconsistent).
+    return `<a href="${escapeAttr(safeUrl(link.url || '#'))}" target="_blank" rel="noopener noreferrer" title="${escapeAttr(title)}" aria-label="${escapeAttr(title)}" style="${aStyle}"><i class="fa ${escapeAttr(iconClass)}" style="font-size:${iconSize}" aria-hidden="true"></i></a>`;
   }).join('\n  ');
 
   return {
diff --git a/craft/src/components/basic/StarRating.toHtml.test.ts b/craft/src/components/basic/StarRating.toHtml.test.ts
new file mode 100644
index 0000000..405c42d
--- /dev/null
+++ b/craft/src/components/basic/StarRating.toHtml.test.ts
@@ -0,0 +1,23 @@
+import { describe, test, expect } from 'vitest';
+import { StarRating } from './StarRating';
+
+const toHtml = (StarRating as any).toHtml;
+
+describe('StarRating.toHtml accessibility (F2.2)', () => {
+  test('wrapper has role="img" and a "Rating: N out of maxStars" aria-label', () => {
+    const { html } = toHtml({ rating: 4.5, maxStars: 5 }, '');
+    expect(html).toMatch(/<span role="img" aria-label="Rating: 4\.5 out of 5"/);
+  });
+
+  test('individual star glyphs are aria-hidden', () => {
+    const { html } = toHtml({ rating: 3, maxStars: 5 }, '');
+    const glyphs = html.match(/<i class="fa fa-star"[^>]*>/g) || [];
+    expect(glyphs.length).toBeGreaterThan(0);
+    glyphs.forEach((tag: string) => expect(tag).toContain('aria-hidden="true"'));
+  });
+
+  test('respects custom maxStars in the aria-label', () => {
+    const { html } = toHtml({ rating: 2, maxStars: 10 }, '');
+    expect(html).toContain('aria-label="Rating: 2 out of 10"');
+  });
+});
diff --git a/craft/src/components/basic/StarRating.tsx b/craft/src/components/basic/StarRating.tsx
index 8159369..6afc986 100644
--- a/craft/src/components/basic/StarRating.tsx
+++ b/craft/src/components/basic/StarRating.tsx
@@ -112,15 +112,18 @@ StarRating.craft = {
   let starsHtml = '';
   for (let i = 1; i <= maxStars; i++) {
     if (i <= Math.floor(rating)) {
-      starsHtml += `<i class="fa fa-star" style="color:${filledColor};font-size:${size}"></i>`;
+      starsHtml += `<i class="fa fa-star" style="color:${filledColor};font-size:${size}" aria-hidden="true"></i>`;
     } else if (i === Math.ceil(rating) && rating % 1 !== 0) {
-      starsHtml += `<span style="position:relative;display:inline-block;font-size:${size}"><i class="fa fa-star" style="color:${emptyColor}"></i><span style="position:absolute;left:0;top:0;overflow:hidden;width:50%"><i class="fa fa-star" style="color:${filledColor}"></i></span></span>`;
+      starsHtml += `<span style="position:relative;display:inline-block;font-size:${size}" aria-hidden="true"><i class="fa fa-star" style="color:${emptyColor}"></i><span style="position:absolute;left:0;top:0;overflow:hidden;width:50%"><i class="fa fa-star" style="color:${filledColor}"></i></span></span>`;
     } else {
-      starsHtml += `<i class="fa fa-star" style="color:${emptyColor};font-size:${size}"></i>`;
+      starsHtml += `<i class="fa fa-star" style="color:${emptyColor};font-size:${size}" aria-hidden="true"></i>`;
     }
   }
 
+  // The star glyphs convey nothing to assistive tech on their own -- wrap
+  // in role="img" with a textual equivalent, and hide the decorative glyphs
+  // themselves (aria-hidden above) so AT doesn't announce each icon.
   return {
-    html: `<span${wrapperStyle ? ` style="${wrapperStyle}"` : ''}>${starsHtml}</span>`,
+    html: `<span role="img" aria-label="Rating: ${rating} out of ${maxStars}"${wrapperStyle ? ` style="${wrapperStyle}"` : ''}>${starsHtml}</span>`,
   };
 };
diff --git a/craft/src/components/forms/ContactForm.toHtml.test.ts b/craft/src/components/forms/ContactForm.toHtml.test.ts
index e64dd22..8f0f7be 100644
--- a/craft/src/components/forms/ContactForm.toHtml.test.ts
+++ b/craft/src/components/forms/ContactForm.toHtml.test.ts
@@ -63,3 +63,28 @@ describe('ContactForm.toHtml successMessage', () => {
     expect(html).not.toContain('onerror="alert(1)"');
   });
 });
+
+describe('ContactForm.toHtml accessibility (F2.1)', () => {
+  const fields = [
+    { type: 'text' as const, label: 'Name', name: 'name', placeholder: 'Your name', required: true },
+    { type: 'email' as const, label: 'Email', name: 'email', placeholder: 'you@example.com', required: true },
+  ];
+
+  test('each field label for= matches its control id=, and ids are unique', () => {
+    const { html } = toHtml({ fields }, '');
+    const labelIds = [...html.matchAll(/<label for="([^"]+)"/g)].map((m) => m[1]);
+    const controlIds = [...html.matchAll(/<(?:input|textarea|select) id="([^"]+)"/g)].map((m) => m[1]);
+    expect(labelIds.length).toBe(2);
+    expect(controlIds.length).toBe(2);
+    expect(labelIds).toEqual(controlIds);
+    expect(new Set(controlIds).size).toBe(2);
+  });
+
+  test('ids are deterministic across repeated calls with the same fields', () => {
+    const { html: html1 } = toHtml({ fields }, '');
+    const { html: html2 } = toHtml({ fields }, '');
+    const ids1 = [...html1.matchAll(/<input id="([^"]+)"/g)].map((m) => m[1]);
+    const ids2 = [...html2.matchAll(/<input id="([^"]+)"/g)].map((m) => m[1]);
+    expect(ids1).toEqual(ids2);
+  });
+});
diff --git a/craft/src/components/forms/ContactForm.tsx b/craft/src/components/forms/ContactForm.tsx
index 7295b63..327d69c 100644
--- a/craft/src/components/forms/ContactForm.tsx
+++ b/craft/src/components/forms/ContactForm.tsx
@@ -2,7 +2,7 @@ import React, { CSSProperties } from 'react';
 import { useNode, UserComponent } from '@craftjs/core';
 import { cssPropsToString } from '../../utils/style-helpers';
 import { relayFormWiring } from '../../utils/form-relay-wiring';
-import { escapeHtml, escapeAttr } from '../../utils/escape';
+import { escapeHtml, escapeAttr, slugId } from '../../utils/escape';
 
 interface ContactFormField {
   type: 'text' | 'email' | 'tel' | 'textarea' | 'select';
@@ -180,18 +180,21 @@ ContactForm.craft = {
   const inputBorder = props.inputBorder || '#d1d5db';
   const inputStyleStr = `width:100%;padding:10px 14px;font-size:14px;font-family:Inter,sans-serif;border:1px solid ${inputBorder};border-radius:6px;background-color:${inputBg};color:#1f2937;box-sizing:border-box;outline:none`;
 
-  const fieldsHtml = (props.fields || defaultFields).map((field) => {
+  const fieldsHtml = (props.fields || defaultFields).map((field, i) => {
     const reqStar = field.required ? '<span style="color:#ef4444;margin-left:2px">*</span>' : '';
-    const labelHtml = `<label style="font-size:14px;font-weight:500;color:${labelColor}">${escapeHtml(field.label)}${reqStar}</label>`;
+    // Deterministic id: index + slugified name, so repeated fields with the
+    // same name (or no name) still get unique, stable ids -- no Math.random.
+    const fieldId = `field-${i}-${slugId(field.name)}`;
+    const labelHtml = `<label for="${escapeAttr(fieldId)}" style="font-size:14px;font-weight:500;color:${labelColor}">${escapeHtml(field.label)}${reqStar}</label>`;
     const reqAttr = field.required ? ' required' : '';
     let inputHtml = '';
     if (field.type === 'textarea') {
-      inputHtml = `<textarea name="${escapeAttr(field.name)}" placeholder="${escapeAttr(field.placeholder)}" rows="4" style="${inputStyleStr};resize:vertical"${reqAttr}></textarea>`;
+      inputHtml = `<textarea id="${escapeAttr(fieldId)}" name="${escapeAttr(field.name)}" placeholder="${escapeAttr(field.placeholder)}" rows="4" style="${inputStyleStr};resize:vertical"${reqAttr}></textarea>`;
     } else if (field.type === 'select') {
       const opts = (field.options || []).map((o) => `<option value="${escapeAttr(o)}">${escapeHtml(o)}</option>`).join('');
-      inputHtml = `<select name="${escapeAttr(field.name)}" style="${inputStyleStr};cursor:pointer"${reqAttr}><option value="">${escapeHtml(field.placeholder || 'Select...')}</option>${opts}</select>`;
+      inputHtml = `<select id="${escapeAttr(fieldId)}" name="${escapeAttr(field.name)}" style="${inputStyleStr};cursor:pointer"${reqAttr}><option value="">${escapeHtml(field.placeholder || 'Select...')}</option>${opts}</select>`;
     } else {
-      inputHtml = `<input type="${field.type}" name="${escapeAttr(field.name)}" placeholder="${escapeAttr(field.placeholder)}" style="${inputStyleStr}"${reqAttr} />`;
+      inputHtml = `<input id="${escapeAttr(fieldId)}" type="${field.type}" name="${escapeAttr(field.name)}" placeholder="${escapeAttr(field.placeholder)}" style="${inputStyleStr}"${reqAttr} />`;
     }
     return `<div style="display:flex;flex-direction:column;gap:6px">${labelHtml}${inputHtml}</div>`;
   }).join('\n  ');
diff --git a/craft/src/components/forms/InputField.toHtml.test.ts b/craft/src/components/forms/InputField.toHtml.test.ts
new file mode 100644
index 0000000..bdd83cc
--- /dev/null
+++ b/craft/src/components/forms/InputField.toHtml.test.ts
@@ -0,0 +1,29 @@
+import { describe, test, expect } from 'vitest';
+import { InputField } from './InputField';
+
+const toHtml = (InputField as any).toHtml;
+
+describe('InputField.toHtml accessibility (F2.1)', () => {
+  test('label for= matches input id=', () => {
+    const { html } = toHtml({ label: 'Your Name', name: 'name' }, '');
+    const forMatch = html.match(/<label for="([^"]+)"/);
+    const idMatch = html.match(/<input id="([^"]+)"/);
+    expect(forMatch).toBeTruthy();
+    expect(idMatch).toBeTruthy();
+    expect(forMatch![1]).toBe(idMatch![1]);
+  });
+
+  test('id is deterministic (derived from name, not random) -- stable across calls', () => {
+    const { html: html1 } = toHtml({ label: 'Email', name: 'email' }, '');
+    const { html: html2 } = toHtml({ label: 'Email', name: 'email' }, '');
+    const id1 = html1.match(/<input id="([^"]+)"/)![1];
+    const id2 = html2.match(/<input id="([^"]+)"/)![1];
+    expect(id1).toBe(id2);
+  });
+
+  test('no visible label: input gets aria-label from placeholder', () => {
+    const { html } = toHtml({ label: '', name: 'phone', placeholder: 'Phone number' }, '');
+    expect(html).not.toContain('<label');
+    expect(html).toContain('aria-label="Phone number"');
+  });
+});
diff --git a/craft/src/components/forms/InputField.tsx b/craft/src/components/forms/InputField.tsx
index 0aa7945..9270efb 100644
--- a/craft/src/components/forms/InputField.tsx
+++ b/craft/src/components/forms/InputField.tsx
@@ -1,7 +1,7 @@
 import React, { CSSProperties } from 'react';
 import { useNode, UserComponent } from '@craftjs/core';
 import { cssPropsToString } from '../../utils/style-helpers';
-import { escapeHtml, escapeAttr } from '../../utils/escape';
+import { escapeHtml, escapeAttr, slugId } from '../../utils/escape';
 
 interface InputFieldProps {
   label?: string;
@@ -95,13 +95,19 @@ InputField.craft = {
     ...props.style,
   });
   const reqAttr = props.required ? ' required' : '';
+  // Deterministic id derived from the field name (pure function of props,
+  // no Math.random) so the <label for> always matches the <input id>.
+  const fieldId = 'field-' + slugId(props.name, 'field');
   const labelHtml = props.label
-    ? `<label style="font-size:14px;font-weight:500;color:#18181b">${escapeHtml(props.label)}${props.required ? '<span style="color:#ef4444"> *</span>' : ''}</label>`
+    ? `<label for="${escapeAttr(fieldId)}" style="font-size:14px;font-weight:500;color:#18181b">${escapeHtml(props.label)}${props.required ? '<span style="color:#ef4444"> *</span>' : ''}</label>`
+    : '';
+  const ariaLabelAttr = !props.label
+    ? ` aria-label="${escapeAttr(props.placeholder || props.name || 'Input field')}"`
     : '';
   return {
     html: `<div${wrapStyle ? ` style="${wrapStyle}"` : ''}>
   ${labelHtml}
-  <input type="${props.type || 'text'}" name="${escapeAttr(props.name || 'field')}" placeholder="${escapeAttr(props.placeholder || '')}"${reqAttr} style="padding:10px 12px;border:1px solid #d4d4d8;border-radius:6px;font-size:14px;color:#18181b;background-color:#ffffff;width:100%;box-sizing:border-box" />
+  <input id="${escapeAttr(fieldId)}" type="${props.type || 'text'}" name="${escapeAttr(props.name || 'field')}" placeholder="${escapeAttr(props.placeholder || '')}"${reqAttr}${ariaLabelAttr} style="padding:10px 12px;border:1px solid #d4d4d8;border-radius:6px;font-size:14px;color:#18181b;background-color:#ffffff;width:100%;box-sizing:border-box" />
 </div>`,
   };
 };
diff --git a/craft/src/components/forms/TextareaField.toHtml.test.ts b/craft/src/components/forms/TextareaField.toHtml.test.ts
new file mode 100644
index 0000000..6a9be42
--- /dev/null
+++ b/craft/src/components/forms/TextareaField.toHtml.test.ts
@@ -0,0 +1,21 @@
+import { describe, test, expect } from 'vitest';
+import { TextareaField } from './TextareaField';
+
+const toHtml = (TextareaField as any).toHtml;
+
+describe('TextareaField.toHtml accessibility (F2.1)', () => {
+  test('label for= matches textarea id=', () => {
+    const { html } = toHtml({ label: 'Message', name: 'message' }, '');
+    const forMatch = html.match(/<label for="([^"]+)"/);
+    const idMatch = html.match(/<textarea id="([^"]+)"/);
+    expect(forMatch).toBeTruthy();
+    expect(idMatch).toBeTruthy();
+    expect(forMatch![1]).toBe(idMatch![1]);
+  });
+
+  test('no visible label: textarea gets aria-label from placeholder', () => {
+    const { html } = toHtml({ label: '', name: 'notes', placeholder: 'Anything else?' }, '');
+    expect(html).not.toContain('<label');
+    expect(html).toContain('aria-label="Anything else?"');
+  });
+});
diff --git a/craft/src/components/forms/TextareaField.tsx b/craft/src/components/forms/TextareaField.tsx
index 1e955e7..aafc295 100644
--- a/craft/src/components/forms/TextareaField.tsx
+++ b/craft/src/components/forms/TextareaField.tsx
@@ -1,7 +1,7 @@
 import React, { CSSProperties } from 'react';
 import { useNode, UserComponent } from '@craftjs/core';
 import { cssPropsToString } from '../../utils/style-helpers';
-import { escapeHtml, escapeAttr } from '../../utils/escape';
+import { escapeHtml, escapeAttr, slugId } from '../../utils/escape';
 
 interface TextareaFieldProps {
   label?: string;
@@ -97,13 +97,19 @@ TextareaField.craft = {
     ...props.style,
   });
   const reqAttr = props.required ? ' required' : '';
+  // Deterministic id derived from the field name (pure function of props,
+  // no Math.random) so the <label for> always matches the <textarea id>.
+  const fieldId = 'field-' + slugId(props.name, 'message');
   const labelHtml = props.label
-    ? `<label style="font-size:14px;font-weight:500;color:#18181b">${escapeHtml(props.label)}${props.required ? '<span style="color:#ef4444"> *</span>' : ''}</label>`
+    ? `<label for="${escapeAttr(fieldId)}" style="font-size:14px;font-weight:500;color:#18181b">${escapeHtml(props.label)}${props.required ? '<span style="color:#ef4444"> *</span>' : ''}</label>`
+    : '';
+  const ariaLabelAttr = !props.label
+    ? ` aria-label="${escapeAttr(props.placeholder || props.name || 'Textarea field')}"`
     : '';
   return {
     html: `<div${wrapStyle ? ` style="${wrapStyle}"` : ''}>
   ${labelHtml}
-  <textarea name="${escapeAttr(props.name || 'message')}" placeholder="${escapeAttr(props.placeholder || '')}" rows="${props.rows || 4}"${reqAttr} style="padding:10px 12px;border:1px solid #d4d4d8;border-radius:6px;font-size:14px;color:#18181b;background-color:#ffffff;width:100%;box-sizing:border-box;resize:vertical;font-family:inherit"></textarea>
+  <textarea id="${escapeAttr(fieldId)}" name="${escapeAttr(props.name || 'message')}" placeholder="${escapeAttr(props.placeholder || '')}" rows="${props.rows || 4}"${reqAttr}${ariaLabelAttr} style="padding:10px 12px;border:1px solid #d4d4d8;border-radius:6px;font-size:14px;color:#18181b;background-color:#ffffff;width:100%;box-sizing:border-box;resize:vertical;font-family:inherit"></textarea>
 </div>`,
   };
 };
diff --git a/craft/src/components/media/MapEmbed.toHtml.test.ts b/craft/src/components/media/MapEmbed.toHtml.test.ts
new file mode 100644
index 0000000..f5b3814
--- /dev/null
+++ b/craft/src/components/media/MapEmbed.toHtml.test.ts
@@ -0,0 +1,16 @@
+import { describe, test, expect } from 'vitest';
+import { MapEmbed } from './MapEmbed';
+
+const toHtml = (MapEmbed as any).toHtml;
+
+describe('MapEmbed.toHtml iframe accessibility (F2.4)', () => {
+  test('iframe has a non-empty title attribute', () => {
+    const { html } = toHtml({ address: 'New York, NY' }, '');
+    expect(html).toMatch(/<iframe[^>]*title="[^"]+"/);
+  });
+
+  test('title reflects the configured address', () => {
+    const { html } = toHtml({ address: 'Golden Gate Bridge' }, '');
+    expect(html).toContain('title="Map of Golden Gate Bridge"');
+  });
+});
diff --git a/craft/src/components/media/MapEmbed.tsx b/craft/src/components/media/MapEmbed.tsx
index f60ffcc..06948d7 100644
--- a/craft/src/components/media/MapEmbed.tsx
+++ b/craft/src/components/media/MapEmbed.tsx
@@ -93,6 +93,6 @@ MapEmbed.craft = {
   const src = buildMapUrl(address, zoom);
 
   return {
-    html: `<div${wrapperStyle ? ` style="${wrapperStyle}"` : ''}><iframe src="${escapeAttr(safeUrl(src))}" loading="lazy" referrerpolicy="no-referrer-when-downgrade" allowfullscreen${iframeStyle ? ` style="${iframeStyle}"` : ''}></iframe></div>`,
+    html: `<div${wrapperStyle ? ` style="${wrapperStyle}"` : ''}><iframe src="${escapeAttr(safeUrl(src))}" title="${escapeAttr(`Map of ${address}`)}" loading="lazy" referrerpolicy="no-referrer-when-downgrade" allowfullscreen${iframeStyle ? ` style="${iframeStyle}"` : ''}></iframe></div>`,
   };
 };
diff --git a/craft/src/components/media/VideoBlock.toHtml.test.ts b/craft/src/components/media/VideoBlock.toHtml.test.ts
index 5158a46..f328554 100644
--- a/craft/src/components/media/VideoBlock.toHtml.test.ts
+++ b/craft/src/components/media/VideoBlock.toHtml.test.ts
@@ -59,3 +59,15 @@ describe('VideoBlock URL parsing (D4)', () => {
     expect(html).not.toContain('javascript:');
   });
 });
+
+describe('VideoBlock.toHtml iframe accessibility (F2.4)', () => {
+  test('normal-mode YouTube/Vimeo iframe has a title attribute', () => {
+    const { html } = toHtml({ videoUrl: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' }, '');
+    expect(html).toMatch(/<iframe[^>]*title="[^"]+"/);
+  });
+
+  test('background-mode YouTube/Vimeo iframe has a title attribute', () => {
+    const { html } = toHtml({ videoUrl: 'https://vimeo.com/123456789', isBackground: true }, '');
+    expect(html).toMatch(/<iframe[^>]*title="[^"]+"/);
+  });
+});
diff --git a/craft/src/components/media/VideoBlock.tsx b/craft/src/components/media/VideoBlock.tsx
index 3b6eec6..7abde01 100644
--- a/craft/src/components/media/VideoBlock.tsx
+++ b/craft/src/components/media/VideoBlock.tsx
@@ -403,7 +403,7 @@ VideoBlock.craft = {
         zIndex: '0',
         pointerEvents: 'none',
       });
-      videoHtml = `<iframe src="${escapeAttr(safeUrl(iframeSrc))}" allow="autoplay; encrypted-media" allowfullscreen${ifrStyle ? ` style="${ifrStyle}"` : ''}></iframe>`;
+      videoHtml = `<iframe src="${escapeAttr(safeUrl(iframeSrc))}" title="Embedded video" allow="autoplay; encrypted-media" allowfullscreen${ifrStyle ? ` style="${ifrStyle}"` : ''}></iframe>`;
     }
 
     return {
@@ -436,7 +436,7 @@ VideoBlock.craft = {
       border: 'none',
     });
     return {
-      html: `<div${wrapperStyle ? ` style="${wrapperStyle}"` : ''}><div${containerStyle ? ` style="${containerStyle}"` : ''}><iframe src="${escapeAttr(safeUrl(iframeSrc))}" allow="autoplay; encrypted-media; picture-in-picture" allowfullscreen${iframeStyle ? ` style="${iframeStyle}"` : ''}></iframe></div></div>`,
+      html: `<div${wrapperStyle ? ` style="${wrapperStyle}"` : ''}><div${containerStyle ? ` style="${containerStyle}"` : ''}><iframe src="${escapeAttr(safeUrl(iframeSrc))}" title="Embedded video" allow="autoplay; encrypted-media; picture-in-picture" allowfullscreen${iframeStyle ? ` style="${iframeStyle}"` : ''}></iframe></div></div>`,
     };
   }
 
diff --git a/craft/src/components/sections/Testimonials.toHtml.test.ts b/craft/src/components/sections/Testimonials.toHtml.test.ts
index fffd8f7..a9cb469 100644
--- a/craft/src/components/sections/Testimonials.toHtml.test.ts
+++ b/craft/src/components/sections/Testimonials.toHtml.test.ts
@@ -37,3 +37,12 @@ describe('Testimonials.toHtml single-layout export parity', () => {
     expect(html).toContain('Name Three');
   });
 });
+
+describe('Testimonials.toHtml decorative star icons (F2.5)', () => {
+  test('star glyphs are aria-hidden', () => {
+    const { html } = toHtml({ testimonials, layout: 'grid' }, '');
+    const stars = html.match(/<i class="fa fa-star[^"]*"[^>]*>/g) || [];
+    expect(stars.length).toBeGreaterThan(0);
+    stars.forEach((tag: string) => expect(tag).toContain('aria-hidden="true"'));
+  });
+});
diff --git a/craft/src/components/sections/Testimonials.tsx b/craft/src/components/sections/Testimonials.tsx
index 99c3d89..5825dc7 100644
--- a/craft/src/components/sections/Testimonials.tsx
+++ b/craft/src/components/sections/Testimonials.tsx
@@ -42,9 +42,9 @@ function renderStars(count: number, color: string): React.ReactNode {
 
 function starsHtml(count: number, color: string): string {
   const stars = [1, 2, 3, 4, 5].map((i) =>
-    `<i class="fa ${i <= count ? 'fa-star' : 'fa-star-o'}" style="color:${color};font-size:14px"></i>`
+    `<i class="fa ${i <= count ? 'fa-star' : 'fa-star-o'}" style="color:${color};font-size:14px" aria-hidden="true"></i>`
   ).join('');
-  return `<div style="display:flex;gap:2px;justify-content:center;margin-bottom:12px">${stars}</div>`;
+  return `<div style="display:flex;gap:2px;justify-content:center;margin-bottom:12px" role="img" aria-label="Rating: ${count} out of 5">${stars}</div>`;
 }
 
 export const Testimonials: UserComponent<TestimonialsProps> = ({
diff --git a/craft/src/utils/escape.ts b/craft/src/utils/escape.ts
index 6296140..bf3470f 100644
--- a/craft/src/utils/escape.ts
+++ b/craft/src/utils/escape.ts
@@ -78,3 +78,14 @@ export function safeUrl(s: string): string {
 
   return trimmed;
 }
+
+/**
+ * Derives a deterministic, HTML-id-safe slug from a field's `name`/`label`
+ * for wiring `<label for>` to a matching `<input id>` in exported markup.
+ * Pure function of the input string -- no Math.random/Date.now -- so the
+ * same field always gets the same id across export runs.
+ */
+export function slugId(s: string | undefined, fallback = 'field'): string {
+  const base = (s || '').toString().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return base || fallback;
+}