aria/feresaria
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Remove design documents and their handbook references

Browse Source
This commit is contained in:
Samuel Onoja committed 2026-10-01 17:51:54 +01:00
1 parent 3d0c85c70a
commit c0010ccbb6
13 files changed
+4 -657
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/README.md
-6
View File
@@ -12,8 +12,6 @@
- [Shortcuts and gestures](shortcuts.md): keyboard navigation, Super-drag, resize, and window grouping.
- [Desktop widgets](desktop-widgets.md): clocks and sticky notes.
- [Notifications](notifications.md): popups, history, and Do Not Disturb.
- [Lock screen](locking.md): appearance, automatic locking, and display sleep.
- [Screen sharing and recording](screen-sharing.md): choosing sources and stopping a session.
- [Desktop portals](portals.md): application integration and supported services.
@@ -21,10 +19,6 @@
## Develop Ferese
- [Development](development.md): builds, tests, and portal checks.
- [Compositor architecture](ferese-window-manager-spec.md).
- [Shell behavior](ferese-shell-design.md).
- [Theme components](ferese-theme-ui-spec.md).
- [Animation checks](animation-validation.md).
- [Nested resize checks](nested-resize-testing.md).
- [Client soak testing](native-soak-testing.md).
- [Performance measurements](performance-baseline.md).
docs/animation-validation.md
-26
View File
@@ -1,26 +0,0 @@
# Animation regression checks
Run `cargo test -p ferese-animation -p ferese --offline` for transition,
resize requests, reduced motion, stacking, and refresh-rate regression tests.
For visual validation, use a disposable Ferese session with three tiled windows
containing text and at least one floating window. Test both the nested and DRM
backends. Record the session at its native refresh rate when comparing builds;
single screenshots cannot establish smoothness.
| Scenario | Expected result |
| --- | --- |
| Super+F on the middle column, then exit | Neighbours remain behind the expanding window. The shrinking window stays above them until the transition finishes. |
| Toggle Super+F repeatedly at 40–80 ms intervals | Every reversal starts at the presented frame. Corners, border and shadow follow the same zoom progress. The final state matches the last input. |
| Cycle width, then immediately Super+F | The old column-width spring cannot override maximized width. |
| Exit maximize or fullscreen and immediately resize or scroll | The current frame is retained when the target changes; scrolling resumes without a position jump. |
| Drag a floating window; resize from its top-left corner | The window follows the pointer directly. The opposite edge stays anchored. Delayed client commits do not move or raise it. |
| Zoom responsive and slow-redrawing clients | Each zoom requests the destination size once. Client redraws do not generate intermediate resize requests or restart the motion. |
| Zoom the leftmost and rightmost columns in and out | Each outer edge moves monotonically toward its destination; neither side trembles or reverses near the screen edge. |
| Disable borders and shadows, then zoom | Rounded corner pixels repaint through the final frame; no corner remnants remain. |
| Repeat on 60 Hz and 144 Hz outputs; move focus between them | Similar elapsed-time motion with no double advancement. Check frame timing on actual DRM hardware. |
| Enable reduced motion | Geometry and decorations reach their final values together. |
Zoom requests the destination client size once and scales the available buffer
along the transition. This avoids repeated content reflow during motion. It is
not a buffer snapshot or a guarantee of perfectly sharp intermediate text.
docs/configuration.md
+3 -9
View File
@@ -6,8 +6,7 @@ which includes app and media shortcuts, appearance, widgets, and optional startu
and display settings. Its browser/editor shortcuts need Firefox/Zed; brightness
keys need `brightnessctl` and audio keys need `wpctl`.
This reference covers layouts, appearance, input, and desktop behavior.
See [Desktop widgets](desktop-widgets.md), [Notifications](notifications.md),
and [Desktop portals](portals.md) for their additional options.
See [Desktop portals](portals.md) for application integration options.
## KDL syntax
@@ -135,8 +134,7 @@ Choose Light, Dark, or Auto in Settings or Control Center. Auto follows local
07:00 and 19:00 boundaries unless you change its schedule.
Selections store preset names. Partial KDL files can override shared colors or
one appearance. See [Themes](theme-engine.md) for files, accessibility options,
and live previews.
one appearance.
| Section / key | Type | Default | Meaning |
| --- | --- | --- | --- |
@@ -145,7 +143,7 @@ and live previews.
| `theme.split` | boolean | `false` | Use separate light/dark families; retains both selections when disabled |
| `theme.light.family`, `theme.dark.family` | family id | `"ferese-blue"` | Stored selections used when split is enabled |
| `theme.custom-themes.<id>.file` | path | unset | Imported KDL family with explicit light and/or dark sections |
| `theme.light.preset` | preset name | `"ferese-blue-light"` | Light palette; see the [preset pairs](theme-engine.md#preset-pairs) |
| `theme.light.preset` | preset name | `"ferese-blue-light"` | Light palette |
| `theme.dark.preset` | preset name | `"ferese-blue"` | Dark palette |
| `theme.file` | path | unset | Shared partial KDL theme |
| `theme.light.file`, `theme.dark.file` | path | unset | Partial KDL theme for one appearance |
@@ -567,7 +565,3 @@ override shell rounding.
Power actions use a centered confirmation. **Super+Shift+E** and
`feresectl request-logout` ask to log out. `feresectl exit` ends the session
immediately.
## Notifications
See [Notifications](notifications.md) for popups, Do Not Disturb, and timeout options.
docs/desktop-widgets.md
-118
View File
@@ -1,118 +0,0 @@
# Desktop widgets
Clock and sticky-note widgets sit above the wallpaper and behind windows.
Drag the clock or a note's title to move it. Release to save, or press Escape to
cancel. Widgets stop at each other's edges on the same display.
Enable it in Settings → Desktop widgets or in your Ferese config:
```kdl
desktop-widgets {
clock enabled=#true anchor="top_left" margin-x=64 margin-y=80 {
style "pixel" // or "minimal"
outputs // every output; or outputs "DP-2"
width 440
height 320
font-family "" // style default; or "Comfortaa"
bold #false
time-size 128.0
date-size 18.0
time-format "%-I:%M %p" // use "%H:%M" for 24-hour time
date-format "%a, %b %-d"
time-zone "" // system zone; or "Africa/Lagos"
show-date #true
lowercase #true
color "" // theme primary text
date-color "" // theme muted text
opacity 0.9
alignment "center" // left, center, right
gap 4.0
padding 12.0
background "" // transparent; or "#10101080"
radius 16.0
}
}
```
Positions: `top_left`, `top_center`, `top_right`, `center_left`, `center`,
`center_right`, `bottom_left`, `bottom_center`, `bottom_right`.
Margins affect anchored axes only: a centered horizontal position ignores
`margin-x`; a centered vertical position ignores `margin-y`.
All geometry and text sizes use logical pixels and follow the output's scale.
Increase the widget width/height for longer formats or larger text.
Choose **Pixel** for stacked hours and minutes with alternating theme colors,
or **Minimal** for a plain time/date layout. Pixel zero-pads hours and hides am/pm.
Formats containing seconds or extra text use a single line. Both styles shrink
time text to fit. Select a different font in Settings, or set `font-family`.
Changes apply live. Colors and fonts follow the theme unless overridden.
Formatting uses [strftime-compatible formats](https://docs.rs/jiff/latest/jiff/fmt/strtime/index.html).
Use `%H:%M` for 24-hour time or `%-I:%M %p` for 12-hour time.
## Clock limits
Clock and note corners follow the shared shell radius. Their `radius` fields
are accepted for compatibility but do not override it.
All clock keys are optional. The example enables the clock (disabled by default);
the other values illustrate defaults or their empty-string equivalents.
`outputs` is an array of strings; `enabled`, `bold`, `show-date`, `lowercase` are
booleans; `width`, `height`, and margins are integers. Other sizes/opacity are numbers.
| Fields | Accepted range |
| --- | --- |
| `width`, `height` | 64–1600, 32–800 |
| `margin-x`, `margin-y` | 0–8192 |
| `time-size`, `date-size` | 8–240, 8–96 |
| `opacity` | 0–1 |
| `gap`, `padding`, `radius` | 0–64, 0–64, 0–128 |
| `font-family`, `time-format`, `date-format` | At most 128 bytes each |
| `outputs` | At most 32 exact output names, each 1–128 bytes |
Formats must be valid; `time-zone` must be empty or a recognized IANA name.
Colors are empty (inherit), `#RRGGBB` or `#RRGGBBAA`; all numeric values must be finite.
## Sticky notes
Settings → Desktop widgets → Add note creates a card. Drag its title to move it;
click Edit for its multiline editor, then Done to finish. Text autosaves after
500 ms without typing. Escape cancels a drag or finishes editing. Position saves
on release; dragging changes the anchor to `top_left` and saves pixel margins.
Title, size and style are also editable in Settings. Notes persist in the config.
Choose a note’s font in Settings or set `font-family "Comfortaa"` in its `note`
node. Without an override, notes use the interface font.
These are plain-text notes, not Markdown or HTML.
```kdl
desktop-widgets {
note id="today" title="Today" text="Review the pull request\nTake a break\n" anchor="top_right" margin-x=48 margin-y=80
}
```
Repeat the `note` node for additional notes; IDs must be unique. Cards stay behind windows
and take keyboard focus only when clicked. Set `interactive #false` for a fully
click-through card. Long text wraps; increase height if needed.
| Key | Type | Default / accepted values |
| --- | --- | --- |
| `id` | string | `"note"`; unique, 1–64 ASCII letters/digits/`-`/`_` |
| `enabled` | boolean | `true` |
| `interactive` | boolean | `true`; drag/edit controls; `false` is click-through |
| `title` | string | `"Note"`; empty hides it; maximum 256 bytes |
| `text` | string | `""`; multiline plain text, maximum 16 KiB |
| `outputs` | string array | `[]` means all; at most 32 exact names, each 1–128 bytes |
| `anchor` | string | `"top_right"`; same nine positions as clock |
| `margin-x`, `margin-y` | integer | `48`, `80`; 0–8192; anchored edges only |
| `width`, `height` | integer | `320`, `240`; 120–1200, 80–1200 |
| `font-family` | string | omitted/empty follows desktop font; maximum 128 bytes |
| `text-size`, `title-size` | number | `16`, `18`; 8–96 |
| `color` | string | omitted/empty/`"theme"` follows primary text; or hex color |
| `background` | string | omitted/`"theme"` follows surface base; empty is transparent; or hex color |
| `opacity` | number | `0.9`; 0–1, multiplies text/background alpha |
| `padding`, `gap` | number | `20`, `8`; 0–64 |
| `radius` | number | `16`; 0–128 |
| `alignment` | string | `"left"`; `left`, `center`, `right` |
At most 32 notes; the entire live config is limited to 60 KiB.
docs/development.md
-4
View File
@@ -14,14 +14,10 @@ Keep another desktop available for direct-session recovery.
## Test guides
- [Animation checks](animation-validation.md): transitions, interruption, and hit testing.
- [Nested resize checks](nested-resize-testing.md): wallpaper and bar responsiveness.
- [Client soak testing](native-soak-testing.md): repeated client lifecycle and resource growth.
- [Performance measurements](performance-baseline.md): sampling and historical results.
The [compositor](ferese-window-manager-spec.md), [shell](ferese-shell-design.md),
and [theme](ferese-theme-ui-spec.md) references describe the main code boundaries.
## Portal checks
Run backend unit tests and compare D-Bus contracts against installed portal XML:
docs/ferese-shell-design.md
-65
View File
@@ -1,65 +0,0 @@
# Shell behavior
This is a maintainer reference. User options are documented in
[Configuration](configuration.md). Common UI belongs in
[ferese-theme](../crates/ferese-theme/README.md).
## Bar and popovers
The shell creates a bar for each output. Workspace buttons use compositor state
and appear in numeric order. The active window title occupies the center when
space allows. Date and time form one calendar button. Right-side controls open
sound, battery, notifications, recording, and Control Center popovers.
A popover is anchored to its control and constrained to the same output.
Opening another primary popover replaces the current one. Popovers reserve no
workspace space; the bar reserves its configured height and margins.
True fullscreen hides the bar without changing the preserved tiled layout.
Use real service availability for controls. Handle missing services and failed
actions without blocking the UI. Settings opens as a separate application.
## Overview
The compositor presents window previews; the shell supplies labels and workspace
controls. Do not continuously copy windows into the shell process.
Clicking a workspace background selects that workspace and keeps overview open
so its windows can be selected. Clicking a window activates that exact window.
Directional keys change selection, Enter activates it, and Escape dismisses.
Activation must use the selected window ID, not the window focused before overview.
## Focus and dialogs
The bar and notification popups do not normally take keyboard focus. Interactive
shell surfaces restore the previous valid app focus when dismissed.
Power actions and logout use a centered system confirmation, including blockers
when present. Input outside the confirmation must not reach applications.
Authentication, screen-sharing, and recording dialogs are separate themed windows.
Use one visible frame, content-sized height, and an output-sized height limit.
Scrollable lists must leave headings and action buttons accessible.
Attach dialog material to the content card using the shared theme helper.
Match blur regions to the displayed card throughout opening and resize; do not
paint an opaque window behind a translucent card.
## Notifications and widgets
The shell provides the standard notification service. Normal popups respect
Do Not Disturb; critical messages bypass it. History is held in memory and clears
when the shell exits. See [Notifications](notifications.md).
Clock and note widgets sit behind application windows, reserve no workspace space,
and save positions after dragging. Only interactive notes take keyboard focus.
See [Desktop widgets](desktop-widgets.md).
## Lifecycle
Shell failure must not destroy managed windows or workspace state. Reconstruct
bars and controls from compositor state after reconnecting, and clear dead shell
focus. Notification history is not reconstructed from disk.
Keep slow service queries, image loading, and filesystem work away from UI event
handling. Stop animation work once the UI settles. Validate popover placement,
fullscreen transitions, dialog dismissal, and shell restart in a nested session.
docs/ferese-theme-ui-spec.md
-83
View File
@@ -1,83 +0,0 @@
# 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.
docs/ferese-window-manager-spec.md
-109
View File
@@ -1,109 +0,0 @@
# Compositor architecture
This is a maintainer reference. For supported configuration and shortcuts, use
[Configuration](configuration.md); for builds and checks, use [Development](development.md).
## Processes and crates
| Component | Responsibility |
| --- | --- |
| `ferese` | Wayland clients, windows, workspaces, input, outputs, and rendering |
| `ferese-shell` | Bar, popovers, notifications, widgets, and system confirmations |
| `ferese-settings` | Configuration editor |
| `feresectl` | Command-line control |
| `ferese-lock` | Lock-screen UI and PAM authentication |
| `ferese-polkit-agent` | System authentication prompts |
| `xdg-desktop-portal-ferese` | Desktop portal requests and PipeWire streams |
| `ferese-record` | Video encoding and saving |
The compositor uses Smithay and calloop. The direct backend renders through
DRM/KMS; the nested backend renders into a window on another Wayland desktop.
Native UIs use libcosmic. Layout, animation, configuration, IPC, protocols, and
[theme components](../crates/ferese-theme/README.md) live in separate crates.
## State and ownership
The event loop owns compositor state and Wayland objects. Background workers
return results through bounded channels; results must be checked against current
window, output, and request identities before application.
Keep these relationships valid after a state change:
- Each window belongs to one workspace and appears once in its layout or floating list.
- Each attached workspace belongs to one output; each output has one active workspace.
- A window's output follows workspace ownership.
- Fullscreen preserves the underlying layout or floating placement.
- Focus points to a live window or authorized shell surface.
- Workspace focus history is distinct from current keyboard focus.
Monitor removal migrates workspaces to a remaining output. Returning monitors
restore eligible workspaces; explicit user moves take priority. Selecting a
workspace visible on another monitor focuses that monitor.
## Layout and presentation
Scrolling layouts arrange columns horizontally. Windows within a column divide
its height. A workspace owns its viewport; presentation subtracts that viewport
from window positions. Tree layouts use nested splits and stacks. Layout changes
preserve window membership and floating placement.
Keep layout targets, animated rectangles, and committed client sizes separate.
A layout transition requests the destination client size rather than sending
one configure per animation frame. Available content is scaled and clipped until
the matching client buffer arrives. Hit testing uses the same presented geometry.
Interrupted animations continue from their current position.
Input and layout use logical pixels. Rendering converts them using the output's
scale and transform. Application popups use their parent's output and presented
position when calculating bounds.
## Rendering and frame delivery
Render damage from client commits, animations, effects, cursor motion, and output
changes. Movement damages both old and new bounds, including shadows and blur.
Output-specific callbacks follow window ownership. Presentation feedback is
collected only for surfaces the renderer actually displayed on that output.
An unchanged frame still permits paced client callbacks without submitting a
new display buffer.
Animations use elapsed time across outputs, with a timer while transitions remain
active. An idle focused monitor must not stall another monitor's animation.
The compositor renders blur from content behind the requesting surface. Material
regions and client content must share coordinates during placement, scaling,
and animation. See [Theme components](ferese-theme-ui-spec.md).
## Input
Use milliseconds for keyboard, pointer, touch, and gesture protocol events;
relative-motion timestamps retain microseconds. Keep keyboard focus, pointer
focus, and window stacking separate. Hover focus does not scroll or raise windows.
Pointer grabs and constraints must end cleanly when their surface disappears.
A locked pointer's position hint is stored while locked, then resolved against
current surface geometry and clamped to an output when the lock is released.
## IPC and private protocols
User control uses `$XDG_RUNTIME_DIR/ferese/control.sock`, restricted to the
session user. The parent directory is private and peers are checked by UID.
IPC frames are length-prefixed JSON with bounded message sizes, workers, and queues.
See `feresectl --help` for commands.
Private Wayland capabilities grant shell control or material effects to trusted
components. Public layer-shell access alone grants neither. Trusted connections
and descriptors must not leak to launched applications. Capture paths check
session policy and reject capture while locked.
Session locking must protect every output, including hotplug, and remain secure
if the lock UI crashes. [Portal integration](portals.md) documents application
consent and the currently supported services.
## Review and testing
Check output ownership, presented geometry, focus restoration, request lifetimes,
and bounded work whenever changing a protocol or rendering path. Test both
backends; a nested result does not establish hardware behavior.
Use the [animation](animation-validation.md), [resize](nested-resize-testing.md),
and [soak](native-soak-testing.md) checks alongside the workspace tests.
docs/notifications.md
-47
View File
@@ -1,47 +0,0 @@
# Notifications
Ferese shows compact notification popups and a history panel opened from the bar.
Their colors, font, corners, and background follow the shell theme.
## Popups and history
Up to three popups are visible at once. Hovering pauses a popup's timer.
History keeps the latest 100 notifications and clears when the shell exits.
App action buttons work when provided by the sender. Transient messages leave
history when closed.
Critical notifications bypass Do Not Disturb and remain visible unless the app
provides a timeout. Other apps can also request a timeout or no timeout.
## Settings
**Settings → Notifications** controls popup visibility, the default timeout, and
the Do Not Disturb preference. The bar toggle changes Do Not Disturb for the
current session; Settings saves it for future sessions. Hidden popups still enter
history.
```kdl
notifications {
show-popups #true
do-not-disturb #false
timeout-ms 6000
}
```
The default timeout accepts 1000–30000 milliseconds.
## Send a test notification
```sh
notify-send --app-name=Ferese --icon=dialog-information "Hello" "Your desktop notification"
```
## Troubleshooting
Only one notification server can run on the session bus. The session launcher
stops `swaync.service` before starting the shell. When launching the shell manually,
stop any existing notification server first. If another server owns the interface,
Ferese logs that native notifications are unavailable.
Ferese supports plain text, app icons, actions, replacement, and urgency. Rich
markup, embedded images, sounds, and saved notification history are not supported.
docs/theme-engine.md
-150
View File
@@ -1,150 +0,0 @@
# Themes
The compositor resolves theme files and publishes a versioned snapshot. Native
apps consume that snapshot; Settings edits references and requests isolated previews.
## Preset pairs
| Family | Dark preset | Light preset |
| --- | --- | --- |
| Ferese Blue (default) | `ferese-blue` | `ferese-blue-light` |
| Catppuccin | `catppuccin-mocha` | `catppuccin-latte` |
| Gruvbox | `gruvbox` | `gruvbox-light` |
| Rosé Pine | `rose-pine-moon` | `rose-pine-dawn` |
| Tokyo Night | `tokyo-night` | `tokyo-night-day` |
| Everforest | `everforest-dark` | `everforest-light` |
Each variant supplies its own surfaces, tint strength, opacity, blur, borders,
and shadows. Shared material overrides apply to both appearances; appearance
specific overrides take precedence. [Palette sources and adjustments](theme-palette-sources.md)
record the upstream colors and contrast tuning.
## Configuration
```kdl
theme {
mode "auto"
family "catppuccin"
split #false
file "themes/custom_theme.kdl"
light {
preset "ferese-blue-light"
file "themes/custom_theme_light.kdl"
material { opacity 0.94; tint-strength 1; }
}
dark { preset "ferese-blue"; file "themes/custom_theme_dark.kdl"; }
schedule { source "schedule"; timezone "system"; light-at "07:00"; dark-at "19:00"; }
accessibility { increase-contrast #false; reduce-transparency #false; }
accent "#3D7BE6"
}
```
Paths are relative to the configuration directory. Partial theme files contain
`theme { colors { accent "#3D7BE6"; } }`, or the token sections directly.
Merge order is preset, shared file, appearance file, shared inline tokens,
appearance inline tokens, then accent and accessibility adjustments. Unknown tokens warn; invalid known values reject
an entire update and retain the last working snapshot.
## Snapshot
`ResolvedTheme` contains effective appearance and typed colors, surfaces, material,
geometry, typography, wallpaper, border paints, and shadow tokens. Base, raised,
and application backgrounds are separate colors. Selected mode,
accessibility inputs, requested accent, adjusted accent, warnings, schema version,
and revision accompany it. Consumers do not infer appearance from brightness.
Material tokens differ by appearance. Light translucent surfaces use full tint strength and
0.94 default opacity to stay pale over dark wallpapers; dark surfaces use a softer
0.5 tint. Shared material overrides apply to both unless the appearance overrides
them. Reduce Transparency resolves to solid
material with zero blur. Increase Contrast adjusts text, borders, and translucent
surface tint for 7:1 text contrast, and enables native high-contrast controls.
Accents are adjusted against surfaces independently for each appearance, then
on-accent text is selected for readability.
## Scheduling
Auto selects the most recent light or dark boundary in the configured timezone.
The interval is circular, so light may start after dark. Equal boundaries are
invalid. Repeated hours use their first occurrence; skipped hours shift forward
by the timezone gap. The next transition arms a realtime timer. Resume, timezone
replacement, and realtime clock jumps trigger recalculation without polling.
## Transitions
Prepare the incoming wallpaper before starting a 250 ms eased transition. Decode
or upload failures and a bounded readiness timeout retain the old wallpaper and
allow the theme change. Reduced motion and accessibility changes apply immediately.
Transitions preserve their exact resolved endpoints. Changes within one appearance
keep the resolved material settings instead of adding temporary tint corrections.
Surface, tint, border, shadow, and accent colors can transition. Fonts and geometry
switch atomically. Foregrounds remain readable across dark and light backdrops. Near the neutral
midpoint, the transition temporarily strengthens material tint instead of fading
text through the background color. Tests sample primary, muted,
and on-accent text throughout the transition. Wallpaper changes use prepared
images rather than a placeholder.
Publish effective appearance at transition start. The portal emits changed
`color-scheme`, `accent-color`, `contrast`, and `reduced-motion` values then.
## Commands
| Command | Action |
| --- | --- |
| `feresectl theme get` | Read the current mode, effective appearance, and colors |
| `feresectl theme status` | Read warnings and the last reload error |
| `feresectl theme subscribe` | Stream changes as JSON; no polling |
| `feresectl theme mode light` | Save Light mode; also accepts `dark` and `auto` |
| `feresectl theme preview PATH` | Resolve a candidate config without applying it |
Settings shows six paired previews, with Light on the left and Dark on the right.
Auto uses a switch in the page header. The adjacent button shows its source and,
when enabled, the effective appearance. It opens source and schedule controls
below the gallery, which can be edited before enabling Auto. Enabling Auto
immediately follows the chosen source; disabling it keeps the current appearance.
Manual appearance controls are in Control Center. Selecting a family
applies the matching variant live and offers Undo for five
seconds. Hovering does not change the desktop. Arrow keys navigate the gallery.
Enable **Use different themes for light and dark** for two independent galleries.
Disabling it uses the active family and retains the stored pair. A missing
variant uses Ferese Blue for that appearance and displays a fallback note.
**Follow system** reads `org.gnome.desktop.interface color-scheme` and monitors
changes. `default` and `prefer-light` mean Light; `prefer-dark` means Dark. If the
setting is unavailable, Ferese uses Dark and displays a note. This source does
not read Ferese's own appearance portal, avoiding a feedback loop. Sunrise/sunset
is deferred.
The gallery’s Import button adds a family to the gallery without selecting it. Give each
variant an explicit section; omitted tokens inherit Ferese Blue for that
appearance. For example:
```kdl
theme {
name "My theme"
light { colors { accent "#8F5300"; }; }
dark { colors { accent "#CBA6F7"; }; }
}
```
Settings stores the file reference under `theme.custom-themes.<id>.file`.
The compositor validates it and publishes its palettes alongside built-ins.
Omit a variant to make a single-variant family. Token-only partial files remain
supported as shared/per-appearance overrides; imports require explicit variants
so appearance is never guessed from brightness. Imported and override files
reload after a short debounce, including saves that replace the file. Invalid
updates retain the last working theme and produce one desktop notification.
High contrast, Reduce Transparency and Reduce Motion are in Accessibility.
Material, accent, font and geometry controls stay visible below the gallery. Theme
overrides are under Advanced customization, in one file-picker row with a
Shared/Light/Dark selector; each stored
reference is retained when selecting another scope. Settings and shell switches
share the same palette. Switch and slider thumbs stay circular regardless of
shell corner radius.
When an older config first adopts mode or preset selection, Ferese moves its
inline palette into the dark selection and preserves comments. Shared wallpaper,
font, and geometry settings continue to apply to both appearances. For a wallpaper
pair, set `background { path "..."; }` inside each appearance or its theme file.
docs/theme-palette-sources.md
-33
View File
@@ -1,33 +0,0 @@
# Theme palette sources
Ferese maps upstream palettes to desktop roles. Materials are authored for Ferese;
text and accents have the adjustments below to meet desktop contrast requirements.
| Family | Source revision | License |
| --- | --- | --- |
| catppuccin | [07d02aa110ef](https://github.com/catppuccin/palette/blob/07d02aa110ef9eb7e7427afca5c73ba9cf7f8ebd/palette.json) | MIT |
| gruvbox | [ef8864bb42bf](https://github.com/morhetz/gruvbox/blob/ef8864bb42bf244f0295d1c5a403b27e3d139695/colors/gruvbox.vim) | MIT/X11 |
| rose-pine | [ff483051a47e](https://github.com/rose-pine/neovim/blob/ff483051a47e27d84bdef47703538df1ed9f4a47/lua/rose-pine/palette.lua) | MIT |
| tokyo-night | [cdc07ac78467](https://github.com/folke/tokyonight.nvim/blob/cdc07ac78467a233fd62c493de29a17e0cf2b2b6/extras/kitty/tokyonight_day.conf) | Apache-2.0; palette exports marked MIT |
| everforest | [85a86eb62409](https://github.com/sainnhe/everforest/blob/85a86eb62409e3ec88713bff3d1b9d7374e112e4/autoload/everforest.vim) | MIT |
Tokyo Night Night also uses its [official export](https://github.com/folke/tokyonight.nvim/blob/cdc07ac78467a233fd62c493de29a17e0cf2b2b6/extras/kitty/tokyonight_night.conf).
## Color adjustments
| Variant | Token | Upstream | Ferese |
| --- | --- | --- | --- |
| rose-pine-moon | muted | `#908CAA` | `#918DAA` |
| rose-pine-dawn | muted | `#797593` | `#716D89` |
| tokyo-night-day | text | `#3760BF` | `#3358B0` |
| tokyo-night-day | muted | `#6172B0` | `#4D5A8C` |
| tokyo-night-day | accent | `#2E7DE9` | `#2C76DD` |
| everforest-light | muted | `#829181` | `#677367` |
| everforest-light | accent | `#8DA101` | `#849601` |
Catppuccin Latte uses upstream subtext1 for muted labels. Gruvbox uses readable
foreground shades rather than its comment gray. Rosé Pine uses its subtle role
for secondary labels and its love accent in Dawn. Everforest uses the Hard pair.
Tokyo Night uses the upstream Night and Day exports.
License texts are bundled in [assets/themes/licenses](../assets/themes/licenses)
and copied into each installed release. Older saved Monochrome, Dracula, Ayu Light,
and Monokai selections remain readable, but are absent from the gallery.