Michael Czechowski
782e87705c
Pedagogical validation message rewrite across 17 English lesson modules and 5 localized variants (ar, de, es, pl, uk).
88 lines
5.2 KiB
Markdown
88 lines
5.2 KiB
Markdown
# Implementation Plan
|
|
|
|
## 1. Objective
|
|
|
|
Rewrite all answer-revealing validation error messages across lesson JSON files to use pedagogical hints (concept questions, property-name nudges, directional guidance) instead of literal CSS solutions. This eliminates the fail-then-copy anti-pattern and promotes genuine learning.
|
|
|
|
## 2. Approach
|
|
|
|
**Phase-based, content-first strategy:**
|
|
|
|
1. Define a message style guide with 3 hint categories:
|
|
- **Concept question:** "Which property adds space inside an element?" (for property discovery)
|
|
- **Property hint:** "Check the `padding` property" (when the property is known but value is wrong)
|
|
- **Directional nudge:** "The items need to wrap to the next line" (for layout concepts)
|
|
|
|
2. Rewrite English priority modules first (flexbox, box-model, colors, positioning) — these are 100% answer-revealing and form the template for all other rewrites.
|
|
|
|
3. Rewrite remaining English modules, reusing the same hint patterns established in step 2.
|
|
|
|
4. Update localized variants with equivalent pedagogical messages in each target language (ar, de, es, pl, uk), translating the English hints while preserving natural phrasing in each language.
|
|
|
|
5. Run `npm run format.lessons` to ensure consistent formatting, then run tests.
|
|
|
|
## 3. File Mapping
|
|
|
|
### Files to modify (message field only, no validation logic changes):
|
|
|
|
**English priority (create → N/A, modify → 4, delete → N/A):**
|
|
- `lessons/flexbox.json` — modify 6 messages
|
|
- `lessons/01-box-model.json` — modify 10 messages
|
|
- `lessons/03-colors.json` — modify 4 messages
|
|
- `lessons/12-positioning.json` — modify 5 messages
|
|
|
|
**English remaining (modify → 13):**
|
|
- `lessons/00-basics.json` — modify 4 messages
|
|
- `lessons/00-basic-selectors.json` — modify 15 messages
|
|
- `lessons/01-advanced-selectors.json` — modify 8 messages
|
|
- `lessons/04-typography.json` — modify 1 message
|
|
- `lessons/05-units-variables.json` — modify 3 messages
|
|
- `lessons/06-transitions-animations.json` — modify 8 messages
|
|
- `lessons/07-layouts.json` — modify 8 messages
|
|
- `lessons/08-responsive.json` — modify 8 messages
|
|
- `lessons/09-gradients.json` — modify 3 messages
|
|
- `lessons/10-tailwind-basics.json` — modify 16 messages
|
|
- `lessons/11-filters.json` — modify 4 messages
|
|
- `lessons/13-pseudo-elements.json` — modify 4 messages
|
|
- `lessons/grid.json` — modify 5 messages
|
|
|
|
**Localized variants (modify):**
|
|
- `lessons/ar/flexbox.json`, `lessons/ar/01-box-model.json`, + other ar/ modules with answer-revealing messages
|
|
- `lessons/de/flexbox.json`, `lessons/de/01-box-model.json`, + other de/ modules
|
|
- `lessons/es/flexbox.json`, `lessons/es/01-box-model.json`, + other es/ modules
|
|
- `lessons/pl/flexbox.json`, `lessons/pl/01-box-model.json`, + other pl/ modules
|
|
- `lessons/uk/flexbox.json`, `lessons/uk/01-box-model.json`, + other uk/ modules
|
|
|
|
**No new files or deleted files.**
|
|
|
|
## 4. Architecture Decisions
|
|
|
|
1. **Message-only changes:** Only the `"message"` string within validation objects is modified. The `type`, `value`, and `options` fields remain untouched. This preserves all validation logic.
|
|
|
|
2. **No code changes to validator.js:** The validator reads the `message` field as a passthrough string for display. No runtime changes needed.
|
|
|
|
3. **Hint style per validation type:**
|
|
- `property_value` validations → concept question or property hint (since the property and value are tested programmatically, the message should teach the concept, not repeat the answer)
|
|
- `regex` validations → directional nudge describing the expected pattern conceptually
|
|
- `contains` / `contains_class` validations → concept question about what to include
|
|
|
|
4. **Localization approach:** Each localized message should be a natural translation of the English pedagogical hint, not a word-for-word translation. The hint category (question, nudge, property hint) should match the English version.
|
|
|
|
5. **Preserve `<kbd>` tags selectively:** `<kbd>` tags may still be used for property names (e.g., "Check the `<kbd>padding</kbd>` property") but never for complete property-value pairs that reveal the answer.
|
|
|
|
## 5. Risks
|
|
|
|
| Risk | Likelihood | Mitigation |
|
|
|------|-----------|------------|
|
|
| Pedagogical hints are too vague, frustrating learners | Medium | Each hint should name the relevant CSS property or concept — just not the exact value. The task description already provides context. |
|
|
| Localized translations lose pedagogical intent | Medium | Use consistent hint categories across languages. Review each language for natural phrasing. |
|
|
| Existing tests assert on specific message text | Low | Check test files for hardcoded message assertions before changing. Adjust tests if needed. |
|
|
| Formatting inconsistency after bulk edits | Low | Run `npm run format.lessons` after all changes. |
|
|
|
|
## 6. Testing Strategy
|
|
|
|
1. **Existing test suite:** Run `npm run test` to verify no regressions. The validator tests should pass since validation logic is unchanged.
|
|
2. **Grep audit:** After changes, grep all lesson files for remaining "Set <kbd>" patterns to confirm none were missed.
|
|
3. **JSON validity:** Ensure all modified JSON files parse correctly (the format.lessons command will catch syntax errors).
|
|
4. **Manual spot-check:** Verify a few lessons in the dev server to confirm messages display correctly in the UI.
|