171 lines
6.1 KiB
Plaintext
171 lines
6.1 KiB
Plaintext
# Build Progress: Conceptual Explanations Feature
|
|
|
|
## Overview
|
|
Adding "Why This Works" explanations to each lesson that explain the concept behind CSS properties, not just syntax.
|
|
|
|
## Status: Planning Complete
|
|
|
|
### Implementation Plan Created: 2025-01-11
|
|
|
|
**6 Phases with 20 Subtasks:**
|
|
|
|
1. **Schema & Data Model** (1 subtask)
|
|
- Update lesson JSON schema with concept field
|
|
|
|
2. **UI Components** (4 subtasks)
|
|
- Add collapsible concept section to HTML
|
|
- Style the concept section
|
|
- Update renderer to display concepts
|
|
- Add i18n keys for concept UI
|
|
|
|
3. **Content - Core CSS Modules** (5 subtasks)
|
|
- Flexbox lessons (with container vs item distinction)
|
|
- Grid lessons
|
|
- Basic selectors
|
|
- Box model
|
|
- Advanced selectors
|
|
|
|
4. **Content - Visual & Layout Modules** (6 subtasks)
|
|
- Colors, Typography, Units/Variables
|
|
- Transitions/Animations, Layouts, Responsive
|
|
|
|
5. **Content - HTML & Tailwind Modules** (4 subtasks)
|
|
- HTML elements, Forms, Advanced HTML elements
|
|
- Tailwind basics
|
|
|
|
6. **Testing & Polish** (3 subtasks)
|
|
- Unit tests, Mobile responsiveness, Final review
|
|
|
|
---
|
|
|
|
## Codebase Analysis
|
|
|
|
### Key Files:
|
|
- schemas/code-crispies-module-schema.json - Lesson schema definition
|
|
- src/index.html - Main HTML layout
|
|
- src/main.css - Styles
|
|
- src/helpers/renderer.js - Lesson rendering
|
|
- src/i18n.js - Internationalization
|
|
- lessons/*.json - ~30 lesson modules (EN), with translations
|
|
|
|
### Current Lesson Structure:
|
|
- Lessons have: id, title, description, task, previewHTML, validations
|
|
- No "concept" field exists yet
|
|
- Description field is used for general info, not conceptual explanations
|
|
|
|
### UI Pattern:
|
|
- Uses native HTML5 elements (dialog, details/summary elsewhere)
|
|
- Left panel: instructions + editor
|
|
- Right panel: preview + navigation
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
Ready to begin Phase 1: Schema & Data Model
|
|
|
|
[2025-01-11 - Subtask 1.1 COMPLETED]
|
|
✓ Added 'concept' object field to lesson schema (code-crispies-module-schema.json)
|
|
✓ Schema properties:
|
|
- explanation: required string for 2-4 sentence beginner-friendly explanation
|
|
- diagram: optional string for SVG/ASCII art visualizations
|
|
- containerVsItem: optional string for Flexbox/Grid container vs item distinction
|
|
✓ Schema validated successfully
|
|
✓ Committed changes: 4486078
|
|
|
|
|
|
=== 2026-01-11 - Subtask 2.1 Completed ===
|
|
Added native <details><summary> element for 'Why This Works' section.
|
|
|
|
Implementation details:
|
|
- Added concept section in src/index.html within .instructions section (lines 37-44)
|
|
- Used semantic HTML5 <details> element for native collapsible behavior
|
|
- Included <summary> with data-i18n="whyThisWorks" for internationalization
|
|
- Created three content divs: concept-explanation, concept-diagram, concept-container-vs-item
|
|
- Maintained proper indentation and tab formatting
|
|
- Follows accessibility best practices with semantic HTML
|
|
|
|
Committed: 2a9565c
|
|
Status: ✓ Completed
|
|
|
|
|
|
=== 2026-01-11 - Subtask 2.2 Completed ===
|
|
Added CSS styles for the concept panel with distinct visual treatment and smooth animations.
|
|
|
|
Implementation details:
|
|
- Added comprehensive CSS styles for all concept section elements in src/main.css
|
|
- Distinct visual treatment:
|
|
* Light purple background (var(--primary-bg-light))
|
|
* 3px left border in primary color for visual emphasis
|
|
* Hover effects changing background to var(--primary-bg-medium)
|
|
* Open state styling for active disclosure
|
|
- Smooth animations:
|
|
* Rotating arrow icon (▶ to ▼) with 0.2s transition
|
|
* Fade-in and slide-down animation (concept-expand keyframes)
|
|
* Background color transitions on hover
|
|
- Diagram container styling:
|
|
* White background with border and padding
|
|
* Monospace font for code/diagrams
|
|
* Overflow-x handling for wide diagrams
|
|
* Auto-hide when empty using :empty pseudo-class
|
|
- Special container-vs-item section:
|
|
* Success color theming (green background and border)
|
|
* Distinct styling to highlight Flexbox/Grid distinctions
|
|
- RTL support:
|
|
* Border positions flip for right-to-left languages
|
|
* Flex direction reversal for proper layout
|
|
- CSS variables used throughout for consistency:
|
|
* --spacing-* for all spacing
|
|
* --primary-*, --success-* for colors
|
|
* --border-radius-* for border radii
|
|
* --font-code for monospace text
|
|
- Follows all existing codebase patterns and design system
|
|
|
|
Committed: 0e39cff
|
|
Status: ✓ Completed
|
|
|
|
|
|
=== 2026-01-11 - Subtask 2.3 Completed ===
|
|
Modified renderer.js renderLesson() function to populate the concept section.
|
|
|
|
Implementation details:
|
|
- Added logic to populate concept section elements in renderLesson() function
|
|
- Get references to concept DOM elements by ID:
|
|
* concept-section (details element)
|
|
* concept-explanation (explanation text container)
|
|
* concept-diagram (optional diagram container)
|
|
* concept-container-vs-item (optional Flexbox/Grid distinction)
|
|
- Conditional rendering based on lesson.concept existence:
|
|
* Show concept section when lesson.concept exists with explanation
|
|
* Hide concept section when concept is not defined
|
|
- Field population:
|
|
* explanation: uses textContent (safe for user content, required field)
|
|
* diagram: uses innerHTML (supports SVG markup, optional field)
|
|
* containerVsItem: uses textContent (safe for user content, optional field)
|
|
- Clear optional fields when not present to prevent stale data from previous lessons
|
|
- Follows existing code patterns in renderer.js
|
|
- Proper null checks for all DOM elements
|
|
|
|
Committed: e21bca1
|
|
Status: ✓ Completed
|
|
|
|
|
|
=== 2026-01-11 - Subtask 2.4 Completed ===
|
|
Added 'whyThisWorks' translation key for the concept section heading.
|
|
|
|
Implementation details:
|
|
- Added translation key to src/i18n.js for all 6 supported languages
|
|
- Translations added:
|
|
* en (English): "Why This Works"
|
|
* de (German): "Warum das funktioniert"
|
|
* pl (Polish): "Dlaczego to działa"
|
|
* es (Spanish): "Por qué funciona"
|
|
* ar (Arabic): "لماذا يعمل هذا"
|
|
* uk (Ukrainian): "Чому це працює"
|
|
- Translation key matches the data-i18n attribute in the concept section summary element
|
|
- Follows existing i18n.js structure and patterns
|
|
- Placed in "Instructions" comment section for consistency
|
|
- Phase 2 (UI Components) is now complete - all 4 subtasks finished
|
|
|
|
Committed: 3c08b45
|
|
Status: ✓ Completed
|