# mgf-brand-qt

**The Magogi Foundation brand kit for Qt (PySide6) desktops** — the
desktop analog of [`mgf-brand-web`](https://codeberg.org/magogi-admin/mgf-brand-web).
One installable package carrying the locked brand tokens, a generated
QSS stylesheet, the self-hosted fonts, the 42-icon set, the
Cornerstone Orbit marks and Federation-Lattice patterns, and the
brand widget layer — so every MGF desktop surface reads Magogi from
one source of truth instead of copying a design system.

First proven as `vmanager.gui.design` in vm-vmanager-app's desktop-UI
redesign (its `docs/archive/2026/desktop-ui-redesign/` is the design
record); extracted 2026-07-10 under the GUI-01 UI-kit carve-out
(mgf-standard PAPER-118).

## Install

```
pip install mgf-brand-qt        # resolves from the Codeberg index (PKG-06)
```

## Use (from your presentation layer ONLY — GUI-01)

```python
# Qt-free core — importable anywhere, no PySide6 side effects:
from mgf.brand_qt import LIGHT, DARK, RAW, SPACE, build_qss

# Qt surfaces — explicit submodule imports, presentation layer only:
from mgf.brand_qt.theme import apply_theme            # Fusion + QPalette + QSS + OS watching
from mgf.brand_qt.icons import icon                   # the 42-icon set, recolorable, DPR-aware
from mgf.brand_qt.fonts import display_font, mono_font
from mgf.brand_qt.motion import fade_in
from mgf.brand_qt.widgets import (
    Badge, StatusChip, StatTile, EmptyState, bind_empty_state,
    StatusChipDelegate, STATUS_ROLE, set_mgf, apply_label_class,
)

app = QApplication(sys.argv)
theme = apply_theme(app, "system", on_mode_changed=persist_to_your_settings)
```

- **Themes:** `"dark"` / `"light"` / `"system"` (follows the OS
  colour scheme live). Persistence is the consumer's job (GUI-08:
  route it through your `BaseAppSettings`-derived config).
- **Styling vocabulary:** widgets opt in via `mgf*` dynamic
  properties — `mgfVariant` (`primary`/`accent`/`danger` buttons),
  `mgfClass` (`hint`/`sectionTitle`/`eyebrow`/…, declarable in `.ui`
  files as `stdset="0"` properties), `mgfChrome` (Ink instrument
  surfaces that stay dark in BOTH themes), `mgfState` (chip
  families).
- **Brand laws baked in:** one gold accent per view; status is
  colour + dot + label, never colour alone; gold is never text and
  never the light-theme focus ring; instrument chrome does not flip;
  motion is restrained and consumer-gateable (reduce-motion).
- **Self-theming components:** delegates/empty states pick light or
  dark from the paint-time palette; chip dots use the brand's
  theme-invariant base hues — no theme-manager plumbing through your
  models.

## What ships

`tokens` (raw palette + light/dark semantic maps with **computed**
color-mix parity + scales + viz palettes) · `qss` (the generated
stylesheet) · `fonts` (Inter / Space Grotesk / JetBrains Mono statics,
OFL) · `icons` · `theme` · `motion` · `widgets` · `assets/`
(fonts, 42 icons, logos, lattice patterns, desktop app icon — sha256
provenance in `assets/ASSETS_MANIFEST.md`).

## Guarantees (mechanically enforced)

- Imports **no domain library or consumer** (import-linter).
- The token/stylesheet core is **Qt-free** (import-linter + a
  fresh-interpreter test).
- **Zero raw hex outside the token core**; light/dark field-set
  parity; a WCAG contrast guard over every text/background token
  pair, per theme.

Token source of truth is `mgf-brand` (LOCK v1) — values are vendored
here, never invented; brand issues go to `mgf-brand/FEEDBACK.md`,
kit issues to this repo's `FEEDBACK.md`.
