# Kiseki Theme

Kiseki Theme is a Drupal theme built with Single Directory Components (SDC),
SCSS, Style Dictionary tokens, and Playwright-based regression testing.

## Requirements

- Drupal 10 or 11
- Required Drupal modules:
    - Media
    - Paragraphs
    - No Markup
    - SDC Display
- Node.js and npm for asset builds and tests

## Installation

1. Place the theme in `web/themes/custom/kiseki_theme`.
2. Enable the required Drupal modules.
3. Install frontend dependencies from the theme directory:

```bash
npm install
```

4. Compile the theme assets:

```bash
npm run build
```

5. Enable the theme in Drupal and set it as default.

## Development

Run all commands from `web/themes/custom/kiseki_theme`.

### SCSS builds

| Command | Purpose |
| --- | --- |
| `npm run build` | Build all theme and component CSS once |
| `npm run watch` | Watch theme and component SCSS together |
| `npm run watch:theme` | Watch only `scss/` to `css/` |
| `npm run watch:components` | Watch only component SCSS |

### Design tokens

The theme uses Style Dictionary to transform exported tokens into generated CSS.

```bash
npm run build:tokens
```

Generated token output is written to `css/generated/`.

## Component demos

Per-component Styleguide tests are discovered automatically from demo files in
the component directories.

Example demo file:

```text
components/atoms/button/button.demo.default.yml
```

Each demo enables both the Styleguide viewer route and automated component
coverage at:

```text
/styleguide/component/{Group}/kiseki_theme:{component_name}/{demo_key}
```

The repository now includes starter demos for the button, card, and banner
components. Add more `*.demo.*.yml` files to expand component coverage.

## Project structure

```
kiseki_theme/
├── components/             # Single Directory Components (SDC)
├── css/
│   └── generated/          # Auto-generated from SCSS (DO NOT EDIT)
├── js/                     # Theme JavaScript files
├── scss/
│   ├── generated/          # Auto-generated token styles (DO NOT EDIT)
│   └── *.scss              # Theme SCSS source files
├── templates/              # Drupal template overrides
├── tests/                  # Playwright visual and a11y tests
├── tokens/
│   └── export-tokens.json  # Design tokens exported from design tool
├── kiseki_theme.info.yml   # Theme metadata
├── kiseki_theme.libraries.yml  # Asset library definitions
├── package.json            # NPM dependencies and scripts
├── style-dictionary.config.js  # Token compilation configuration
└── style-dictionary-README.md  # Token system documentation
```

## Testing

The theme ships with Playwright-based visual and accessibility tests.

### First-time setup

1. Install Chromium for Playwright:

```bash
NODE_TLS_REJECT_UNAUTHORIZED=0 npx playwright install chromium
```

2. Create a local environment file:

```bash
cp .env.example .env
```

3. Fill in these values:

```dotenv
BASE_URL=https://your-local-site.example
DRUPAL_USER=admin
DRUPAL_PASS=yourpassword
```

`BASE_URL` is required so tests are not tied to a project-specific hostname.
The `.env` file is gitignored and must not be committed.

### Test commands

```bash
NODE_TLS_REJECT_UNAUTHORIZED=0 npm test
NODE_TLS_REJECT_UNAUTHORIZED=0 npm run test:visual
NODE_TLS_REJECT_UNAUTHORIZED=0 npm run test:a11y
npm run test:report
```

### Snapshot updates

```bash
NODE_TLS_REJECT_UNAUTHORIZED=0 npm run test:update-snapshots
```

Review changes in `tests/__snapshots__/` before committing them.

## License

This theme is distributed under GPL-2.0-or-later. See `LICENSE.txt`.
