Skip to content

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.

Theme guide (docs/THEMES-GUIDE.md) and a minimal example theme (examples/theme-minimal); the theme switch keeps the last theme that loaded as the fallback after a refusal (two refused switches could leave no theme)

Federico Pereiraeaf139dee22c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 839822f..b907bf4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),
### Added
+- **A guide to building an appearance.** `docs/THEMES-GUIDE.md` explains, for a React developer new to
+ LordOS, what a theme is, its parts (theme.json, tokens, the shell, window frames, menus, layers),
+ right-to-left, light and dark, several displays and the performance rules, how to build and test one,
+ and a checklist; `examples/theme-minimal/` is a small working theme to start from. It also says
+ plainly what is missing: a theme LordOS didn't sign doesn't load on a release build yet (no theme
+ package format or user trust decision exists).
- **Settings → Displays: numbers, Identify and snapping.** With more than one display each one has a
number (the main display is 1); clicking a display in the arrangement, or Identify, shows its number
big on that monitor for a moment, so you know which screen is which. Dragging a display snaps it edge
@@ -120,6 +126,9 @@ of the matching [GitHub release](https://github.com/lordbasex/LordOS/releases),
### Fixed
+- **Two failed theme switches in a row could leave the session without a theme.** After a theme was
+ refused, the server still took it as the current one, so a second refused switch fell back to it.
+ Now the last theme that loaded stays the fallback.
- **Apps whose launcher file has a space in its name didn't appear in Apps.** A package may name its
`.desktop` file freely (the LordOS Imager's is `LordOS Imager.desktop`), but the launcher skipped any
name with a space or another unusual character. Such a name now gets an id with those characters
diff --git a/docs/README.md b/docs/README.md
index a887eed..73fc440 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -40,6 +40,7 @@ Website: [lordos.org](https://lordos.org) · Brand kit: [LORDOS-BRAND.md](LORDOS
| [DISPLAYS.md](DISPLAYS.md) | Several displays and HiDPI |
| [GPU.md](GPU.md) | GPU composition, dmabuf and the CPU path |
| [DOCK.md](DOCK.md) | Dock and taskbar |
+| [THEMES-GUIDE.md](THEMES-GUIDE.md) | How to build a LordOS appearance (theme): anatomy, tokens, frames, building, verified code, testing |
| [LAYERS.md](LAYERS.md) | The desktop's stacking order: what is drawn and clicked above what |
| [SPOTLIGHT.md](SPOTLIGHT.md) | Search and the advanced clipboard |
| [TRACKPAD.md](TRACKPAD.md) | Touchpads, gestures and touchscreens |
diff --git a/docs/THEMES-GUIDE.md b/docs/THEMES-GUIDE.md
new file mode 100644
index 0000000..2296a75
--- /dev/null
+++ b/docs/THEMES-GUIDE.md
@@ -0,0 +1,538 @@
+# How to build a LordOS appearance (theme)
+
+This guide is for a React developer who has never seen LordOS. It explains what a theme is, what it
+must provide, the SDK pieces it builds on, how it is built and loaded, and what to check before
+sharing it. Everything here is checked against the current code; file references point to where
+each piece lives. A small working starting point is in [`examples/theme-minimal/`](../examples/theme-minimal/).
+
+Read first, if you can: [`themes/README.md`](../themes/README.md) (the short reference: components,
+events and the supported style subset), [DESIGN.md](DESIGN.md) (tokens and the shared controls),
+[LAYERS.md](LAYERS.md) (stacking order) and [WINDOWS.md](WINDOWS.md) (moving and resizing).
+
+> **Today a theme only runs on a development build of LordOS.** A release build loads only JavaScript
+> that is listed in LordOS's signed code manifest, and a theme you build yourself is not in it. See
+> [Verified code](#verified-code-what-happens-to-a-theme-that-lordos-did-not-sign) for exactly what happens and what
+> would be needed.
+
+## 1. What a theme is
+
+A theme is **the whole desktop, written in React**: wallpaper, menu bar or taskbar, Dock, app
+launcher, panels, menus and every window frame. It is not a style sheet and it does not run in a web
+engine. `lord-server` (the display server and Wayland compositor, in C) evaluates the theme's bundle
+with QuickJS; a React reconciler (`runtime/index.js`) turns the tree into native nodes
+(`lord.setStyle`, `appendChild`…) that `lord-server` lays out (flexbox) and paints itself, on the
+CPU or the GPU. So you write ordinary function components with hooks, but with `<View>`, `<Text>`,
+`<Image>` instead of DOM elements, and a CSS subset as React Native-style style objects
+(`themes/README.md`, "Supported styles").
+
+**What the SDK (`@lordos/sdk`, `sdk/`) gives a theme:**
+
+- the native components and events (`View`, `Text`, `Image`, `Terminal`, `addListener`, gestures);
+- the window manager: the window list, open/focus/minimize/maximize/snap, the work area, moving and
+ resizing done in C (`sdk/windows.js`, `sdk/windowshell.jsx`);
+- `AppHost`, which draws an app inside a window; the native apps themselves come from `apps/`
+ (`@lordos/apps`) and Linux (Wayland and X11) windows arrive on their own (`sdk/wayland.js`);
+- the token contract and the shared controls apps use (`ThemeProvider`, `useTheme`,
+ `sdk/theme.js`, `sdk/components.jsx`, `sdk/controls.jsx`);
+- the layers that order everything above the windows (`Layer`, `Overlay`, `sdk/layers.js`);
+- the models behind the desktop pieces, without their look: the Dock and taskbar (`sdk/dock.js`),
+ app menus and the Window menu (`useAppMenus`, `appMenuItems`, `windowMenuItems`), notifications,
+ status items, search, sound, battery, Bluetooth, Night Light, displays, the clock, translations;
+- the surfaces that look the same in every theme, placed by `startShell`: search, notification
+ banners, permission and keyring prompts, the file chooser, the print dialog, the input method's
+ candidate window, fullscreen and picture-in-picture windows.
+
+**What the theme must provide:** the colors and shapes (tokens), the window frame, the desktop
+around the windows (bars, Dock, launcher, panels), where menus open, and the keyboard shortcuts of
+its own layout (for example what the Super key alone does).
+
+**The two built-in themes are the references:**
+
+| Theme | Folder | Layout |
+|---|---|---|
+| Lord Flow | `themes/default` | menu bar on top (with the app's menus), magnifying Dock, app launcher, Control Center |
+| Lord Classic | `themes/classic` | taskbar (bottom, top or a side), start menu with search, quick settings, notification panel, menus in each window, snapping and a task view |
+
+`themes/greeter` is the login and lock screen: it is a separate program, not a desktop theme (see
+[The login and lock screen](#the-login-and-lock-screen-are-not-your-theme)).
+
+**Switching.** The user switches themes live from **Settings → Appearance → Desktop style**, which
+since 0.8.5 lists every installed theme (the only place to choose one; `StylePicker` in
+`apps/settings/index.jsx`). Lord Flow and Lord Classic come first, the others by name; a theme with
+`"hidden": true` in its `theme.json` is not listed. Switching discards the JavaScript context and
+loads the new bundle (`themes.use` in `sdk/index.js`, `lord.themes.use` in `server/src/ui/js_sys.c`,
+`switch_theme` in `server/src/main.c`): the LordOS app windows that were open (up to 8) reopen in
+the new theme with their frames, and Linux windows stay connected and get the new frame. The
+choice is stored as `theme` in `~/.config/lordos/settings.json`.
+
+How a session starts: `lord-sessiond` always starts `lord-server` with
+`--theme <LordOS folder>/themes/default/theme.bundle.js` (`server/src/remote/sessiond.c`,
+`sess.c`); the default theme's `startShell()` sees that the user chose another one and switches to
+it at once. If the chosen theme can't be loaded, the session stays on the theme it came from.
+
+## 2. Anatomy of a theme
+
+```
+themes/<id>/
+ theme.json name, description, hidden
+ index.jsx the entry point: puts the desktop together, ends with startShell(<App />)
+ tokens.js the colors and shapes (by convention; the bundled themes use makeTheme())
+ components/ the frame, bars, Dock, menus… (by convention)
+ assets/ images the theme loads (<Image src="assets/…">)
+ theme.bundle.js the build output (generated)
+```
+
+The theme's **id is its folder name**: letters, digits, `-` and `_`, at most 64 characters
+(`valid_id` in `js_sys.c`). A folder is listed as a theme when it holds a readable
+`theme.bundle.js`.
+
+### `theme.json`
+
+```json
+{ "name": "Minimal", "description": "One sentence for Settings.", "hidden": false }
+```
+
+- `name` and `description` are what Settings shows, unless the `shell` catalog has
+ `shell.theme.<id>.name` / `shell.theme.<id>.description` (the bundled themes translate theirs
+ that way; `themes.list` in `sdk/index.js`). A missing or invalid `theme.json` shows the id.
+- `hidden: true` keeps it out of Settings (the login screen uses it).
+- It is read as text of at most 4 KB. It is data, not code, so it is not in the code manifest.
+
+### `tokens.js`: the contract with the apps
+
+Every app reads its colors with `useTheme()` (`sdk/theme.js`), so it looks right in any theme. The
+theme passes its tokens to `<ThemeProvider tokens={…}>`; whatever it leaves out falls back to
+`DEFAULT_TOKENS` (Lord Flow's dark colors), and its own extra keys pass through untouched. Isolated
+apps (their own processes) receive the same tokens through the broker, and Linux apps get the mode,
+the accent and the title-bar button order through the settings portal (`publishTokens` and
+`syncPortal` in `sdk/theme.js`). So the tokens must be plain JSON values (no functions).
+
+**Base tokens (required in practice: apps use all of them):**
+
+| Token | Meaning | Used by |
+|---|---|---|
+| `mode` | `'dark'` or `'light'`: apps pick icons, shadows and contrast from it | 67 places in `apps/` |
+| `accent` | the accent color (`#rrggbb`): selection, focus, toggles, primary buttons | 118 |
+| `text` | primary text | 281 |
+| `textDim` | secondary text: labels, hints, captions | 446 |
+| `windowBg` | the window's content background | 28 |
+| `sidebarBg` | sidebars and secondary panes | 17 |
+| `separator` | hairlines and borders between areas (usually a translucent `rgba`) | 101 |
+| `hover` | the fill of a hovered row or button (translucent) | 18 |
+| `control` | neutral control fills (buttons, tracks, segmented controls) | 44 |
+| `inputBg` | text fields | the SDK's `TextInput`, `SearchField` |
+
+(The counts are uses of `t.<token>` in `apps/**/*.jsx` on 2026-10-26.)
+
+**Optional tokens apps and the SDK read:**
+
+- `accents`: a map name → color. Settings → Appearance shows these swatches and stores the chosen
+ *name* (`settings.accent`). Use the same names as the bundled themes (`azul`, `violeta`, `rosa`,
+ `naranja`, `verde`, `grafito`) so the user's choice survives a switch; `syncPortal` maps them to
+ the portal's accent names.
+- `wallpapers`: `[{ id, nameKey, name, src, thumb?, category?, variants? }]` for Settings →
+ Wallpaper; `lordosWallpapers` from the SDK is the LordOS collection
+ (`assets/wallpapers/README.md`).
+- Shape tokens for the shared controls: `controlRadius`, `controlRadiusSmall`, `groupRadius`,
+ `menuRadius`, `menuItemRadius`, `menuHighlight` (`'accent'`|`'subtle'`), `selection`
+ (`'fill'`|`'indicator'`), `inputFocus` (`'ring'`|`'underline'`), `buttonBorder`, `popupBg`. They
+ restyle `Button`, `TextInput`, `GroupBox`, `SidebarItem`, menus… in every app without touching
+ the apps ([DESIGN.md](DESIGN.md#theme-tokens-for-the-shared-controls)).
+- Scroll bars: `scrollThumb`, `scrollThumbHover`, `scrollRadius`, `scrollThumbBorder`.
+- `gtkButtons`: the GTK title-bar button order sent to Linux apps (`':minimize,maximize,close'` for
+ buttons on the right; by default `'close,minimize,maximize:'`).
+- `radius`: a general corner radius (default 8).
+
+`ThemeProvider` adds two tokens from the user's settings: `scrollBars` and `reduceMotion`. The
+user's choices that a theme turns into tokens itself are in `settings` (`sdk/settings.js`): `mode`,
+`accent` (a name), `effects` (transparency with blur), `wallpaper`. Both bundled themes do it with a
+`makeTheme({ mode, accent, effects })` in `tokens.js`, called on every render with
+`useSettings()`, so a change in Settings → Appearance applies at once.
+
+### `index.jsx`: what it does and how the shell starts it
+
+There is no exported component: `index.jsx` is a script that runs once when the bundle is
+evaluated. The order the bundled themes follow:
+
+```jsx
+import { startShell, configureWindows, ThemeProvider, useSettings, useWindows, getApp, Layer } from '@lordos/sdk';
+import { apps } from '@lordos/apps'; // every native app in apps/, added by the build
+import { makeTheme } from './tokens.js';
+
+// 1. At module level: the apps, the work area and the frame size (before startShell)
+configureWindows({ apps, workArea: (d) => areaFor(d), chrome: { w: 2, h: TITLE_H + 2 } });
+
+function App() {
+ const [s] = useSettings();
+ const t = makeTheme(s);
+ const { windows, visible, focused } = useWindows();
+ return (
+ <ThemeProvider tokens={t}>
+ {/* wallpaper, <DesktopWidgets layer="below" />, the windows, <DesktopWidgets layer="above" /> */}
+ {/* <Layer name="dock">…</Layer>, <Layer name="menubar">…</Layer>, popovers, modals */}
+ </ThemeProvider>
+ );
+}
+
+// 2. Last: the SDK starts the desktop
+startShell(<App />);
+```
+
+**`configureWindows({ apps, workArea, chrome, snap })`** (`sdk/windows.js`):
+
+- `apps`: always the `apps` from `@lordos/apps`.
+- `workArea`: a function `display → { x, y, w, h }`, the free area for windows on that display
+ (without the bar and the Dock). Maximize, snapping, new windows and `wm.beginMove`'s top limit use
+ it. An object is still accepted and means the main display's area. Call it again when the bar or
+ Dock changes (both themes do it in a `useEffect` on the Dock settings and the screen size).
+- `chrome: { w, h }`: how much the frame adds around the content (borders plus title bar), so a
+ Linux window opens at the size it asked for.
+- `snap: true`: window snapping (drag to the edges, `wm.snap`, `wm.snapKey`, the `snapPreview`
+ store to draw the preview; [WINDOWS.md](WINDOWS.md#snapping-083)). Lord Classic turns it on.
+
+**`startShell(element)`** (`sdk/index.js`): switches to the user's theme if it isn't this one, turns
+the layers on, reopens the windows after a theme switch, renders your element inside a root that
+remounts on a language change, and adds the SDK's own surfaces in their layers (search,
+clipboard and emoji panels, print dialog, notification banners, prompts, Identify displays,
+fullscreen windows, the input method). It also starts the background services every theme gets:
+alarms, mail and reminder notifications, hardware (Night Light, idle, battery), disk health,
+browser video, the network item, and the "modified component" notice.
+
+The window objects (`useWindows()`: `windows` all of them bottom to top, `visible` without
+minimized/fullscreen/picture-in-picture, `focused` the id in front) carry `id`, `app`, `title`,
+`args`, `x`, `y`, `w`, `h`, `minimized`, `maximized`, `snapped`, `fullscreen`, `pip`, `protected`
+and, for Linux windows, `windowMenu`. Use `wm.frame(w)` for the effective geometry (a maximized
+window takes the work area), `windowTitle(w)` for the title, `windowIcon(w)` for its icon, and
+`getApp(w.id)` for the app (`transparent`, `minSize`, `name`…). The `wm` object has `open`, `close`,
+`focus`, `minimize`, `toggleMaximize`, `snap`, `center`, `moveToDisplay`, `arrange`, `move`,
+`resize`, `setFrame`, `beginMove`, `beginResize` and more (`sdk/windows.js`).
+
+Both bundled themes open windows at start (`wm.open('files')`, `wm.open('about')`); that is a
+choice, not a requirement.
+
+### Window frames
+
+Build every frame on **`<WindowShell win={w} style={…} onMouseDown={() => wm.focus(w.id)}>`**
+(`sdk/windowshell.jsx`). It positions the window, marks the node for the C side (`wm.frameRef`), and
+adds invisible resize edges on 4 sides and 4 corners (6 px outside, 3 px inside) with their cursors.
+Inside it:
+
+- a title bar whose `onMouseDown` calls **`wm.beginMove(w.id)`**. Moving and resizing are then done
+ by `lord-server` in C (`server/src/ui/grab.c`): React gets no event per frame, and the moving
+ window is painted from a cached layer ([WINDOWS.md](WINDOWS.md)). `beginMove` returns `false` when
+ it can't (a maximized window, no button held); Lord Classic then drags out of the maximized place
+ in JS with `wm.move`;
+- **`<AppHost id={w.id} focused={…} />`** for the content, in a `flex: 1` box;
+- no background under the content when `getApp(w.id).transparent` (the Terminal). Such a window has
+ nothing behind its border either: draw the border with `solidOver(line, titleBg)` so it stays
+ opaque (both themes do);
+- the title with `windowTitle(w)` (apps change it, for example the Terminal);
+- buttons that `stopPropagation()` on mouse down, so pressing them doesn't start a move.
+
+**Linux windows** enter as windows of the internal app `linux` (`sdk/wayland.js`). When
+**`w.args.csd`** is true the app draws its own title bar: render only `<WindowShell>` +
+`<AppHost>` (with your shadow) and no frame. `args.csd` can change while the window is open (the
+browsers' "tabs in the title bar" switch), so decide on every render. When such an app asks for the
+window menu (a right click on its own bar), `w.windowMenu` is `{ x, y }`: draw your window menu there
+and call `wm.closeWindowMenu(w.id)` when it closes ([WAYLAND.md](WAYLAND.md)). With `chrome`
+declared in `configureWindows`, server-side-decorated windows open at the size they requested.
+
+### Menus
+
+The SDK gives menus as **item lists**; the theme draws them. An item is
+`{ label, onClick, hint, disabled, checked, submenu, header }` or `'-'` for a separator.
+
+| Source | What it is |
+|---|---|
+| `useAppMenus(winId)` | the app's own menus (`[{ label, items }]`, e.g. the Terminal's Shell, Edit, View); `null` if it has none. Isolated apps' menus come through the broker and arrive the same way |
+| `appMenuItems(winId)` | the app menu: About *app*, Settings…, Hide, Hide Others, Show All, Quit (`sdk/appcontrol.js`) |
+| `windowMenuItems(winId)` | the Window menu, the same in every theme: Minimize, Zoom, Fill, Center, Move & Resize (halves, quarters, thirds, arrangements), Move to *display*, Bring All to Front, the window list (`sdk/windowmenu.js`) |
+| `dockMenu(entry)` | a Dock or taskbar item's context menu |
+| `trashMenu({ onEmpty })` | the Trash's menu |
+| `recentItems(n)`, `storeUpdates()`, `runningApps()`, `forceQuit(key)`, `appGroup(winId)` | for a system menu like Lord Flow's crown menu |
+
+Where they go is the theme's choice: Lord Flow shows the app menus in its top menu bar
+(`themes/default/components/MenuBar.jsx`), Lord Classic in a strip under each window's title bar
+(`themes/classic/components/Window.jsx`). A theme without either must still give the app's menus a
+place, or the apps lose commands. Each bundled theme has its own `components/Menu.jsx` that puts the
+menu in the `popover` layer.
+
+### Layers
+
+`zIndex` only orders siblings. Everything above the windows goes into a named **layer**:
+`<Layer name="dock|menubar|overlay|popover|modal|notification|tooltip|drag">` (the full order, with
+`floating`, `system` and `input` reserved for the SDK, is in `sdk/layers.js` and
+[LAYERS.md](LAYERS.md)). The layer, not the tree, decides what is drawn and clicked on top, so a menu
+is never under the Dock. A popover anchored to a control is `<Overlay anchor={ref} onClose={…}>`.
+While something is in `overlay`, `modal` or `system`, Linux apps don't get the keyboard; `popover`
+keeps it.
+
+### The Dock or taskbar
+
+`sdk/dock.js` is the model; the theme draws it ([DOCK.md](DOCK.md)):
+
+```js
+const entries = useDockEntries(['files', DOCK_LAUNCHER, 'terminal', 'settings'], { launcher: { Icon, onOpen }, recents: 0 });
+// entry = { id, kind, name, Icon, windows, pinned, running, focused, locked, movable, … }
+dockActivate(entry); // click: launch, or bring up (cycle) its windows
+dockMenu(entry); // context menu items
+dock.pin(id, i) · dock.move(id, i) · dock.unpin(id) · dock.reset()
+```
+
+Pinned items are typed ids (`app:`, `lpk:`, `desktop:`, `shell:launcher`; `sdk/dockmodel.js`);
+Files is always first and the Trash last. `dockPrefs(settings)` gives the user's position, size,
+magnification and auto-hide (and `taskbarPosition` for a taskbar). Dragging uses
+`beginDockDrag`, `registerDockTarget`, the `dockDrag` and `dockPoof` stores (the theme draws the
+drag image and the "poof"). The Trash: `useTrash()`, `openTrash()`, `emptyTrash()` (ask first with
+`ConfirmDialog`).
+
+### Panels: launcher, Control Center, quick settings, notifications
+
+There are no ready-made panels in the SDK: each theme draws its own from SDK stores and controls.
+
+- **App launcher / start menu:** `useLauncherApps()` (LordOS apps and installed Linux apps, sorted by
+ name, with `name`, `Icon`, `kind`), `launchApp(id)`, `appCategory(app)`, `APP_CATEGORIES`;
+ system-wide search results from `searchEverything` (Lord Classic's start menu).
+- **Control Center / quick settings:** `Toggle`, `Slider`, `Segmented`; `useSound`, `sound`,
+ `defaultSink`; `useBluetooth`; `useBattery`, `BatteryGlyph`; `nightActive`, `setNightManual`;
+ `notifyPrefs`, `dndActive` (Do Not Disturb); `NowPlayingTile`; `useCpuUsage`, `useSystemInfo`;
+ `keyboard.label(keyboard.active())`, `keyboard.next()`. See
+ `themes/default/components/ControlCenter.jsx` and `themes/classic/components/QuickSettings.jsx`.
+- **Status area:** `<StatusItems color={…} />` (items apps register with `registerStatusItem`, such
+ as the network item) and `<PrivacyIndicators />` (camera, microphone, screen in use).
+- **Notifications:** banners are drawn by the SDK (`NotificationBanner`, placed by `startShell`);
+ `setBannerPlacement('bottom')` puts them above a bottom taskbar. A notification centre reads
+ `notifyHistory` (and `useNotifications()` for what is on screen), with `dismissNotification(id)`
+ and `clearNotifyHistory()` (`themes/classic/components/NotificationCenter.jsx`).
+- **Search:** the SDK's search panel opens with ❖Space or Ctrl+Space by itself; a button calls
+ `spotlight.toggle()` ([SPOTLIGHT.md](SPOTLIGHT.md)).
+- **Session:** `session.quit()`, `session.lock()`, `session.switchUser()` (with `session.managed()`),
+ `session.restart()`, `session.shutdown()` (60 s confirmations; render `<PowerDialog />` in the
+ `modal` layer, inside your `ThemeProvider`, so it takes your colors).
+- **Gestures:** `registerGestureActions({ up, down, left, right })` in a `useEffect` (it returns the
+ function that removes them; [TRACKPAD.md](TRACKPAD.md)).
+- **Desktop widgets:** `<DesktopWidgets layer="below" />` between the wallpaper and the windows and
+ `<DesktopWidgets layer="above" />` after them (the Notes app's notes, [NOTES.md](NOTES.md)).
+
+Keyboard shortcuts of the layout are the theme's own (`addListener('keydown', …)`): both bundled
+themes open their launcher or start menu with Super pressed and released alone, and Lord Classic
+adds Super+arrows, Super+Tab, Alt+F4. The SDK already handles ❖Space (search) and ❖L / ❖Ctrl+Q (lock).
+
+### The login and lock screen are not your theme
+
+`themes/greeter` is loaded by `lord-sessiond` with `lord-server --greeter`, as the system user
+`lordos-greeter`, from a fixed path (`server/src/remote/sessiond.c`). It is also the lock screen
+(mode `lock`) and the user switcher. It calls `render()` itself instead of `startShell()`, and it never
+sees passwords being checked: it sends them with `lord.greeter.send()` and the root process answers
+([SESSIONS.md](SESSIONS.md)). A desktop theme can't replace or restyle it; the first frame of a
+boot (the hand-off from the boot splash) is the greeter's, or the default theme's with autologin.
+
+### Right to left
+
+With Arabic or Hebrew the engine flips rows and alignment by itself. Your part
+([LANGUAGES.md](LANGUAGES.md)):
+
+- text that follows the language uses `textAlign: 'start'`/`'end'`, never `'left'`/`'right'`;
+- use the logical edges (`paddingStart`, `marginInlineEnd`, `insetInlineStart`,
+ `borderTopStartRadius`…) instead of physical ones;
+- anything positioned from the mouse x (a magnifying Dock) is laid out with `direction: 'ltr'` or
+ takes `direction()` into account; drop-down menus open towards the inside (`direction() === 'rtl'`);
+- physical things stay physical: Super+Left snaps to the left in any language, and the Dock's
+ `left`/`right` positions are screen sides.
+
+### Light, dark, accent, transparency and motion
+
+- Build every color from `mode` (both themes switch the whole palette in `makeTheme`).
+- The accent comes as a name (`settings.accent`) mapped through your `accents`.
+- `settings.effects === false` means "no transparency": draw opaque bars and `blur: 0`.
+- **Reduce motion** (`settings.reduceMotion`, also `useTheme().reduceMotion`): skip decorative
+ animation (both themes skip the Dock's "poof" when an item is removed, Lord Flow also the Dock's
+ reorder glide; `ScrollView` stops fading).
+
+### Several displays
+
+Use `screenDisplays()` (`[{ id, name, x, y, w, h, scale, main }]`), `mainDisplay()`,
+`displayAt(x, y)`, `displayFor(rect)` and `screen.mirror` ([DISPLAYS.md](DISPLAYS.md#the-theme-and-the-sdk)).
+The bundled themes draw a wallpaper per display at its pixel size
+(`wallpaperSrc(w, d.w * d.scale / 100, d.h * d.scale / 100)`), and put the bar and the Dock on the
+main display (Lord Flow also on the others with "Show menu bar on all displays",
+`settings.menuBarAllDisplays`). Your `workArea` function receives each display; `workAreaOf(d)` and
+`pointerWorkArea()` read it back. New windows open on the display under the pointer, or the one the
+user assigned the app to from the Dock. The window list is global: windows are not per display.
+
+### Performance rules
+
+Everything runs on `lord-server`'s main thread, which also composites the screen and serves the
+Linux apps. A slow theme makes the whole desktop slow.
+
+- **No React render per frame.** Moving and resizing windows is already in C. To animate, change one
+ style with **`lord.setStyle(ref.current.id, 'opacity' | 'transform' | …, value)`** from a timer or
+ `requestAnimationFrame` (the `ScrollView` thumb fade in `sdk/components.jsx`, the fans in
+ `sdk/cooling.jsx`); stop the loop when the animation ends or the surface is hidden, and don't start
+ it with reduce motion.
+- **`transform` scale and rotate are cheap**: the subtree is painted once into a cached raster and
+ composited (Lord Flow's minimize effect scales a whole window).
+- **Blur costs**: `backdropFilter: blur(r)` reads a margin of 2×r around the surface, and any change
+ touching it repaints the whole surface ([LAYERS.md](LAYERS.md#blurred-surfaces-and-partial-repaints)).
+ Keep blurred surfaces few and small, and turn blur off with `effects: false`.
+- **Subscribe narrowly**: `useStore(store, selector)` re-renders only when the selected value changes;
+ a clock that renders every second should only re-render its own text.
+- **Don't poll** when a store exists (sound, battery, Bluetooth and displays arrive as events). Lord
+ Classic's network glyph polls every 5 s; that is the upper bound to aim for.
+- The style subset has no CSS animations, dashed borders, skew or 3D (`themes/README.md`). An
+ unknown style key is logged as `js: unsupported style '<key>'`.
+
+### Images, fonts and other files
+
+`<Image src="assets/x.png">` is resolved against the theme's folder; `asset:wallpapers/…` against
+LordOS's `assets/`; an absolute path as is (`server/src/ui/js.c`). PNG and JPEG. Text uses the
+bundled Inter (400/500/600/700). The `.deb` packaging copies only `theme.json`, `theme.bundle.js`
+and `assets/` of each theme (`tools/iso/mkdeb.sh`), so keep your files there.
+
+### Translations
+
+Visible text goes through `t('namespace.key')` ([LANGUAGES.md](LANGUAGES.md)); app names through
+`appName(app)`, dates and times through `formatDate`/`formatTime`. The bundled themes' strings are in
+the `shell` catalog (`assets/locales/{en,es,pt}/shell.json`). A theme of your own can reuse existing
+`shell.*` keys (the example does) or bring its own namespace: `lord.locale.catalog` reads
+`<lang>/<namespace>.json` from `~/.local/share/lordos/locales/` first and then LordOS's
+`assets/locales/` (`f_locale_catalog` in `js_sys.c`). A missing key shows the key itself. Inside the
+LordOS tree, `node tools/i18n-check.mjs` checks every `t()` key in `themes/` against the English
+catalog and every language against English.
+
+## 3. Building it
+
+`npm install` once (React, the reconciler and esbuild), then:
+
+```sh
+npm run build # every theme, the isolated-app host and the system apps
+node tools/build-theme.mjs <id> # only themes/<id>
+```
+
+`tools/build-theme.mjs` bundles `themes/<id>/index.jsx` with esbuild into
+**`themes/<id>/theme.bundle.js`** (one minified IIFE, ES2020, JSX automatic). React, the reconciler,
+`@lordos/runtime` (`runtime/index.js`) and `@lordos/sdk` (`sdk/index.js`) are **bundled into it**, and
+so is every native app: the virtual module `@lordos/apps` imports `apps/<id>/index.jsx` and
+`manifest.json` for each app (and checks that each has a semver `version`). That is why a theme
+bundle is 1.5–1.8 MB and why every theme carries the same apps. Apps with `"process": "isolated"`
+(Passwords, Mail…) run as their own processes; in the theme they are only a starter
+(`isolatedApp` in `sdk/packages.js`).
+
+The tool only builds folders under `themes/` of the tree it lives in: there is no option for a theme
+elsewhere, so a theme is developed inside a LordOS development tree (copy it to `themes/<id>`).
+
+After building, it rewrites **`code-manifest.json`** at the tree's root (`tools/code-manifest.mjs`):
+the size and SHA-256 of every `themes/*/theme.bundle.js`, `assets/app-host.bundle.js` and
+`assets/sysapps/*/app.js`. If the manifest changed, a `code-manifest.sig` next to it is deleted (it
+signed the old one).
+
+### Verified code: what happens to a theme that LordOS did not sign
+
+LordOS's own JavaScript is checked before it runs ([SIGNING.md](SIGNING.md#verified-system-code-082)).
+Every bundle goes through `codesig_load` (`server/src/sec/codesig.c`, called from `load_code` in
+`server/src/ui/js.c`): once per process `lord-server` reads `code-manifest.json` and
+`code-manifest.sig` from the LordOS folder (`/usr/lib/lordos` installed, the repository root in a
+development tree) and verifies the signature with the release key compiled into it. Then, per
+bundle:
+
+| `lord-server` build | Manifest in the LordOS folder | A `themes/<id>/theme.bundle.js` that is not listed |
+|---|---|---|
+| **Release** (`make -C server RELEASE=1`; the published images and `.deb`) | signed by LordOS | **refused**: `code: REFUSED themes/<id>/theme.bundle.js: not listed in the manifest` |
+| Release | missing, unsigned, or a bad signature | **everything is refused** (state "invalid"): the recovery screen |
+| Development (`make -C server`) | none | **loads** (About says "Development build") |
+| Development | unsigned (what `npm run build` writes) | **refused unless listed**: the hashes are still checked, so rebuild with `npm run build` / `build-theme.mjs` to list it |
+| Development | signed | refused unless listed |
+
+So on an installed release system, copying a theme into `/usr/lib/lordos/themes/<id>/` (which needs
+root anyway) makes it **appear** in Settings → Appearance → Desktop style (the list only looks for a
+readable `theme.bundle.js`), but choosing it does nothing visible except a notice: the switch is
+refused, `lord-server` reloads the theme it was on (`switch_theme`), the session shows the sticky
+notification "This LordOS component was modified and was not loaded" naming the file
+(`sdk/codesig.js`), and choosing it again in that session does nothing (`ui.theme_failed`). Because `theme` was already
+saved in the settings, the same happens once at every login. **Do not** try to make it load by
+regenerating the installed manifest: on a release build an unsigned or changed manifest invalidates
+all of LordOS's code and leaves only the recovery screen.
+
+A bundle outside the LordOS folder (for example `lord-server --theme /home/me/x/theme.bundle.js`)
+is run only when the state is "development" (a development build with no manifest or an unsigned
+one), logged as `code: … loaded unchecked (outside …, development build)`; otherwise it is refused
+with "not part of LordOS's system code".
+
+**Third-party themes can't run on release builds today.** That is deliberate for now: a theme is not
+sandboxed. It runs inside `lord-server`, in the same JavaScript context as every native app, with
+the whole `lord.*` API of the session (files, the terminal, the network, administrator requests),
+and it sees the desktop's keyboard and pointer input. It also carries its own copy of the SDK,
+including the code that shows the permission prompts and records the answers (`lord.perms.set`,
+`server/src/ui/js_sec.c`), so a theme decides what those prompts do. Supporting
+them would need, at least: a theme package format and a separate, user-confirmed trust decision
+(signed like `.lpk` packages, [SIGNING.md](SIGNING.md), not the LordOS release key), a place for
+user-installed themes that the code check knows about, and probably a narrower API for theme code
+than what built-in code gets. None of that exists yet.
+
+## 4. Installing and testing
+
+**Where themes live.** Installed: `/usr/lib/lordos/themes/<id>/` (`theme.json`, `theme.bundle.js`,
+`assets/`), next to `/usr/lib/lordos/code-manifest.json`; the development VMs also use
+`/usr/local/lib/lordos` ([VM-SETUP.md](VM-SETUP.md), step 22). The list of themes is the folder that
+holds the running theme's folder (`themes_root` in `js_sys.c`); there is no per-user themes folder.
+
+**Trying one in a development session** (a development build of `lord-server`, see the table
+above):
+
+1. Put the theme in `themes/<id>` of your LordOS tree and run `node tools/build-theme.mjs <id>` (or
+ `npm run build`).
+2. Copy the tree to the VM and build `lord-server` as in [VM-SETUP.md](VM-SETUP.md), step 6 (`themes/`
+ and `assets/` with `server/`). Copy `code-manifest.json` too, or none at all: a stale manifest
+ refuses the new bundle.
+3. Start it and choose the theme in **Settings → Appearance → Desktop style**. Passing
+ `--theme ../themes/<id>/theme.bundle.js` to a standalone `sudo ./build/lord-server` also works,
+ but `startShell` switches to the theme saved in `~/.config/lordos/settings.json` (`"theme"`) if it
+ is another one, so set that too.
+4. After rebuilding, switch to another theme and back (or log out and in) to load the new bundle.
+ There is no hot reload.
+
+A theme that throws while its bundle is evaluated makes the switch fall back to the theme you came
+from (`lord-server: the theme failed, going back to …`); the error is in the log. Keep Lord Flow or
+Lord Classic installed: they are the fallback (`start_theme` in `main.c`).
+
+**Debugging.**
+
+- Sessions started by `lord-sessiond` write their log to **`~/.cache/lordos/session.log`** (the login
+ screen to `greeter.log`); a standalone `lord-server` writes to the terminal it was started from.
+- `console.log`, `.info`, `.debug` → `js: …` lines; `console.warn` → `js: [warn] …`;
+ `console.error` → `js: [error] …` (the prelude in `server/src/ui/js.c`). Exceptions in timers
+ and animation frames are logged as `js: [error] timer: …` / `raf: …`.
+- Useful lines: `js: theme <path> loaded in N ms (K KB)`, `code: …` (the verified-code state and each
+ check or refusal), `lord-server: cambiando a tema <path>` (a switch), `js: unsupported style '<key>'`.
+- `sudo /usr/lib/lordos/bin/lord-server --check-code [<folder>]` checks a whole tree the way a session
+ would; `lord-server --debug` and `--profile` (per-primitive timings) for drawing problems.
+- `lord.getLayout(node.id)` returns `[x, y, w, h]` of a node (both themes use it to place menus).
+
+## 5. Checklist before sharing a theme
+
+Check each item on a real session and take a screenshot ([VM-SETUP.md](VM-SETUP.md), `screendump`):
+
+- **Both kinds of window:** LordOS apps (the Terminal for a transparent one, Settings, Files) and
+ Linux apps with and without their own frame (`args.csd`), including the window menu from a right
+ click on an app's own bar, and an app opening at the size it asked for (`chrome`).
+- **Menus:** every app's menus are reachable (`useAppMenus`), the Window menu works, menus never open
+ under the Dock or off screen.
+- **Light and dark**, every accent, transparency on and off.
+- **Right to left:** with the Arabic test pack (`docs/packs/lordos-lang-ar.json`): rows mirrored,
+ `textAlign: 'start'`, menus opening inwards, mouse-driven pieces in `direction: 'ltr'`.
+- **Translations:** no hard-coded text; en, es and pt at least; long translations truncate with an
+ ellipsis instead of overflowing.
+- **Accessibility:** readable contrast of `text` and `textDim` on `windowBg`, `sidebarBg` and your
+ bars in both modes; reduce motion respected; everything opened from the keyboard can be closed
+ with Escape; targets big enough to hit with a touchpad.
+- **Several displays:** wallpaper on each, the work area right on each, maximize on a second display,
+ a display unplugged and plugged back, mirror mode; and a single display at 150 % scale.
+- **The work area follows the bar and the Dock** (position, size, auto-hide) live.
+- **Performance:** dragging and resizing stay smooth with your blur; nothing re-renders per frame
+ when idle (no `requestAnimationFrame` loop left running).
+- **Theme switch both ways** with windows open: they come back in your theme, and back in Lord Flow.
+- **The login and lock screen** are the system's (`themes/greeter`): nothing in your theme should
+ try to imitate them.
+- **Notifications, search, permission prompts and the power dialog** look right inside your
+ `ThemeProvider` (they use your tokens).
+- And the [DESIGN.md](DESIGN.md#robustness-checklist) robustness checklist.
diff --git a/examples/theme-minimal/README.md b/examples/theme-minimal/README.md
new file mode 100644
index 0000000..742bb8e
--- /dev/null
+++ b/examples/theme-minimal/README.md
@@ -0,0 +1,44 @@
+# Minimal: an example LordOS theme
+
+A deliberately small theme that shows every piece a LordOS theme needs, for the guide
+[`docs/THEMES-GUIDE.md`](../../docs/THEMES-GUIDE.md):
+
+- `theme.json`: the name and description Settings → Appearance → Desktop style shows;
+- `tokens.js`: the base tokens every app reads (`mode`, `accent`, `text`, `textDim`, `windowBg`,
+ `sidebarBg`, `separator`, `hover`, `control`, `inputBg`), the `accents` map, the wallpapers, and a
+ few keys of its own (`titleBg`, `windowBorder`, `barBg`, `blur`, `shadow`);
+- `index.jsx`: the work area (`configureWindows`), a window frame built on `<WindowShell>` and
+ `<AppHost>` (moving and resizing in C), Linux windows that draw their own frame (`args.csd`) and
+ their window menu, a bar in the `dock` layer with an apps menu, one button per window and a clock,
+ menus in the `popover` layer built from the SDK's item lists (`useAppMenus`, `windowMenuItems`),
+ the power confirmations, desktop widgets, a wallpaper per display, and `startShell`.
+
+It has no text of its own: every label is an existing key of the `shell` catalog
+(`shell.menu.apps`, `shell.menu.settings`, `shell.menu.logout`, `shell.menu.window`,
+`shell.classic.minimize`, `shell.classic.maximize`, `shell.classic.restore`, `shell.classic.close`),
+so it is translated into every language LordOS ships. A theme with new text adds its own catalog (see
+the guide, "Translations").
+
+## Building it
+
+Themes are built from the `themes/` folder of a LordOS development tree; `tools/build-theme.mjs`
+has no option for a theme elsewhere. Copy this folder in and build only it:
+
+```sh
+cp -R examples/theme-minimal themes/minimal
+node tools/build-theme.mjs minimal # → themes/minimal/theme.bundle.js (about 1.8 MB)
+```
+
+The build also rewrites `code-manifest.json` with the new bundle in it (and removes a
+`code-manifest.sig` that no longer matches). That is what lets a development build of lord-server
+load it; a release build will not (see the guide, "Verified code: what happens to a theme that
+LordOS did not sign").
+
+`themes/minimal` is a copy for your own tree: don't commit it to LordOS.
+
+## Status
+
+Built with the repository's own tooling (`node tools/build-theme.mjs minimal`, esbuild 0.24.2) on
+2026-10-26 in a copy of the tree, where `node tools/i18n-check.mjs` also passed with it in `themes/`.
+**Not yet run on a LordOS session**: there is no screenshot of it,
+so treat it as a starting point and check it with the guide's checklist.
diff --git a/examples/theme-minimal/index.jsx b/examples/theme-minimal/index.jsx
new file mode 100644
index 0000000..f1130d7
--- /dev/null
+++ b/examples/theme-minimal/index.jsx
@@ -0,0 +1,199 @@
+// "Minimal" — an example LordOS theme (docs/THEMES-GUIDE.md). It is deliberately small: a bar at
+// the bottom of the main display with an apps menu, one button per open window and a clock; a plain
+// window frame; menus from the SDK's item lists. Everything an app needs from a theme is here
+// (tokens, frames, both kinds of window, the work area, layers); the polish of the bundled themes
+// (themes/default, themes/classic) is not.
+//
+// tokens.js the colors (the contract with the apps) and this theme's own keys
+// index.jsx this file: work area, window frame, bar, menus, startShell
+import {
+ startShell, View, Text, Image, Layer, ScrollView, ThemeProvider, useSettings, useWindows, configureWindows, getApp, wm, AppHost,
+ WindowShell, windowTitle, windowIcon, useAppMenus, windowMenuItems, useLauncherApps, launchApp, DesktopWidgets, PowerDialog,
+ findWallpaper, wallpaperSrc, mainDisplay, screenDisplays, screen, useClock, formatTime, solidOver, session, t as tr,
+} from '@lordos/sdk';
+import { apps } from '@lordos/apps';
+import { useState } from 'react';
+import { makeTheme } from './tokens.js';
+
+const BAR_H = 40;
+const TITLE_H = 32;
+
+// The free area for windows on each display: the bar takes the bottom of the main one; the other
+// displays are all work area (docs/DISPLAYS.md). Maximized and new windows use it.
+const workAreaFor = (d) => (d.main ? { x: d.x, y: d.y, w: d.w, h: d.h - BAR_H } : { x: d.x, y: d.y, w: d.w, h: d.h });
+
+// chrome: what the frame adds around the content (1 px borders and the title bar), so Linux windows
+// open at the size they ask for.
+configureWindows({ apps, workArea: workAreaFor, chrome: { w: 2, h: TITLE_H + 2 } });
+
+// A menu from the SDK's item lists ([{ label, onClick, hint, disabled, checked, submenu, header } | '-'],
+// as useAppMenus, windowMenuItems and dockMenu return them). A submenu is shown inline under its
+// label, to keep the example short. at: { x, y } where it opens, or { x, bottom } to open upwards.
+function Menu({ t, at, items, onClose }) {
+ const W = 240;
+ const flat = [];
+ const add = (list) => {
+ for (const it of list || []) {
+ if (it && it !== '-' && it.submenu) { flat.push({ label: it.label, header: true }); add(it.submenu); flat.push('-'); } else flat.push(it);
+ }
+ };
+ add(items);
+ // rows are 26 px and separators 9 px: a long list (every installed app) scrolls
+ const h = Math.min(flat.reduce((n, it) => n + (it === '-' || it == null ? 9 : 26), 0), screen.height - 140);
+ const left = Math.max(8, Math.min(at.x, screen.width - W - 8));
+ const place = at.bottom != null ? { bottom: at.bottom } : { top: Math.max(8, Math.min(at.y, screen.height - h - 20)) };
+ return (
+ <Layer name="popover">
+ {/* a click anywhere outside closes it */}
+ <View onMouseDown={onClose} style={{ position: 'absolute', left: 0, top: 0, right: 0, bottom: 0 }} />
+ <View onMouseDown={(e) => e.stopPropagation()}
+ style={{ position: 'absolute', left, ...place, width: W, padding: 5, borderRadius: t.menuRadius, backgroundColor: t.popupBg || t.windowBg,
+ border: `1px solid ${t.windowBorder}`, boxShadow: t.shadow }}>
+ <ScrollView style={{ height: h }}>
+ {flat.map((it, i) => (it === '-' || it == null
+ ? <View key={i} style={{ height: 1, marginVertical: 4, backgroundColor: t.separator }} />
+ : <MenuItem key={i} t={t} item={it} onClose={onClose} />))}
+ </ScrollView>
+ </View>
+ </Layer>
+ );
+}
+
+function MenuItem({ t, item, onClose }) {
+ const [hover, setHover] = useState(false);
+ const off = item.disabled || item.header;
+ return (
+ <View onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}
+ onClick={() => { if (off) return; onClose(); item.onClick?.(); }}
+ style={{ flexDirection: 'row', alignItems: 'center', height: 26, paddingHorizontal: 8, borderRadius: t.menuItemRadius,
+ backgroundColor: hover && !off ? t.accent : 'transparent' }}>
+ <Text style={{ width: 16, fontSize: 12, color: hover && !off ? '#ffffff' : t.text }}>{item.checked ? '✓' : ''}</Text>
+ <Text style={{ flex: 1, fontSize: 13, textAlign: 'start', whiteSpace: 'nowrap', textOverflow: 'ellipsis',
+ fontWeight: item.header ? 600 : 400, color: hover && !off ? '#ffffff' : off ? t.textDim : t.text }}>{item.label}</Text>
+ {item.hint ? <Text style={{ fontSize: 12, color: hover && !off ? '#ffffff' : t.textDim }}>{item.hint}</Text> : null}
+ </View>
+ );
+}
+
+function FrameButton({ t, label, onClick }) {
+ const [hover, setHover] = useState(false);
+ return (
+ <View onMouseDown={(e) => e.stopPropagation()} onClick={onClick} onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}
+ style={{ height: 22, paddingHorizontal: 8, borderRadius: t.controlRadiusSmall, justifyContent: 'center', backgroundColor: hover ? t.hover : 'transparent' }}>
+ <Text style={{ fontSize: 12, color: t.text, whiteSpace: 'nowrap' }}>{label}</Text>
+ </View>
+ );
+}
+
+// One window. Moving and resizing happen in C (WindowShell's edges, wm.beginMove): React gets no
+// event per frame. A Linux window with its own decorations (args.csd) gets only the content.
+function Window({ t, win, focused }) {
+ const app = getApp(win.id);
+ const menus = useAppMenus(win.id) || [];
+ const [menu, setMenu] = useState(null);
+ const border = focused ? t.windowBorder : t.separator;
+ const items = [...menus.map((m) => ({ label: m.label, submenu: m.items })), { label: tr('shell.menu.window'), submenu: windowMenuItems(win.id) }];
+
+ if (win.args?.csd) {
+ // the app draws its own bar; a right click on it asks for the window menu (win.windowMenu)
+ return (
+ <WindowShell win={win} onMouseDown={() => wm.focus(win.id)} style={{ boxShadow: t.shadow }}>
+ <AppHost id={win.id} focused={focused} />
+ {win.windowMenu && <Menu t={t} at={win.windowMenu} items={windowMenuItems(win.id)} onClose={() => wm.closeWindowMenu(win.id)} />}
+ </WindowShell>
+ );
+ }
+ const Icon = windowIcon(win);
+ return (
+ <WindowShell win={win} onMouseDown={() => wm.focus(win.id)} style={{
+ borderRadius: win.maximized ? 0 : 8, overflow: 'hidden', boxShadow: focused ? t.shadow : undefined,
+ backgroundColor: app?.transparent ? 'transparent' : t.windowBg,
+ // a transparent app (the Terminal) has nothing behind its border: draw it already mixed
+ border: `1px solid ${app?.transparent ? solidOver(border, t.titleBg) : border}`,
+ }}>
+ <View onMouseDown={(e) => { if (!e.button) wm.beginMove(win.id); }} onDoubleClick={() => wm.toggleMaximize(win.id)}
+ onContextMenu={(e) => setMenu({ x: e.x, y: e.y })}
+ style={{ height: TITLE_H, flexDirection: 'row', alignItems: 'center', gap: 8, paddingStart: 10, paddingEnd: 4,
+ backgroundColor: t.titleBg, borderBottom: `1px solid ${t.separator}` }}>
+ {Icon ? <Icon size={16} /> : null}
+ <Text style={{ flex: 1, fontSize: 12, fontWeight: 500, textAlign: 'start', whiteSpace: 'nowrap', textOverflow: 'ellipsis',
+ color: focused ? t.text : t.textDim }}>{windowTitle(win)}</Text>
+ <FrameButton t={t} label={tr('shell.classic.minimize')} onClick={() => wm.minimize(win.id)} />
+ <FrameButton t={t} label={tr(win.maximized ? 'shell.classic.restore' : 'shell.classic.maximize')} onClick={() => wm.toggleMaximize(win.id)} />
+ <FrameButton t={t} label={tr('shell.classic.close')} onClick={() => wm.close(win.id)} />
+ </View>
+ <View style={{ flex: 1 }}><AppHost id={win.id} focused={focused} /></View>
+ {menu && <Menu t={t} at={menu} items={items} onClose={() => setMenu(null)} />}
+ </WindowShell>
+ );
+}
+
+// The bar: apps menu at the start, the windows, the clock at the end. The row flips by itself in a
+// right-to-left language.
+function Bar({ t, windows, focused, onApps }) {
+ const m = mainDisplay();
+ const clock = useClock((d) => formatTime(d), 1000);
+ const own = windows.filter((w) => !(getApp(w.id)?.builtin && !String(w.id).startsWith('linux#')));
+ return (
+ <View style={{ position: 'absolute', left: m.x, top: m.y + m.h - BAR_H, width: m.w, height: BAR_H, flexDirection: 'row', alignItems: 'center',
+ gap: 4, paddingHorizontal: 6, backgroundColor: t.barBg, backdropFilter: t.blur ? `blur(${t.blur}px)` : undefined,
+ borderTop: `1px solid ${t.separator}` }}>
+ <FrameButton t={t} label={tr('shell.menu.apps')} onClick={onApps} />
+ <View style={{ flex: 1, flexDirection: 'row', gap: 4, overflow: 'hidden' }}>
+ {own.map((w) => {
+ const Icon = windowIcon(w);
+ const front = w.id === focused;
+ return (
+ <View key={w.id} onClick={() => (front ? wm.minimize(w.id) : wm.focus(w.id))}
+ style={{ maxWidth: 200, height: 30, flexDirection: 'row', alignItems: 'center', gap: 6, paddingHorizontal: 8, borderRadius: t.controlRadius,
+ backgroundColor: front ? t.hover : 'transparent', borderBottom: `2px solid ${front ? t.accent : 'transparent'}` }}>
+ {Icon ? <Icon size={18} /> : null}
+ <Text style={{ fontSize: 12, color: w.minimized ? t.textDim : t.text, whiteSpace: 'nowrap', textOverflow: 'ellipsis' }}>{windowTitle(w)}</Text>
+ </View>
+ );
+ })}
+ </View>
+ <Text style={{ fontSize: 13, color: t.text, paddingHorizontal: 8 }}>{clock}</Text>
+ </View>
+ );
+}
+
+function App() {
+ const [s] = useSettings();
+ const t = makeTheme(s);
+ const { windows, visible, focused } = useWindows();
+ const launcher = useLauncherApps();
+ const [appsMenu, setAppsMenu] = useState(null);
+ const m = mainDisplay();
+ const wallpaper = findWallpaper(t.wallpapers, s.wallpaper);
+ const appItems = [
+ ...launcher.map((a) => ({ label: a.name, onClick: () => launchApp(a.id) })),
+ '-',
+ { label: tr('shell.menu.settings'), onClick: () => wm.open('settings') },
+ { label: tr('shell.menu.logout'), onClick: () => session.quit() },
+ ];
+ return (
+ <ThemeProvider tokens={t}>
+ <View style={{ width: '100%', height: '100%', backgroundColor: t.mode === 'dark' ? '#111114' : '#d5d9e0' }}>
+ {/* a wallpaper per display, at that display's pixel size */}
+ {screenDisplays().map((d) => (
+ <Image key={d.id + ':' + d.x} src={wallpaperSrc(wallpaper, d.w * (d.scale || 100) / 100, d.h * (d.scale || 100) / 100)}
+ style={{ position: 'absolute', left: d.x, top: d.y, width: d.w, height: d.h, objectFit: 'cover' }} />
+ ))}
+ <DesktopWidgets layer="below" />
+ {visible.map((w) => <Window key={w.id} t={t} win={w} focused={w.id === focused} />)}
+ <DesktopWidgets layer="above" />
+ <Layer name="dock">
+ <Bar t={t} windows={windows} focused={focused} onApps={() => setAppsMenu((v) => (v ? null : { x: m.x + 6, bottom: screen.height - (m.y + m.h - BAR_H) + 6 }))} />
+ </Layer>
+ {appsMenu && (
+ <Menu t={t} at={appsMenu} onClose={() => setAppsMenu(null)} items={appItems} />
+ )}
+ {/* Restart… and Shut Down… confirmations (sdk/power.jsx) */}
+ <Layer name="modal"><PowerDialog /></Layer>
+ </View>
+ </ThemeProvider>
+ );
+}
+
+startShell(<App />);
diff --git a/examples/theme-minimal/theme.json b/examples/theme-minimal/theme.json
new file mode 100644
index 0000000..a33b4af
--- /dev/null
+++ b/examples/theme-minimal/theme.json
@@ -0,0 +1,4 @@
+{
+ "name": "Minimal",
+ "description": "An example theme: a bottom bar with an apps menu, the open windows and a clock."
+}
diff --git a/examples/theme-minimal/tokens.js b/examples/theme-minimal/tokens.js
new file mode 100644
index 0000000..b514f44
--- /dev/null
+++ b/examples/theme-minimal/tokens.js
@@ -0,0 +1,41 @@
+// Tokens of the "Minimal" example theme. The base keys (mode … inputBg) are the contract with the
+// apps (sdk/theme.js, docs/THEMES-GUIDE.md "tokens.js"); every app reads them through useTheme().
+// The keys after "This theme's own" are used only by this theme's frame and bar.
+import { lordosWallpapers } from '@lordos/sdk';
+
+// The same names as the bundled themes' accents, so the user's choice in Settings → Appearance
+// survives a theme switch (Settings shows these swatches).
+export const accents = {
+ azul: '#3478f6',
+ violeta: '#9b5de5',
+ rosa: '#e5487f',
+ naranja: '#f08c2e',
+ verde: '#2fb171',
+ grafito: '#7d7d85',
+};
+
+export function makeTheme({ mode, accent, effects }) {
+ const dark = mode === 'dark';
+ return {
+ mode,
+ accent: accents[accent] || accents.azul,
+ accents,
+ wallpapers: lordosWallpapers,
+ text: dark ? '#f2f2f5' : '#1c1c21',
+ textDim: dark ? 'rgba(242,242,245,0.58)' : 'rgba(28,28,33,0.6)',
+ windowBg: dark ? '#1e1e22' : '#fcfcfd',
+ sidebarBg: dark ? '#242429' : '#f2f2f5',
+ separator: dark ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.08)',
+ hover: dark ? 'rgba(255,255,255,0.07)' : 'rgba(0,0,0,0.05)',
+ control: dark ? '#34343a' : '#e6e6eb',
+ inputBg: dark ? '#28282d' : '#ffffff',
+ // GTK apps put their buttons on the right, like this frame
+ gtkButtons: ':minimize,maximize,close',
+ // This theme's own:
+ titleBg: dark ? '#26262b' : '#ededf0',
+ windowBorder: dark ? 'rgba(255,255,255,0.12)' : 'rgba(0,0,0,0.14)',
+ barBg: dark ? (effects !== false ? 'rgba(28,28,32,0.82)' : '#1c1c20') : (effects !== false ? 'rgba(244,244,247,0.85)' : '#f1f1f4'),
+ blur: effects !== false ? 20 : 0,
+ shadow: dark ? '0 12px 32px rgba(0,0,0,0.5)' : '0 12px 32px rgba(0,0,0,0.2)',
+ };
+}
diff --git a/server/src/main.c b/server/src/main.c
index 2e062f6..ab0d7db 100644
--- a/server/src/main.c
+++ b/server/src/main.c
@@ -1540,7 +1540,9 @@ static int check_code(int argc, char **argv) {
return bad ? 1 : 0;
}
-static void switch_theme(const char *current) {
+/* 0 if the requested theme is running; -1 if it failed and `current` (the last one that loaded) was put
+ * back: the caller keeps `current` then, so a second failed switch never falls back to a refused theme */
+static int switch_theme(const char *current) {
char path[sizeof ui.theme_request];
snprintf(path, sizeof path, "%s", ui.theme_request);
ui.theme_request[0] = 0;
@@ -1553,9 +1555,12 @@ static void switch_theme(const char *current) {
snprintf(ui.theme_failed, sizeof ui.theme_failed, "%s", path);
js_shutdown();
ui_reset();
- js_init(current);
+ if (js_init(current)) fprintf(stderr, "lord-server: %s did not load again either\n", current);
+ wl_remap_all();
+ return -1;
}
wl_remap_all(); /* Linux app windows stay connected: they come back in the new theme */
+ return 0;
}
/* ---- Settings → Displays and the other hardware pages (src/hw, docs/SETTINGS.md) ---- */
@@ -1765,8 +1770,7 @@ int main(int argc, char **argv) {
if (ui.theme_request[0]) {
char next[sizeof current];
snprintf(next, sizeof next, "%s", ui.theme_request);
- switch_theme(current);
- snprintf(current, sizeof current, "%s", next);
+ if (!switch_theme(current)) snprintf(current, sizeof current, "%s", next);
}
/* El movimiento del puntero juntado: una vez por cuadro, cuando terminó el page flip. Así un
* mouse de 1000 Hz no llama a JS (ni a las apps Linux) mil veces por segundo. */
diff --git a/themes/README.md b/themes/README.md
index 3ebf816..1f188d2 100644
--- a/themes/README.md
+++ b/themes/README.md
@@ -14,12 +14,17 @@ npm install # once (React + esbuild)
npm run build # bundles every theme, with the SDK and every app
```
-The user switches themes live from **Settings → Appearance → Desktop style** (Lord Flow and
-Lord Classic) or **Settings → Themes** (any installed theme), with no restart: the LordOS app windows that
-were open come back in the new theme. The choice is saved and respected on the next start.
+The user switches themes live from **Settings → Appearance → Desktop style**, which lists every
+installed theme (since 0.8.5 there is no separate Themes page), with no restart: the LordOS app
+windows that were open come back in the new theme. The choice is saved and respected on the next start.
## Creating a new theme
+The full guide, for a React developer new to LordOS, is [`docs/THEMES-GUIDE.md`](../docs/THEMES-GUIDE.md)
+(anatomy, the token contract, frames, menus, layers, building, the verified-code check, testing and
+a checklist); a small starting point is [`examples/theme-minimal/`](../examples/theme-minimal/).
+Note that a theme LordOS did not sign only loads on a development build (see the guide). In short:
+
1. Copy `themes/classic` to `themes/mytheme` (`index.jsx` puts the pieces together; the frame,
taskbar and panels are in `components/`, the colors and shape tokens in `tokens.js`).
2. Edit `theme.json` (the name and description Settings shows).
@@ -60,7 +65,7 @@ were open come back in the new theme. The choice is saved and respected on the n
When such an app asks for the window menu (right click on its own bar), `win.windowMenu` is
`{ x, y }`: draw the theme's window menu there and call `wm.closeWindowMenu(win.id)` when it
closes.
-4. `npm run build` and pick it in Settings → Themes.
+4. `npm run build` and pick it in Settings → Appearance → Desktop style.
Images (`<Image src="assets/...">`) are resolved relative to the theme's folder.