templates/modernkit/README.md

# ModernKit Project

ModernKit is a versatile and performant project boilerplate built with Gulp, Twig, and SCSS. It provides a robust build system and a foundational UI kit to kickstart your web development.

## Features

- **Build System:**
  - Gulp-powered task runner.
  - SCSS compilation with Autoprefixer and minification (for production).
  - JavaScript transpilation (Babel) and concatenation with separate development (unminified) and production (minified) builds.
  - Image optimization (including WebP generation for production).
  - Twig templating with dynamic data injection from JSON files (only top-level templates are processed into HTML files).
  - Asset copying (e.g., other static files).
  - Favicon copying.
  - Font copying.
  - SVG sprite generation and injection into HTML.
  - Resource versioning (cache busting) using content hashing (for production).
  - Source map generation for CSS and JavaScript (for development).
  - **Code Quality:** Biome integration for JavaScript linting and formatting.
  - Robust error handling with `gulp-plumber`.
  - **Performance Optimization:** Utilizes `gulp-cached` and `gulp-remember` to speed up recompilation of unchanged files.
  - Clean task to remove build artifacts.
- **UI Kit:**
  - Basic styles and resets.
  - Comprehensive typography.
  - Responsive grid system.
  - Utility classes for spacing, text alignment, display, and colors.
  - Basic components (e.g., buttons).

## Getting Started

### Prerequisites

Make sure you have Node.js and npm installed on your system.

### Installation

1. Clone the repository:
   ```bash
   git clone <your-repository-url>
   cd modernkit
   ```
2. Install the dependencies:
   ```bash
   npm install
   ```

## Available Commands

- `npm start`: Runs the default Gulp task, which starts a development server with BrowserSync, watches for file changes, and recompiles assets automatically. This uses the development JavaScript build (unminified) and generates source maps.
- `npm run build`: Performs a one-time development build. Cleans the `dist` directory, lints JavaScript, generates SVG sprites, compiles Twig templates, SCSS, JavaScript (development version), optimizes images, and copies assets, favicon, and fonts.
- `npm run build:prod`: Performs a one-time production build. Similar to `npm run build`, but uses minified CSS and JavaScript (production version), optimizes images more aggressively, generates WebP versions of images, and applies content hashing for cache busting.
- `npm run test`: Runs Jest tests.
- `npm run lint`: Runs Biome check on JavaScript files.
- `npm run format`: Runs Biome formatter on JavaScript files.

## Project Structure

```
modernkit/
├───gulpfile.js
├───jest.config.js
├───package-lock.json
├───package.json
├───biome.json
├───dist/                 # Compiled output (ignored by Git)
├───node_modules/         # Node.js dependencies (ignored by Git)
└───src/
    ├───images/           # Source images
    │   └───test.png
    ├───js/               # Source JavaScript files
    │   ├───main.js
    │   └───main.test.js
    ├───scss/             # Source SCSS files
    │   ├───main.scss
    │   ├───_variables.scss
    │   ├───_base.scss
    │   ├───_typography.scss
    │   ├───_grid.scss
    │   ├───_utilities.scss
    │   └───_components.scss
    ├───templates/        # Twig templates
    │   ├───index.twig
    │   ├───about.twig
    │   └───components/   # Twig components
    │       ├───button.twig
    │       ├───footer.twig
    │       └───header.twig
    ├───data/             # JSON data for Twig templates
    │   ├───global.json
    │   └───about.json
    ├───assets/           # Static assets (e.g., other files)
    │   └───test.txt
    ├───icons/            # SVG icons for sprite generation
    │   ├───clock.svg
    │   └───info.svg
    └───fonts/            # Font files
        └───test.ttf
```

## UI Kit Usage

### Typography

Use standard HTML heading tags (`<h1>` to `<h6>`) and paragraph tags (`<p>`). Utility classes like `.small` can be applied for smaller text.

### Grid System

Utilize the `.container`, `.row`, and `.col-*` classes for responsive layouts. Breakpoints are defined in `src/scss/_variables.scss`.

```html
<div class="container">
  <div class="row">
    <div class="col-12 col-md-6">
      <!-- Content -->
    </div>
    <div class="col-12 col-md-6">
      <!-- Content -->
    </div>
  </div>
</div>
```

### Buttons

Apply the `.btn` base class along with contextual classes like `.btn-primary`, `.btn-secondary`, etc.

```html
<button class="btn btn-primary">Primary Button</button>
<a href="#" class="btn btn-success">Success Link</a>
```

### Utility Classes

Various utility classes are available for common styling needs:

- **Spacing:** `m-1`, `pt-3`, `px-auto`, etc. (for margin and padding)
- **Text Alignment:** `text-left`, `text-center`, `text-right`
- **Display:** `d-block`, `d-inline-block`, `d-flex`
- **Colors:** `text-primary`, `bg-dark`, etc.

### SVG Icons

SVG icons from `src/icons` are compiled into a sprite and injected into your HTML. Use them with the `<svg><use>` pattern:

```html
<svg class="icon" width="24" height="24"><use xlink:href="#clock"></use></svg>
```

## Data Management

Twig templates can access global data from `src/data/global.json` and page-specific data from `src/data/<template-name>.json` (e.g., `src/data/about.json` for `about.twig`). Page-specific data will override global data if keys conflict.

Example in Twig:

```twig
<h1>{{ global.welcomeMessage }}</h1>
<p>{{ pageTitle }}</p>
```

## Testing

Jest is configured to run unit tests for JavaScript files. The test environment is set to `jsdom` to simulate a browser environment.

To run tests:

```bash
npm test
```

## Contributing

Feel free to contribute to this project by submitting issues or pull requests.