# 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//` — 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//` 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 `·`. > 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/-hero.png` (1536x1024 GPT output), `heroes/-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.