Research IBM Carbon desktop strategy for VoidKontrol

2026-09-21 05:06:57 +00:00
1 changed files with 278 additions and 0 deletions
@@ -0,0 +1,278 @@
 # IBM Carbon desktop UI strategy for VoidKontrol
 Research date: 2026-09-21. Decision input for
 [Establish a faithful IBM Carbon desktop UI strategy for Void Linux](https://git.bongbetic.com/xavierk/voidkontrol/issues/4).
 This report recommends a direction and records evidence; it does not select the
 final stack, establish hardware support, or provide a prototype.
 ## Recommendation
 Evaluate **official Carbon React in an unprivileged Tauri desktop application**
 first. It combines Carbon's maintained component implementation with Void's
 packaged GTK3/WebKitGTK stack and leaves the device service responsible for all
 hardware control. Gate selection on a small native-Wayland, accessibility, and
 packaging proof on the actual supported Void targets. This is an architectural
 recommendation, not a completed compatibility test. [C1][T1][T2][V1]
 Electron remains a viable Carbon rendering alternative if the project accepts
 owning a maintained Electron distribution/update route. Do not base that choice
 on the mere existence of Void's `electron35` source template: the inspected
 template is explicitly marked broken. A QML main application can implement Carbon,
 but it would own a new Carbon implementation instead of consuming IBM's maintained
 React or Web Components libraries. Reserve that extra cost for a demonstrated
 requirement that the webview approach cannot satisfy. [C1][E1][E2][V2][Q1]
 A Noctalia plugin and the full editor have different responsibilities. The full
 editor should use Carbon; the shell plugin should use Noctalia's supported API and
 components and expose a small entry point/status surface. They can share the
 device service without sharing a rendering toolkit. Exact Noctalia API choices
 belong to the separate desktop-integration research.
 ## Existing behavior and boundaries
 The supplied [control specification](../../KREO-SWARM75-LINUX-CONTROL-SPEC.md)
 requires an unprivileged UI, a single service owner for discovery/authentication/
 serialization/readback, a complete backup before the first write, and comparison
 of readback after every update. It prohibits grabbing input devices, detaching
 the kernel driver, and automatic writes on startup/reconnect/resume. Protocol
 payloads and persistence semantics still require authenticated hardware capture.
 The user has chosen verification of the observed USB presentation first and has
 kept firmware flashing and the factory-reset UI outside v1. A GUI library cannot
 close any of those protocol evidence gaps. The display should initially use the
 specification's `Kreo Swarm 75 (signature match)` identification until successful
 authentication; the observed VID/PID does not establish physical layout or
 connection-mode compatibility.
 The repository contains a specification and agent documentation, with no existing
 UI implementation or architecture decision to extend at this research checkout.
 Consequently, the comparisons below do not propose replacing a working stack.
 ## Maintained Carbon support and obligations
 1. Carbon's official developer guide lists **React and Web Components** as
   officially supported. Other web frameworks have community implementations.
   The maintained monorepo includes component styles, design tokens, icons, grid,
   spacing, motion, and typography packages. It does not list an official Qt/QML
   implementation. This is evidence about the supported offerings, not a claim
   that no third-party QML project exists. [C1][C2]
 2. `@carbon/react` supplies components, styles, and icons and requires a frontend
   build pipeline. A static bundled frontend is sufficient for this desktop
   editor; a web server framework is not required by Carbon. Official Web
   Components are a legitimate alternative if the architecture decision finds a
   concrete reason to avoid React; they still require a web rendering engine.
   [C1][C2]
 3. Carbon's themes are `white`, `g10`, `g90`, and `g100`. Use semantic theme,
   spacing, typography, focus, and layer tokens instead of approximate custom
   colors. Offer a supported light/dark choice; use Carbon's layering mechanism
   for nested surfaces. Shell theme synchronization can select a Carbon theme,
   but arbitrary wallpaper colors should not silently replace its contrast and
   semantic color relationships. The latter is a product recommendation. [C3]
 4. Carbon uses IBM Plex. Its current guide recommends per-family packages such
   as `@ibm/plex-sans` and `@ibm/plex-mono`; the legacy monolithic `@ibm/plex`
   package is no longer updated. Bundle the required fonts locally so installed
   operation does not depend on a font CDN. Carbon is Apache-2.0; Plex is SIL
   OFL-1.1 with reserved name `Plex`. Include the applicable notices and license
   texts in the distribution. [C2][C4][C5]
 5. Carbon components follow IBM's accessibility checklist, based on WCAG AA,
   Section 508, and European standards. Carbon explicitly says accessible
   components are only part of an accessible product. Test the assembled product
   in the selected Linux renderer, including screen-reader integration, rather
   than treating component adoption as application certification. [C6]
 ## Desktop choices
 | Choice | Carbon fidelity and ownership | Linux/Void evidence | Decision cost or gate |
 | --- | --- | --- | --- |
 | Carbon React + Tauri | Reuses official components; small native IPC bridge can call the service. | Tauri uses WebKitGTK on Linux; its windowing stack uses GTK3. Wry documents the GTK route for Wayland. Void packages the required GTK3/libsoup3 WebKit 4.1 variant with Wayland enabled. [T1][T2][V1] | Build/runtime dependencies and WebKit behavior depend on the distribution. Test Carbon rendering, AT-SPI/screen reader operation, dialogs, scaling, and window activation on niri. |
 | Carbon React + Electron | Reuses the same official components in bundled Chromium. | Upstream Linux binaries are built on Ubuntu; Electron documents native Wayland selection from version 38 when `XDG_SESSION_TYPE=wayland`. Void's inspected `electron35` template has musl build paths but is marked broken. [E1][E3][V2] | Ships Chromium/Node/Electron updates with the application. Establish a supported runtime distribution, musl route if needed, and package maintenance; the distro template is insufficient proof. |
 | Qt Quick/QML with a custom Carbon style | Uses Qt controls and explicitly recreates Carbon appearance, layout, states, and interactions. | Qt provides native controls, accessibility metadata, and custom styling. Its listed styles do not include Carbon. [Q1][Q2] | Own the custom Carbon component set, visual parity, accessibility behavior, token mapping, and upstream design changes. Similarity to Noctalia's toolkit does not remove this work. |
 A smaller Tauri application bundle would **not** prove a smaller total installed
 system or better memory/startup performance: GTK and WebKit dependencies still
 exist. No benchmark was run. Conversely, Electron's bundled renderer can reduce
 renderer-version variability but creates direct runtime update responsibility;
 Electron supports the latest three stable major releases. [T1][E2]
 ### glibc and musl
 - Upstream Tauri now includes Alpine/musl prerequisites, warning that some static
  dependencies may need source builds. Therefore, a blanket claim that Tauri
  cannot run on musl would be incorrect. Those Alpine instructions are **not a
  Void compatibility result**. [T3]
 - Void's `libwebkit2gtk41` template at
  `954278b83979958bcfdff05f22cf699c9dc20346` is version `2.50.4_1`, enables
  Wayland, defaults to a bubblewrap sandbox, and depends on `xdg-dbus-proxy` when
  that option is enabled. It includes musl-compatible build paths rather than a
  blanket musl prohibition. `libwebkitgtk60` is the GTK4 subpackage; it is not a
  drop-in substitute for Tauri's GTK3 WebKit 4.1 requirement. Package source
  availability alone does not prove a successful application build. [V1][T2]
 - Void's `electron35` template at the same revision is `35.7.2_1`, has
  `x86_64* aarch64*` architecture patterns and `musl-legacy-compat` paths, but is
  marked `broken` because its configure tooling uses `FancyURLopener` removed in
  Python 3.14. This disproves neither all Electron-on-musl possibilities nor the
  possible existence of an older binary package; it does mean that this template
  cannot establish a reproducible, maintained current runtime. [V2]
 - Treat glibc and musl as separate build and runtime targets. A glibc binary or
  AppImage must not be presented as proof of native musl support. Tauri's own
  Linux distribution guidance warns that the build system's libc baseline affects
  compatibility. Which libc and architectures v1 promises remains an architecture
  decision informed by the Void research. [T4]
 ### Security and process boundary
 Both wrappers can preserve the service boundary in the supplied specification.
 Keep packaged UI assets local, render imported names as text, and expose only
 typed domain operations through the desktop bridge. Neither JavaScript nor a QML
 plugin should accept arbitrary HID frames, open `/dev/hidraw*`, run arbitrary shell
 commands, or gain service credentials. The service must independently authorize
 and validate requests; hiding a control is not authorization.
 For Tauri, capability/permission configuration constrains webview-to-core calls,
 while core/plugin code itself has the application's OS privileges. Command
 implementations remain responsible for enforcing scopes. This is a separate
 boundary from the service's own peer authentication and device policy. [T5]
 For Electron, retain renderer sandboxing and context isolation, disable Node
 integration in the renderer, validate IPC sender and arguments, constrain
 navigation, and use a restrictive content-security policy. Its security guidance
 also explicitly assigns responsibility for updating Electron, Chromium, Node, and
 dependencies to the application maintainer. [E4]
 ## Proposed interaction requirements
 These are design recommendations derived from the supplied protocol invariants,
 not additional asserted keyboard capabilities. The service remains authoritative
 for advertised features, verified ranges, physical key identifiers, raw-value
 translation, and transaction state.
 ### Main organization and keyboard accessibility
 Use a compact Carbon application shell with Device, Lighting, Key mapping,
 Macros, Typing and power, and Backups as ordinary navigation destinations. Use
 standard forms for editors and a restrained amount of custom rendering for the
 physical keyboard preview. This is information architecture for later review,
 not a locked wireframe.
 The layout preview should use the authenticated physical layout map and identify
 each key by its position, legend, selected layer, and current assignment. A
 keyboard-accessible list/form view must offer the same selection and editing
 operations. The preview cannot be the only means of choosing a key, and color
 cannot be the only indication of selection, assignment, or errors. A labelled
 hex/RGB input or equivalent text entry should accompany any color picker.
 For layers, Carbon Tabs can expose Base, Fn, Fn1, and Fn2. Carbon supplies arrow-key
 navigation and distinguishes automatic versus manual activation. Choose manual
 activation if changing tabs causes a perceptible read delay; switching the editor
 layer must not itself write settings or claim to change the keyboard's active
 hardware layer. [C7]
 All functionality must be reachable without dragging or mouse-only gestures:
 visible focus, logical tab order, standard activation keys, Escape for transient
 surfaces, and focus restoration after dialogs. Preserve a path out of every custom
 control. Provide move-up/down controls if macro actions are reorderable. Avoid
 stealing ordinary typing or compositor shortcuts just to select physical keys.
 Carbon's accessibility guidance explicitly requires full keyboard access and
 testing beyond automated checks. [C6][C8]
 ### Readback, changes, and failures
 Keep three concepts separate: the last configuration read from the device, the
 user's unapplied edits, and the service's current transaction status. Recommended
 visible states are:
 | Condition | UI behavior |
 | --- | --- |
 | No device, unsupported signature, unavailable service, or permission failure | Show a persistent, specific status with the relevant recovery action. Do not present cached state as live device state. |
 | Authenticating or reading | Identify the operation and withhold hardware writes until the service declares them safe. |
 | Edits pending | Clearly show unapplied changes and an explicit Apply action. Updating a form or selecting an effect changes local intent only. |
 | Backing up, writing, or verifying | Show those actual stages. Prevent duplicate submission; do not call a sent command “Saved.” |
 | Readback matches | Show “Applied and verified.” Claim persistence across power cycles only if the protocol/hardware evidence establishes it. |
 | Timeout, disconnect, malformed reply, or mismatch | Preserve useful edit context, mark device state uncertain, and show a persistent error. Reconnection/readback precedes an explicit retry; no blind automatic replay. |
 Carbon InlineLoading supplies active/finished/error states and recommends
 disabling associated actions during submission. Inline notifications persist,
 and error messages should state the user action that resolves the problem. Use
 these patterns for operation status; a fleeting toast is insufficient for a failed
 hardware update. [C9][C10]
 ### Feature editors
 | Area | v1 editor implications from the supplied specification |
 | --- | --- |
 | Lighting | Only capability-backed effects; five brightness/speed levels; monochrome/colourful; LED enable; one custom per-key frame. Use protocol-owned mappings for self-defined mode and colour-mode raw IDs. Do not invent direction controls or multiple onboard lighting profiles. |
 | Key mapping | Four layers; physical keys only; keyboard/modifier/combination/media/mouse/disabled/macro choices where verified. Show current and proposed assignments; flag unknown readback without silently replacing it. |
 | Macros | List the 32 slots; edit ordered press/release/delay actions with visible bounds and slot usage. Limit to 112 actions, 0–65,535 ms delays, and 127 encoded name bytes. Confirm the name encoding before implementing byte counting; “127 characters” is not equivalent. Offer only verified execution modes and validated parameter ranges. |
 | Typing | Debounce choices 0/10/20/30/40 ms. Tap-delay UI must await its verified range/units. Do not expose unsupported NKRO, report-rate, OS-mode, Win-lock, or Hall-effect controls. |
 | Power | Display battery/charging only when valid data is available; unknown is not zero. Sleep uses the stated discrete choices, not a free-form unbounded duration. |
 | Backups and restore | Export a versioned, protocol-independent document; show source identity, timestamp, compatibility checks, and a change preview before explicit restore. Validation and a fresh pre-write backup belong to the service. Do not promise atomic restore unless evidence establishes it; identify partial/interrupted outcomes. |
 A macro action form is sufficient for complete authoring. If a later decision adds
 recording, it must remain an explicit focused interaction with an obvious stop
 path and must obey the specification's ban on input-device grabs. Global keyboard
 recording is not required by the supplied capabilities and should not be added as
 an implicit interpretation of “complete control.” Never execute a macro merely
 because a user previews its steps. Layer reset, if included, needs separate
 verified protocol behavior and explicit user intent; factory reset and firmware
 flashing remain excluded.
 ## Smallest sufficient proof before choosing the stack
 The later architecture/prototype decision should evaluate one packaged Carbon
 form, layer tabs, a modal, a representative long macro list, the labelled keyboard
 selector, and simulated service states. It does not need hardware writes.
 1. Build/install/uninstall on the intended Void libc/architecture targets with
   declared runtime dependencies. Confirm local fonts/assets work without network
   access and record exact dependency versions.
 2. Launch as a native Wayland window on niri; verify app identity, keyboard focus,
   normal resizing, fractional scaling, dialogs/file selection, and behavior when
   launched from the shell integration. A successful XWayland fallback does not
   satisfy a native-Wayland claim.
 3. Operate every representative control by keyboard; test meaningful reading and
   actions with the target Linux accessibility stack, including modal focus and
   operation-status announcements. Carbon's upstream tabs screen-reader evidence
   names JAWS, VoiceOver, and NVDA, so it is not a substitute for a Linux/Orca test.
   [C7]
 4. Exercise disconnected, unauthenticated, pending, verifying, and failed states
   against a fake service; prove no simulated write occurs on launch, navigation,
   refresh, or reconnect. Confirm duplicate Apply is blocked and stale drafts
   cannot overwrite a newly read configuration without review.
 Unresolved product decisions are the supported libc/architecture matrix, wrapper
 selection, theme synchronization policy, and the preferred editor interaction.
 Unresolved hardware facts include the layout, name encoding, tap-delay parameters,
 transaction persistence, and individual capability read/write validation. These
 are explicit decision/proof obligations, not missing Carbon documentation.
 ## Sources and retrieval
 Context7 was used first for Carbon, Tauri, Electron, and Qt (`library` then
 `docs`, no more than three commands for each question). Findings were checked
 against the following primary documentation/source. No application was built,
 no packages were installed, no host configuration was changed, and no device I/O
 was performed for this report.
 - [C1] [Carbon developer introduction](https://carbondesignsystem.com/developing/get-started/) and [React guide](https://carbondesignsystem.com/developing/frameworks/react/).
 - [C2] [Carbon official repository, packages and license](https://github.com/carbon-design-system/carbon/blob/main/README.md).
 - [C3] [Carbon themes](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/README.md), [Theme component](https://github.com/carbon-design-system/carbon/blob/main/packages/react/src/components/Theme/Theme.mdx), and [Layer component](https://github.com/carbon-design-system/carbon/blob/main/packages/react/src/components/Layer/Layer.mdx).
 - [C4] [Carbon IBM Plex guide](https://github.com/carbon-design-system/carbon/blob/main/docs/guides/ibm-plex.md).
 - [C5] [IBM Plex license](https://github.com/IBM/plex/blob/master/LICENSE.txt).
 - [C6] [Carbon accessibility overview](https://carbondesignsystem.com/guidelines/accessibility/overview/).
 - [C7] [Carbon Tabs accessibility](https://carbondesignsystem.com/components/tabs/accessibility/).
 - [C8] [Carbon accessibility verification guide](https://github.com/carbon-design-system/carbon/blob/main/docs/guides/accessibility.md). Its old IBM-internal DAP setup instructions are not adopted as a project tool requirement.
 - [C9] [Carbon InlineLoading usage](https://carbondesignsystem.com/components/inline-loading/usage/).
 - [C10] [Carbon notification usage](https://carbondesignsystem.com/components/notification/usage/) and [Form usage](https://carbondesignsystem.com/components/form/usage/).
 - [T1] [Tauri webview versions](https://v2.tauri.app/reference/webview-versions/).
 - [T2] [Wry Wayland/GTK integration](https://github.com/tauri-apps/wry/blob/dev/README.md) and [Tao Linux GTK3 dependency](https://github.com/tauri-apps/tao/blob/dev/README.md).
 - [T3] [Tauri prerequisites, including Alpine](https://github.com/tauri-apps/tauri-docs/blob/v2/src/content/docs/start/prerequisites.mdx).
 - [T4] [Tauri Linux distribution/libc baseline guidance](https://github.com/tauri-apps/tauri-docs/blob/v2/src/content/docs/distribute/debian.mdx).
 - [T5] [Tauri security boundaries](https://github.com/tauri-apps/tauri-docs/blob/v2/src/content/docs/security/index.mdx) and [capabilities](https://github.com/tauri-apps/tauri-docs/blob/v2/src/content/docs/security/capabilities.mdx).
 - [E1] [Electron platform support](https://github.com/electron/electron/blob/main/README.md).
 - [E2] [Electron version support policy and cadence](https://github.com/electron/electron/blob/main/docs/tutorial/electron-timelines.md).
 - [E3] [Electron breaking changes, v38 Wayland default](https://github.com/electron/electron/blob/main/docs/breaking-changes.md).
 - [E4] [Electron security guidance](https://github.com/electron/electron/blob/main/docs/tutorial/security.md).
 - [V1] [Void WebKitGTK package source at inspected revision](https://github.com/void-linux/void-packages/blob/954278b83979958bcfdff05f22cf699c9dc20346/srcpkgs/libwebkit2gtk41/template).
 - [V2] [Void Electron package source at inspected revision](https://github.com/void-linux/void-packages/blob/954278b83979958bcfdff05f22cf699c9dc20346/srcpkgs/electron35/template).
 - [Q1] [Qt Quick Controls available styles](https://doc.qt.io/qt-6/qtquickcontrols-styles.html).
 - [Q2] [Qt Quick accessibility](https://doc.qt.io/qt-6/accessible-qtquick.html).