{ "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
element for 'Why This Works' section in index.html within the .instructions section. Use semantic HTML5 for accessibility.", "status": "completed", "notes": "Successfully added native
element for 'Why This Works' section in src/index.html within the .instructions section. The implementation includes:\n- Semantic HTML5
element with id='concept-section'\n- 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": "pending", "notes": "" }, { "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": "pending", "notes": "" } ] }, { "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": "pending", "notes": "" }, { "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": "pending", "notes": "" }, { "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": "pending", "notes": "" }, { "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": "pending", "notes": "" }, { "id": "3.5", "title": "Add concepts to 02-selectors.json", "description": "Add explanations for advanced selectors including pseudo-classes and combinators.", "status": "pending", "notes": "" } ] }, { "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-11T03:35:41.967508+00:00" }