MayteraOS UI Style Guide

Version: 1.0 Last Updated: 2026-01-29 Author: UI Lead / Art Director

Table of Contents

1. Design Philosophy
2. Theme System Overview
3. Color Palettes
4. Typography
5. Spacing and Layout Grid
6. Component Specifications
7. Icon Style Guidelines
8. Animation Guidelines
9. Accessibility
10. Implementation Reference

1. Design Philosophy

Default: 1990s UNIX Aesthetic

MayteraOS defaults to a CDE/Motif-inspired visual language reminiscent of classic UNIX workstations (CDE, NeXTSTEP, early IRIX, Solaris). This aesthetic prioritizes:

• Functional over flashy - Every visual element serves a purpose
• Beveled 3D elements - Raised buttons, sunken input fields, clear depth hierarchy
• Muted color palettes - Grays, tans, muted blues; no harsh saturated colors
• Pixel-perfect borders - Clean 1-2px borders with highlight/shadow pairs
• Information density - Efficient use of screen real estate
• Predictable behavior - Visual affordances clearly communicate interactivity

Theme Variants

While the default is retro UNIX, MayteraOS supports modern themes:

2. Theme System Overview

Architecture (corrected)

Themes in MayteraOS are defined in flat /THEMES/<name>.mtheme files, one file per theme (plain text, key=value lines), and loaded by the kernel's theme system (kernel/gui/themes.c). There is no per-theme subdirectory and no theme.ini; the layout below describes an earlier, superseded design.

Theme File Structure (superseded, kept for history)

/THEMES/
  retro-unix/
    theme.ini           # Color and style definitions
    wallpapers/         # Theme-specific wallpapers (optional)
    icons/              # Theme-specific icon overrides (optional)
    sounds/             # Theme-specific sounds (optional)
  modern-light/
    theme.ini
    ...

What actually ships is flatter:

/THEMES/
  RETRO_UNIX.mtheme
  MODERN_LIGHT.mtheme
  MODERN_DARK.mtheme
  FLUENT_LIGHT.mtheme
  FLUENT_DARK.mtheme
  ... 9 more, 14 total

Theme.ini Format

See Section 10: Implementation Reference for the complete theme.ini specification. Note this describes the superseded format above, not the shipping .mtheme key=value format.

3. Color Palettes

3.1 Retro UNIX Theme (Default)

Based on CDE's default "Crimson" and "Neptune" color schemes with influences from NeXTSTEP's grayscale elegance.

Primary Colors

Window Chrome

Widget Colors

Semantic Colors

Desktop and Taskbar

3.2 Modern Light Theme (macOS-inspired)

Clean, airy aesthetic with subtle shadows and rounded corners.

Primary Colors

Window Chrome

Traffic Light Buttons

Widget Colors

3.3 Modern Dark Theme (macOS Dark-inspired)

Primary Colors

Window Chrome

Widget Colors

3.4 Fluent Light Theme (Windows 11-inspired)

Microsoft Fluent Design with Mica-like materials.

Primary Colors

Window Chrome

Window Buttons (Right-aligned)

Widget Colors

3.5 Fluent Dark Theme (Windows 11 Dark-inspired)

Primary Colors

Window Chrome

4. Typography

Font Stack

MayteraOS uses a layered font stack prioritizing system fonts for performance:

Retro UNIX Theme

Primary:    "Fixed", "Terminus", "DejaVu Sans Mono", monospace
UI Labels:  "Helvetica", "Liberation Sans", "Arial", sans-serif

The retro theme favors bitmap fonts at small sizes (typically 10-12pt) for authentic appearance.

Modern Themes

Primary:    "SF Pro Display", "SF Pro Text", "Segoe UI", "Helvetica Neue", sans-serif
Monospace:  "SF Mono", "Cascadia Code", "Consolas", "DejaVu Sans Mono", monospace

Type Scale

Font Rendering

5. Spacing and Layout Grid

Base Unit

All spacing in MayteraOS is based on a 4px base unit.

4px  = 1 unit  (xs)
8px  = 2 units (sm)
12px = 3 units (md)
16px = 4 units (lg)
24px = 6 units (xl)
32px = 8 units (2xl)

Window Dimensions

Retro UNIX Theme

Modern Themes

Fluent Themes

Layout Grid

Desktop Grid

• Grid cell size: 80x80px (retro), 90x90px (modern)
• Icon spacing: 16px between icons
• Desktop margin: 16px from screen edges

Window Content Grid

• Column width: Fluid, based on window width
• Gutter: 16px between columns
• Maximum content width: None (fill available)

6. Component Specifications

6.1 Buttons

Retro UNIX (Motif-style 3D Button)

+------------------------------------------+
|  highlight (1px) - #FFFFFF               |
| +--------------------------------------+ |
| |                                      | |
| |        BUTTON LABEL                  | |
| |                                      | |
| +--------------------------------------+ |
|                        shadow (1px) - #808080
+------------------------------------------+
  outer shadow (1px) - #404040

Specifications:

• Height: 24px (standard), 20px (compact)
• Min width: 75px
• Padding: 8px horizontal, 4px vertical
• Border: 2px 3D beveled (highlight top/left, shadow bottom/right)
• Corner radius: 0px (square)

States: | State | Background | Border | Text | |-------|------------|--------|------| | Normal | #C0C0C0 | 3D raised | #000000 | | Hover | #D0D0D0 | 3D raised | #000000 | | Pressed | #A0A0A0 | 3D sunken (inverted) | #000000 | | Disabled | #C0C0C0 | Flat gray | #808080 | | Focused | #C0C0C0 | + 1px dotted inner | #000000 |

Modern Themes (macOS-style)

Specifications:

• Height: 28px (standard), 22px (small)
• Min width: 64px
• Padding: 12px horizontal, 6px vertical
• Border: 1px solid + subtle shadow
• Corner radius: 6px

States: | State | Background | Border | Shadow | |-------|------------|--------|--------| | Normal | #FFFFFF | #D1D1D6 | 0 1px 2px rgba(0,0,0,0.05) | | Hover | #F5F5F7 | #C8C8CC | 0 1px 3px rgba(0,0,0,0.08) | | Pressed | #E5E5EA | #BEBEC2 | inset 0 1px 2px rgba(0,0,0,0.05) | | Primary | #007AFF | none | 0 1px 3px rgba(0,122,255,0.3) |

Fluent Themes (Windows 11-style)

Specifications:

• Height: 32px
• Min width: 96px
• Padding: 12px horizontal
• Border: 1px solid (bottom 1px darker)
• Corner radius: 4px

States: | State | Background | Border | |-------|------------|--------| | Normal | #FDFDFD | #D6D6D6 + bottom #A0A0A0 | | Hover | #F9F9F9 | Same | | Pressed | #F0F0F0 | Same | | Accent | #0078D4 | Subtle dark |

6.2 Scrollbars

Retro UNIX (Always visible, substantial)

+---+
| ^ |  <- Arrow button (16x16)
+---+
|   |
| # |  <- Thumb (draggable)
|   |
+---+
| v |  <- Arrow button
+---+

Specifications:

• Width: 16px
• Arrow buttons: 16x16px with 3D beveling
• Thumb: Min 20px height, 3D raised
• Trough: Sunken 3D appearance

Modern Themes (Overlay scrollbars)

Specifications:

• Width: 8px (expanded on hover: 12px)
• No arrow buttons
• Thumb: Rounded, semi-transparent
• Trough: Transparent until hover

Fluent Themes (Thin, revealed on scroll)

Specifications:

• Width: 6px (expanded: 12px)
• Thumb: 2px corner radius
• Auto-hide: Fades after 2 seconds idle

6.3 Menus

Retro UNIX (Motif-style popup)

Specifications:

• Background: #C0C0C0
• Border: 2px 3D raised
• Item height: 20px
• Item padding: 8px horizontal
• Separator: 1px sunken line with 4px margin
• Submenu arrow: > character, right-aligned

Item States: | State | Background | Text | |-------|------------|------| | Normal | Transparent | #000000 | | Hover | #4B6983 | #FFFFFF | | Disabled | Transparent | #808080 |

Modern Themes

Specifications:

• Background: #FFFFFF with shadow
• Border: None (shadow provides edge)
• Corner radius: 6px
• Item height: 28px
• Item padding: 12px horizontal
• Icon area: 24px left margin for checkmarks/icons

Fluent Themes

Specifications:

• Background: Semi-transparent with Acrylic blur
• Border: 1px #E5E5E5
• Corner radius: 8px
• Item height: 36px
• Flyout animation: 100ms ease-out

6.4 Checkboxes and Radio Buttons

Retro UNIX

Checkbox:

• Size: 13x13px
• Border: 2px sunken 3D
• Checkmark: X or checkmark glyph in black
• Label spacing: 4px

Radio Button:

• Size: 13x13px (circular)
• Border: 2px sunken 3D
• Indicator: Filled circle 7px

Modern Themes

Checkbox:

• Size: 16x16px
• Border: 1px #D1D1D6
• Corner radius: 4px
• Checked: Blue fill with white checkmark

Fluent Themes

Checkbox:

• Size: 20x20px
• Border: 1px #8A8A8A
• Corner radius: 4px
• Checked: Accent color fill with white checkmark

6.5 Text Inputs

Retro UNIX

Specifications:

• Height: 22px
• Border: 2px sunken 3D
• Background: #FFFFFF
• Padding: 4px
• Cursor: Block cursor (black)

Modern Themes

Specifications:

• Height: 28px
• Border: 1px #D1D1D6
• Corner radius: 6px
• Background: #FFFFFF
• Padding: 8px
• Focus: Blue border #007AFF

Fluent Themes

Specifications:

• Height: 32px
• Border: 1px (bottom 2px accent on focus)
• Corner radius: 4px
• Focus: Bottom border changes to accent color

6.6 Window Title Bars

Retro UNIX

+========================================================+
| [#] Window Title                          [_] [O] [X] |
+========================================================+

• Height: 20px
• Gradient: None (solid color)
• Title: Left-aligned, 4px from icon
• Buttons: Right-aligned, 16x16px each
• Icon: 16x16px app icon (optional)

Modern Themes

+----------------------------------------------------------+
|  (O) (O) (O)    Window Title                             |
+----------------------------------------------------------+

• Height: 28px
• Buttons: Left-aligned traffic lights (macOS style)
• Title: Centered
• Background: Semi-transparent (vibrancy)

Fluent Themes

+----------------------------------------------------------+
|  [icon] Window Title                      [_] [O] [X]   |
+----------------------------------------------------------+

• Height: 32px
• Buttons: Right-aligned, wide buttons
• Title: Left-aligned with app icon
• Background: Mica material effect

7. Icon Style Guidelines

Retro UNIX Icons

Characteristics:

• Size: 32x32px (standard), 16x16px (small)
• Color depth: 16-256 colors
• Style: Flat with minimal gradients, 1px black outline
• Perspective: Front-facing, 2D
• No drop shadows on icons

Inspiration: CDE icons, early GNOME, NeXTSTEP

Modern Theme Icons

Characteristics:

• Size: 32x32px, 64x64px, 128x128px
• Style: SF Symbols-inspired, outlined or filled
• Stroke weight: 2px for outlined style
• Colors: Monochrome with accent color highlights
• Soft drop shadows optional

Fluent Theme Icons

Characteristics:

• Size: 16x16, 20x20, 24x24, 32x32, 48x48px
• Style: Fluent System Icons - outlined by default
• Stroke weight: 1.5px
• Colors: Single color, system accent
• No gradients or shadows

Icon Grid

All icons should be designed on a pixel grid:

• 16px icons: 14px safe area, 1px padding
• 32px icons: 28px safe area, 2px padding
• 64px icons: 56px safe area, 4px padding

8. Animation Guidelines

General Principles

1. Purpose over decoration - Animations should provide feedback, not distraction
2. Quick and responsive - Most animations < 200ms
3. Respect reduced motion - Provide static alternatives

Retro UNIX Theme

Approach: Minimal to no animation

• Window open/close: Instant (no animation)
• Button press: Immediate visual state change
• Menu appearance: Instant

Modern Themes

Timing:

• Micro-interactions: 100-150ms
• State transitions: 150-200ms
• Page/view transitions: 250-350ms

Easing:

• Enter: ease-out (cubic-bezier(0, 0, 0.2, 1))
• Exit: ease-in (cubic-bezier(0.4, 0, 1, 1))
• Standard: ease-in-out (cubic-bezier(0.4, 0, 0.2, 1))

Animations: | Action | Animation | Duration | |--------|-----------|----------| | Window open | Scale 0.95->1.0, fade in | 200ms | | Window close | Scale 1.0->0.95, fade out | 150ms | | Window minimize | Scale to taskbar position | 300ms | | Button hover | Background fade | 100ms | | Menu open | Fade in + slight Y translation | 150ms |

Fluent Themes

Timing:

• Fast: 83ms (button hover)
• Normal: 167ms (standard transitions)
• Slow: 250ms (page transitions)

Easing: Windows uses custom bezier curves

• Standard: cubic-bezier(0.8, 0, 0.2, 1)

9. Accessibility

Color Contrast

All themes must meet WCAG 2.1 AA standards:

• Normal text: 4.5:1 minimum contrast ratio
• Large text (18px+): 3:1 minimum contrast ratio
• UI components: 3:1 minimum contrast ratio

High Contrast Mode

MayteraOS includes a dedicated High Contrast theme:

• Background: Pure black #000000
• Text: Pure white #FFFFFF
• Links/accents: Bright cyan #00FFFF
• Borders: White 2px
• No gradients or shadows

Focus Indicators

All interactive elements must have visible focus states:

• Retro: 1px dotted outline inside component
• Modern: Blue ring shadow
• Fluent: Black 2px outline with 2px white offset

Motion Sensitivity

• Respect OS-level "reduce motion" settings
• Provide instant alternatives for all animations
• Avoid parallax and auto-playing animations

10. Implementation Reference

Theme.ini File Format

[theme]
name = "Retro UNIX"
version = 1.0
author = "MayteraOS Team"
description = "Classic CDE/Motif inspired theme"
style = "retro"  # retro, modern, fluent

[colors]
; Window titlebar
titlebar_active = 0x4B6983
titlebar_inactive = 0x8B8682
titlebar_text = 0xFFFFFF

; Window body
window_bg = 0xAEB2C3
window_border = 0x000000

; Window control buttons
close_button = 0xC0C0C0
close_button_hover = 0xE04040
minimize_button = 0xC0C0C0
maximize_button = 0xC0C0C0

; Button widgets
button_bg = 0xC0C0C0
button_bg_hover = 0xD0D0D0
button_bg_pressed = 0xA0A0A0
button_border = 0x606060
button_text = 0x000000
button_disabled = 0x808080

; Text widgets
label_text = 0x000000
textbox_bg = 0xFFFFFF
textbox_border = 0x808080
textbox_text = 0x000000
textbox_cursor = 0x000000

; Checkbox
checkbox_bg = 0xFFFFFF
checkbox_border = 0x808080
checkbox_check = 0x000000

; Desktop
desktop_bg = 0x5F7B97

; Taskbar/Dock
taskbar_bg = 0xC0C0C0
taskbar_hover = 0xD0D0D0
taskbar_active = 0x4B6983
start_button = 0xC0C0C0
gauge_bg = 0x808080
gauge_fg = 0x4B6983

; Menus
menu_bg = 0xC0C0C0
menu_border = 0x000000
menu_item_hover = 0x4B6983
menu_text = 0x000000
menu_text_disabled = 0x808080
menu_separator = 0x808080

; Scrollbar
scrollbar_bg = 0xA0A0A0
scrollbar_thumb = 0xC0C0C0
scrollbar_thumb_hover = 0xD0D0D0

; Selection
selection_bg = 0x4B6983
selection_text = 0xFFFFFF

[dimensions]
titlebar_height = 20
border_width = 2
corner_radius = 0
button_height = 24
scrollbar_width = 16
resize_grip_size = 10

[typography]
font_family = "Terminus"
font_size = 12
font_weight = 400
titlebar_font_size = 12
titlebar_font_weight = 600

[effects]
; 0 = none, 1 = subtle, 2 = full
animations = 0
shadows = 0
transparency = 0
blur = 0

[borders]
; Style: flat, 3d-raised, 3d-sunken, outline
button_style = 3d-raised
input_style = 3d-sunken
window_style = 3d-raised

C API Integration

The theme system integrates with the kernel via themes.h:

// Get current theme colors
const theme_t *theme = theme_get_current();
uint32_t titlebar_color = theme->titlebar_active;

// Or use convenience macros
draw_rect(x, y, w, h, THEME_BUTTON_BG);

Adding a New Theme

1. Create directory: /THEMES/<theme-name>/
2. Create theme.ini with all required fields
3. Add theme ID to themes.h:

   #define THEME_MY_THEME  8

1. Add theme definition to g_themes[] array in themes.c
2. Increment MAX_THEMES if needed
3. Rebuild kernel

Appendix A: Color Conversion Reference

Appendix B: Quick Reference Card

Retro UNIX At-a-Glance

• Titlebar: 20px, solid color
• Borders: 2px 3D beveled
• Corners: Square (0px radius)
• Buttons: 3D raised/sunken
• Shadows: None
• Animations: None

Modern Light At-a-Glance

• Titlebar: 28px, translucent
• Borders: 1px subtle
• Corners: 10px radius
• Buttons: Flat with subtle shadow
• Shadows: Soft drop shadows
• Animations: 150-200ms ease

Fluent Light At-a-Glance

• Titlebar: 32px, Mica material
• Borders: 1px with accent bottom
• Corners: 8px radius
• Buttons: Flat with bottom border
• Shadows: Elevation-based
• Animations: 167ms standard This style guide is a living document. Updates should be coordinated through the UI Lead.