Samuel Onoja
3d950a0411
Resolve light, dark and automatic appearance centrally and publish live theme snapshots to native surfaces and the appearance portal. Add paired preset families, custom theme imports, accessibility transforms and contrast-safe transitions. Refine the Settings gallery and Auto controls, move overrides under advanced customization, and share palette-aware switches and circular slider thumbs. Document configuration and include theme licenses and integration coverage.
84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
# Theme components
|
|
|
|
Ferese's native apps use [ferese-theme](../crates/ferese-theme/README.md) for
|
|
colors, fonts, controls, menus, icons, calendar elements, and dialog materials.
|
|
Use [Configuration → Appearance](configuration.md#appearance) for supported keys
|
|
and defaults.
|
|
|
|
## Shared appearance
|
|
|
|
The six theme families are Ferese Blue, Catppuccin, Gruvbox, Rosé Pine, Tokyo
|
|
Night, and Everforest. Each has a paired light and dark palette. Ferese Blue uses the
|
|
logo accent, `#3D7BE6`. Presets supply colors and materials; explicit wallpaper,
|
|
typography, geometry, and material overrides remain in place.
|
|
|
|
The interface font applies to shell text and native dialogs. Clock and note
|
|
widgets can override it. Managed-window corners and shell corners are separate
|
|
settings; small controls cap their corners to fit their size.
|
|
|
|
## Materials
|
|
|
|
Two material styles are supported:
|
|
|
|
| Style | Background |
|
|
| --- | --- |
|
|
| `solid` | Opaque theme surface |
|
|
| `translucent` | Theme tint over blurred background content |
|
|
|
|
Bars, popovers, notifications, and themed dialogs share `theme.material.opacity`
|
|
and `blur-radius`. Text and icons stay opaque. An opacity of zero hides the
|
|
material; blur radius zero disables blur. Solid mode stays opaque.
|
|
|
|
```kdl
|
|
theme {
|
|
colors {
|
|
accent "#3D7BE6"
|
|
}
|
|
material {
|
|
style "translucent"
|
|
opacity 0.78
|
|
blur-radius 12
|
|
}
|
|
geometry {
|
|
shell-radius 14
|
|
window-radius 14
|
|
}
|
|
}
|
|
```
|
|
|
|
The compositor owns blur and tint. `material::ModalMaterial` attaches native
|
|
dialogs to that rendering path. Keep the attachment alive with the window and
|
|
make the attached client background transparent. Outside Ferese, retain a client
|
|
background so the dialog remains usable.
|
|
|
|
## Components
|
|
|
|
| Module | Use |
|
|
| --- | --- |
|
|
| `palette` | Resolve configuration colors and build the native toolkit theme |
|
|
| `controls` | Surfaces, navigation, text buttons, and input styles |
|
|
| `menus` | Rows, headings, sections, separators, switches, and sliders |
|
|
| `gallery` | Split theme previews, selected badges and accessible radio navigation |
|
|
| `calendar` | Date/time labels, clock digits, and calendar grids |
|
|
| `icons` | Shared SVG assets, sizing, and tint |
|
|
| `typography` | Shared font selection and text |
|
|
| `contrast` | Readable labels on filled controls |
|
|
| `material` | Attach modal cards to compositor materials |
|
|
|
|
Applications provide data, layout, actions, and animation progress. Extend shared
|
|
components when a style is needed in multiple apps. Avoid hardcoded app-specific
|
|
fonts, foreground colors, or opacity values.
|
|
|
|
## UI checks
|
|
|
|
- Check text and icons in all twelve light and dark variants.
|
|
- Check rest, hover, pressed, focused, selected, and disabled controls.
|
|
- Keep accent-button labels readable after typing or changing focus.
|
|
- Keep controls usable with solid materials and blur disabled.
|
|
- Align material regions with the visible card at every output scale.
|
|
- Give dialogs one frame; cap their height and scroll their content, preserving actions.
|
|
- Respect reduced motion and stop requesting animation frames after settling.
|
|
|
|
Theme changes affect appearance; they do not change focus, workspace ownership,
|
|
input permissions, or authentication policy.
|