public/code-crispies
2
1
Fork 0
Code Issues Pull Requests Actions Activity

docs: update README to include Tailwind CSS support and enhance clarity

Browse Source
This commit is contained in:
Michael Czechowski
2025-06-10 23:46:00 +02:00
parent 671b6cc813
commit 906eda02b5
1 changed files with 126 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

172
README.md
View File

@@ -1,28 +1,32 @@
![Code Crispies Logo](./public/android-chrome-192x192.png) ![Code Crispies Logo](./public/android-chrome-192x192.png)
# Code Crispies # Code Crispies
An interactive platform for learning CSS through practical challenges. An interactive platform for learning CSS and Tailwind CSS through practical challenges.
## 📚 Overview ## 📚 Overview
Code Crispies is a web-based learning platform designed to help users master CSS through hands-on exercises. The application presents a series of progressive challenges organized into themed modules, allowing learners to build their skills step by step while receiving immediate feedback. Code Crispies is a web-based learning platform designed to help users master CSS and Tailwind CSS through hands-on exercises. The application presents a series of progressive challenges organized into themed modules, allowing learners to build their skills step by step while receiving immediate feedback.
### Key Features ### Key Features
- **Interactive Lessons**: Learn CSS concepts through practical, hands-on challenges - **Interactive Lessons**: Learn CSS and Tailwind concepts through practical, hands-on challenges
- **Dual Mode Support**: Switch between CSS and Tailwind CSS learning modes
- **Progressive Difficulty**: Modules are structured to build skills gradually from basic to advanced - **Progressive Difficulty**: Modules are structured to build skills gradually from basic to advanced
- **Real-Time Feedback**: Get immediate validation on your code solutions - **Real-Time Feedback**: Get immediate validation on your code solutions with comprehensive feedback
- **Progress Tracking**: Your learning progress is automatically saved in the browser - **Progress Tracking**: Your learning progress is automatically saved in the browser
- **Visual Preview**: See the results of your CSS code in real-time - **Visual Preview**: See the results of your code in real-time with live preview
- **Comprehensive Modules**: Cover various CSS topics in organized learning paths - **Comprehensive Modules**: Cover various CSS and Tailwind topics in organized learning paths
- **Schema-Validated Lessons**: All lessons follow a strict JSON schema for consistency
## 🛠️ Technical Stack ## 🛠️ Technical Stack
- Pure JavaScript (ES Modules) - Pure JavaScript (ES Modules)
- HTML5 & CSS3 - HTML5 & CSS3
- Vite for bundling and development - Vite for bundling and development
- Vitest for testing - Vitest for testing with coverage reporting
- JSON Schema validation for lesson structure
- Local Storage for progress persistence - Local Storage for progress persistence
- whatwg-fetch polyfill for compatibility
## 🚀 Getting Started ## 🚀 Getting Started
@@ -61,39 +65,46 @@ Code Crispies is a web-based learning platform designed to help users master CSS
### Available Scripts ### Available Scripts
- `npm run dev` - Start the development server - `npm start` - Start the development server (alias for `npm run dev`)
- `npm run dev` - Start the development server with host binding
- `npm run build` - Build for production - `npm run build` - Build for production
- `npm run preview` - Preview the production build locally - `npm run preview` - Preview the production build locally with debug mode
- `npm run test` - Run tests - `npm run test` - Run tests once
- `npm run test.watch` - Run tests in watch mode - `npm run test.watch` - Run tests in watch mode
- `npm run test.coverage` - Run tests with coverage report - `npm run test.coverage` - Run tests with coverage report
- `npm run format` - Format source code with Prettier - `npm run format` - Format source code with Prettier (includes config files)
- `npm run format.lessons` - Format lesson JSON files with Prettier - `npm run format.lessons` - Format lesson JSON files with Prettier
## 📖 Usage Guide ## 📖 Usage Guide
### How to Use Code Crispies ### How to Use Code Crispies
1. **Select a Module**: Choose a learning module from the Progress menu 1. **Select a Module**: Choose a learning module from the available options
2. **Read the Challenge**: Each lesson includes an objective and task instructions 2. **Choose Mode**: Select between CSS or Tailwind CSS learning mode (if applicable)
3. **Write CSS Code**: Enter your CSS solution in the editor 3. **Read the Challenge**: Each lesson includes a description, task instructions, and learning objectives
4. **Run Your Code**: Click the "Run" button (or press Ctrl+Enter) to test your solution 4. **Write Code**: Enter your CSS or Tailwind solution in the editor
5. **Review Feedback**: Get immediate feedback on your solution 5. **Run Your Code**: Click the "Run" button (or press Ctrl+Enter) to test your solution
6. **Progress**: Move to the next lesson once your solution is correct 6. **Review Feedback**: Get comprehensive feedback with validation messages
7. **Progress**: Move to the next lesson once your solution passes all validations
### Keyboard Shortcuts ### Keyboard Shortcuts
- `Ctrl+Enter` - Run your code - `Ctrl+Enter` - Run your code
- `Tab` - Insert two spaces (for indentation) - `Tab` - Insert appropriate indentation
## 🧩 Project Structure ## 🧩 Project Structure
``` ```
code-crispies/ code-crispies/
├── public/ # Static assets ├── coverage/ # Test coverage reports
├── docs/ # Documentation files (multilingual)
├── lessons/ # JSON lesson definitions
├── public/ # Static assets and PWA manifests
├── schemas/ # JSON Schema definitions
│ └── code-crispies-module-schema.json
├── src/ ├── src/
│ ├── config/ # Configuration files │ ├── config/ # Configuration files
│ │ └── lessons.js # Module and lesson definitions │ │ └── lessons.js # Module and lesson loading logic
│ ├── helpers/ # Helper utilities │ ├── helpers/ # Helper utilities
│ │ ├── renderer.js # UI rendering functions │ │ ├── renderer.js # UI rendering functions
│ │ └── validator.js # Code validation logic │ │ └── validator.js # Code validation logic
@@ -104,62 +115,89 @@ code-crispies/
│ └── main.css # Global styles │ └── main.css # Global styles
├── tests/ # Test files ├── tests/ # Test files
│ ├── setup.js # Test configuration │ ├── setup.js # Test configuration
│ └── *.test.js # Test files │ └── unit/ # Unit tests
├── vite.config.js # Vite configuration ├── vite.config.js # Vite configuration
└── vitest.config.js # Vitest configuration └── vitest.config.js # Vitest configuration
``` ```
## 📝 Adding New Lessons ## 📝 Adding New Lessons
Lessons are defined in JSON format in the `lessons.js` file. Each lesson includes: Lessons are defined in JSON format following the schema in `schemas/code-crispies-module-schema.json`. Each module includes comprehensive lesson definitions with validation rules.
- Title and description ### Module Structure
- Task instructions
- HTML content for the preview area
- CSS prefix and suffix (the code before and after the user's input)
- Validation criteria
Example lesson structure: ```json
```js
{ {
id: "selector-basics", "id": "unique-module-id",
title: "CSS Selectors Basics", "title": "Module Title",
description: "Learn to select and style HTML elements", "description": "Detailed description of module content and purpose",
lessons: [ "mode": "css", // or "tailwind"
{ "difficulty": "beginner", // "intermediate" or "advanced"
title: "Element Selectors", "lessons": [
description: "Style HTML elements using element selectors", // Lesson objects...
taskDescription: "Make all paragraphs red",
html: "<p>This is a paragraph</p><p>This is another paragraph</p>",
cssPrefix: "/* Write your CSS below */\n",
cssSuffix: "",
validationCriteria: {
type: "regex",
pattern: "p\\s*{\\s*color\\s*:\\s*red\\s*;?\\s*}"
}
}
// More lessons...
] ]
} }
``` ```
### Lesson Structure
```json
{
"id": "unique-lesson-id",
"title": "Lesson Title",
"description": "Detailed lesson description and concepts",
"mode": "css", // Optional override for module mode
"task": "Specific task instructions for the student",
"previewHTML": "<div>HTML for preview</div>",
"previewBaseCSS": "/* Base styles for preview */",
"sandboxCSS": "/* Additional sandbox styles */",
"initialCode": "/* Starting code for student */",
"solution": "/* Optional solution code */",
"previewContainer": "container-id",
"validations": [
{
"type": "contains", // "contains_class", "not_contains", "regex", "property_value", "syntax", "custom"
"value": "expected-content",
"message": "Feedback message for validation failure",
"options": {
"caseSensitive": false
}
}
]
}
```
### Validation Types
- **contains**: Check if code contains specific text
- **contains_class**: Check if HTML contains specific CSS class
- **not_contains**: Ensure code doesn't contain specific text
- **regex**: Validate against regular expression pattern
- **property_value**: Validate specific CSS property values
- **syntax**: Check for valid CSS syntax
- **custom**: Custom validation logic
## 🧪 Testing ## 🧪 Testing
The project uses Vitest for testing. Tests are located in the `tests/` directory. The project uses Vitest for comprehensive testing with coverage reporting. Tests are organized in the `tests/unit/` directory.
Run tests with:
Run tests:
```bash ```bash
npm run test npm run test
``` ```
Generate coverage report: Run tests in watch mode:
```bash
npm run test.watch
```
Generate coverage report:
```bash ```bash
npm run test.coverage npm run test.coverage
``` ```
Coverage reports are generated in the `coverage/` directory with detailed HTML reports.
## 🚢 Deployment ## 🚢 Deployment
To build the project for production: To build the project for production:
@@ -172,16 +210,38 @@ The output will be generated in the `dist/` directory, which can be deployed to
For GitHub Pages deployment, the configuration is already set up with the base path `/code-crispies/`. For GitHub Pages deployment, the configuration is already set up with the base path `/code-crispies/`.
Preview the production build locally:
```bash
npm run preview
```
## 🌐 Internationalization
The project supports multilingual documentation in the `docs/` directory:
- English documentation (`en-*.md`)
- German documentation (`de-*.md`)
## 🤝 Contributing ## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. Contributions are welcome! Please ensure all lessons follow the JSON schema validation.
1. Fork the repository 1. Fork the repository
2. Create your feature branch (`git switch -c feature/amazing-feature`) 2. Create your feature branch (`git switch -c feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`) 3. Add/modify lessons following the schema in `schemas/code-crispies-module-schema.json`
4. Push to the branch (`git push origin feature/amazing-feature`) 4. Format your code: `npm run format` and `npm run format.lessons`
5. Open a Pull Request 5. Run tests: `npm run test`
6. Commit your changes (`git commit -m 'Add some amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
### Adding New Lessons
When adding new lessons:
1. Create or modify JSON files in the `lessons/` directory
2. Ensure they validate against the schema
3. Test thoroughly with various validation scenarios
4. Update documentation if needed
## 📄 License ## 📄 License
Copyright (c) 2023 Michael Czechowski. Licensed under the [./LICENSE](WTFPL). Copyright (c) 2025 Michael Czechowski. Licensed under the [./LICENSE](WTFPL).