100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# 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.
|