docs: shell theme (theme.toml) authoring guide #9

Closed

Breadway wants to merge 1 commit from docs/shell-themes-guide into main

Breadway commented

2026-09-03 22:56:23 +08:00

Owner

No authoring documentation existed for the declarative shell-theme system shipped in v0.7.7 — only bread-theme describe (the JSON schema), the commented builtins, and scattered rustdoc.

Adds docs/shell-themes.md:

theme discovery + the shell.toml active selector
a quick-start with a tested minimal extends example (bread-theme diagnose exit 0)
extends deep-merge + the "+" slot-splice rule
the full [tokens] table (type / default / effect)
[bar.window], [bar.slots] (+ widget: aliases), [modules.*], [launcher], [surfaces.*], [compositor.*]
palette slots (never hex)
the live-switch vs restart matrix (needs_restart = modules or launcher.mode)
the extra.css escape hatch + the unknown-[tokens]-key {name} passthrough
testing / common failures

Also links it from the README Theming section and fills in the bread-theme subcommands table (layerrules, describe, diagnose were missing).

Docs-only, no code.

No authoring documentation existed for the declarative shell-theme system shipped in v0.7.7 — only `bread-theme describe` (the JSON schema), the commented builtins, and scattered rustdoc. Adds `docs/shell-themes.md`: - theme discovery + the `shell.toml` active selector - a quick-start with a **tested** minimal `extends` example (`bread-theme diagnose` exit 0) - `extends` deep-merge + the `"+"` slot-splice rule - the full `[tokens]` table (type / default / effect) - `[bar.window]`, `[bar.slots]` (+ `widget:` aliases), `[modules.*]`, `[launcher]`, `[surfaces.*]`, `[compositor.*]` - palette slots (never hex) - the **live-switch vs restart** matrix (`needs_restart` = modules or launcher.mode) - the `extra.css` escape hatch + the unknown-`[tokens]`-key `{name}` passthrough - testing / common failures Also links it from the README Theming section and fills in the `bread-theme` subcommands table (`layerrules`, `describe`, `diagnose` were missing). Docs-only, no code.

Breadway added 1 commit

2026-09-03 22:56:26 +08:00

docs: shell theme (theme.toml) authoring guide af3690fe89

No authoring documentation existed for the declarative shell-theme
system shipped in v0.7.7 — only the machine-readable `bread-theme
describe` schema, the commented builtins, and scattered rustdoc.

Add docs/shell-themes.md: discovery + the active selector, a tested
minimal example, the `extends` / "+" splice rules, the full token
table, [bar.window]/[bar.slots]/[modules]/[launcher]/[surfaces]/
[compositor], palette slots, the live-switch vs restart matrix, the
extra.css escape hatch, and troubleshooting. Link it from the README
Theming section and fill in the missing bread-theme subcommands.

Breadway referenced this pull request from a commit

2026-09-04 14:25:50 +08:00

docs: shell-themes guide + the four UI-control axes

Breadway referenced this pull request

2026-09-04 14:32:10 +08:00

Expand shell-theme UI control: typography, [panel]/[osd], [[bar.widget]] (v0.7.8) #11

Breadway closed this pull request

2026-09-04 14:40:56 +08:00

Breadway referenced this pull request

2026-09-28 06:39:02 +08:00

Dev track builds against dependency main; releases stay on locked tag pins #38

Breadway referenced this pull request