mokosh/.planning/intel/assets-spec.md

Mokosh Asset Specification

Concrete deliverables list derived from design-system.md. Each entry tells a contributor (you, an agent, a hired designer) exactly what file to produce, what dimensions/format, what to draw, and where to commit it. Authored 2026-05-17 to unblock Plan 01-09's notification-icon failure + Plan 01-10's welcome page.

Status: draft — first iteration; revise as actual designs surface.

---

Priority 0 — blocks Plan 01-09 closeout

These three icons unblock the notification + toolbar UX. Plan 01-09 cannot land its operator-empirical UAT until valid versions exist.

A-01 — icons/icon16.png

Path	icons/icon16.png (commit to source tree; vite copies to dist/icons/ on build)
Dimensions	16 × 16 px
Format	PNG, RGBA (transparent background), 8-bit
Min file size	≥ 200 bytes (current placeholder is 79 B — Chrome rejects it)
Subject	The Mokosh mark per design-system.md §5.2. At 16px most detail is lost; produce as a single recognizable silhouette.
Color	Single accent color OR transparent + accent. Recommended: a filled circle in #212121 (near-black, neutral) for visibility on both light and dark Chrome themes. Adding the recording dot in --mks-rec makes this state-coloured, which conflicts with the "neutral mark + state via badge" decision (design-system §5.2). Pick neutral.
Where used	Chrome menu bars, Extensions page list, autocomplete popup
Validation	After committing: npm run build && grep -q '"16"' dist/manifest.json && [ -s dist/icons/icon16.png ]

A-02 — icons/icon48.png

Path	icons/icon48.png
Dimensions	48 × 48 px
Format	PNG, RGBA, 8-bit
Min file size	≥ 500 bytes (current placeholder is 123 B)
Subject	Same mark as A-01, more visible internal detail. The frame/ring around the dot can resolve at this size.
Color	Same constraint: neutral.
Where used	Chrome Extensions page (chrome://extensions card icon), some context menus
Validation	grep -q '"48"' dist/manifest.json && [ -s dist/icons/icon48.png ]

A-03 — icons/icon128.png

Path	icons/icon128.png
Dimensions	128 × 128 px (REQUIRED minimum for chrome.notifications.create({type:'basic'}))
Format	PNG, RGBA, 8-bit
Min file size	≥ 1 KB (current placeholder is 306 B — silently rejected by chrome.imageUtil per the empirical finding)
Subject	Full Mokosh mark, all detail visible. This is the primary brand asset.
Color	Neutral mark; the badge layer adds state colour.
Where used	Chrome Web Store thumbnail (someday), notification iconUrl (per design-system.md §8.2), about-extension dialogs
Validation	[ $(stat -c%s dist/icons/icon128.png) -gt 1024 ] AND chrome.notifications.create succeeds in smoke without imageUtil error

---

Priority 1 — Plan 01-10 welcome page

A-04 — icons/icon192.png (optional, retina-safe notification icon)

Path	icons/icon192.png
Dimensions	192 × 192 px
Format	PNG, RGBA, 8-bit
Min file size	≥ 2 KB
Subject	Identical to A-03 at higher resolution; for hi-DPI displays in notification rendering
Status	Optional but recommended. If skipped, A-03 (128px) is the fallback.

A-05 — Welcome page hero mark (Plan 01-10)

Path	src/welcome/hero.svg (preferred — vector) OR src/welcome/hero.png (1024×512 fallback)
Format	SVG (inline-safe, no external refs) OR PNG
Subject	Lockup of the Mark + the wordmark "Mokosh" OR "AI Call Recorder". Type lockup at large scale. Per design-system.md §10 ODD-4, default is "type-only hero" if no illustration exists — in that case the SVG can be a stylized rendering of the wordmark alone.
Used by	src/welcome/welcome.html (Plan 01-10)
Status	Required for Plan 01-10 closure. Acceptable interim: type-only HTML/CSS lockup (no asset file needed)

---

Priority 2 — refinement passes (future phases)

A-06 — Status-glyph variants for badge composition

The current architecture uses Chrome's badge API (text + background color) for state communication. If a future phase wants richer state indication (e.g. a recording-dot embedded in the toolbar icon itself, swapped via chrome.action.setIcon), we'd need per-state icon variants:

Variant	Dimensions	When used
icons/icon-rec-16.png etc.	16/48/128	When recording active (red dot overlay)
icons/icon-err-16.png etc.	16/48/128	When in error state
icons/icon-off-16.png etc.	16/48/128	When idle

Recommendation: defer to Phase 5 hardening unless badge text proves insufficient. The performance cost of setIcon swaps every state change is non-trivial.

A-07 — Popup polish

Path	src/popup/popup-bg.svg
Subject	Optional subtle background pattern OR colour for popup container; currently popup uses solid --mks-popup-bg-dark/light
Status	Skip; current solid background is fine

A-08 — Operator runbook visuals (smoke.sh page enhancements)

The smoke test page (in smoke.sh's SMOKE_HTML) currently uses emoji and inline CSS. Could be replaced with a properly-designed instructional page if operators actually use it for onboarding. Currently dev-only; defer.

---

Implementation pathways for the contributor

Pick ONE based on availability:

Path A — auto-generated solid-color placeholder set

Use case: quickly unblock Plan 01-09 closeout. Replace placeholders with real designed assets later.

# Quick generator using ImageMagick (one-liner per size)
convert -size 16x16  xc:'#212121' -draw "fill #00C853 circle 8,8 8,4"  icons/icon16.png
convert -size 48x48  xc:'#212121' -draw "fill #00C853 circle 24,24 24,12" icons/icon48.png
convert -size 128x128 xc:'#212121' -draw "fill #00C853 circle 64,64 64,32" icons/icon128.png

Produces dark-square + green-dot icons (~1 KB each). Functional, not branded.

Path B — design-first

You produce the assets per the design-system.md constraints. Drop them at the spec'd paths. Run npm run build, smoke.sh, confirm notification fires.

Path C — hire / commission

Send design-system.md + this file to a designer. Acceptance: deliverables at the listed paths, dimensions, formats, with file sizes above the floors.

---

Acceptance checklist (any pathway)

Plan 01-09's operator UAT can resume when ALL of these are true:

• icons/icon16.png exists, ≥ 200 bytes, is 16×16 PNG
• icons/icon48.png exists, ≥ 500 bytes, is 48×48 PNG
• icons/icon128.png exists, ≥ 1024 bytes, is 128×128 PNG
• npm run build mirrors them to dist/icons/
• Smoke run: chrome.notifications.create does NOT throw imageUtil error
• Recovery notification visibly appears after click "Stop sharing" in Chrome

Once those pass + Plan 01-09 Bug B fix (state routing for user-stopped-sharing → setIdleMode) lands, the wave closes.

---

Related

• design-system.md — visual + interaction language this spec realises
• .planning/phases/01-stabilize-video-pipeline/01-09-PLAN.md — the plan that surfaced the icon need
• .planning/debug/01-09-recovery-flow.md — the debug session that confirmed the icon files are the blocker
• src/background/index.ts lines 54, 833-840 — NOTIFICATION_ICON_PATH constant
  • the chrome.notifications.create call site that needs valid icons
• manifest.json icons and action.default_icon — declare which sizes exist