Assets
The main JSON UI resources of system super are concentrated in the Shell directory, organized as constants + screens + flows + templates.
Overview
The Shell resource directory structure:
resource/shell/root.json: the single Shell app entry, loading constants, generatedimageSetdescriptors, screens, flows, and templates.resource/shell/constants/*.json: default and resolution-override tokens.resource/shell/screens/*.json: the Background, Home, App Launcher, Notifications, Overlay, and keyboard input screens.resource/shell/flows/*.json: thescreenFlowassets for background, content pages, and overlay.resource/shell/templates/*.json: dynamic instance templates.resource/themes/*.json: Runtime theme descriptors, loaded by ShellApp at startup, not written intoroot.json.assets.resource/startup/root.json: the boot screen mounted by system core toSystemTopbefore the Shell loads.
The source images live under assets/shell/images/**. At build time, CMake first stages resource/ verbatim to the runtime resource root, then converts the images under assets/ with brookesia_gui_lvgl_pack_images() into LVGL .bin + imageSet index.json: PNG outputs as ARGB8888 and JPG/JPEG outputs as RGB565, and the generated files are not committed to the source directory.
Constants Namespaces
Constants use ui as the internal Shell token namespace:
Namespace |
Purpose |
|---|---|
|
Light semantic colors such as surface, border, accent, status colors, and overlay-specific colors |
|
Shared metrics that need explicit reference, such as page title, caption, and card corner radius |
|
Content page sizes such as the work area, launcher grid, chip, and search |
|
The status bar, gesture indicator, and overlay animation sizes |
Common visuals such as the default font, base text color, transparent screen/container background, and default borders of button/text input are provided by resource/themes/*.json; constants are reserved for semantic colors, font sizes, and layout sizes that need explicit reference in specific nodes.
Runtime Themes
A theme descriptor is a global Runtime resource, not a Shell document asset. ShellApp scans all *.json in the first level of <system-root>/super/themes at startup, loads them sorted by file name, and sets the default theme to shell.light. The current V1 provides light.json (shell.light) and dark.json (shell.dark). Shell screens reference named styles such as shell.card, shell.pageTitle, and shell.navButton through styleRefs; an explicit node style takes precedence. Do not write resource/themes/*.json into the assets of root.json; the JSON UI parser rejects the document asset type theme.
Shell Root
The Shell root defines the Shell background screens, content pages, overlay, and launcher button template. Key nodes:
Node or Template |
Path or Id |
C++ Constant |
|---|---|---|
Desktop background screen |
|
|
App background screen |
|
JSON screen id |
Home Dashboard screen |
|
|
App Launcher screen |
|
|
Notifications screen |
|
|
overlay screen |
|
|
keyboard input screen |
|
|
status bar |
|
|
status Wi-Fi |
|
|
status clock |
|
|
gesture indicator |
|
|
summary label |
|
|
launcher grid |
|
|
launcher button template |
|
|
A dynamic instance uses the instance id prefix app_ and the path prefix /launcher/content/grid/app_. A valid tap on the launcher button root starts an app through the action super.launch.app (SUPER_ACTION_LAUNCH_APP).
Screen Flows
The Shell root references 3 flows: flows/background.json manages /background (mounted to SystemBottom); flows/shell_pages.json manages Home / App Launcher / Notifications (mounted to AppDefault); flows/overlay.json manages /overlay (mounted to AppTop with Stack and z_order = 101). The state id of shell_pages uses the top-level screen id directly, and the navigation bar actions serve as flow transition actions:
Action |
Target Screen |
|---|---|
|
|
|
|
|
|
The Shell manifest auto-starts the shell_pages flow, and subsequent page switching only triggers the flow, without manual unmount/mount of content screens.
Startup Overlay
resource/startup/root.json is a standalone lightweight JSON UI root, loaded by system_core after the GUI runtime is created and before the Shell and app scan, and mounted to SystemTop through a transient screen to avoid a long blank screen during ESP-side file parsing, resource registration, and Shell initialization. The default screen path is /startup, and the root file path can be changed via Super Kconfig or PC CMake config.
Background Screens
The background flow is the bottom background state machine in the Shell root. /background is the Shell desktop image background, and /app_background is the solid background when a regular app is in front. At runtime the Shell manifest mounts the background flow to SystemBottom: it switches to /background when the Shell is in front and to /app_background when a regular app is in front. Content pages still mount to the app layer and the overlay still mounts to the top of the AppTop stack, so there is no need to repeat the background node in each content screen.
Keyboard Input
Keyboard input is the on-demand transient screen /keyboard_input in the Shell root, not part of any Shell screenFlow. When an app requests the system keyboard, ShellApp shows it through a transient mount to the top of the AppTop stack with a higher z-order than the overlay. The screen contains a full-screen mask, a single-line textInput, and a keyboard; abc / ABC / 123 / ,.?!, confirm, and cancel are embedded in the keyboard key layout. The keyboard layout is described by keyboardProps.layouts for the text / upper / number / special layouts, mapped by the backend to the LVGL keyboard map, with disallowed mode switch keys disabled by allowedModes. Key actions include super.keyboard.text_changed, super.keyboard.submit.*, super.keyboard.cancel.*, and super.keyboard.toggle_password.
Modification Notes
If you change a JSON node id, template id, screen path, or action string, you must sync the corresponding constant in src/private/system_constants.hpp.