From c0010ccbb6933ff706fc4f21226f188bd2800f4a Mon Sep 17 00:00:00 2001 From: Samuel Onoja Date: Thu, 1 Oct 2026 17:51:54 +0100 Subject: [PATCH] Remove design documents and their handbook references --- docs/README.md | 6 -- docs/animation-validation.md | 26 ----- docs/configuration.md | 12 +-- docs/desktop-widgets.md | 118 ----------------------- docs/development.md | 4 - docs/ferese-shell-design.md | 65 ------------- docs/ferese-theme-ui-spec.md | 83 ---------------- docs/ferese-window-manager-spec.md | 109 --------------------- docs/notifications.md | 47 --------- docs/theme-engine.md | 150 ----------------------------- docs/theme-palette-sources.md | 33 ------- scripts/build-site.py | 4 - site/content/index.md | 4 +- 13 files changed, 4 insertions(+), 657 deletions(-) delete mode 100644 docs/animation-validation.md delete mode 100644 docs/desktop-widgets.md delete mode 100644 docs/ferese-shell-design.md delete mode 100644 docs/ferese-theme-ui-spec.md delete mode 100644 docs/ferese-window-manager-spec.md delete mode 100644 docs/notifications.md delete mode 100644 docs/theme-engine.md delete mode 100644 docs/theme-palette-sources.md diff --git a/docs/README.md b/docs/README.md index 279682e..4e97502 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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). diff --git a/docs/animation-validation.md b/docs/animation-validation.md deleted file mode 100644 index 9806999..0000000 --- a/docs/animation-validation.md +++ /dev/null @@ -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. diff --git a/docs/configuration.md b/docs/configuration.md index d394722..dc8a278 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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..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. diff --git a/docs/desktop-widgets.md b/docs/desktop-widgets.md deleted file mode 100644 index 2e5bd66..0000000 --- a/docs/desktop-widgets.md +++ /dev/null @@ -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. diff --git a/docs/development.md b/docs/development.md index d7aa035..2d067b9 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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: diff --git a/docs/ferese-shell-design.md b/docs/ferese-shell-design.md deleted file mode 100644 index 40fea05..0000000 --- a/docs/ferese-shell-design.md +++ /dev/null @@ -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. diff --git a/docs/ferese-theme-ui-spec.md b/docs/ferese-theme-ui-spec.md deleted file mode 100644 index b214c3e..0000000 --- a/docs/ferese-theme-ui-spec.md +++ /dev/null @@ -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. diff --git a/docs/ferese-window-manager-spec.md b/docs/ferese-window-manager-spec.md deleted file mode 100644 index 106c14b..0000000 --- a/docs/ferese-window-manager-spec.md +++ /dev/null @@ -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. diff --git a/docs/notifications.md b/docs/notifications.md deleted file mode 100644 index 1ecb169..0000000 --- a/docs/notifications.md +++ /dev/null @@ -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. diff --git a/docs/theme-engine.md b/docs/theme-engine.md deleted file mode 100644 index fe72259..0000000 --- a/docs/theme-engine.md +++ /dev/null @@ -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..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. diff --git a/docs/theme-palette-sources.md b/docs/theme-palette-sources.md deleted file mode 100644 index f43e403..0000000 --- a/docs/theme-palette-sources.md +++ /dev/null @@ -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. diff --git a/scripts/build-site.py b/scripts/build-site.py index 3a28b29..d41cce1 100644 --- a/scripts/build-site.py +++ b/scripts/build-site.py @@ -17,11 +17,7 @@ PAGES = [ ('why-ferese', 'Why Ferese', ROOT / 'docs/why-ferese.md'), ('installation', 'Installation', ROOT / 'docs/installation.md'), ('configuration', 'Configuration', ROOT / 'docs/configuration.md'), - ('theme-engine', 'Themes', ROOT / 'docs/theme-engine.md'), - ('theme-palette-sources', 'Theme palette sources', ROOT / 'docs/theme-palette-sources.md'), ('shortcuts', 'Shortcuts and gestures', ROOT / 'docs/shortcuts.md'), - ('desktop-widgets', 'Desktop widgets', ROOT / 'docs/desktop-widgets.md'), - ('notifications', 'Notifications', ROOT / 'docs/notifications.md'), ('locking', 'Lock screen', ROOT / 'docs/locking.md'), ('screen-sharing', 'Screen sharing', ROOT / 'docs/screen-sharing.md'), ('portals', 'Desktop portals', ROOT / 'docs/portals.md'), diff --git a/site/content/index.md b/site/content/index.md index 602e9ef..c85b37e 100644 --- a/site/content/index.md +++ b/site/content/index.md @@ -10,7 +10,7 @@ use ## Get started 1. [Install Ferese](installation.md), or try a [nested preview](installation.md#preview-and-logs). -2. Choose Light, Dark, or Auto in **Control Center**. Open **Settings** for [theme files and presets](theme-engine.md). +2. Choose Light, Dark, or Auto in **Control Center**. Open **Settings** for theme files and presets. 3. Use the [configuration reference](configuration.md) for shortcuts, gestures, window rules, and displays. ## Default shortcuts @@ -40,8 +40,6 @@ group windows, resize them and move between workspaces. ## Desktop guides -- [Desktop widgets](desktop-widgets.md): clocks and sticky notes. -- [Notifications](notifications.md): history and Do Not Disturb. - [Lock screen](locking.md): appearance, automatic locking, and display sleep. - [Screen sharing and recording](screen-sharing.md): share an app or display, or save a video. - [Desktop portals](portals.md): integration with applications.