# Tonalmine

Material Design 3 theme for Redmine 7.0.

## Install

1. Copy the `tonalmine/` folder into `<redmine>/themes/`.
2. Restart Redmine (theme assets are compiled at boot).
3. Select **Tonalmine** in Administration → Settings → Display → Theme.

Optional: the `redmine_tonalmine` plugin adds a default appearance for administrators and saves each
user's choice on their account. Copy the `redmine_tonalmine/` folder into `<redmine>/plugins/` and
restart Redmine (no migrations).

## Development

Requires Docker.

```sh
cd dev
docker compose up -d                                         # Redmine 7.0.1 on http://localhost:3070
docker compose exec redmine bin/rails runner /seed/seed.rb   # once: demo data, selects the theme
docker compose restart redmine                               # after every CSS change
```

Login: `admin` / `admin`.

The theme folder is bind-mounted into the container, so edits are picked up on restart.

### Screenshots

```sh
cd e2e
npm install && npx playwright install chromium   # once
node screenshots.mjs            # all pages, light/dark × desktop/mobile → screenshots/
node screenshots.mjs issue      # only pages whose name contains "issue"
node check-form-alignment.mjs   # fails if a form label is not level with its field
node check-font-sizes.mjs       # fails if any text is off the type scale (e.g. core 0.9em leftovers)
node check-sizes.mjs            # fails if text, fields, buttons or rows are off in a size mode (needs the plugin)
SIZE=large node screenshots.mjs # screenshots or check-form-alignment.mjs in a size mode (compact or large; needs the plugin)
```

### Icons

`tonalmine/images/icons.svg` replaces Redmine's icon sprite with Material Symbols Outlined.
It is generated from `tools/icon_map.yml`:

```sh
ruby tools/build_icons.rb
```

The script fails when Redmine's `config/icon_source.yml` (7.0-stable) has icon names that are missing from
the map, so run it after every Redmine update.

### Colors

Each user picks a mode (Auto / Light / Dark), a contrast level (Standard / Medium / High), a size
(Compact / Normal / Large) and a color (Purple, Blue, Green, Orange) in the
**Appearance** section of the profile menu (top right; in the mobile menu at the bottom). Auto follows
the operating system. The size scales text (13 / 14 / 16px) and the height of fields, buttons and
table rows (32 / 40 / 48px), also on phones, where Compact makes touch targets smaller than 48px.
Without the plugin, the choice is stored per browser (`localStorage`).

With the `redmine_tonalmine` plugin:

- Administrators set the default appearance in Administration → Settings → Display, below the Theme
  select. It shows while Tonalmine is selected; when switching from another theme, save once first.
- Logged-in users' choices are saved on their account (`pref[:tonalmine]`) and follow them to every
  browser. Only the parts a user changed override the default; **Reset to default** clears them.
  A choice already stored in the browser is moved to the account on the first visit.
- Anonymous visitors get the default; their own choice is still stored per browser.

`node e2e/check-appearance.mjs` checks this end to end (it empties the default when done). The last (rainbow) swatch
lets users pick any color: `javascripts/scheme.js` is loaded on demand, generates the scheme in the
browser, and the generated CSS is stored with the choice, so later page loads don't need it.

The color roles are generated from one seed color per palette with `@material/material-color-utilities`
(scheme TonalSpot) into `tonalmine/stylesheets/palettes.css`:

```sh
cd tools/palettes
npm install      # once
npm run build    # writes palettes.css and javascripts/scheme.js
```

To add or change a palette, edit `PALETTES` in `tools/palettes/build_palettes.mjs` and in
`tonalmine/javascripts/theme.js` (the build fails if they differ), then rebuild.

To use a scheme from [Material Theme Builder](https://material-foundation.github.io/material-theme-builder/)
as-is: export it as Web (CSS), copy its `light.css` and `dark.css` into `tools/palettes/themes/<name>/`,
and also its `light-mc.css`, `light-hc.css`, `dark-mc.css` and `dark-hc.css` contrast files. Then add
`['<name>', '<seed>', 'themes/<name>']` to `PALETTES`. The roles are copied from the export; the seed
only tints the success/warning colors.

The only other hard-coded colors are the select chevrons `images/arrow-drop-down*.svg` (one per mode).

## License

MIT, see `LICENSE`. Roboto (OFL 1.1) and Material Symbols (Apache 2.0) keep their own licenses.