auto-claude: 5.1 - Explain semantic HTML and why using proper element

lessons/20-html-elements.json

@@ -17,6 +17,10 @@
 			"initialCode": "<p>This is a paragraph with an important word.</p>",
 			"solution": "<p>This is a paragraph with an <strong>important</strong> word.</p>",
 			"previewContainer": "preview-area",
+			"concept": {
+				"explanation": "The browser's layout engine treats block and inline elements fundamentally differently. Block elements create a rectangular box that starts on a new line and expands to fill available width, stacking vertically like building blocks. Inline elements flow horizontally within text content, wrapping to new lines only when they run out of space—like words in a paragraph. This distinction controls document flow: use block for structure (sections, paragraphs) and inline for content emphasis (bold, links) without breaking the text flow.",
+				"diagram": "Block vs Inline Layout\n\nBlock elements (vertical stacking):\n┌─────────────────────────────┐\n│ <div> Full width block     │ ← New line\n└─────────────────────────────┘\n┌─────────────────────────────┐\n│ <p> Another block element  │ ← New line\n└─────────────────────────────┘\n\nInline elements (horizontal flow):\n┌─────────────────────────────┐\n│ Text with <a>link</a> and  │\n│ <strong>bold</strong> flows │ ← Wraps naturally\n│ like words in a sentence.   │\n└─────────────────────────────┘\n\nKey differences:\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nBlock:   New line, full width\nInline:  Same line, auto width\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+			},
 			"validations": [
 				{
 					"type": "element_exists",
@@ -41,6 +45,10 @@
 			"initialCode": "",
 			"solution": "<header>\n  <h1>My Website</h1>\n</header>\n<main>\n  <p>Welcome to my site!</p>\n</main>\n<footer>\n  <p>Copyright 2026</p>\n</footer>",
 			"previewContainer": "preview-area",
+			"concept": {
+				"explanation": "Semantic HTML elements convey meaning about their content, not just appearance. Screen readers use semantic tags to help blind users navigate (\"skip to main content\" relies on <main>), search engines rank pages higher when structure is clear (<article> signals important content), and developers understand code faster when tags describe purpose. Using <header> instead of <div class=\"header\"> gives the same visual result but adds machine-readable meaning that assistive technology and search crawlers can understand. This is the foundation of accessible, SEO-friendly web development.",
+				"diagram": "Semantic Page Structure\n\n┌─────────────────────────────┐\n│ <header>                    │ ← Page header\n│   <h1>Site Title</h1>       │   (branding, logo)\n│   <nav>Menu</nav>           │   (navigation)\n└─────────────────────────────┘\n┌─────────────────────────────┐\n│ <main>                      │ ← Primary content\n│   <article>Blog Post</article> (unique per page)\n│   <section>Comments</section>  (landmarks)\n└─────────────────────────────┘\n┌─────────────────────────────┐\n│ <footer>                    │ ← Page footer\n│   Copyright, links          │   (metadata)\n└─────────────────────────────┘\n\nBenefits:\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nAccessibility: Screen readers\nSEO:           Search ranking\nMaintainability: Self-documenting\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+			},
 			"validations": [
 				{
 					"type": "element_exists",
@@ -75,6 +83,10 @@
 			"initialCode": "The most highlighted moment was unforgettable.",
 			"solution": "<div>The most <span>highlighted</span> moment was unforgettable.</div>",
 			"previewContainer": "preview-area",
+			"concept": {
+				"explanation": "While semantic elements describe content meaning, <div> and <span> are semantically neutral containers used purely for styling or JavaScript hooks when no semantic element fits. Use <div> to group block-level content for layout purposes (like creating a grid wrapper) and <span> to target inline text portions for styling (like highlighting a word). However, always ask first: is there a better semantic choice? For example, use <article> instead of <div class=\"post\">, or <strong> instead of <span class=\"bold\">. Generic containers should be your last resort, not your first choice.",
+				"diagram": "When to Use Generic Containers\n\nSemantic First (Preferred):\n✓ <header>   instead of  <div class=\"header\">\n✓ <nav>      instead of  <div class=\"nav\">\n✓ <strong>   instead of  <span class=\"bold\">\n✓ <em>       instead of  <span class=\"italic\">\n\nGeneric When Needed:\n✓ <div>      Layout wrapper (grid/flex)\n✓ <span>     Style hook (color/bg only)\n\nDecision Tree:\n┌─────────────────────────────┐\n│ Does a semantic tag exist?  │\n│    ↓ Yes     ↓ No           │\n│  Use it    Use div/span     │\n└─────────────────────────────┘\n\nPrinciple: Meaning > Presentation"
+			},
 			"validations": [
 				{
 					"type": "element_exists",