From b25e6a4e2080b60b3fbfcae6310882c2cd8aae54 Mon Sep 17 00:00:00 2001 From: Michael Czechowski Date: Sun, 29 Mar 2026 23:24:32 +0200 Subject: [PATCH] docs: add spec, plan, and tasks for filters task wording fix (#12) --- specs/012-filters-tasks/plan.md | 65 ++++++++++++++++++++++++++++++++ specs/012-filters-tasks/spec.md | 30 +++++++++++++++ specs/012-filters-tasks/tasks.md | 12 ++++++ 3 files changed, 107 insertions(+) create mode 100644 specs/012-filters-tasks/plan.md create mode 100644 specs/012-filters-tasks/spec.md create mode 100644 specs/012-filters-tasks/tasks.md diff --git a/specs/012-filters-tasks/plan.md b/specs/012-filters-tasks/plan.md new file mode 100644 index 0000000..d878e58 --- /dev/null +++ b/specs/012-filters-tasks/plan.md @@ -0,0 +1,65 @@ +# Implementation Plan + +## Objective + +Rewrite the 4 CSS Filters lessons in `lessons/11-filters.json` so tasks describe visual outcomes instead of giving exact CSS code, and validations accept multiple valid answers. + +## Approach + +Follow the same pattern established in issue #9 (colors/box-model rewrite): +1. Rewrite each `task` field to describe the desired visual effect +2. Replace exact-match validations (`property_value`, `contains`) with `regex` validations that accept a range of values +3. Update validation `message` fields to give pedagogical hints without revealing answers +4. Keep `description`, `previewHTML`, `previewBaseCSS`, `codePrefix`, `codeSuffix`, and `solution` unchanged + +## File Mapping + +| File | Action | Description | +|------|--------|-------------| +| `lessons/11-filters.json` | modify | Rewrite tasks and validations for all 4 lessons | + +## Lesson-by-Lesson Plan + +### filters-1: Blur Filter +- **Current task:** "Blur the background image using `filter: blur(4px)`." +- **New task:** Describe frosted-glass effect, mention blur radius range (2px-8px) +- **Validation:** `regex` matching `filter:\s*blur\((2|3|4|5|6|7|8)px\)` — accepts 2px through 8px +- **Message:** Hint about the `filter` property and `blur()` function + +### filters-2: Grayscale Filter +- **Current task:** "Make the image grayscale with `filter: grayscale(100%)`." +- **New task:** Describe removing all color to create a black-and-white effect +- **Validation:** `regex` matching `filter:\s*grayscale\(100%\)` — grayscale only makes sense at 100% for "fully desaturated" +- **Message:** Hint about which filter function removes color + +### filters-3: Brightness Filter +- **Current task:** "Brighten the card with `filter: brightness(120%)`." +- **New task:** Describe making the card appear brighter/more vivid, accept range 110%-150% +- **Validation:** `regex` matching `filter:\s*brightness\(1[1-5]0%\)` — accepts 110% through 150% +- **Message:** Hint about the brightness function and values above 100% + +### filters-4: Drop Shadow +- **Current task:** "Add a drop shadow with `filter: drop-shadow(4px 4px 8px gray)`." +- **New task:** Describe adding a soft shadow behind the star to give it depth +- **Validation:** `regex` matching `filter:\s*drop-shadow\(` with reasonable offset/blur values +- **Message:** Hint about the drop-shadow filter function + +## Architecture Decisions + +- Use `regex` validation type (not `property_value`) to allow multiple acceptable values, consistent with the colors/box-model rewrite +- Use `options: { "caseSensitive": false }` on all regex validations for consistency +- Keep solution fields unchanged as reference answers + +## Risks + +| Risk | Mitigation | +|------|------------| +| Regex too permissive | Test edge cases; only accept pedagogically reasonable values | +| Regex too restrictive | Allow generous ranges; err on the side of accepting creative answers | +| Breaking existing progress | localStorage keys are based on lesson IDs which are unchanged | + +## Testing Strategy + +- Run existing test suite (`npm test`) to verify no regressions +- Validate JSON file against schema +- Manual review of regex patterns for correctness diff --git a/specs/012-filters-tasks/spec.md b/specs/012-filters-tasks/spec.md new file mode 100644 index 0000000..f62d1e3 --- /dev/null +++ b/specs/012-filters-tasks/spec.md @@ -0,0 +1,30 @@ +# fix: rewrite CSS Filters tasks to describe visual outcomes instead of exact code + +**Issue:** [#12](https://git.librete.ch/libretech/code-crispies/issues/12) +**Repository:** libretech/code-crispies +**Author:** libretech +**State:** open +**Labels:** none + +## Problem + +Pedagogy audit: the Filters module has a 100% copy-paste score. Every exercise gives the exact CSS declaration in the task text, so students can complete lessons without understanding the concepts. + +## Requirements + +- Rewrite ONLY the filters module (`lessons/11-filters.json`) task descriptions to describe the desired visual effect instead of the exact code +- Accept multiple valid values in validations (e.g., accept blur values between 2px and 8px instead of only 4px) +- Do NOT change any other module + +## Example + +- **Before:** "Add `filter: blur(4px)`" +- **After:** "Blur the background image to create a frosted-glass effect. Use a blur radius between 2px and 8px." + +## Acceptance Criteria + +1. All 4 filter lesson tasks describe visual outcomes, not exact CSS +2. Validations accept a range of valid values using regex patterns +3. Validation messages provide pedagogical hints without revealing answers +4. No changes to any file outside `lessons/11-filters.json` +5. Existing tests continue to pass diff --git a/specs/012-filters-tasks/tasks.md b/specs/012-filters-tasks/tasks.md new file mode 100644 index 0000000..89b67da --- /dev/null +++ b/specs/012-filters-tasks/tasks.md @@ -0,0 +1,12 @@ +# Tasks + +## Phase 1: Core Implementation +- [ ] Task 1.1: Rewrite filters-1 (Blur) task and validations [P] +- [ ] Task 1.2: Rewrite filters-2 (Grayscale) task and validations [P] +- [ ] Task 1.3: Rewrite filters-3 (Brightness) task and validations [P] +- [ ] Task 1.4: Rewrite filters-4 (Drop Shadow) task and validations [P] + +## Phase 2: Validation +- [ ] Task 2.1: Validate JSON against schema +- [ ] Task 2.2: Run existing test suite +- [ ] Task 2.3: Format lesson file with Prettier