{
  "spec_id": "001-conceptual-explanations",
  "title": "Conceptual Explanations Feature",
  "summary": "Add 'Why This Works' explanations to each lesson that explain the concept behind CSS properties, not just syntax. Include collapsible UI and visual diagrams where helpful.",
  "phases": [
    {
      "phase": 1,
      "name": "Schema & Data Model",
      "description": "Extend the lesson JSON schema to support conceptual explanations",
      "subtasks": [
        {
          "id": "1.1",
          "title": "Update lesson schema with concept field",
          "description": "Add 'concept' object field to lesson schema with properties: 'explanation' (string, 2-4 sentences), 'diagram' (optional string for SVG/ASCII art), and 'containerVsItem' (optional string for Flexbox-specific distinction)",
          "status": "completed",
          "notes": "Successfully added 'concept' object field to lesson schema with explanation (required), diagram (optional), and containerVsItem (optional) properties. Schema validated and committed.",
          "updated_at": "2026-01-11T03:29:15.174421+00:00"
        }
      ]
    },
    {
      "phase": 2,
      "name": "UI Components",
      "description": "Create collapsible concept section in the lesson UI",
      "subtasks": [
        {
          "id": "2.1",
          "title": "Add collapsible concept section to HTML",
          "description": "Add a native <details><summary> element for 'Why This Works' section in index.html within the .instructions section. Use semantic HTML5 for accessibility.",
          "status": "completed",
          "notes": "Successfully added native <details><summary> element for 'Why This Works' section in src/index.html within the .instructions section. The implementation includes:\n- Semantic HTML5 <details> element with id='concept-section'\n- <summary> with data-i18n attribute for internationalization\n- Three content divs for explanation, diagram, and container-vs-item distinction\n- Proper indentation and accessibility structure",
          "updated_at": "2026-01-11T03:32:46.857276+00:00"
        },
        {
          "id": "2.2",
          "title": "Style the concept section",
          "description": "Add CSS styles for the concept panel: distinct visual treatment, diagram container, smooth animation for expand/collapse. Use CSS variables for consistency.",
          "status": "completed",
          "notes": "Successfully added CSS styles for the concept panel with distinct visual treatment, smooth animations, and proper RTL support. Implementation includes:\n- Distinct visual treatment with light purple background and primary color left border\n- Hover and open state effects for better interactivity\n- Smooth expand/collapse animation using CSS keyframes (concept-expand)\n- Rotating arrow icon animation with transform and transition\n- Styled diagram container with monospace font, white background, and overflow handling\n- Special styling for container-vs-item section with success color theming\n- Auto-hide empty content sections with :empty pseudo-class\n- Full RTL support for right-to-left languages\n- All styles use CSS variables for consistency (--spacing-*, --primary-*, --border-radius-*, etc.)\n- Follows existing codebase patterns and design system\nCommitted: 0e39cff",
          "updated_at": "2026-01-11T03:35:41.967502+00:00"
        },
        {
          "id": "2.3",
          "title": "Update renderer to display concepts",
          "description": "Modify renderer.js renderLesson() to populate the concept section with explanation text and optional diagram. Handle case when concept is not defined.",
          "status": "completed",
          "notes": "Successfully modified renderer.js renderLesson() function to populate the concept section. Implementation includes:\n- Populate concept explanation text (required field) using textContent\n- Populate optional diagram field using innerHTML (to support SVG markup)\n- Populate optional containerVsItem field using textContent\n- Show concept section when lesson.concept exists with explanation\n- Hide concept section when concept is not defined\n- Clear optional fields to prevent stale data from previous lessons\nCommitted: e21bca1",
          "updated_at": "2026-01-11T03:38:59.760229+00:00"
        },
        {
          "id": "2.4",
          "title": "Add i18n keys for concept UI",
          "description": "Add translation keys for 'Why This Works' heading and any other UI text in i18n.js for all supported languages.",
          "status": "completed",
          "notes": "Successfully added 'whyThisWorks' translation key to i18n.js for all 6 supported languages:\n- en: \"Why This Works\"\n- de: \"Warum das funktioniert\"\n- pl: \"Dlaczego to dzia\u0142a\"\n- es: \"Por qu\u00e9 funciona\"\n- ar: \"\u0644\u0645\u0627\u0630\u0627 \u064a\u0639\u0645\u0644 \u0647\u0630\u0627\"\n- uk: \"\u0427\u043e\u043c\u0443 \u0446\u0435 \u043f\u0440\u0430\u0446\u044e\u0454\"\n\nThe translation key is used by the concept section summary element with data-i18n=\"whyThisWorks\". All translations maintain consistency with the existing patterns in i18n.js.\n\nCommitted: 3c08b45",
          "updated_at": "2026-01-11T03:40:28.748935+00:00"
        }
      ]
    },
    {
      "phase": 3,
      "name": "Content - Core CSS Modules",
      "description": "Add conceptual explanations to fundamental CSS lesson modules",
      "subtasks": [
        {
          "id": "3.1",
          "title": "Add concepts to flexbox.json",
          "description": "Add 'concept' objects to all 6 Flexbox lessons. Explicitly explain container vs item distinction. Include simple ASCII diagrams showing axis direction.",
          "status": "completed",
          "notes": "Successfully added 'concept' objects to all 6 Flexbox lessons with:\n- Beginner-friendly explanations (2-4 sentences) for each lesson\n- ASCII diagrams showing main/cross axis direction for visual learners\n- Clear container vs item distinctions for each property\n- Lessons covered: display: flex, flex-direction/flex-wrap, justify-content, align-items, flex (grow), and align-self\n- All concepts follow the schema requirements (explanation required, diagram and containerVsItem optional)\n- JSON validated and committed: 0cf25b6",
          "updated_at": "2026-01-11T03:44:06.818262+00:00"
        },
        {
          "id": "3.2",
          "title": "Add concepts to grid.json",
          "description": "Add conceptual explanations to CSS Grid lessons explaining the 2D grid system, tracks, and cell placement.",
          "status": "completed",
          "notes": "Successfully added 'concept' objects to all 6 CSS Grid lessons with:\n- Beginner-friendly explanations (2-4 sentences) for each lesson\n- ASCII diagrams illustrating 2D grid system, tracks, and cell placement\n- Clear container vs item distinctions for each property\n- Lessons covered: grid container basics, template areas, spanning cells, auto-fit responsive, alignment, and overlapping items\n- All concepts follow the schema requirements (explanation required, diagram and containerVsItem optional)\n- JSON validated and committed: 29c019b",
          "updated_at": "2026-01-11T03:48:22.575319+00:00"
        },
        {
          "id": "3.3",
          "title": "Add concepts to 00-basic-selectors.json",
          "description": "Add explanations for CSS selector specificity and cascade. Help beginners understand WHY certain selectors match elements.",
          "status": "completed",
          "notes": "Successfully added 'concept' objects to 4 lessons in 00-basic-selectors.json with:\n- Beginner-friendly explanations (2-4 sentences) for each lesson\n- ASCII diagrams showing selector matching and specificity\n- Clear explanations of CSS cascade and specificity point system\n- Lessons covered: Type + ID combination, Selector Lists (grouping), Universal Selector (*), and Specificity basics\n- All concepts follow the schema requirements (explanation required, diagram optional)\n- JSON validated and committed: 39f1fb5",
          "updated_at": "2026-01-11T04:08:03.241534+00:00"
        },
        {
          "id": "3.4",
          "title": "Add concepts to 01-box-model.json",
          "description": "Add explanations for the CSS box model - content, padding, border, margin. Include simple diagram showing the layers.",
          "status": "completed",
          "notes": "Successfully added 'concept' objects to all 8 box model lessons with:\n- Beginner-friendly explanations (2-4 sentences) for each lesson\n- ASCII diagrams illustrating the 4-layer box model (content, padding, border, margin)\n- Visual comparisons of margin vs padding, content-box vs border-box, and margin collapse\n- Clear explanations of shorthand notation patterns and individual side targeting\n- Lessons covered: box model components, borders, margins, box-sizing, margin collapse, margin shorthand, padding shorthand, and individual border sides\n- All concepts follow the schema requirements (explanation required, diagram optional)\n- JSON validated and committed: 435381b",
          "updated_at": "2026-01-11T04:13:22.379924+00:00"
        },
        {
          "id": "3.5",
          "title": "Add concepts to 02-selectors.json",
          "description": "Add explanations for advanced selectors including pseudo-classes and combinators.",
          "status": "completed",
          "notes": "Successfully added 'concept' objects to all 4 lessons in 02-selectors.json with:\n- Beginner-friendly explanations (2-4 sentences) for each lesson\n- ASCII diagrams showing DOM traversal, attribute matching, and specificity comparisons\n- Clear explanations of specificity point system (ID=0,1,0,0, class=0,0,1,0, element=0,0,0,1)\n- Lessons covered: Element selectors, Class selectors, ID selectors, and Combined selectors with specificity\n- All concepts explain WHY selectors work, not just syntax\n- Emphasis on CSS cascade and how specificity resolves conflicts\n- JSON validated and committed: 3df98fe",
          "updated_at": "2026-01-11T04:19:15.816366+00:00"
        }
      ]
    },
    {
      "phase": 4,
      "name": "Content - Visual & Layout Modules",
      "description": "Add concepts to visual styling and layout lessons",
      "subtasks": [
        {
          "id": "4.1",
          "title": "Add concepts to 03-colors.json",
          "description": "Explain color theory basics, color formats (hex, rgb, hsl), and why different formats exist.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "4.2",
          "title": "Add concepts to 04-typography.json",
          "description": "Explain font stacks, web-safe fonts, and how browsers render text.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "4.3",
          "title": "Add concepts to 05-units-variables.json",
          "description": "Explain relative vs absolute units, why rem is preferred, and CSS custom properties.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "4.4",
          "title": "Add concepts to 06-transitions-animations.json",
          "description": "Explain how CSS transitions interpolate values and keyframe animation timing.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "4.5",
          "title": "Add concepts to 07-layouts.json",
          "description": "Explain different layout systems and when to use each approach.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "4.6",
          "title": "Add concepts to 08-responsive.json",
          "description": "Explain media queries, breakpoints, and mobile-first design principles.",
          "status": "pending",
          "notes": ""
        }
      ]
    },
    {
      "phase": 5,
      "name": "Content - HTML & Tailwind Modules",
      "description": "Add concepts to HTML semantic elements and Tailwind lessons",
      "subtasks": [
        {
          "id": "5.1",
          "title": "Add concepts to 20-html-elements.json",
          "description": "Explain semantic HTML and why using proper elements matters for accessibility and SEO.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "5.2",
          "title": "Add concepts to HTML form lessons (21-22)",
          "description": "Explain native form validation, input types, and accessibility patterns.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "5.3",
          "title": "Add concepts to remaining HTML lessons (23-32)",
          "description": "Add explanations to details/summary, progress/meter, datalist, data attributes, dialog, fieldset, figure, tables, marquee, SVG lessons.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "5.4",
          "title": "Add concepts to 10-tailwind-basics.json",
          "description": "Explain Tailwind's utility-first approach and how it differs from traditional CSS.",
          "status": "pending",
          "notes": ""
        }
      ]
    },
    {
      "phase": 6,
      "name": "Testing & Polish",
      "description": "Verify implementation and add final touches",
      "subtasks": [
        {
          "id": "6.1",
          "title": "Add unit tests for concept rendering",
          "description": "Add tests to verify concept section renders correctly, handles missing concepts gracefully, and collapses/expands properly.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "6.2",
          "title": "Verify mobile responsiveness",
          "description": "Test concept section on mobile viewports, ensure diagrams scale appropriately.",
          "status": "pending",
          "notes": ""
        },
        {
          "id": "6.3",
          "title": "Review and refine explanations",
          "description": "Final review of all concept texts for clarity, consistency, and beginner-friendliness. Ensure 2-4 sentence limit.",
          "status": "pending",
          "notes": ""
        }
      ]
    }
  ],
  "qa_signoff": {
    "status": "pending",
    "tests_passed": "",
    "issues": ""
  },
  "created_at": "2025-01-11T00:00:00Z",
  "updated_at": "2025-01-11T00:00:00Z",
  "last_updated": "2026-01-11T04:19:15.816374+00:00"
}