223 lines
11 KiB
JSON
223 lines
11 KiB
JSON
{
|
|
"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": "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:40:28.748942+00:00"
|
|
} |