From ac062d5c53e526afbd4d685fa651788026456241 Mon Sep 17 00:00:00 2001
From: Michael Czechowski <mail@dailysh.it>
Date: Tue, 30 Dec 2025 12:25:33 +0100
Subject: [PATCH] docs: add lesson design best practices to CLAUDE.md

Document learnings for creating effective lessons:
- Clear task instructions with selector and property
- Use codePrefix for context
- Simple, human-friendly values
- Named CSS colors for engagement
- Focused validations
- Semantic HTML in examples
---
 CLAUDE.md | 32 ++++++++++++++++++++++++++++++++
 README.md |  4 ++--
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 29fac00..6252da6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -67,6 +67,38 @@ When creating or editing lessons:
 - Use native form validation attributes instead of JavaScript validation
 - Teach the platform's native capabilities first
 
+### Lesson Design Best Practices
+
+**Clear Task Instructions:**
+- Always state the selector AND the property explicitly in the task
+- Good: "Add `display: flex` to `.flex-container`"
+- Bad: "Use flexbox to align the items" (unclear what selector to use)
+
+**Use `codePrefix` for Context:**
+- Include the selector in `codePrefix` so students know where to write
+- Example: `"codePrefix": ".flex-container {\n  "` with `"codeSuffix": "\n}"`
+- This shows students exactly which rule they're editing
+
+**Simple, Human-Friendly Values:**
+- Use round numbers: `1rem` not `1.25rem`, `8px` not `0.5rem`
+- Avoid tiny values: `2px` not `0.125rem`
+- Students should focus on learning concepts, not deciphering odd numbers
+
+**Named CSS Colors:**
+- Use descriptive color names: `steelblue`, `coral`, `mediumseagreen`, `gold`
+- Avoid hex codes: `#3498db` is less memorable than `steelblue`
+- Named colors make lessons more engaging and easier to remember
+
+**Focused Validations:**
+- When `codePrefix` includes the selector, validations only need to check the property value
+- Use `property_value` type for direct checks: `{ "property": "display", "expected": "flex" }`
+- Avoid redundant `contains` checks when `property_value` already validates the same thing
+
+**Semantic HTML in Examples:**
+- Never use non-semantic wrapper classes like `.form-group` or `.container`
+- Use semantic HTML elements that match the context
+- Keep `previewHTML` clean and focused on the lesson objective
+
 ## Git Commits
 
 - Do NOT add co-authoring lines to commit messages
diff --git a/README.md b/README.md
index 4226f02..5bbb5b8 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ Code Crispies is a web-based learning platform designed to help users master CSS
 
 1. Clone the repository:
    ```bash
-   git clone https://github.com/nextlevelshit/code-crispies.git
+   git clone https://git.librete.ch/public/code-crispies.git
    cd code-crispies
    ```
 
@@ -244,4 +244,4 @@ When adding new lessons:
 
 ## 📄 License
 
-Copyright (c) 2025 Michael Czechowski. Licensed under the [./LICENSE](WTFPL).
\ No newline at end of file
+Copyright (c) 2025 Michael Czechowski. Licensed under the [./LICENSE](WTFPL).