Michael Czechowski
ac062d5c53
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
106 lines
4.9 KiB
Markdown
106 lines
4.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Code Crispies is an interactive CSS/Tailwind learning platform built with pure JavaScript (ES Modules) and Vite. Users complete lessons by writing CSS or Tailwind code that passes validation rules.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm start # Start dev server at http://localhost:1312
|
|
npm run build # Production build to dist/
|
|
npm run test # Run tests once
|
|
npm run test.watch # Run tests in watch mode
|
|
npm run test.coverage # Run tests with coverage report
|
|
npm run format # Format source files with Prettier
|
|
npm run format.lessons # Format lesson JSON files
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
- **LessonEngine** (`src/impl/LessonEngine.js`): Single source of truth for lesson state, progress tracking, and code validation. Manages user code application to preview iframes and persists progress to localStorage.
|
|
|
|
- **Validator** (`src/helpers/validator.js`): Validates user code against lesson requirements. Supports validation types: `contains`, `contains_class`, `not_contains`, `regex`, `property_value`, `syntax`, `custom`.
|
|
|
|
- **Lesson Config** (`src/config/lessons.js`): Loads and validates lesson modules from JSON. Modules are imported statically and stored in `moduleStore`.
|
|
|
|
### Data Flow
|
|
|
|
1. Lesson JSON files define modules with lessons, each containing `previewHTML`, `validations`, and other metadata
|
|
2. `LessonEngine` loads modules and tracks user progress per lesson
|
|
3. User code is applied to an iframe preview and validated against lesson rules
|
|
4. Progress is persisted to `localStorage` under `codeCrispies.progress` and `codeCrispies.userCode`
|
|
|
|
### Lesson Structure
|
|
|
|
Lessons are JSON files in `lessons/` following the schema in `schemas/code-crispies-module-schema.json`. Each module has:
|
|
- `mode`: "css" or "tailwind"
|
|
- `difficulty`: "beginner", "intermediate", or "advanced"
|
|
- `lessons[]`: Array of lessons with validations
|
|
|
|
For Tailwind mode, user classes are injected via `{{USER_CLASSES}}` placeholder in `previewHTML`.
|
|
|
|
### Testing
|
|
|
|
Tests use Vitest with jsdom environment. Setup in `tests/setup.js` includes DOM testing library matchers. Test files are in `tests/unit/`.
|
|
|
|
## Code Quality Standards
|
|
|
|
This project adheres to the highest standards for web development:
|
|
|
|
- **Semantic HTML5**: Always use semantic elements (`<header>`, `<nav>`, `<main>`, `<article>`, `<section>`, `<footer>`, `<figure>`, etc.) over generic `<div>` containers
|
|
- **WCAG Compliance**: Ensure accessibility - proper heading hierarchy, ARIA labels where needed, keyboard navigation support
|
|
- **Native HTML over JavaScript**: Prefer native HTML elements and attributes (e.g., `<dialog>`, `<details>`, `required`, `pattern`) over JS-driven solutions
|
|
- **No unnecessary classes**: Avoid presentational classes like `.form-group` or `.container` in lesson examples - teach pure semantic HTML first
|
|
- **Progressive enhancement**: Core functionality should work without JavaScript where possible
|
|
- **Valid HTML**: All HTML must be valid according to W3C standards
|
|
|
|
### Lesson Content Guidelines
|
|
|
|
When creating or editing lessons:
|
|
- Student code examples should be minimal and semantic
|
|
- Avoid CSS framework patterns (Bootstrap, Tailwind utility classes) in HTML 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
|
|
- Follow conventional commit format (feat:, fix:, refactor:, docs:, etc.)
|