diff --git a/specs/009-colors-boxmodel-tasks/plan.md b/specs/009-colors-boxmodel-tasks/plan.md new file mode 100644 index 0000000..1c55305 --- /dev/null +++ b/specs/009-colors-boxmodel-tasks/plan.md @@ -0,0 +1,106 @@ +# Implementation Plan + +## Objective + +Rewrite task descriptions in the Colors (4 lessons) and Box Model (8 lessons x 6 locales) modules so they describe desired visual outcomes rather than giving exact CSS declarations. For colors, also update validations to accept multiple valid color values. + +## Approach + +This follows the same pattern as the flexbox fix (PR #5). Two types of changes: + +1. **Colors module**: Rewrite tasks AND update validations from `property_value` (single answer) to `regex` (multiple valid colors). This is because the issue explicitly says "accept multiple valid solutions" and colors naturally have many equivalent options. +2. **Box Model module**: Rewrite tasks only. Validation messages already use pedagogical hints. Box model properties have specific correct answers (e.g., `box-sizing: border-box` has no alternative), so validations stay as-is. + +## File Mapping + +| File | Action | Description | +|------|--------|-------------| +| `lessons/03-colors.json` | modify | Rewrite 4 tasks + change 4 validations from `property_value` to `regex` | +| `lessons/01-box-model.json` | modify | Rewrite 8 task fields | +| `lessons/ar/01-box-model.json` | modify | Rewrite 8 task fields (Arabic) | +| `lessons/de/01-box-model.json` | modify | Rewrite 8 task fields (German) | +| `lessons/es/01-box-model.json` | modify | Rewrite 8 task fields (Spanish) | +| `lessons/pl/01-box-model.json` | modify | Rewrite 8 task fields (Polish) | +| `lessons/uk/01-box-model.json` | modify | Rewrite 8 task fields (Ukrainian) | + +No validator code changes needed — existing `regex` type already supports multi-value patterns. + +## Detailed Changes + +### Colors Module + +#### colors-1 (Background Color) +- **Task**: Describe that notification card looks bare, needs a soft warm background +- **Validation**: Change from `property_value` (seashell only) to `regex` accepting warm named colors (seashell, linen, mistyrose, lavenderblush, cornsilk, oldlace, papayawhip, antiquewhite, bisque, peachpuff) +- **Message**: Hint at background-color property + +#### colors-2 (Text Color) +- **Task**: Describe that title needs to pop with a warm accent color +- **Validation**: Change from `property_value` (coral only) to `regex` accepting warm accent colors (coral, tomato, orangered, indianred, salmon, darksalmon) +- **Message**: Hint at color property + +#### colors-3 (Border Color) +- **Task**: Describe that card border needs a warm accent color +- **Validation**: Change from `property_value` (coral only) to `regex` accepting warm accent colors (coral, tomato, orangered, indianred, salmon, darksalmon, crimson) +- **Message**: Hint at border-color property + +#### colors-4 (Hex Colors) +- **Task**: Describe wanting a gold/yellow badge background, mentioning hex format since that's the lesson's teaching point +- **Validation**: Change from `property_value` (#ffd700 only) to `regex` accepting gold hex variants (#ffd700, #ffcc00, #ffc107, #f0c000) and also the named color `gold` +- **Message**: Hint at using a hex code for background-color + +### Box Model Module (per-lesson, applied across all 6 locales) + +#### box-model-1 (Padding) +- **Current**: "Add `padding: 1rem`..." +- **New**: Describe that text is pressed against the edges and needs inner breathing room + +#### box-model-2 (Borders) +- **Current**: "Add `border-left: 4px solid steelblue`" +- **New**: Describe wanting a colored accent line on the left side of the card + +#### box-model-3 (Margins) +- **Current**: "Add `margin-bottom: 1rem`" +- **New**: Describe that the two cards are touching and need space between them + +#### box-model-4 (Box Sizing) +- **Current**: "Fix with `box-sizing: border-box`" +- **New**: Describe the visual problem (right card overflows) and ask to fix its sizing model + +#### box-model-5 (Padding Shorthand) +- **Current**: "Set `padding: 8px 1rem`" +- **New**: Describe the button needing more horizontal than vertical space, mention the two-value shorthand concept + +#### box-model-6 (Margin Shorthand) +- **Current**: "Set `margin: 0 auto`" +- **New**: Describe the card being left-aligned and needing to be horizontally centered + +#### box-model-7 (Border Radius) +- **Current**: "Make with `border-radius: 50%`" +- **New**: Describe the square avatar needing to appear as a circle + +#### box-model-8 (Complete Card) +- **Current**: Lists all 3 exact property declarations +- **New**: Describe three visual goals: inner spacing, left accent line, softened corners + +## Architecture Decisions + +1. **No validator code changes**: The existing `regex` validation type handles multi-value matching. +2. **Colors get multi-value validations**: Colors naturally have equivalents (coral vs tomato). Accept a curated set of named colors per lesson. +3. **Box model keeps exact validations**: Properties like `padding: 1rem` or `box-sizing: border-box` have only one correct answer. The task text changes are sufficient. +4. **Solution fields unchanged**: The `solution` field shows the canonical answer and is unrelated to copy-paste behavior. +5. **codePrefix unchanged**: Already shows the selector context. + +## Risks + +| Risk | Likelihood | Mitigation | +|------|-----------|------------| +| Color regex too permissive/restrictive | Medium | Curate a small set of 6-10 named colors per lesson that visually work in the preview | +| Locale translations lose nuance | Low | Follow the same structure: describe the visual outcome in each language | +| Box model tasks become too vague | Low | Keep mentioning the visual problem — students have the description for concept reference | + +## Testing Strategy + +1. Run `npm run test` — all existing tests should pass +2. Run `npm run format.lessons` — ensure JSON files are properly formatted +3. Verify JSON schema conformance for all modified files diff --git a/specs/009-colors-boxmodel-tasks/spec.md b/specs/009-colors-boxmodel-tasks/spec.md new file mode 100644 index 0000000..bf484a3 --- /dev/null +++ b/specs/009-colors-boxmodel-tasks/spec.md @@ -0,0 +1,50 @@ +# fix: rewrite colors and box-model task descriptions to remove copy-paste answers + +**Issue**: [public/code-crispies#9](https://git.librete.ch/public/code-crispies/issues/9) +**State**: open +**Author**: libretech +**Labels**: none +**Complexity**: medium + +## Issue Body + +Pedagogy audit Runde 3: Colors (copy-paste 90%) and Box Model (copy-paste 85%) are the next worst modules after flexbox was fixed. Same pattern — task says 'Add background-color: coral' and student just types it. Rewrite to describe desired outcome: 'The card background should be a warm color.' Accept multiple valid solutions. + +## Current State + +### Colors Module (`lessons/03-colors.json`) — English only, 4 lessons + +| Lesson | Current Task (gives away answer) | +|--------|----------------------------------| +| colors-1 | "Add `background-color: seashell`" | +| colors-2 | "Add `color: coral`" | +| colors-3 | "Add `border-color: coral`" | +| colors-4 | "Add `background-color: #ffd700`" | + +All 4 validations use `property_value` with exact expected values — only one answer accepted. + +### Box Model Module (`lessons/01-box-model.json`) — 6 locales (en, ar, de, es, pl, uk), 8 lessons + +| Lesson | Current Task (gives away answer) | +|--------|----------------------------------| +| box-model-1 | "Add `padding: 1rem`" | +| box-model-2 | "Add `border-left: 4px solid steelblue`" | +| box-model-3 | "Add `margin-bottom: 1rem`" | +| box-model-4 | "Fix with `box-sizing: border-box`" | +| box-model-5 | "Set `padding: 8px 1rem`" | +| box-model-6 | "Set `margin: 0 auto`" | +| box-model-7 | "Make with `border-radius: 50%`" | +| box-model-8 | Lists all 3 properties verbatim | + +Box model validation messages are already well-written (hint without revealing). The `task` fields contain `` tags with exact answers. + +## Acceptance Criteria + +1. All 4 colors task descriptions rewritten to describe desired visual outcomes +2. All 8 box-model task descriptions rewritten to describe desired visual outcomes +3. Students cannot copy-paste from the task into the editor to pass +4. Colors validations accept multiple valid CSS color values where appropriate +5. Box-model validation messages remain as-is (already hint without revealing) +6. All 5 localized box-model files updated to match the English rewrite pattern +7. Existing tests continue to pass +8. Lesson descriptions (which teach the concepts) remain unchanged diff --git a/specs/009-colors-boxmodel-tasks/tasks.md b/specs/009-colors-boxmodel-tasks/tasks.md new file mode 100644 index 0000000..00556d5 --- /dev/null +++ b/specs/009-colors-boxmodel-tasks/tasks.md @@ -0,0 +1,22 @@ +# Tasks + +## Phase 1: Colors Module +- [ ] Task 1.1: Rewrite task text for all 4 colors lessons to describe visual outcomes +- [ ] Task 1.2: Change colors validations from property_value to regex accepting multiple valid color names +- [ ] Task 1.3: Update colors validation error messages to hint without revealing answers + +## Phase 2: Box Model Module (English) +- [ ] Task 2.1: Rewrite task text for all 8 box-model lessons to describe visual outcomes +- [ ] Task 2.2: Review box-model validation messages (already good, update only if needed) + +## Phase 3: Box Model Translations [P] +- [ ] Task 3.1: Rewrite task text in Arabic (ar/01-box-model.json) [P] +- [ ] Task 3.2: Rewrite task text in German (de/01-box-model.json) [P] +- [ ] Task 3.3: Rewrite task text in Spanish (es/01-box-model.json) [P] +- [ ] Task 3.4: Rewrite task text in Polish (pl/01-box-model.json) [P] +- [ ] Task 3.5: Rewrite task text in Ukrainian (uk/01-box-model.json) [P] + +## Phase 4: Validation +- [ ] Task 4.1: Run existing test suite to confirm no regressions +- [ ] Task 4.2: Run lesson format check (npm run format.lessons) +- [ ] Task 4.3: Verify all modified JSON files conform to module schema