# Build Process - KERN Components

This document explains the Vite build process for KERN CSS.

## Overview

The theme uses Vite to compile KERN CSS from the `@kern-ux/native` package into a single optimized CSS file located in `dist/index.css`.

## Build Commands

### Install Dependencies

```bash
npm install
```

### Production Build

```bash
npm run build
```

Compiles CSS once to `dist/` directory.

### Development (Watch Mode)

```bash
npm run dev
```

Watches for changes and recompiles automatically.

### Storybook

```bash
# Start Storybook dev server (port 6006)
npm run storybook

# Build static Storybook
npm run build-storybook
```

### CSS Linting

```bash
# Check for CSS issues
npm run lint:css

# Auto-fix CSS issues
npm run lint:css:fix
```

## Build Output

The build process generates:

- `dist/index.css` - Compiled KERN CSS styles
- `dist/FiraSans-*.woff2` - Fira Sans font files

---

## Visual Regression Testing (VRT)

Visual Regression Testing ensures KERN UX components maintain visual consistency with the official KERN-UX design system. The VRT suite uses Playwright to capture and compare screenshots of each component story.

### Prerequisites

Before running VRT, ensure you have:

1. Node.js and npm installed
2. Dependencies installed (`npm install`)
3. Playwright browsers installed

```bash
# Install Playwright browsers (one-time setup)
npx playwright install
```

### Running VRT Locally

#### Run All VRT Tests

```bash
# Build Storybook and run visual tests
npm run vrt
```

This command:
1. Builds a static Storybook
2. Serves it locally
3. Captures screenshots of all component stories
4. Compares against the expected KERN-UX design
5. Reports any visual differences

#### Interactive UI Mode

For debugging and exploring test results:

```bash
npm run vrt:ui
```

This opens Playwright's interactive UI where you can:
- See all tests and their status
- View screenshots and diffs
- Re-run individual tests
- Debug failing tests

#### View Test Report

After running tests, view the detailed HTML report:

```bash
npm run vrt:report
```

#### Debug Mode

Step through tests in the browser:

```bash
npm run vrt:debug
```

### Using with DDEV

When developing with DDEV, prefix all npm commands with `ddev`:

```bash
ddev npm install
ddev npm run build
ddev npm run vrt
```

### Understanding Test Results

- **Pass**: Component matches KERN-UX design
- **Fail**: Visual diff shows differences between expected and actual

Failed tests generate artifacts in `test-results/` and `playwright-report/`. Run `npm run vrt:report` to view details.

### Theme Testing

VRT currently tests **light theme only** (`data-kern-theme="light"`).

> **Note:** Dark mode testing is temporarily disabled due to upstream KERN-UX theme parameter issues. This will be re-enabled when upstream fixes the issue.

### CI/CD Integration

> **Note:** VRT CI/CD integration is planned but not yet implemented. Currently, VRT tests should be run locally before submitting merge requests.

### After Modifying Components

When you modify components, run VRT to verify they still match KERN-UX:

```bash
npm run vrt
```

If tests fail, review the diff report to understand the visual differences. Your components should match the KERN-UX design system.

### Configuration

VRT configuration is in `playwright.config.ts`:

| Setting             | Default  | Description                                    |
| ------------------- | -------- | ---------------------------------------------- |
| `maxDiffPixelRatio` | 0.02     | Maximum allowed pixel difference (2%)          |
| `threshold`         | 0.3      | Per-pixel color tolerance                      |
| `animations`        | disabled | Disables animations for consistent screenshots |

### Component Naming

Drupal SDC components use different naming conventions than KERN-UX. The VRT system maps between these automatically.

#### Key Naming Differences

| Drupal SDC      | KERN-UX            | Notes                |
| --------------- | ------------------ | -------------------- |
| `error`         | `danger`           | Alert/Badge severity |
| `h-1`, `h-2`    | `x-large`, `large` | Heading sizes        |
| `kern-ux-sdc-*` | `komponenten-*`    | Story ID prefix      |

### Troubleshooting

#### Tests fail locally but pass in CI (or vice versa)
- Ensure Playwright browser versions match
- Run `npx playwright install` to update browsers
- Check font loading - fonts may render differently

#### Flaky tests
- Increase `additionalWait` in test configuration
- Check for dynamic content (timestamps, random data)
- Ensure network requests complete before screenshot

#### Components don't match KERN-UX
- Compare the HTML structure between your Twig template and the KERN-UX HTML
- Check CSS class names match exactly
- Verify icon and typography are loading correctly

### Directory Structure

```
tests/
└── vrt/
    ├── vrt.spec.ts           # Main VRT test file
    ├── component-mapping.ts  # Maps Drupal → KERN-UX story IDs
    └── helpers/
        └── storybook.ts      # Utility functions

playwright.config.ts          # Playwright configuration
playwright-report/            # HTML test reports (generated)
test-results/                 # Test artifacts (diffs, failures)
```

---

## Resources

- [Vite Documentation](https://vitejs.dev/)
- [KERN-UX Native Package](https://www.npmjs.com/package/@kern-ux/native)
- [KERN Documentation](https://www.kern-ux.de/)
- [Playwright Documentation](https://playwright.dev/)
- [Playwright Visual Comparisons](https://playwright.dev/docs/test-snapshots)
