14 KiB
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 policyferese-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:
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:
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
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
ferese-glass
ferese-translucent
ferese-solid
All share:
component geometry
spacing
typography
icon metrics
interaction states
motion semantics
6. Background
Supported:
solid color
image fill
image fit
[theme.background]
path = "/path/to/wallpaper.png"
mode = "fill" # fill or fit
Ferese SHOULD NOT globally blur the wallpaper.
Optional restrained adjustments MAY include:
brightness
dimming
saturation
Default fallback:
#0B0F14
7. Color tokens
Representative dark profile:
[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:
[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
[theme.geometry]
base_unit = 8.0
window_radius = 14.0
top_bar_height = 38.0
top_bar_margin_top = 4.0
top_bar_margin_horizontal = 10.0
top_bar_radius = 19.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
[theme.typography]
font_family = "sans-serif"
Initial roles:
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.
The configured family applies consistently to shell text. Icon assets use the theme icon set and are sized from the same scale tokens rather than text glyph metrics.
Clocks and changing numeric values SHOULD use tabular numerals where available.
11. Iconography
System icons are monochrome vectors.
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:
╭──────────────────────────────────────────────────────────────╮
│ F 1 2 3 4 Zed 09:41 🔊 ◉ │
╰──────────────────────────────────────────────────────────────╯
Surface role:
surface.panel
Workspace state
Inactive workspaces use muted text.
Active workspace uses a compact filled or accent-backed indicator.
Focused application
May display:
application icon
application name
Full changing window titles are not part of the default bar.
Clock
Compact:
09:41
Optional wide:
Mon, Sep 23 09:41
13. Launcher
The launcher is the primary application-selection surface.
Default placement:
centered horizontally
upper-middle or center of usable workspace
Surface role:
surface.panel_elevated
Default geometry:
width theme.geometry.launcher_width
max height 70% of usable output
radius theme.geometry.launcher_radius
Initial content:
╭──────────────────────────────────────╮
│ Search apps… │
├──────────────────────────────────────┤
│ │
│ Zed Firefox Foot │
│ Files Settings Music │
│ │
╰──────────────────────────────────────╯
Initial implementation is apps-only.
14. Launcher search field
height 44-48 px
radius 12 px
Placeholder:
Search apps…
The search field is the visual focus.
15. Launcher application grid
Recommended:
4-6 columns depending on launcher width
Entries show:
application icon
one-line application name
Long names truncate with ellipsis.
16. Top-bar popovers
Surface:
surface.popover
Recommended:
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:
╭──────────────────────────────╮
│ 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:
surface.menu
Row:
icon label shortcut
Disabled items use text_disabled.
19. Modals
Modals use:
surface.modal
Default width:
360-480 px
Background scrim uses theme.colors.scrim.
Modal visuals do not imply a Ferese authentication agent.
20. Notifications
Toast surface:
surface.notification
Recommended width:
320-360 px
Structure:
icon
summary
body
time
optional actions
Newest appears nearest the top bar.
21. OSD
Surface:
surface.hud
Example:
╭──────────────────────╮
│ 🔊 ━━━━━━━●━━━━━ │
╰──────────────────────╯
Default placement is centered or lower-middle.
22. Overview chrome
Managed windows remain live compositor surfaces.
Theme/UI owns only:
selection ring
labels
workspace strip
scrim
overview control surfaces
Selected preview uses an accent ring, not a large glow.
23. Interaction states
Controls support:
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:
2 px accent ring
2 px visual separation where needed
Focus rings MUST NOT alter component geometry.
25. Shadows
Levels:
none
soft
elevated
Representative:
[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:
1 logical px
Glass uses subtle highlight borders.
Solid may use slightly stronger borders.
Borders MUST NOT resemble neon outlines.
27. Motion tokens
spatial spring
bounded easing
Approximate ranges:
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:
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:
╭──────────────────────────────────────────────╮
│ sidebar │ content │
│ │ │
│ General │ Appearance │
│ Appearance │ │
│ Tiling │ live preview │
│ Workspaces │ controls │
│ Shortcuts │ │
│ Input │ │
╰──────────────────────────────────────────────╯
31. Appearance settings
Expose:
material style
accent
corner radius
shadow intensity
glass blur
glass opacity
animation speed
reduced motion
Material style:
Glass
Translucent
Solid
Changing style MUST preserve geometry.
32. Theme configuration
[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 = 38.0
top_bar_radius = 19.0
launcher_width = 560.0
launcher_radius = 20.0
[theme.motion]
speed = 1.0
reduced_motion = false
33. Validation
Reject:
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:
colors
material parameters
radii
shadows
typography
accent
icon tint
motion scale
validated component geometry tokens
Themes MUST NOT change:
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:
1. geometry correctness
2. input latency
3. text/icon clarity
4. animation continuity
5. shadow quality
6. blur quality
7. decorative effects
Allowed degradation:
glass
-> lower-resolution glass
-> translucent
-> solid
Component geometry remains unchanged.
36. Visual acceptance criteria
Implementation succeeds when:
- top bar, launcher, popovers, notifications, OSD, overview chrome, and Settings share one spacing/material/typography system;
- glass, translucent, and solid profiles preserve geometry;
- typography remains readable on bright and dark backgrounds;
- icons have consistent optical weight;
- launcher and popovers look anchored and intentional;
- focus/selection/urgent states remain distinct without relying on glow;
- disabling blur does not make the desktop look unfinished;
- reduced-motion mode remains coherent; and
- the desktop feels complete without a persistent dock or bottom application bar.