diff --git a/.auto-claude/specs/001-conceptual-explanations/build-progress.txt b/.auto-claude/specs/001-conceptual-explanations/build-progress.txt new file mode 100644 index 0000000..762f08a --- /dev/null +++ b/.auto-claude/specs/001-conceptual-explanations/build-progress.txt @@ -0,0 +1,124 @@ +# 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
element for 'Why This Works' section. + +Implementation details: +- Added concept section in src/index.html within .instructions section (lines 37-44) +- Used semantic HTML5
element for native collapsible behavior +- Included 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 diff --git a/.auto-claude/specs/001-conceptual-explanations/implementation_plan.json b/.auto-claude/specs/001-conceptual-explanations/implementation_plan.json new file mode 100644 index 0000000..bca8e35 --- /dev/null +++ b/.auto-claude/specs/001-conceptual-explanations/implementation_plan.json @@ -0,0 +1,221 @@ +{ + "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" +} \ No newline at end of file