Mark
949aa03db5
Two new cross-phase intel docs surfacing the visual + interaction
language and the concrete asset deliverables list.
Triggered by Plan 01-09's notification-icon failure: the original
placeholder PNGs (icons/icon{16,48,128}.png at 79/123/306 bytes)
are too small for chrome.notifications.create's imageUtil validation.
Plan 01-09 closeout blocks on valid replacement icons.
design-system.md captures:
- Brand voice (quietly competent operator-tool; not playful)
- Identity (Mokosh codename + "AI Call Recorder" display name)
- Color tokens (semantic state + UI surfaces; WCAG AA validated)
- Typography (system fonts only; type scale)
- Iconography (solid filled, 24px grid, neutral mark + state via badge)
- Spacing (4px base scale)
- Motion (conservative; reduced-motion-aware)
- Component conventions (toolbar action, notification, popup, welcome)
- Accessibility & i18n (Russian-first, contrast floors)
- Open design decisions (mark concept, pulsing badge, tagline)
assets-spec.md captures:
- Priority 0 (blocks Plan 01-09): icons 16/48/128 with min file sizes
+ dimension/format requirements + validation commands
- Priority 1 (Plan 01-10): welcome page hero, optional 192px icon
- Priority 2 (future phases): per-state icon variants, popup polish,
runbook visuals
- Three implementation paths: auto-generated placeholders (interim),
design-first (commission), hire/commission
User will delegate execution to designer team; specs are handoff-ready
with binding technical floor + designer-judgment aesthetic direction.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
174 lines
7.6 KiB
Markdown
174 lines
7.6 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
# 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
|