LumaUI
What LumaUI is, what it draws, how its C library, Python package and LumaSemantics-1 divide the work, which to use from which language, and the rules every app follows.
LumaUI is Luma’s app toolkit. It is Luma’s own layer on stock GTK 4, not a fork of GTK: GTK is the engine underneath and handles rendering, input and accessibility. LumaUI owns everything a person sees in a Luma app.
Who draws what
There are two parties, and the line between them does not move.
LumaUI draws the whole visible app. The window frame and its elevation, the 46px title row, the identity in the top-left corner (your app’s name and icon from its desktop entry, with its menu), the window controls, the 8px gutter, every island, and every component inside them: toolbars, buttons, sidebars, fields, menus, dialogs, toasts and empty states. It also owns the design tokens, motion, and how each part adapts at phone width.
Your app composes those parts and draws only its own content: a canvas, a document, a timeline, a photo.
Apps say what they need through semantic APIs (“a count that needs attention”, “ask before deleting this”), and LumaUI decides how it looks. When the LumaUI design changes, every Luma app gets the change without editing the app.
The pieces
| Piece | Use it from | What it gives you | Reference |
|---|---|---|---|
LumaUI for Python (luma_appkit) |
Python | The whole toolkit: windows, islands, commands, menus, navigation, controls and every LumaUI part | Python reference |
LumaUI-1 |
C, C++, and GObject introspection | The window, islands, adaptive scaffold and the LumaUI parts in C | LumaUI-1 reference, LumaUI for C |
LumaSemantics-1 |
C, C++, and introspection; Python dataclasses in the SDK | Semantic objects, actions, risk, privacy, Live Extensions | Semantics and actions |
luma command |
Your terminal and CI | Project creation and contract checks | The luma command |
LumaUI’s Python package is luma_appkit. It uses LumaUI-1 and
LumaAppearance-1 through introspection, so a Python app needs the platform
package installed, not a copy of the toolkit.
Topics
- LumaUI principles: why LumaUI exists, the semantic-API rule, who owns what, and the API level and deprecation policy.
- LumaUI behaviour: hover, press, focus, keyboard, motion, auto-close and reduced motion for every part.
- Windows and islands: the window contract, the body, islands, split views, and what your stylesheet may not declare.
- Commands and menus: one command model for the identity menu, context menus, shortcuts and semantics.
- Adaptive layouts: width, presentation and input, and how one app works from 360px to a wide desktop.
- Background agents: keep your app working when its windows are closed, with wakes, published values, schedules and the Background portal.
- Semantics and actions: stable action IDs, risk and privacy, the Semantic Broker, Live Extensions.
Rules every app follows
- One source tree and one binary across every Luma presentation.
- Width changes layout; it never identifies a device.
- Presentation mode controls chrome, independently of width.
- Input capability controls target sizes and affordances, independently of both.
- Compact layouts keep every function, moving actions into navigation, sheets or overflow.
- Every custom widget sets GTK accessible names, roles and relationships.
- Each meaningful operation has one stable action ID, shared by its button, menu item, shortcut, accessibility action and semantic action.
- Secrets never appear in a semantic object or Live Extension.
- Third-party code never renders inside the shell.
- Colors come from tokens. A literal color in an app stylesheet is a defect.
Use the installed toolkit; do not copy it
Build against the installed platform: pkg-config luma-ui-1 for C and C++, the
installed luma_appkit package for Python. A copy of LumaUI’s source or
stylesheets inside your repository is a fork, and forks drift. If LumaUI cannot
express something you need, ask for the component rather than drawing a local
imitation; see the FAQ.
Stability
The platform is a 0.x preview. The C libraries use the -1 namespace so
that 1.0 can stabilize without breaking the name, but the 0.x ABI is not
stable. The Python package’s public names are those in luma_appkit.__all__;
anything starting with an underscore is private. Pin the platform release you
tested against and read the changelog before moving.
In this section
- LumaUI Python referenceLumaUI's Python package, luma_appkit: its public classes and functions, with their purpose, constructors, properties, signals and methods as they exist in platform 0.1.0.
- LumaUI-1 referenceLumaUI's C library, LumaUI-1: initialization, the window, islands, the adaptive scaffold, context and the media and imaging controls, with properties, signals and introspection names, as they exist in platform 0.1.0.
- Windows and islandsThe anatomy of a Luma window, how the title row, identity, body and islands fit together, common island arrangements, and what your stylesheet must never declare.
- Commands and menusOne command model drives the identity menu, context menus, buttons, shortcuts and semantics. How to define commands, where each menu lives, and the menu rules.
- Semantics and actionsStable action IDs, risk and privacy classes, semantic objects, publishing to the Semantic Broker, how other apps get access, and Live Extensions.
- Adaptive layoutsHow one Luma app adapts from a 360px phone to a wide desktop using width breakpoints, LumaUI's width tiers, presentation mode and input mode, with the required test widths and common patterns.
- Background agentsKeep your app working when its windows are closed. Declare a small background agent, handle wakes, publish values for Live Extensions and dock badges, schedule work, and ask for permission.
- The luma commandReference for the SDK command line, luma new, lint, inspect, test, release-check, live-preview and semantic, with usage, output and exit codes.
- LumaUI principlesWhy LumaUI exists, the semantic-API rule, who owns what between GTK, LumaUI and apps, and how the API is versioned.
- LumaUI behaviourHow LumaUI parts respond, with their motion tokens: hover, press, focus, keyboard, slide in and out, scroll fades, auto-close, reduced motion and phone width.
- LumaUI for CThe LumaUI parts in C (LumaUI-1), each next to its Python twin, the rules they share, and how to build a C or C++ app against them.