Metadata-Version: 2.4
Name: mgf-brand-qt
Version: 0.1.3
Summary: The Magogi Foundation brand kit for Qt (PySide6) desktops — design tokens, generated QSS, self-hosted fonts, the 42-icon set, brand marks/patterns, and the brand widget layer (chips, tiles, empty states, delegates), shipped as one package so every MGF desktop surface shares one source of truth. Desktop analog of mgf-brand-web; sibling of mgf-common under the mgf.* namespace.
Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf-brand-qt
Project-URL: Issues, https://codeberg.org/magogi-admin/mgf-brand-qt/issues
Project-URL: Changelog, https://codeberg.org/magogi-admin/mgf-brand-qt/src/branch/main/CHANGELOG.md
Author: Bassam Alsanie, mgf-brand-qt contributors
License: Apache-2.0
License-File: LICENSE
License-File: LICENSE-APACHE.txt
License-File: NOTICE
Keywords: brand,design-system,desktop,magogi,pyside6,qt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pyside6<7,>=6.6
Provides-Extra: dev
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: mgf-standard<0.2,>=0.1.6; extra == 'dev'
Requires-Dist: mgf-test-supervisor<0.2,>=0.1.3; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-qt<5,>=4.4; extra == 'dev'
Requires-Dist: pytest-timeout<3,>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.4; extra == 'dev'
Provides-Extra: standards
Requires-Dist: mgf-common[standards]<1.0,>=0.47; extra == 'standards'
Description-Content-Type: text/markdown

# 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`.
