From 85f2aa47fe1d815c098662020e0d3bb22a729700 Mon Sep 17 00:00:00 2001
From: Michael Czechowski <mail@dailysh.it>
Date: Sun, 11 Jan 2026 14:33:12 +0100
Subject: [PATCH] auto-claude: 5.2 - Explain native form validation, input
 types, and accessibility patterns

---
 lessons/21-html-forms-basic.json      | 12 ++++++++++++
 lessons/22-html-forms-validation.json | 12 ++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/lessons/21-html-forms-basic.json b/lessons/21-html-forms-basic.json
index 2c80946..12c20c1 100644
--- a/lessons/21-html-forms-basic.json
+++ b/lessons/21-html-forms-basic.json
@@ -17,6 +17,10 @@
 			"initialCode": "",
 			"solution": "<form>\n  <label for=\"name\">Name:</label>\n  <input type=\"text\" id=\"name\" name=\"name\">\n</form>",
 			"previewContainer": "preview-area",
+			"concept": {
+				"explanation": "The label-for-id connection creates an accessible relationship that assistive technologies understand. When a screen reader encounters <label for=\"name\">, it announces \"Name, edit text\" so blind users know what to enter. Clicking the label also focuses the input, giving users a larger click target (helpful on mobile and for motor disabilities). The name attribute identifies the field when submitting data to a server, while the id attribute creates the accessibility link—both serve different but essential purposes.",
+				"diagram": "Form Accessibility Chain\n\n┌─────────────────────────────┐\n│ <label for=\"email\">        │ ← Click target\n│   Email:                    │   (focuses input)\n│ </label>                    │\n└────────────┬────────────────┘\n             │ for=\"email\"\n             ↓ connects to id\n┌────────────┴────────────────┐\n│ <input id=\"email\"           │ ← Accessibility link\n│        name=\"email\">        │   (server identifier)\n└─────────────────────────────┘\n\nWhat Happens:\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n1. User clicks label\n2. Browser finds matching id\n3. Input receives focus\n4. Screen reader announces label\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nWhy Both Attributes?\nid   → Accessibility (label link)\nname → Server data (form submit)"
+			},
 			"validations": [
 				{
 					"type": "element_exists",
@@ -56,6 +60,10 @@
 			"initialCode": "<form>\n  \n</form>",
 			"solution": "<form>\n  <label for=\"email\">Email:</label>\n  <input type=\"email\" id=\"email\" name=\"email\">\n  \n  <label for=\"password\">Password:</label>\n  <input type=\"password\" id=\"password\" name=\"password\">\n</form>",
 			"previewContainer": "preview-area",
+			"concept": {
+				"explanation": "Input types give the browser semantic understanding of what data to expect, enabling native features without JavaScript. On mobile, type=\"email\" shows a keyboard with @ and .com shortcuts, type=\"tel\" displays a numeric dialpad, and type=\"number\" shows +/- controls. The browser also provides free validation: type=\"email\" automatically checks for @ symbols and rejects invalid formats on submit. Using semantic input types is the foundation of progressive enhancement—you get better UX, accessibility, and validation for free.",
+				"diagram": "Input Type Benefits\n\nMobile Keyboard Optimization:\n┌────────────────────────────┐\ntype=\"text\"    → QWERTY      │ ABC...\ntype=\"email\"   → @ .com keys │ user@domain\ntype=\"tel\"     → Dialpad     │ 0-9 only\ntype=\"number\"  → +/- arrows  │ Steppers\ntype=\"url\"     → .com / www  │ https://\n└────────────────────────────┘\n\nNative Validation (Free!):\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nemail    → Must contain @\nurl      → Must start http://\nnumber   → Numeric characters only\ntel      → No validation (varies)\npassword → Hides characters ••••\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nAccessibility:\nScreen readers announce input type\n\"Email, edit text\" vs just \"edit text\""
+			},
 			"validations": [
 				{
 					"type": "element_exists",
@@ -85,6 +93,10 @@
 			"initialCode": "<form>\n  <label for=\"email\">Email:</label>\n  <input type=\"email\" id=\"email\">\n  \n  <label for=\"password\">Password:</label>\n  <input type=\"password\" id=\"password\">\n  \n</form>",
 			"solution": "<form>\n  <label for=\"email\">Email:</label>\n  <input type=\"email\" id=\"email\">\n  \n  <label for=\"password\">Password:</label>\n  <input type=\"password\" id=\"password\">\n  \n  <button type=\"submit\">Sign In</button>\n</form>",
 			"previewContainer": "preview-area",
+			"concept": {
+				"explanation": "When clicked, a submit button triggers the form's native submit event, which validates all required fields, checks input constraints (minlength, pattern, etc.), and prevents submission if validation fails—all without JavaScript. The browser handles Enter key submission automatically when focus is in any text input. Prefer <button type=\"submit\"> over <input type=\"submit\"> because buttons can contain HTML (icons, spinners during loading), while input elements can only display plain text set via the value attribute.",
+				"diagram": "Form Submission Flow\n\nUser Action:\n┌────────────────────────────┐\n│ <button type=\"submit\">     │ ← Click or\n│   Sign In                  │   Enter key\n│ </button>                  │   pressed\n└────────────┬───────────────┘\n             │\n             ↓ Triggers\n┌────────────┴───────────────┐\n│ Browser Validation:        │\n│  ✓ Check required fields   │\n│  ✓ Validate input types    │\n│  ✓ Test constraints        │\n│  ✓ Match patterns          │\n└────────────┬───────────────┘\n             │\n      ┌──────┴──────┐\n   ✓ Valid      ✗ Invalid\n      │              │\n      ↓              ↓\n  Submit form    Show error\n  (POST data)    (block submit)\n\nButton vs Input:\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n<button>   → Can contain HTML\n<input>    → Plain text only\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+			},
 			"validations": [
 				{
 					"type": "element_exists",
diff --git a/lessons/22-html-forms-validation.json b/lessons/22-html-forms-validation.json
index ef7e909..ca45647 100644
--- a/lessons/22-html-forms-validation.json
+++ b/lessons/22-html-forms-validation.json
@@ -17,6 +17,10 @@
 			"initialCode": "<form>\n  <label for=\"name\">Name: *</label>\n  <input type=\"text\" id=\"name\" name=\"name\">\n  \n  <label for=\"email\">Email: *</label>\n  <input type=\"email\" id=\"email\" name=\"email\">\n  \n  <button type=\"submit\">Submit</button>\n</form>",
 			"solution": "<form>\n  <label for=\"name\">Name: *</label>\n  <input type=\"text\" id=\"name\" name=\"name\" required>\n  \n  <label for=\"email\">Email: *</label>\n  <input type=\"email\" id=\"email\" name=\"email\" required>\n  \n  <button type=\"submit\">Submit</button>\n</form>",
 			"previewContainer": "preview-area",
+			"concept": {
+				"explanation": "The required attribute activates the browser's Constraint Validation API, which checks field values before allowing form submission. When a user tries to submit with empty required fields, the browser automatically focuses the first invalid field, displays a localized error message (\"Please fill out this field\" in English), and blocks the submit event—no JavaScript needed. The :invalid CSS pseudo-class lets you style invalid fields (like red borders), and screen readers announce required fields as \"Email, required, edit text\" so all users know which fields are mandatory.",
+				"diagram": "Native Validation Flow\n\nBefore Submit:\n┌────────────────────────────┐\n│ <input required>           │ ← Browser monitors\n│   [empty]                  │   validity state\n└────────────────────────────┘\n     :invalid pseudo-class\n\nOn Submit Click:\n┌────────────────────────────┐\n│ Browser checks:            │\n│  ✓ Is field filled?        │\n│  ✗ Empty → INVALID         │\n└────────────┬───────────────┘\n             │\n             ↓ Blocks submit\n┌────────────┴───────────────┐\n│ [!] Please fill out this   │ ← Localized\n│     field                  │   browser message\n└────────────────────────────┘\n      Focus moved here\n\nCSS States Available:\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n:valid      → Green border\n:invalid    → Red border\n:required   → Asterisk icon\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+			},
 			"validations": [
 				{
 					"type": "attribute_value",
@@ -41,6 +45,10 @@
 			"initialCode": "<form>\n  <label for=\"password\">Password:</label>\n  <input type=\"password\" id=\"password\" name=\"password\" required aria-describedby=\"password-hint\">\n  <small id=\"password-hint\">Must be 8-20 characters</small>\n  \n  <button type=\"submit\">Create Account</button>\n</form>",
 			"solution": "<form>\n  <label for=\"password\">Password:</label>\n  <input type=\"password\" id=\"password\" name=\"password\" required minlength=\"8\" maxlength=\"20\" placeholder=\"Enter password\" aria-describedby=\"password-hint\">\n  <small id=\"password-hint\">Must be 8-20 characters</small>\n  \n  <button type=\"submit\">Create Account</button>\n</form>",
 			"previewContainer": "preview-area",
+			"concept": {
+				"explanation": "Constraint attributes define validation rules that the browser enforces automatically. The minlength attribute triggers :invalid state and blocks submission if the value is shorter than 8 characters, while maxlength physically prevents typing beyond 20 characters (a hard limit, not just validation). The pattern attribute accepts regex for complex rules like \"uppercase + lowercase + number\" without any JavaScript validation code. Placeholder text disappears when typing starts, so never use it instead of a label—use aria-describedby to link visible hint text for screen reader users.",
+				"diagram": "Constraint Validation Rules\n\nAttribute Behaviors:\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nminlength=\"8\"   Validates on submit\n                Can type less, can't submit\n                Error: \"Too short (min 8)\"\n\nmaxlength=\"20\"  Prevents typing\n                Keyboard blocked at char 20\n                No error (can't violate)\n\npattern=\"...\"   Regex validation\n                Example: \"[A-Z][a-z]+\"\n                Error: \"Match format\"\n\nmin=\"1\" max=\"5\"  Number range\n                For type=\"number\"\n                Error: \"Out of range\"\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nAccessibility Pattern:\n┌────────────────────────────┐\n│ <label for=\"pw\">Password   │ ← Visible label\n│ <input id=\"pw\"             │\n│   aria-describedby=\"hint\">│ ← Links to hint\n│ <small id=\"hint\">          │ ← Visible hint\n│   Must be 8-20 chars       │   (not placeholder)\n└────────────────────────────┘"
+			},
 			"validations": [
 				{
 					"type": "attribute_value",
@@ -70,6 +78,10 @@
 			"initialCode": "<form>\n  <h2>Create Account</h2>\n  \n  <label for=\"fullname\">Full Name *</label>\n  <input type=\"text\" id=\"fullname\" name=\"fullname\">\n  \n  <label for=\"email\">Email *</label>\n  <input id=\"email\" name=\"email\">\n  \n  <label for=\"password\">Password *</label>\n  <input id=\"password\" name=\"password\">\n  \n  <label>\n    <input type=\"checkbox\" id=\"terms\" name=\"terms\">\n    I agree to the Terms of Service *\n  </label>\n  \n  <button type=\"submit\">Register</button>\n</form>",
 			"solution": "<form>\n  <h2>Create Account</h2>\n  \n  <label for=\"fullname\">Full Name *</label>\n  <input type=\"text\" id=\"fullname\" name=\"fullname\" required>\n  \n  <label for=\"email\">Email *</label>\n  <input type=\"email\" id=\"email\" name=\"email\" required>\n  \n  <label for=\"password\">Password *</label>\n  <input type=\"password\" id=\"password\" name=\"password\" required minlength=\"8\">\n  \n  <label>\n    <input type=\"checkbox\" id=\"terms\" name=\"terms\" required>\n    I agree to the Terms of Service *\n  </label>\n  \n  <button type=\"submit\">Register</button>\n</form>",
 			"previewContainer": "preview-area",
+			"concept": {
+				"explanation": "This form demonstrates layered validation and accessibility best practices working together. Semantic input types (email, password) provide baseline validation and appropriate mobile keyboards, required attributes enforce mandatory fields, minlength adds password security rules, and the visual asterisks (*) in labels give sighted users a hint—but screen readers rely on the required attribute to announce \"Email, required, edit text\". Checkboxes can be required too, forcing users to agree to terms before submission. All validation happens natively in the browser before any server-side processing, saving bandwidth and providing instant feedback.",
+				"diagram": "Complete Form Validation Layers\n\n┌─────────────────────────────┐\n│ <input type=\"email\"         │ Layer 1: Type Validation\n│   required                  │ Layer 2: Required\n│   minlength=\"8\">            │ Layer 3: Constraints\n└─────────────────────────────┘\n\nValidation Execution Order:\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n1. Check required (not empty?)\n2. Check type (valid email?)\n3. Check constraints (minlength?)\n4. Check pattern (regex match?)\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nALL must pass to submit ✓\n\nAccessibility Checklist:\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n✓ <label for=\"id\"> linked\n✓ Semantic input types\n✓ required attribute (not just *)\n✓ Visible error hints\n✓ Focus outline (keyboard nav)\n✓ Checkbox labeled correctly\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nBenefits:\n• No JavaScript needed\n• Localized error messages\n• Mobile keyboard optimization\n• Screen reader compatible\n• Instant client-side feedback"
+			},
 			"validations": [
 				{
 					"type": "attribute_value",