# Recipe: the Magogi desktop brand (Qt) — adopt, don't re-derive

> **Audience:** any agent or maintainer giving a Magogi **desktop** (PySide6)
> app its face. The web has [`WEB_UI.md`](../standards/WEB_UI.md) +
> `mgf-brand-web`; this is the desktop counterpart, recipe-level until a
> second adopter lands (see *Graduation* below).
> **Rules touched:** [GUI-01](../standards/GUI_CONSUMERS.md#GUI-01) (the
> UI-kit carve-out — PAPER-118), GUI-consumer layering, NM-05.
> **Origin:** PAPER-119 — vm-vmanager-app derived the full web→Qt brand
> translation during its desktop-UI redesign (C10, 2026-07); this recipe
> exists so the next adopter reads the result instead of re-deriving it.

## The kit: `mgf-brand-qt`

The sanctioned shared implementation (registry: 0.1.0, added 2026-07-10 —
GUI-01 names it the UI-kit library). Import it **only from your presentation
layer** (your `mgf.<consumer>.gui` / `<app>.gui` package — the same discipline
`mgf-brand-web` consumers follow for CSS; enforce with `import-linter` on your
side, as the kit does on its own):

| Module (`mgf.brand_qt.…`) | Owns |
|---|---|
| `tokens` (+ `_mix`) | The brand tokens (color/spacing/type ramps) — **Qt-free core**, importable anywhere |
| `qss` | The QSS stylesheet builder over the tokens — Qt-free |
| `theme` | Tokens → `QPalette` + application-level theme wiring |
| `fonts`, `icons` | Brand font loading, icon set (Qt-dependent) |
| `motion` | Motion/duration constants incl. the reduced-motion path |
| `widgets/` | Self-theming brand widgets (tiles, empty-states, delegates, props) |

## The five translation rules (derived once, by vm-vmanager-app)

1. **Tokens → QPalette + QSS, never ad-hoc colors.** All chrome color flows
   from the token set through `theme`/`qss`; a hex literal in app code is a
   defect (the Qt analog of inline CSS).
2. **Chrome vs readout split.** UI chrome (navigation, panels, buttons)
   follows the brand theme; live *readout* surfaces (terminals, logs, metric
   readouts) keep their own high-legibility treatment and do not restyle with
   the chrome.
3. **One gold per view.** The brand's single-accent discipline: at most one
   gold-accent element per view (the primary action / the live flame);
   everything else stays in the neutral ramp.
4. **Self-theming widgets.** Shared widgets style themselves from the tokens
   (no per-consumer QSS overrides of kit widgets) — consumers compose, they
   don't repaint.
5. **Reduced motion is a setting, not a media query.** Desktop has no
   `prefers-reduced-motion`; the kit's `motion` constants honor an app-level
   setting the consumer exposes.

## Deep reference (the full rationale + verification)

`vm-vmanager-app/docs/archive/2026/desktop-ui-redesign/` — docs `00`–`04`
(brand understanding → standards context → current state → target design →
execution plan), 11 chunk records, and `verification/state-coverage.md`.
vm-vmanager-app is the reference consumer; its GUI-01 `import-linter`
contract is the layering example to copy.

## Adopting in a new consumer — the short path

1. Depend on `mgf-brand-qt`; import it only from your presentation package.
2. Wire `theme` at app startup (palette + QSS from tokens); load `fonts`.
3. Add/extend your `import-linter` contract: domain packages may not import
   `PySide6` or `mgf.brand_qt` (GUI-01 both ways).
4. Apply rules 2–5 above as you build views; prefer kit `widgets/` over
   bespoke ones (rule-of-three per [`shared-code.md`](shared-code.md) for
   anything you'd add to the kit — file it to mgf-brand-qt's `FEEDBACK.md`,
   AG-13).

## Graduation

When a **second** consumer adopts (named candidates at filing: hrb-app,
figrecovery Phase 7 — "styled after VManager"), promote this recipe's rules
1–5 to a DESKTOP_UI standard (EXTEND-class, founder-enacted — the
`PRESENTATION_LAYER.md`/`WEB_UI.md` two-adopter pattern). Until then:
recipe-level, deliberately.
