# Imperium OS software mockups — the replication recipe

How every Imperium OS interface graphic on the master sheet is made, and how to make more.
Canonical source tree (all editable code): `Alex OS/assets/imperium/mockups-v5/`
- `due-diligence/due-diligence-v5.html` — glass task-list card
- `opportunities-3d/method1-v5.html` — 3D-tilted CRM table on dot grid
- `os-renders/<uc>/` — the 30-asset Imperium OS matrix: 10 use cases (home, os, aireos,
  e, hosp, legal, prop, rec, ag, util) x three framings: `-t` 3D tilt hero, `-m` macro
  close-up, `-f` flat fragment. Plus 5 approved HOME alphas.
- `_brand/system.css` — the shared design system (master copy; each folder self-contained)
- `_scripts/` — rebrand.mjs, codicon-swap.mjs, render-all.sh, render-alpha.sh
This folder carries the COMPLETE source tree in `src/` (every mockup HTML, per-folder
system.css + fonts + monogram assets, the scripts); copy `src/os-renders/<uc>/` anywhere
and it renders standalone.

## The premium finish layer (v4, 2026-07-30, applied to every card)

Every mockup carries the approved premium treatment. When creating a NEW mockup, apply all of it:
- **Transparent object only.** Card + drop shadow in the alpha channel; no scene grounds,
  no vignettes, no floating annotation pills, no logo tiles. The render must sit on any background.
- **Surface**: `linear-gradient(165deg, #FAF9F4 0%, #F7F5EE 60%, #F2F0E6 100%)` (never flat,
  never pure white), border `1px solid rgba(255,255,255,.6)`.
- **Shadow stack**: `inset 0 1px 0 rgba(255,255,255,.95), 0 0 0 1px rgba(76,183,130,.14),
  0 2px 8px rgba(21,19,14,.07), 0 34px 70px -18px rgba(21,19,14,.28), 0 90px 160px -50px rgba(21,19,14,.30)`.
  3D tilt bezels use ink throws (`rgba(21,19,14,.36-.40)`), never warm brown.
- **Glass**: specular sweep `::after` (118deg, white .14 at 50%), plus the shared `.glint` +
  `.grain` divs from system.css inside every overflow:hidden card (set `--card-r` to the
  surface's actual radius: R40 cards/panels, 12px app-window chrome per BRAND-BOOK §5 —
  the 22px fallback in system.css is a legacy default, always override it; same for its
  8px button radius — small product buttons are 10px per the BRAND-BOOK radius scale).
- **Type**: display lines and hero figures = Emilio Light (`font-weight:300`); hero NUMBERS in
  Racing Green `#11462C`. Emphasis inside an Emilio line = green colour, never synthetic bold.
  Eyebrows = Switzer Medium uppercase, `rgba(17,70,44,.62)`.
- **Accents**: mint-lit bars/rules `linear-gradient(90deg, rgba(17,70,44,.55), #4CB782)` with a
  `rgba(76,183,130,.35-.5)` glow where a metric is positive; Ember only for the ONE alert.
- **Depth of field** (multi-window scenes): back window `filter: blur(2.6px) saturate(.95);
  opacity: .88`, front window carries the deep shadow + `.glintFW`.
- No em dashes anywhere, including literal dash characters; use `&middot;`.

> Known deviation: `src/due-diligence/` and `src/opportunities-3d/` bundle an `inter.woff2`
> from their pre-brand-v5 origin. The brand face is Switzer; swap it in only if re-rendering
> those two mockups anyway (the shipped renders are approved as-is).

## The pipeline (mockup-studio skill, two stages)

1. **CODE owns the UI.** Build/edit the interface as standalone HTML/CSS on `system.css`.
   Brand contract: Switzer UI text, Emilio Light for display lines and the greyed monogram
   watermark (`mark-watermark.svg`, never a generic serif "I"), greens only (Racing Green
   `#11462C`, Mint `#4CB782`, Bali `#3FA085`, ONE Ember `#E23A28` alert max per view),
   paper/sage grounds, panels `#F9F8F3` (never pure white), 40px outer radius on cards/panels
   (app-window/browser chrome uses the official 12px exception, BRAND-BOOK §5), codicon
   glyphs only (`github.com/microsoft/vscode-codicons`), current monogram logo. Screenplay:
   fictional clients (Meridian Group, AIREOS, Halewood & Co...), never real client data.
2. **Render.** `bash _scripts/render-all.sh` (opaque scenes) and
   `bash _scripts/render-alpha.sh` (transparent: page background stripped, card shadows
   kept in the alpha channel, canvas auto-expands until nothing clips). Renders use
   Playwright's chrome-headless-shell; per-file size is parsed from the `html, body` rule.
   Transparent PNGs are the website-ready deliverables — they sit on any ground. All 36 ship in the kit under mockups/alpha/ (matrix + HOME alphas + the opportunities tilt); the master sheet embeds every one directly on the page ground.

## Premium finishing ladder (optional, per hero)

3. **GPT Image 2 (edit mode) — the ONLY UI-safe generative finisher.** Direct OpenAI API:
   `node ~/.claude/skills/mockup-studio/scripts/gpt-finish.mjs --image render.png --out hero.png --preset premium-3d`
   (presets: premium-3d, reflection, desk-scene, gradient-bg, glass, studio). It preserves
   layout and text while adding reflections, depth-of-field, lighting, environments.
4. **Higgsfield — art passes on top of the GPT-finished hero** (higgsfield /
   higgsfield-generate skills, or the MCP `generate_image`/`upscale_image` tools): extra
   glass, light blooms, cinematic grades, upscales to 2K/4K. CAVEAT (tested 2026-07-03 and
   2026-07-26): Higgsfield and every non-GPT-Image-2 model garble UI text and invent rows
   when given raw UI. Only hand Higgsfield an already-finished hero for atmosphere, accept
   that fine UI text may soften, and never use it as the primary finisher or for
   transparent assets. For consistent product sets, ship the code render.

## Worked examples: the four finished heroes (2026-07-30, in heroes/)

Each is: transparent render composited onto a brand ground (PIL), then GPT Image 2 edit with a
brand prompt + layout guard, then Higgsfield 4K upscale (`upscale_image`, bytedance provider).
Files: `heroes/<name>-hero.png` (1536x1024 GPT output), `heroes/<name>-hero-4k.png`, and for
rec-f/home-f a `-alpha.png` transparent extraction (see below).

1. **home-t · racing-green studio**: "deep racing-green (#11462C) studio environment, soft
   spotlight pool behind it, physical glass screen with faint specular reflection, subtle
   mirrored floor reflection, gentle atmospheric haze, soft mint-green rim light."
3. **prop-t · classical architecture** (v3 final; a desk scene was too literal and abstract
   waves read sci-fi, both rejected): "a softly blurred classical stone building facade
   (elegant columns, cornices, tall sash windows) in warm early-morning light, photographed
   from street level at a gentle upward angle, a sliver of pale sky, warm sunlight grazing
   one column near the centre; deep soft natural drop shadow; shallow photographic depth of
   field, fine film grain; no lasers, no neon, no abstract shapes." Guard: "every scheme
   name, number, column position and row line must stay in exactly the same place."
4. **home-f · cinematic key light** (v2): "deep rich gradient flowing diagonally from dark
   forest green (#0A1F14) top-left through sage to warm bone lower-right, strong directional
   key light from upper left, both windows get visible physical thickness like slabs of
   frosted glass (bright lit top edge, subtle darker side face), stronger mint bloom, long
   soft shadows to the lower right, fine grain." Guard: "do not repaint, sharpen or alter
   the intentionally blurred rear window."
2. **rec-f · warm office interior** (v3 final; earlier dark-glass bloom and laser-line passes
   were rejected as too sci-fi — see doctrine below): "floating in a real office interior, softly blurred behind the sharp card:
   warm oak desk with a laptop partially visible, muted sage-green rug and soft neutral walls,
   natural window light from the upper left, shallow photographic depth of field, fine film
   grain, deep soft natural drop shadow; no light rays, no laser lines, no glowing particles."

**ENVIRONMENT DOCTRINE (Alex, 2026-07-30, binding for all future heroes):** real-world
editorial scenes (classical architecture, warm interiors, studio product light) or calm
brand-solid grounds. NEVER sci-fi: no laser lines, no neon streaks, no abstract alien waves,
no glowing particles, nothing "too AI". Reference vibe: a UI card floating over a blurred
Beaux-Arts facade, or a popup over a warm wood-and-sage office. Corporate but never boring.

## Transparent extraction of a finished hero (chroma-free matte)

Generative output is opaque, but a finished TILE can be cut back out (worked script pattern,
pure PIL + numpy, no scipy): detect the card/window rects (luminance threshold on dark scenes;
gradient-edge search near known geometry on light scenes), mask them as rounded rects
(feather ~1px) keeping the baked lighting inside the tile (glass lips, slab edges), then
REBUILD the scene effects in the alpha channel: layered ink drop shadows (two throws of the
offset blurred mask), mint under-glow / key-light bloom as blurred ellipses with partial
alpha, and a faint white rim. Tilted panels are non-rectangular: flood-grow the bright panel from its centre (threshold
high enough not to leak into sky/sunlit stone), fill text holes via border-flood complement,
use the filled blob itself as the mask. Result sits on any ground. Examples:
`heroes/rec-f-hero-alpha.png` (office card), `heroes/home-f-hero-alpha.png` (two windows),
`heroes/prop-t-hero-alpha.png` (tilted quad).

Lessons baked into the guards (both failures happened on the first attempt): GPT re-invents
intentionally BLURRED windows unless told to leave them blurred, and it will offset dense
table values unless the prompt locks row/column positions. Expect the very smallest labels
(sub-11px) to soften; that is the accepted cost of the generative pass. Always diff the output
against the source render before shipping.

## Rules recap

- Never let any image model draw UI, text, logos, or icons from scratch.
- Transparent deliverables: CSS-native finish only (shadows, specular sweeps, reflections
  as mirrored clones) — GPT Image 2 cannot output alpha.
- Quality gate before shipping (AGENTS.md §4 — avg ≥9.5, no dimension <8, max 3 iterations): colour drift, wrong weight, a second Ember, a
  stray brown, or an em dash are fail conditions.
