# Magogi brand-web kit

A **self-contained, drop-in** brand layer for any Magogi Foundation web surface —
the CSS implementation of the [Magogi Brand Book][bb] (Part V Colour, Part VI
Typography, Part VII/VIII components) that `mgf-brand` itself ships only as prose
+ tokens. Everything here is plain CSS + assets: no build step, no framework.

> **Status:** vendored into `mgf-cloud-app` today (the "copy now, kit-ready"
> decision). It is deliberately self-contained so it can lift **wholesale** into
> a shared `mgf-brand-web` package once a second consumer needs it — at which
> point each tool depends on the package instead of copying this folder. More
> local web tools are coming, so keep this folder free of app-specific CSS
> (that lives in `../app.css`, not here).

## Contents

| File | Role |
|------|------|
| `tokens.css` | Design tokens (`--mgf-*`, `--color-*`, spacing, radius, motion) + dark mode. **Ported verbatim from mgf-website's `global.css`** — the canonical reconciliation. Source of truth; never hardcode hex. |
| `base.css` | Element defaults, type scale, links, focus rings, buttons, a11y utilities. |
| `components.css` | Reusable components: nav, cards, stat tiles, tables, status badges, forms, empty state, Evidence Ledger. |
| `instruments.css` | **Operator-instrument layer** (optional, additive): control-surface components for federation/console/testing tools — state chips, live indicators, progress, tabs, the dark streaming console, authority markers, ribbons, the telemetry live-pane, the config panel, level badges, reference pills, detail/evidence blocks, empty-state variants. |
| `fonts.css` + `fonts/` | Self-hosted OFL families: Inter (body), Space Grotesk (display), JetBrains Mono (code/labels). |
| `logo/` | Cornerstone Orbit marks (icon, lockup, on-dark, mono) + favicon. |
| `pattern/` | Federation Lattice tiles (fine/medium, light/dark). |

Load order matters: **tokens → fonts → base → components → instruments**, then
your app CSS. `instruments.css` is optional — load it only on operator/console
surfaces; pure content surfaces can skip it.

## Drop-in usage

1. Copy this `brand/` folder into your app's static dir and mount it (FastAPI:
   `app.mount("/static", StaticFiles(directory=...), name="static")`).
2. Put this in your base template `<head>` (adjust the `/static` prefix to your
   mount point):

```html
<link rel="icon" href="/static/brand/logo/magogi-favicon.svg" />
<link rel="preload" as="font" type="font/woff2" crossorigin
      href="/static/brand/fonts/inter-latin.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin
      href="/static/brand/fonts/space-grotesk-latin.woff2" />
<link rel="stylesheet" href="/static/brand/tokens.css" />
<link rel="stylesheet" href="/static/brand/fonts.css" />
<link rel="stylesheet" href="/static/brand/base.css" />
<link rel="stylesheet" href="/static/brand/components.css" />
<link rel="stylesheet" href="/static/app.css" />  <!-- your app-specific layer -->
```

3. Use the classes: `.button`/`.button-primary`/`.button-accent`, `.card`,
   `.stat`/`.stat-grid`, `.table`/`.table-wrap`, `.badge`/`.badge-success`…,
   `.form`/`.field`/`.input`, `.app-nav`, `.eyebrow`, `.empty`, `.ledger`.

## Operator-instrument layer (`instruments.css`)

The control-surface vocabulary for operator tools, on the same tokens. ~14
families:

| Family | Classes |
|--------|---------|
| **State chips** (SYNC + TEST language) | `.status-chip` + `--in-sync/--stale/--tampered/--unknown/--unreadable/--checking/--syncing/--error` and `--pass/--fail/--error/--skipped/--running`; `.status-chip__dot`, `.spinner`. Map a state with `state.toLowerCase().replaceAll('_','-')`. |
| **Live indicator dots** | `.status-indicator` + `--running/--queued/--down` (pulsing). |
| **Progress bars** | `.progress`, `.progress__fill` (+ `--done`), `.progress--indeterminate`. |
| **Tabs / lens-tabs** | `.tabs`/`.tab`/`.tab--active` (gold underline); `.lens-tabs`/`.lens-tab`/`.lens-tab--active` (pill). |
| **Dark streaming console** | `.console`, `.console__line/__seq/__ts/__kind/__text`; per-kind colours via shared `.kind--<event>` (e.g. `--session-start`, `--step`, `--gate`, `--artifact`, `--error`). Light text on dark ink — stays dark in both themes. |
| **Authority / broker** | `.authority-badge` (violet dashed), `.service-status--up/--down`. |
| **Ribbons** | `.ribbon--warning/--danger/--info`. |
| **Live-pane** (telemetry) | `.live-pane`, `__head/__op/__body/__step/__meta/__latest/__timeline/__events/__event` + `.live-pane__kind` (reuses `.kind--*`). |
| **Config-panel** | `.config-toggle`, `.config-panel`, `__head/__row/__foot/__note`. |
| **Level badges** | `.level-badge--low/--medium/--high` (+ `--effort`). |
| **Telemetry marker** | `.telemetry-marker`, `.live-dot` (+ `--ended`), `.live-chip` (+ `--ended`). |
| **Reference pills** | `.pill` + `--age/--priority`. |
| **Detail / evidence** | `.detail` (+ `.detail__key`), `.detail-block` (+ `--warning/--derived`), `.evidence`. |
| **Empty-state variants** | `.empty--unknown/--unreadable/--no-data`, `.empty__icon`, `.empty__desc` (extend the existing `.empty`). |

See `../../../../docs/instruments-demo.html` for a live gallery of all of them.

## Brand rules baked in

- **One gold accent per view** ("one flame per room") — Keystone Gold
  (`--color-accent`) is for the single primary action / active marker, never
  body text. The active tab/lens marker uses gold only as the underline; text
  stays dark for contrast.
- **Colour policy (D-BRAND-ACCENT, locked)** for the instrument layer:
  **gold** = affirmative action (use `.button-accent`; blue is *never* a CTA),
  **blue** (`--state-busy`) = functional "busy / running" only, **violet**
  (`--state-derived`) = "derived / authority / telemetry". The
  success/warning/error/info tokens carry the rest of the state language.
- Status is **colour + dot + label**, never colour alone (a11y).
- Dark mode is automatic via `prefers-color-scheme` — tokens remap, no JS.
- Motion is restrained and honours `prefers-reduced-motion`.

[bb]: https://codeberg.org/magogi-admin/mgf-brand — `brand/MAGOGI_BRAND_BOOK.md`
