823 lines
14 KiB
Markdown
823 lines
14 KiB
Markdown
# 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
|
|
```
|
|
|
|
```toml
|
|
[theme.background]
|
|
path = "/path/to/wallpaper.png"
|
|
mode = "fill" # fill or 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 = 4.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
|
|
|
|
```toml
|
|
[theme.typography]
|
|
font_family = "sans-serif"
|
|
```
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
```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.
|