266 lines
11 KiB
Plaintext
266 lines
11 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
|
|
|
|
=== 2026-01-11 - Subtask 3.2 Completed ===
|
|
Added conceptual explanations to all 6 CSS Grid lessons.
|
|
|
|
Implementation details:
|
|
- Added 'concept' objects to all Grid lessons explaining the 2D grid system, tracks, and cell placement
|
|
- Lesson 1 (Grid Container Basics):
|
|
* Explanation of 2D layout system, tracks (rows/columns), 1fr units, and gap property
|
|
* Diagram showing grid container with 3 equal columns and 2 rows
|
|
* Container vs Item: display: grid, grid-template-columns, and gap are container properties
|
|
- Lesson 2 (Grid Template Areas):
|
|
* Explanation of ASCII-art layouts and named grid areas for spanning
|
|
* Diagram showing visual layout with header, sidebar, content, footer regions
|
|
* Container vs Item: grid-template-areas (container) vs grid-area (item)
|
|
- Lesson 3 (Spanning Grid Cells):
|
|
* Explanation of spanning multiple cells with grid-column/grid-row span keyword
|
|
* Diagram showing 2x2 spanning featured item with auto-flow around it
|
|
* Container vs Item: grid-column and grid-row are item properties
|
|
- Lesson 4 (Automatic Grid Placement):
|
|
* Explanation of auto-fit with minmax for responsive grids without media queries
|
|
* Diagram comparing wide vs narrow viewport behavior
|
|
* Container vs Item: grid-template-columns with auto-fit is a container property
|
|
- Lesson 5 (Grid Alignment):
|
|
* Explanation of justify-items (horizontal) and align-items (vertical) alignment
|
|
* Diagram showing items centered within grid cells on both axes
|
|
* Container vs Item: justify-items/align-items (container) can be overridden by justify-self/align-self (item)
|
|
- Lesson 6 (Overlapping Grid Items):
|
|
* Explanation of overlapping items in same cell using explicit positioning and z-index
|
|
* Diagram showing layered items with z-index stacking
|
|
* Container vs Item: grid-column, grid-row, and z-index are item properties
|
|
- All explanations are beginner-friendly, 2-4 sentences
|
|
- ASCII diagrams provide visual understanding of grid concepts
|
|
- Clear distinction between container and item properties throughout
|
|
|
|
Committed: 29c019b
|
|
Status: ✓ Completed
|
|
|
|
=== 2026-01-11 - Subtask 3.3 Completed ===
|
|
Added conceptual explanations for CSS selector specificity and cascade.
|
|
|
|
Implementation details:
|
|
- Added 'concept' objects to 4 lessons in lessons/00-basic-selectors.json
|
|
- Lesson 7 (Type + ID): Explains specificity boost from combining type and ID selectors
|
|
* Shows how p#special has higher specificity than #special alone
|
|
* Diagram demonstrates both conditions must match (type AND id)
|
|
* Emphasizes enforcement pattern for IDs on specific element types
|
|
- Lesson 8 (Selector Lists): Explains OR logic and independent matching
|
|
* Shows how comma-separated selectors are treated independently
|
|
* Diagram demonstrates each selector matches separately
|
|
* Clarifies that selectors maintain individual specificity
|
|
- Lesson 9 (Universal Selector): Explains wildcard matching and descendant context
|
|
* Shows how * matches all element types
|
|
* Diagram demonstrates descendant relationship with space
|
|
* Explains difference between global * and contextual .container *
|
|
- Lesson 10 (Specificity): Explains CASCADE and specificity point system
|
|
* Introduces point system: IDs=100, classes=10, elements=1
|
|
* Diagram shows specificity calculation with example selectors
|
|
* Demonstrates how higher specificity wins the cascade
|
|
- All explanations are beginner-friendly, 2-4 sentences
|
|
- ASCII diagrams provide visual understanding of selector matching and cascade resolution
|
|
- Focuses on WHY certain selectors match and HOW conflicts are resolved
|
|
|
|
Committed: 39f1fb5
|
|
Status: ✓ Completed
|
|
|
|
=== 2026-01-11 - Subtask 3.5 Completed ===
|
|
Added conceptual explanations to advanced selectors (02-selectors.json).
|
|
|
|
Implementation details:
|
|
- Added 'concept' objects to all 4 lessons explaining advanced selector concepts
|
|
- Lesson 1 (Element Selectors):
|
|
* Explanation of DOM traversal and how browser matches tag names
|
|
* ASCII diagram showing browser checking each element type
|
|
* Specificity: 0,0,0,1 (lowest - easy to override)
|
|
- Lesson 2 (Class Selectors):
|
|
* Explanation of attribute matching independent of element type
|
|
* Diagram showing class matching across different element types
|
|
* Specificity: 0,0,1,0 (10x stronger than elements)
|
|
- Lesson 3 (ID Selectors):
|
|
* Explanation of unique ID matching and high specificity
|
|
* Diagram showing single match and specificity comparison table
|
|
* Specificity: 0,1,0,0 (100x stronger than classes)
|
|
* Explains why developers prefer classes over IDs
|
|
- Lesson 4 (Combined Selectors):
|
|
* Explanation of AND logic (no space between selectors)
|
|
* Diagram showing both conditions must match
|
|
* Specificity addition: div.note = 0,0,1,1 beats .note = 0,0,1,0
|
|
* Emphasizes how cascade resolves conflicts with specificity
|
|
- All explanations are beginner-friendly (2-4 sentences)
|
|
- ASCII diagrams provide visual understanding of selector matching
|
|
- Focus on WHY selectors work and HOW specificity cascade resolves conflicts
|
|
- Explains the fundamental CSS specificity point system throughout
|
|
|
|
Committed: 3df98fe
|
|
Status: ✓ Completed
|