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

docs: install canonical Ferese specifications

Browse Source
This commit is contained in:
Samuel Onoja committed 2026-09-24 11:22:17 +01:00
1 parent e963b82a9e
commit e1f1c1b9b6
4 files changed
+1584 -138
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/ferese-shell-design.md
+454
View File
@@ -0,0 +1,454 @@
# Ferese Shell Design Specification
Status: Draft for implementation
Target: Ferese desktop tier
Normative owner: shell behavior and interaction
Companion documents:
- `ferese-window-manager-spec.md` — compositor mechanism and policy
- `ferese-theme-ui-spec.md` — visual tokens and exact component geometry
## 1. Purpose
`ferese-shell` provides the integrated desktop interface around Ferese-managed
windows.
The initial shell consists of:
- one floating top bar per output;
- an apps-only launcher;
- overview controls;
- top-bar popovers and a compact control center;
- notifications and notification history; and
- volume/brightness OSD.
Ferese deliberately provides no persistent dock or bottom application bar.
The shell MUST remain optional. If it crashes, managed windows, layout trees,
workspaces, focus topology, and client sessions remain valid.
## 2. Document boundaries
This document owns:
```text
shell visibility
layer-shell roles
exclusive-zone behavior
focus acquisition/restoration
launcher behavior
top-bar actions
notification/DND behavior
modal interaction
fullscreen shell behavior
shell restart behavior
```
It MUST NOT define raw colors, pixel heights, radii, blur amounts, icon sizes,
font sizes, or shadows. Those belong to `ferese-theme-ui-spec.md`.
## 3. Surface architecture
The shell uses public layer-shell for normal shell surfaces.
```text
background(output) background layer, optional
top_bar(output) top layer, exclusive zone
launcher(output) overlay layer, exclusive_zone = 0
notification_stack(output) overlay layer, exclusive_zone = 0
osd(output) overlay layer, exclusive_zone = 0
popover(output) overlay/top, exclusive_zone = 0
modal(output) overlay layer, exclusive_zone = 0
```
`ferese-shell-v1` is a private control protocol only. It MUST NOT duplicate
layer-shell geometry or roles.
Its initial responsibilities are:
```text
window list and lifecycle
application identity metadata
focused / urgent state
activate managed window
request close
enter / exit overview
select overview window / workspace
```
## 4. Top bar
A top bar exists on every active output unless disabled.
Its conceptual regions are:
```text
LEFT
Ferese mark
workspace switcher
focused application
CENTER
clock / date
RIGHT
notifications
sound
power
control-center entry
```
The top bar is the only persistent shell surface that reserves workspace space.
Workspace controls MUST use compositor workspace truth and ordinary Ferese
workspace policy.
The top bar SHOULD remain non-keyboard-interactive during ordinary use.
## 5. Fullscreen behavior
Entering fullscreen hides the top bar visually.
The underlying tiled workspace layout region MUST remain unchanged while
fullscreen is active.
A temporary top-bar reveal over fullscreen:
```text
uses overlay presentation
uses exclusive_zone = 0
does not resize the fullscreen client
does not mutate the underlying workspace layout
```
Leaving fullscreen restores the ordinary top-bar presentation without
reconfiguring hidden tiled windows merely because the bar reappears.
## 6. Shell reservation lease
If `ferese-shell` disconnects unexpectedly, Ferese SHOULD retain the most recent
valid Ferese-owned top-bar reservation for a short bounded grace period.
If the shell reconnects before expiry with a compatible reservation, tiled
windows MUST NOT reflow.
If the grace period expires, Ferese removes the reservation and performs at most
one ordinary layout reflow.
Default:
```text
reservation_grace_ms = 2000
```
## 7. Launcher
The initial launcher is apps-only.
Default invocation:
```text
Super + Space
```
The launcher MAY also be opened by a Ferese control in the top bar.
The launcher:
- receives keyboard focus immediately;
- discovers XDG desktop applications;
- searches by application name and normalized desktop identity;
- supports pointer and keyboard navigation;
- launches selected applications with XDG activation;
- dismisses on Escape; and
- restores the previous valid managed-window focus on dismissal.
Initial placeholder:
```text
Search apps…
```
The launcher MUST NOT expose dead tabs for files, settings, commands, or recents.
Future search providers MAY extend it without changing the base interaction
model.
## 8. Application identity and launch state
The launcher consumes the compositor's normalized application identity and launch
association model.
It MUST NOT assume strings such as:
```text
firefox
org.mozilla.firefox
Mozilla Firefox
```
are the same application unless desktop-entry or activation metadata establishes
that relationship.
Ferese does not maintain a persistent running-application strip.
## 9. Top-bar popovers
A top-bar control may own one anchored popover.
Only one primary top-bar popover SHOULD be open per output at a time.
Initial popovers MAY include:
```text
calendar / time
sound
battery / power status
notifications
control center
```
Network and Bluetooth configuration are not part of the initial desktop tier and
MUST NOT appear as required or placeholder rows.
Opening another primary popover closes the previous one on that output.
## 10. Control center
The initial control center MAY expose only services backed by real providers:
```text
sound
battery / power status
Do Not Disturb
notification state
Ferese Settings
```
Unavailable capabilities are omitted.
## 11. Do Not Disturb
When DND is off:
```text
eligible notifications may create transient toasts
notifications enter history according to normal policy
```
When DND is on:
```text
normal transient toasts are suppressed
notifications still enter history
unread state still updates
```
A future explicitly defined critical-urgency policy MAY bypass DND.
No application-name heuristic may bypass DND.
DND state persists across shell restart.
## 12. Notifications
`ferese-shell` implements `org.freedesktop.Notifications`.
Initial support:
```text
summary
body
icon metadata
expiry
replacement
close
actions
urgency metadata
```
Notification content is untrusted.
Transient toasts:
- do not reserve workspace space;
- appear beneath the top bar;
- obey DND;
- do not take keyboard focus by default.
## 13. Notification center
Notification history opens from the top bar.
The initial implementation SHOULD use a large anchored popover rather than a
permanent side drawer.
The center may take shell keyboard focus while interactive and MUST restore the
previous managed-window focus when dismissed.
## 14. OSD
OSD handles transient state such as:
```text
volume
brightness
microphone mute
keyboard backlight
```
OSD surfaces:
```text
use overlay layer
use exclusive_zone = 0
never take keyboard focus
dismiss automatically
```
## 15. Overview
`Super+Tab` enters overview.
Managed-window previews remain compositor-owned live scene nodes.
The shell provides:
```text
selection affordances
application/window labels
workspace controls
optional later search UI
```
The shell MUST NOT implement overview by continuously copying each managed
window into the shell process.
Window activation and close actions use `ferese-shell-v1`.
## 16. Modal interaction
Shell modals are reserved for:
```text
destructive confirmation
security-sensitive confirmation
irreversible shell action
```
Ordinary settings MUST NOT use shell modals.
When a shell modal opens:
```text
SeatState.keyboard_focus -> FocusTarget::Shell(modal)
```
The compositor presents the modal above a scrim.
Input outside the modal is consumed by the scrim and MUST NOT reach managed
applications.
On dismissal, the previous valid managed-window focus is restored.
Ferese does not ship a polkit authentication agent in the initial desktop tier.
## 17. Shell restart
On restart:
```text
managed windows remain unchanged
workspace assignments remain unchanged
layout trees remain unchanged
managed-window focus remains valid where possible
```
The restarted shell reconstructs:
```text
top bars
workspace indicators
focused-app metadata
notification service/state
DND state
```
from compositor truth and persistent shell state.
## 18. Shell configuration
Representative behavior-only configuration:
```toml
[shell]
enabled = true
reservation_grace_ms = 2000
[shell.top_bar]
enabled = true
hide_in_fullscreen = true
show_workspaces = true
show_focused_app = true
show_clock = true
[shell.launcher]
enabled = true
binding = "Super+Space"
[shell.overview]
enabled = true
binding = "Super+Tab"
[shell.notifications]
enabled = true
do_not_disturb = false
```
Visual measurements do not belong here.
## 19. First shell implementation slice
```text
top bar
launcher
one top-bar popover
OSD
```
Demo:
```text
1. Start Ferese.
2. Top bar appears.
3. Workspace and focused-app state are correct.
4. Press Super+Space.
5. Launcher opens and receives focus.
6. Search for Foot and launch it.
7. Foot enters the current workspace through normal tiling policy.
8. Open Sound from the top bar.
9. Sound popover anchors to its invoking control.
10. Enter fullscreen.
11. Top bar hides without changing the underlying tiled layout region.
12. Reveal top bar temporarily as an overlay.
13. Exit fullscreen.
14. Top bar returns to normal reserved presentation.
15. Restart ferese-shell.
16. Tiled windows do not reflow during the reservation grace period.
```
## 20. Completion criteria
The initial shell is complete when:
1. every active output has a functional top bar;
2. launcher search and application launching work;
3. workspace indicators reflect compositor truth;
4. focused application state is accurate;
5. top-bar popovers anchor correctly;
6. notifications and DND work;
7. OSD works without taking focus;
8. overview uses compositor-owned live windows;
9. fullscreen hide/reveal does not alter underlying layout geometry;
10. shell restart does not disturb managed windows; and
11. all visual presentation is supplied through the theme/UI token system.
docs/ferese-theme-ui-spec.md
+807
View File
@@ -0,0 +1,807 @@
# Ferese Theme and UI Specification
Status: Draft for implementation
Target: Ferese desktop tier
Normative owner: visual tokens and component geometry
Companion documents:
- `ferese-window-manager-spec.md` — compositor mechanism and policy
- `ferese-shell-design.md` — shell behavior and interaction
## 1. Purpose
This document defines the Ferese visual language.
It owns:
- desktop background treatment;
- color tokens;
- semantic surface tokens;
- typography;
- iconography;
- spacing;
- exact top-bar geometry;
- launcher geometry;
- popover/menu/modal geometry;
- notification geometry;
- OSD geometry;
- settings UI primitives;
- motion tokens; and
- glass, translucent, and solid visual profiles.
It does not define shell focus, fullscreen behavior, workspace policy, launcher
behavior, notification policy, or compositor security.
Ferese intentionally has no persistent dock or bottom application bar.
## 2. Design language
Ferese UI should feel:
```text
quiet
precise
soft
material
low-latency
high-contrast
spatially consistent
```
The shell MUST avoid:
- excessive glow;
- RGB/gamer styling;
- ornamental gradients;
- gratuitous transparency;
- oversized shadows;
- arbitrary component styling;
- large chrome that steals workspace area; and
- pixel-for-pixel imitation of another operating system.
Ferese must still look complete with blur disabled.
## 3. Theme model
Components request semantic surface roles:
```text
surface.panel
surface.panel_elevated
surface.popover
surface.menu
surface.notification
surface.hud
surface.modal
```
The active profile maps each role to material parameters.
Themes change appearance, not component structure or behavior.
## 4. Material styles
```rust
pub enum MaterialStyle {
Glass,
Translucent,
Solid,
}
```
### Glass
Backdrop blur plus restrained tint, saturation, brightness, and optional noise.
### Translucent
Alpha-composited semantic tint with no backdrop blur.
### Solid
Opaque semantic surface with identical geometry.
Changing material style MUST NOT move, resize, or restructure shell components.
## 5. Built-in profiles
```text
ferese-glass
ferese-translucent
ferese-solid
```
All share:
```text
component geometry
spacing
typography
icon metrics
interaction states
motion semantics
```
## 6. Background
Supported:
```text
solid color
image fill
image fit
```
Ferese SHOULD NOT globally blur the wallpaper.
Optional restrained adjustments MAY include:
```text
brightness
dimming
saturation
```
Default fallback:
```text
#0B0F14
```
## 7. Color tokens
Representative dark profile:
```toml
[theme.colors]
desktop_background = "#0B0F14"
surface_base = "#111821"
surface_raised = "#18212C"
surface_elevated = "#202B37"
text_primary = "#F4F7FB"
text_secondary = "#B7C0CB"
text_muted = "#7F8A98"
text_disabled = "#58616D"
accent = "#5B8CFF"
accent_soft = "#8EAFFF"
accent_text = "#FFFFFF"
success = "#4CC38A"
warning = "#F0B45B"
danger = "#F06A6A"
border = "#FFFFFF18"
border_strong = "#FFFFFF2A"
shadow = "#00000055"
scrim = "#05070AB8"
```
## 8. Surface tokens
Representative glass profile:
```toml
[theme.surface.panel]
style = "glass"
opacity = 0.78
blur = 24.0
saturation = 1.08
brightness = 1.02
noise = 0.012
border_opacity = 0.10
shadow = "soft"
[theme.surface.panel_elevated]
style = "glass"
opacity = 0.84
blur = 28.0
saturation = 1.10
brightness = 1.03
noise = 0.014
border_opacity = 0.12
shadow = "elevated"
[theme.surface.popover]
style = "glass"
opacity = 0.84
blur = 28.0
saturation = 1.10
brightness = 1.03
noise = 0.014
border_opacity = 0.12
shadow = "elevated"
[theme.surface.hud]
style = "glass"
opacity = 0.88
blur = 30.0
saturation = 1.06
brightness = 1.04
noise = 0.010
border_opacity = 0.12
shadow = "elevated"
```
## 9. Geometry tokens
```toml
[theme.geometry]
base_unit = 8.0
window_radius = 14.0
top_bar_height = 32.0
top_bar_margin_top = 8.0
top_bar_margin_horizontal = 10.0
top_bar_radius = 16.0
launcher_width = 560.0
launcher_radius = 20.0
popover_radius = 16.0
menu_radius = 14.0
modal_radius = 18.0
hud_radius = 18.0
panel_padding = 12.0
control_gap = 8.0
section_gap = 16.0
```
Only the top bar consumes persistent shell space.
## 10. Typography
Initial roles:
```text
caption 11-12 px
body 13-14 px
body-strong 13-14 px medium
label 12-13 px medium
title 16-18 px semibold
display 22-28 px semibold
```
Use the system UI sans-serif by default.
Clocks and changing numeric values SHOULD use tabular numerals where available.
## 11. Iconography
System icons are monochrome vectors.
```text
visual box 16-20 px
stroke approximately 1.5-2 px
style simple and optically balanced
```
Application icons retain original artwork.
System icons MUST NOT use arbitrary gradients.
## 12. Top bar
Default composition:
```text
╭──────────────────────────────────────────────────────────────╮
│ F 1 2 3 4 Zed 09:41 🔊 ◉ │
╰──────────────────────────────────────────────────────────────╯
```
Surface role:
```text
surface.panel
```
### Workspace state
Inactive workspaces use muted text.
Active workspace uses a compact filled or accent-backed indicator.
### Focused application
May display:
```text
application icon
application name
```
Full changing window titles are not part of the default bar.
### Clock
Compact:
```text
09:41
```
Optional wide:
```text
Mon, Sep 23 09:41
```
## 13. Launcher
The launcher is the primary application-selection surface.
Default placement:
```text
centered horizontally
upper-middle or center of usable workspace
```
Surface role:
```text
surface.panel_elevated
```
Default geometry:
```text
width theme.geometry.launcher_width
max height 70% of usable output
radius theme.geometry.launcher_radius
```
Initial content:
```text
╭──────────────────────────────────────╮
│ Search apps… │
├──────────────────────────────────────┤
│ │
│ Zed Firefox Foot │
│ Files Settings Music │
│ │
╰──────────────────────────────────────╯
```
Initial implementation is apps-only.
## 14. Launcher search field
```text
height 44-48 px
radius 12 px
```
Placeholder:
```text
Search apps…
```
The search field is the visual focus.
## 15. Launcher application grid
Recommended:
```text
4-6 columns depending on launcher width
```
Entries show:
```text
application icon
one-line application name
```
Long names truncate with ellipsis.
## 16. Top-bar popovers
Surface:
```text
surface.popover
```
Recommended:
```text
width 280-360 px
padding 12 px
radius theme.geometry.popover_radius
anchor gap 8 px
```
They visually align with the invoking top-bar control.
## 17. Control center
Representative:
```text
╭──────────────────────────────╮
│ Sound │
│ ━━━━━━━━━━━●━━━━━━ │
│ │
│ Battery 92% │
│ Do Not Disturb Off │
│ Notifications 3 │
│ │
│ Ferese Settings │
╰──────────────────────────────╯
```
Network/Bluetooth rows are not part of the initial visual contract.
## 18. Menus
Menus use:
```text
surface.menu
```
Row:
```text
icon label shortcut
```
Disabled items use `text_disabled`.
## 19. Modals
Modals use:
```text
surface.modal
```
Default width:
```text
360-480 px
```
Background scrim uses `theme.colors.scrim`.
Modal visuals do not imply a Ferese authentication agent.
## 20. Notifications
Toast surface:
```text
surface.notification
```
Recommended width:
```text
320-360 px
```
Structure:
```text
icon
summary
body
time
optional actions
```
Newest appears nearest the top bar.
## 21. OSD
Surface:
```text
surface.hud
```
Example:
```text
╭──────────────────────╮
│ 🔊 ━━━━━━━●━━━━━ │
╰──────────────────────╯
```
Default placement is centered or lower-middle.
## 22. Overview chrome
Managed windows remain live compositor surfaces.
Theme/UI owns only:
```text
selection ring
labels
workspace strip
scrim
overview control surfaces
```
Selected preview uses an accent ring, not a large glow.
## 23. Interaction states
Controls support:
```text
rest
hover
pressed
focused
selected
disabled
urgent where applicable
```
Hover changes color/contrast only.
Pressed controls MAY use a tiny local scale response around `0.98`.
There is no dock-style magnification behavior.
## 24. Focus rings
Keyboard focus:
```text
2 px accent ring
2 px visual separation where needed
```
Focus rings MUST NOT alter component geometry.
## 25. Shadows
Levels:
```text
none
soft
elevated
```
Representative:
```toml
[theme.shadow.soft]
offset_y = 4.0
blur = 18.0
opacity = 0.20
[theme.shadow.elevated]
offset_y = 10.0
blur = 36.0
opacity = 0.28
```
Top bar uses `soft`.
Launcher, popovers, notifications, modals, and HUDs typically use `elevated`.
## 26. Borders
Default:
```text
1 logical px
```
Glass uses subtle highlight borders.
Solid may use slightly stronger borders.
Borders MUST NOT resemble neon outlines.
## 27. Motion tokens
```text
spatial spring
bounded easing
```
Approximate ranges:
```text
micro feedback 80-120 ms
popover/menu 140-200 ms
launcher 180-240 ms
notification 160-220 ms
```
Managed-window and overview motion remains compositor spring-driven.
## 28. Reduced motion
Reduced motion:
```text
removes decorative scale
shortens/removes large shell translation
uses opacity where spatial context is unnecessary
does not animate blur intensity
```
## 29. Fullscreen visual presentation
When fullscreen is active, the top bar is visually absent.
Temporary reveal uses the same visual tokens without implying any layout change.
## 30. Settings application
Ferese Settings consumes the same tokens.
Representative layout:
```text
╭──────────────────────────────────────────────╮
│ sidebar │ content │
│ │ │
│ General │ Appearance │
│ Appearance │ │
│ Tiling │ live preview │
│ Workspaces │ controls │
│ Shortcuts │ │
│ Input │ │
╰──────────────────────────────────────────────╯
```
## 31. Appearance settings
Expose:
```text
material style
accent
corner radius
shadow intensity
glass blur
glass opacity
animation speed
reduced motion
```
Material style:
```text
Glass
Translucent
Solid
```
Changing style MUST preserve geometry.
## 32. Theme configuration
```toml
[theme]
profile = "ferese-glass"
mode = "dark"
[theme.colors]
accent = "#5B8CFF"
[theme.material]
style = "glass"
[theme.material.glass]
blur = 24.0
opacity = 0.80
saturation = 1.08
noise = 0.012
[theme.geometry]
window_radius = 14.0
top_bar_height = 32.0
top_bar_radius = 16.0
launcher_width = 560.0
launcher_radius = 20.0
[theme.motion]
speed = 1.0
reduced_motion = false
```
## 33. Validation
Reject:
```text
non-finite dimensions
negative radii
negative blur
opacity outside 0..1
invalid colors
unknown material style
invalid font sizes
invalid motion factors
```
Theme changes use the same transactional Ferese configuration path.
## 34. Custom theme scope
Themes MAY change:
```text
colors
material parameters
radii
shadows
typography
accent
icon tint
motion scale
validated component geometry tokens
```
Themes MUST NOT change:
```text
top-bar behavior
launcher behavior
focus behavior
workspace behavior
notification policy
Wayland roles
security behavior
```
Ferese intentionally does not expose arbitrary CSS.
## 35. Performance degradation
Priority:
```text
1. geometry correctness
2. input latency
3. text/icon clarity
4. animation continuity
5. shadow quality
6. blur quality
7. decorative effects
```
Allowed degradation:
```text
glass
-> lower-resolution glass
-> translucent
-> solid
```
Component geometry remains unchanged.
## 36. Visual acceptance criteria
Implementation succeeds when:
1. top bar, launcher, popovers, notifications, OSD, overview chrome, and Settings
share one spacing/material/typography system;
2. glass, translucent, and solid profiles preserve geometry;
3. typography remains readable on bright and dark backgrounds;
4. icons have consistent optical weight;
5. launcher and popovers look anchored and intentional;
6. focus/selection/urgent states remain distinct without relying on glow;
7. disabling blur does not make the desktop look unfinished;
8. reduced-motion mode remains coherent; and
9. the desktop feels complete without a persistent dock or bottom application bar.
docs/ferese-window-manager-spec.md
+1424
View File
File diff suppressed because it is too large. Load diff