LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.
Design guide for LordOS apps
LordOS apps follow our design guide, modeled on widely used desktop human-interface conventions: generous whitespace, a small type scale,
consistent control heights and one accent-colored action per view. This guide is the reference
for every polish pass, so all apps share the same spacing, type and controls. The shared building
blocks are in sdk/controls.jsx and sdk/components.jsx, and the tokens below are exported from
the SDK as spacing, typeScale and controlSize.
The first pass (Calculator, Text Editor, Notes, Photos, PDF Viewer and Fonts) and the second one
(Terminal, Store, Monitor, Player, Screenshots, Camera, Voice Recorder, Scanner, Emoji & Symbols
with the system emoji picker, About and the Installer) are documented with before/after
screenshots in docs/polish/, as is the third (Settings page by page, Files, Terminal
Preferences and the Store's remaining pages), and the fourth (the system apps: Disks, Backups, Logs,
Clock and Help), as is the fifth (Mail, Calendar, Contacts and Reminders) and the last one (Passwords).
Spacing: an 8 px grid
| Token | px | Use |
|---|---|---|
xs |
4 | tight spots: between a glyph and its label, between grouped toolbar buttons |
s |
8 | between controls in a row, between rows of a list, toolbar gap |
m |
12 | toolbar side insets, inside a grouped box, between a label and its control |
l |
16 | padding of panels and dialogs that sit inside a window |
xl |
20 | window content inset (nothing touches the window edge), dialog padding |
xxl |
24 | between groups and sections |
Rules:
- The content of a window starts 20 px from its edges. Lists in a sidebar start 10 px in, with 8–10 px of padding inside each row.
- Separate groups by 20–24 px and controls by 8–12 px. Never place two controls touching.
- Use hairlines (1 px,
separator) between a sidebar and its content, under a toolbar and above a status bar. Don't use thick borders.
Type scale
Inter, weights 400 / 500 / 600 only (700 only for very short emphasis).
| Token | px | Weight | Use |
|---|---|---|---|
caption |
11 | 400–600 | secondary labels, section captions in sidebars, status bars, counts |
callout |
12 | 400 | hints, secondary text in rows |
body |
13 | 400–500 | default text, list rows, buttons, menus |
headline |
15 | 600 | dialog titles, month headers, empty-state titles |
title |
17 | 600 | the title of a pane when space is short |
largeTitle |
22 | 600 | the title of a library or detail view (Photos, Fonts) |
Secondary text uses textDim. Avoid uppercase captions: use sentence case ("Contents",
not "CONTENTS").
Controls
| Control | Height | Radius | Notes |
|---|---|---|---|
Button |
28 (regular), 22 (small) |
7 / 6 | primary = the one accent action of the view; plain = borderless; destructive |
TextInput |
28 (13 px text) | 7 | grows with size |
SearchField |
28 | 7 | magnifier at the leading edge, clear button at the trailing edge |
Segmented |
28 (22 small) |
8 | appearance="neutral" for view switchers (Read/Edit, Sample/Characters/Info); fill to share the width |
ToolbarButton |
28 (22 small) |
6 | icon-only items must have a title (tooltip); active = toggled on |
ToolbarGroup |
32 | 8 | buttons that belong together: zoom −/value/+, markup tools |
Toolbar |
44 | — | 12 px side insets, 8 px gap, hairline at the bottom |
SidebarItem |
28 | 6 | source list row; string icon is drawn in the accent color; optional detail |
MenuButton |
28 | 8 | "⋯" or "⊕" button that opens a small menu (checked, disabled and destructive items) |
Toggle |
24 (20 small) |
— | small = the 36 × 20 switch of grouped forms (Settings rows) |
Hairline |
1 | — | edge="top" | "bottom" | "start" | "end": a 1 px separator on that edge of its parent; start/end follow RTL |
Icons are monochrome Unicode glyphs from the fallback fonts (Inter, DejaVu Sans, Noto Sans
Symbols 1/2), not color emoji. Verified on the VM:
✎ ⧉ ⊕ ⋯ ◫ ⛶ ⤢ ⟲ ⟳ ↻ ⎙ ⌕ ✕ ◐ ▬ ▤ ▦ ▶ ⓘ ☺ ‹ ›. Color emoji (🗑 📎 🖼 🗨) and some
symbols (🗀) don't render as icons: draw a small shape instead (see FolderGlyph in Photos).
The media symbols (⏮ ⏸ ⏭ 🔁 🔊 💬 🎙 📷) are color emoji too: the Player draws its transport
glyphs (PlayGlyph, PauseGlyph, SkipGlyph, SpeakerGlyph, CaptionsGlyph), the Camera and
the Recorder draw their empty-state icons. ↻ ⤮ ♪ ◫ ▣ ☺ ≡ render monochrome.
Layout patterns
- Sidebar (source list): 200–240 px,
sidebarBg, a hairline on its trailing edge,SectionTitlecaptions (11 px, 600,textDim) andSidebarItemrows. A search field goes at the top of the sidebar when the list is what you search. - Toolbar: icon-only buttons with tooltips where that is the convention. Show a text label only for
the main mode switch or the back button. Push trailing items to the end with
ToolbarSpacer. In narrow windows, hide items that are also in the app menus (print, invert, rotate), and move secondary actions into aMenuButton("⋯"), so the toolbar never wraps to a second row. - Grouped form ("inset"):
GroupBoxwithFormRowchildren: a rounded box (radius 10) with hairlines between rows. Rows are at least 32–36 px. In a key/value list, put the labels in a right-aligned column (labelWidth) and the values leading-aligned. - Empty state:
EmptyStatewith an icon, a short title (15/600) and one hint line (12,textDim), centered. At most one primary button. For an outcome worth a little warmth (an error or an unavailable service, "everything is up to date") passmascotinstead of the icon:mascot="confused","celebrate","shield"or"wave"draws Lumo at 112 px (sdk/mascot.js, docs/LORDOS-BRAND.md). Not in "nothing selected" panes, and never more than one Lumo per view. - Dialogs and sheets: 20 px padding, title 15/600, body 13 with
lineHeight: 1.4, buttons at the end of the last row with 12 px above them. The default action isprimary. - Hierarchy: one primary (accent) action per view. Everything else is plain or neutral.
- Inspector / detail pane: a fixed-width pane (200–280 px,
sidebarBg,Hairline edge="start") shows anEmptyStateuntil something is selected, never a blank column (Emoji & Symbols). - Media bar: the Player's now-playing bar spans the whole window: cover and title at the
start, the transport (buttons above a progress row) in a 380 px center column, the volume at
the end. Under 720 px it keeps only the cover and the transport. Measure the box after layout
(
lord.getLayout(ref.current.id)[2]) to adapt columns and widths (Player, Recorder waveform). - Viewfinder apps (Camera): always dark, whatever the theme; mode switch as two words with
the current one in yellow, a 60 px shutter centered between two
flex: 1columns. - Wizards (Installer): step list in the sidebar (numbered circles, the current row
highlighted),
largeTitlestep title, fields with 16 px between them, a footer with a hairline and Back / Next (disabledinstead of a faded look). - Utility (Disks): the actions for the selection are labelled
ToolbarButtons over the detail pane (the ones that don't fit go into "⋯"), the details are aGroupBoxofFormRows with a right-aligned label column, and the selection title islargeTitle. - Console (Logs): one 44 px toolbar (live, export, process field,
SearchField), a 40 px scope bar with small neutralSegmentedfilters, column captions over the list, a detail pane and a status bar, each separated by aHairline. - Settings plus browser (Backups): a header with the app icon, status and the one primary action;
a neutral
Segmentedcentered in a 44 px bar; settings asGroupBoxes in a 640 px centered column; the browser as a dated source list plus a file list with column captions. - Tabbed utility (Clock): the tabs in the toolbar, centered, and the "add" action as a "+" toolbar button at the trailing edge, never a button floating at the bottom.
- Reader (Help): a centered reading column up to 680 px; the article keeps its own direction
(
textDirection(body)), so an English article in an Arabic interface still reads left to right. - Mail / Calendar / Contacts / Reminders: source lists use monochrome glyphs in the accent
color; where the glyph would be a color emoji (tray, archive, trash, folder, person) it is drawn
with views (
Glyphinapps/mail,PersonGlyphinapps/contacts). Mail keeps three panes with an icon-only toolbar over the list and the message; list rows are 86 px (sender, subject, two lines of preview) with a rounded selection, and under 1000 px the panes shrink to 200 / 290 px. Calendar centers the Day/Week/Month switch, puts the period title (22/700) over the grid with ‹ Today › at its trailing edge, and hides the sidebar below 760 px unless asked for. Bottom bars of adjacent columns share one height (40 px) so their hairlines line up. Text that belongs to the user (event titles, previews) keeps its own direction (textDirection) in an RTL UI.ToolbarButton'siconmay also be an element (a drawn glyph). - Settings (System Settings): a 220 px sidebar (search field, the user card, groups of
SidebarItemrows 12 px apart with 20 px colored badges: a soft vertical gradient and a white glyph, or a drawn shape where the glyph is a color emoji), a 48 px title bar over the page with a hairline, and the page in a scroll view (20 px from the top, 24 px side insets, at most 680 px wide, centered). Pages are built only fromapps/settings/ui.jsx:Stack(sections 20 px apart),Section(13/600 header, an insetGroupBox, an 11 px footer),SettingRow(28 px of content with 4 px above and below, so 36 px between hairlines; the control at the trailing edge),ValueRow(value right-aligned intextDim),FieldRow(a field of a fixed width at the trailing edge),Actions(buttons under a group, trailing),Note/Message. Buttons inside rows aresmall(22 px); switches are<Toggle small>(36 × 20). Pickers between a few pictures (light/dark, Dock side) are thumbnail tiles with a 2 px accent ring. - Passwords (an isolated app): a 220 px source list (
SearchField, then accent glyph rows,SectionTitlecaptions, category rows with 18 px colored tiles and tag rows with a color dot; a 41 px bottom bar with the generator, settings and Lock), a 290 px item list (17/600 title, 48 px rows with a 30 px tile, sort and "+" as toolbar buttons) and the detail pane (22/600 title, chips, the fields in an inset group with icon-only copy/show buttons, small secondary buttons, destructive ones in red). Under 960 px the columns shrink to 200 / 250 px and the detail title to 17 px. Category glyphs are drawn (apps/passwords/glyphs.jsx); a category stores the glyph's name, and old emoji values map to the nearest glyph. The lock screens are a 360–460 px centered column with a 22/600 title and a neutral method switch; sheets are 48 px title + 20 px padding and scroll when the window is too small. An isolated app gets the UI direction with the language (locale.dir), so it mirrors in RTL too. - Preferences panes (Terminal): sections as sidebar rows (not a long tab bar that cannot fit),
a header with the section and profile names and the
Donebutton, and a form with a 170 px right-aligned label column. Measure the pane: under 480 px the labels go above their controls. Lists of editable items (key mappings, triggers, shortcuts) are insetGroupBoxrows.
Theme tokens for the shared controls
A theme gives the shared controls (sdk/components.jsx, sdk/controls.jsx, Settings' ui.jsx,
the shell's confirmation and power sheets) their shape through tokens next to the colors
(sdk/theme.js, DEFAULT_TOKENS). Apps don't read them: they use the controls, so every app takes
the theme's look without changes, and isolated apps receive the same tokens through the broker.
| Token | Lord Flow | Lord Classic | What it changes |
|---|---|---|---|
controlRadius / controlRadiusSmall |
7 / 6 | 4 / 4 | Button, TextInput, SearchField, Segmented, Stepper, toolbar buttons, sidebar rows, pop-up buttons |
groupRadius |
10 | 6 | GroupBox, Settings' sections and page headers, dialogs (+2) |
menuRadius / menuItemRadius |
8 / 5 | 8 / 4 | MenuButton menus, pop-up lists, tooltips (menuRadius − 2) |
menuHighlight |
'accent' |
'subtle' |
the hovered menu item: filled with the accent and white text, or a light fill |
selection |
'fill' |
'indicator' |
the selected SidebarItem: an accent fill, or a light fill with a 3 px accent bar at its leading edge |
inputFocus |
'ring' |
'underline' |
the focused TextInput: an accent border, or a 2 px accent line along its bottom |
buttonBorder |
false |
true |
a 1 px border around neutral buttons and pop-up buttons |
popupBg |
null (by mode) |
its own | the surface of menus, lists and tooltips |
Control heights, spacing and the type scale stay the same in both themes, so layouts don't move when the user switches.
Lord Classic
The second full appearance (0.8.3), for people used to a taskbar layout. Same apps, same SDK; only
the frame, the shell and the tokens above change. Our own design: drawn icons (themes/classic/glyphs.jsx),
Inter, the LordOS wallpapers and LordOS names, no assets or names from any other system.
![]() |
![]() |
| The desktop: the centered taskbar and a window frame | Start menu: search, pinned, recent, user and power |
![]() |
![]() |
| Typing in the start menu searches like the system search | Quick settings, light mode |
![]() |
![]() |
| Notifications and the calendar, from the clock | Task view (Super+Tab): live windows, smaller |
![]() |
![]() |
| Snap layouts, from the maximize button | Dragging to the left edge: the preview |
![]() |
![]() |
| Arabic: the taskbar and the frame mirror | Settings → Appearance → Desktop style |
![]() |
![]() |
| Before (0.8.2): the Lord Classic template | After: the start menu in light mode |
![]() |
![]() |
| Files in Arabic | Settings in Arabic: the selection bar on the leading edge |
- Window frame: a 34 px title bar with the app icon and the title (12 px) at the start and 44 × 34 px minimize, maximize/restore and close buttons at the end (close turns red on hover); corners of 8 px, square when maximized or snapped; the focused window has a stronger border and shadow. In right-to-left languages the engine mirrors the row (buttons at the start).
- Menus inside the window (0.8.5): Lord Classic has no menu bar on top, so an app that declares
menus (
useAppMenus: Files, Text Editor, Notes, Terminal, PDF Viewer, Photos, Screenshots, Mail, Passwords) shows them in a 26 px strip under its title bar (File, Edit, View, Go…, then Window and Help, one menu open at a time;MenuStripinthemes/classic/components/Window.jsx). Apps without menus of their own get no strip. Help holds About ; the Window menu is the same in both themes (windowMenuItems,sdk/windowmenu.js: Minimize, Zoom, Fill, Center, Move & Resize, Move to , Bring All to Front and the open windows), and the app menu and Force Quit come fromsdk/appcontrol.js(Lord Flow shows them under the app's name and in the crown menu). - Taskbar: 48 px (56 px wide on the left or right), a translucent material with the theme's blur (none with Transparency off). Buttons are 40 × 40 with a 6 px radius; the running app has a short pill below its icon, longer and in the accent color when it is in front. Tooltips after 600 ms. The tray ends with a narrow "show desktop" strip.
- Panels (start menu 640 × up to 700, quick settings 360, notifications 380): 10 px radius,
the panel material with a 1 px border, 28 px side insets in the start menu, a footer band
(
panelFoot) for the user and power or the battery and Settings. - Quick settings tiles: 48 px high, accent fill when on, a chevron segment that opens the matching Settings page.
- Shortcuts: Super alone opens the start menu; Super+arrows snap the window in front; Super+Tab is the task view; Super+A quick settings; Super+N notifications; Alt+F4 closes the window in front.
Every app in both themes, dark and light, is in docs/classic/ (<app>-classic-dark.png,
<app>-classic-light.png, <app>-default-dark.png, <app>-default-light.png; 28 apps), with
right-to-left samples (files, settings, calculator, notes, mail: <app>-<theme>-rtl.png)
and the shell (shell-*.png; shell-before-*.png is the 0.8.2 template).
| Lord Classic | Lord Flow |
|---|---|
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Scroll bars (0.8.3)
Every scrolling area uses the SDK's ScrollView, which draws an overlay scroll bar
(sdk/components.jsx, model in sdk/scrollbar.js):
- Over the content, at the very edge: a 6 px thumb, 2 px from the end edge of the view (and from
its top and bottom), widening to 10 px and darkening under the pointer or while dragged. It never
reserves a strip: give the content its normal padding (
contentStyle, or a padded first child) and the bar sits in it. Content that should run to the edge of a card can bleed into the card's padding:style={{ marginHorizontal: -12 }} contentStyle={{ paddingHorizontal: 12 }}(Monitor → Network). At least 12 px of end padding keeps the widened bar off the text. - Hidden until used: it appears while the view scrolls (wheel, touchpad, a keyboard jump through
scrollRef.scrollTo, dragging the thumb) and, with Automatically, when the pointer comes within 16 px of the edge; it fades out over 200 ms a second after the last scroll. Settings → Appearance → Show scroll bars: Automatically (default), When scrolling (no pointer reveal), Always (a persistent bar, for accessibility; the 0.8.1gutterprop reserves an 11 px strip only in this mode). With Reduce motion it shows and hides without the fade. - Hit-testing: while shown, a 14 px strip at the edge over the thumb takes the pointer, so the
thumb can be dragged; while hidden it has
pointerEvents: 'none'and clicks reach the content. The fade changes only the thumb's opacity withlord.setStyle(no React render per frame). - Direction and themes: the bar is on the end edge (
end), so on the left in right-to-left languages. The theme styles it with the optional tokensscrollThumb,scrollThumbHover,scrollRadiusandscrollThumbBorder(a pill in Lord Flow; the Lord Classic theme's is squarer and solid with a hairline).ThemeProviderpasses the setting (scrollBars) andreduceMotionwith the tokens, so isolated apps follow them too. - The Terminal's history bar (drawn in C,
term_paint.c) uses the same size and inset and shows only while you look at the history.
Tests: tests/scrollbar_model_test.mjs (geometry, thumb hit-test and drag, show/hide per mode,
fade timing, reduce motion) and test_overlay_scrollbar in build/engine-test (painted over the
content, no strip reserved, never over the text, the strip takes the pointer only while shown,
the faded opacity, RTL). Screenshots: scrollbars-network-{light,dark}-{hidden,scrolling}.png,
scrollbars-settings-{light,dark}.png.

Robustness checklist
Check every pass on the VM with:
- light and dark mode;
- RTL (Arabic test pack
docs/packs/lordos-lang-ar.json). The engine mirrors rows. Content that is itself left to right keepsdirection: 'ltr'(calculator keypad, code, sliders, page geometry), and user text follows its own direction withtextDirection(text)(a Spanish note in an Arabic UI still reads left to right); - the minimum window size (
minSizein the manifest) and a large/maximized window; - no overlapping or clipped controls, and no toolbar that wraps. Text that can be long uses
whiteSpace: 'nowrap'andtextOverflow: 'ellipsis'inside aflex: 1box (see "Engine notes").
Engine notes
- Long text: truncate it, don't let it be cut at the edge. A file name, a song title or a
subject in a row:
whiteSpace: 'nowrap', textOverflow: 'ellipsis'inside aflex: 1(orminWidth: 0) box. A preview or a description:numberOfLines: 2(the last line ends in "…"). Text that has a fixed height andtextOverflow: 'ellipsis'keeps the lines that fit. The cut never splits a ligature, a mark or an emoji sequence, and the "…" goes where the text ends: on the left in Arabic and Hebrew (screenshots:engine-ellipsis-*.png). - Hairlines: a separator that belongs to a box is a border of that box:
borderBottomWidth: 1, borderBottomColor: t.separator(orborderTop…,borderStart…/borderEnd…, which follow RTL). Remember that a border is inside the box: add 1 px to a fixed height to keep the content where it was.Hairline(an absolute 1 px view) is still the tool for a line inset from the edges or over something else. - Corners:
borderTopLeftRadius… or the logicalborderTopStartRadius… for shapes rounded on one side (a segmented control's ends, a bubble). - Logical edges:
marginInlineStart/End,paddingInlineStart/EndandinsetInlineStart/Endfollow the node's direction, so[direction() === 'rtl' ? 'right' : 'left']is no longer needed (left/rightandmargin*Left/Rightstay physical, as in CSS). - Scale and rotate:
transform: [{ scale: pressed ? 0.96 : 1 }]for a press effect,transform: 'rotate(…deg)'for a spinner; layout doesn't change and clicks follow what is painted. lord-server paints the subtree once into a cached raster and composites it, so animating the scale is cheap (the Dock's minimize effect does it on a whole window:engine-dock-minimize.png). flex: 0is React Native's: the box keeps itswidth/heightand doesn't grow or shrink (it used to mean a zero basis, which collapsed a box with awidth).flex: 1and awidthon the same box still mean "grow from 0" (thewidthis ignored): pass one or the other.
Pending (engine)
- No vector icon set: icons are font glyphs (see above).



















