From b0519749576a5ce0ac19eda0341d3774cb525b8e Mon Sep 17 00:00:00 2001 From: Michael Czechowski Date: Fri, 16 Jan 2026 13:47:42 +0100 Subject: [PATCH] docs: add comprehensive roadmap for lessons and milestone system - Analyze MDN HTML/CSS documentation for new lesson ideas - Design milestone-based progress system (1, 5, 10, 20, 30, 50, 75, 100) - Document 13 inactive lesson files ready to activate - Plan 34 new lessons to reach 100 total - Include technical implementation notes --- docs/ROADMAP.md | 287 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 docs/ROADMAP.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..7e59ed7 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,287 @@ +# Code Crispies Roadmap + +## Current State + +**Total Active Lessons:** ~66 (excluding welcome, goodbye, playground) +**Target:** 100 lessons for milestone system + +### Current Module Breakdown + +| Module | Lessons | Category | +|--------|---------|----------| +| Basic Selectors | 10 | CSS | +| Colors | 4 | CSS | +| Typography | 4 | CSS | +| Box Model | 8 | CSS | +| Flexbox | 6 | CSS | +| Grid | 6 | CSS | +| Units & Variables | 4 | CSS | +| Responsive | 4 | CSS | +| Transitions & Animations | 4 | CSS | +| HTML Elements | 2 | HTML | +| Figure | 3 | HTML | +| SVG | 3 | HTML | +| Details/Summary | 3 | HTML | +| Forms Basic | 3 | HTML | +| Forms Validation | 1 | HTML | +| Tables | 1 | HTML | +| **Total** | **66** | | + +--- + +## Phase 1: Milestone Progress System + +### Design + +Replace percentage-based progress with milestone markers: + +``` +[1] [5] [10] [20] [30] [50] [75] [100] + ● ● ◐ ○ ○ ○ ○ ○ +``` + +**Milestones:** +- 1 lesson - First Step +- 5 lessons - Getting Started +- 10 lessons - Rookie +- 20 lessons - Learner +- 30 lessons - Intermediate +- 50 lessons - Halfway Hero +- 75 lessons - Advanced +- 100 lessons - Master + +### Implementation + +1. **Update `LessonEngine.getProgressStats()`** + - Add `currentMilestone` and `nextMilestone` fields + - Add `milestonesReached: number[]` + +2. **Update Progress UI** + - Replace linear progress bar with milestone dots + - Animate milestone completion + - Show current milestone badge + +3. **Add Milestone Celebration** + - Confetti/animation on reaching milestones + - Achievement unlocks in sidebar + +--- + +## Phase 2: New Lessons (34 needed to reach 100) + +### Priority 1: Expand Existing Modules (+15 lessons) + +#### CSS Colors (+3) +- Gradients (linear-gradient) +- Color functions (hsl, rgb) +- Opacity and transparency + +#### Typography (+3) +- Web fonts (@font-face) +- Text shadows +- Letter/word spacing + +#### Responsive (+3) +- Container queries +- Aspect ratio +- Clamp() for fluid typography + +#### Transitions & Animations (+3) +- Keyframe animations +- Animation timing functions +- Transform origin + +#### Tables (+3) +- Table styling (borders, spacing) +- Responsive tables +- Table accessibility + +### Priority 2: New CSS Modules (+12 lessons) + +#### Filters & Effects (4 lessons) +- CSS filters (blur, brightness, contrast) +- Backdrop filters +- Mix-blend-mode +- Box shadows advanced + +#### Positioning (4 lessons) +- Relative positioning +- Absolute positioning +- Fixed/sticky positioning +- Z-index stacking + +#### Pseudo-elements (4 lessons) +- ::before and ::after +- ::first-letter and ::first-line +- ::marker for lists +- Content property + +### Priority 3: New HTML Modules (+7 lessons) + +#### Semantic Structure (3 lessons) +- Article vs Section +- Header/Footer/Main +- Nav and Aside + +#### Media Elements (2 lessons) +- Picture element (responsive images) +- Audio/Video basics + +#### Accessibility (2 lessons) +- ARIA labels +- Skip links +- Focus management + +--- + +## MDN Topics Reference + +### CSS Topics from MDN (prioritized for interactive lessons) + +**Layout Systems:** +- [x] Flexbox (covered) +- [x] Grid (covered) +- [ ] Multi-column layout +- [ ] Positioned layout (z-index, stacking) + +**Visual Effects:** +- [x] Colors (partially covered) +- [ ] Filters (blur, brightness, contrast, drop-shadow) +- [ ] Blend modes (mix-blend-mode, background-blend-mode) +- [ ] Masking and clipping +- [ ] Shapes (shape-outside) + +**Typography:** +- [x] Basic text (covered) +- [ ] Web fonts (@font-face) +- [ ] Variable fonts +- [ ] Text decoration advanced + +**Animations:** +- [x] Transitions (covered) +- [ ] Keyframe animations +- [ ] Scroll-driven animations (experimental) +- [ ] View transitions + +**Advanced:** +- [x] Custom properties (covered in units-variables) +- [ ] Container queries +- [ ] Anchor positioning (new) +- [ ] Logical properties (for RTL support) + +### HTML Topics from MDN + +**Structural:** +- [x] Basic elements (covered) +- [x] Figure/figcaption (covered) +- [ ] Article vs section semantics +- [ ] Template element + +**Interactive:** +- [x] Details/Summary (covered) +- [x] Dialog (have JSON, not active) +- [ ] Datalist (have JSON, not active) +- [ ] Progress/Meter (have JSON, not active) + +**Forms:** +- [x] Basic forms (covered) +- [x] Validation (covered) +- [x] Fieldset (have JSON, not active) +- [ ] Input types exploration + +**Media:** +- [x] SVG basics (covered) +- [ ] Picture element +- [ ] srcset and sizes +- [ ] Audio/Video + +--- + +## Inactive Lesson Files (Ready to Activate) + +These lesson files exist but aren't in the active module list: + +| File | Lessons | Topic | +|------|---------|-------| +| 24-html-progress-meter.json | 3 | Progress/Meter elements | +| 25-html-datalist.json | 2 | Datalist for autocomplete | +| 27-html-dialog.json | 2 | Native dialog element | +| 28-html-forms-fieldset.json | 3 | Fieldset/legend grouping | +| 31-html-marquee.json | 3 | Marquee (deprecated but fun) | +| **Total** | **13** | | + +**Quick Win:** Activating these adds 13 lessons immediately → 79 total + +--- + +## Implementation Order + +### Week 1: Foundation +1. Design milestone UI component +2. Implement milestone progress system +3. Add milestone celebrations + +### Week 2: Quick Wins +4. Activate 5 inactive HTML modules (+13 lessons) +5. Test and fix translations + +### Week 3-4: New Content +6. Create Filters & Effects module (+4) +7. Create Positioning module (+4) +8. Expand existing modules (+7) + +### Final Polish +9. Reach 100 lessons milestone +10. Add milestone achievements to sidebar +11. Update landing page messaging + +--- + +## Technical Notes + +### Milestone Data Structure + +```js +const MILESTONES = [1, 5, 10, 20, 30, 50, 75, 100]; + +function getMilestoneProgress(completed) { + const reached = MILESTONES.filter(m => completed >= m); + const current = reached[reached.length - 1] || 0; + const next = MILESTONES.find(m => m > completed) || 100; + + return { + current, + next, + reached, + percentToNext: ((completed - current) / (next - current)) * 100 + }; +} +``` + +### Progress Display Update + +```html +
+
+ 1 + 5 + 10 + 20 + +
+
+
+
+ 12 of 100 lessons +
+``` + +--- + +## Success Metrics + +- [ ] 100 total lessons +- [ ] Milestone system implemented +- [ ] All 6 languages have translations +- [ ] Achievement celebrations working +- [ ] Mobile responsive milestone UI