mokosh/.planning/intel/design-system.md

Mokosh Design System

Cross-phase visual + interaction language for the Mokosh extension (user-facing name "AI Call Recorder", internal codename "Mokosh"). Authored 2026-05-17 in response to Plan 01-09's notification-icon discovery that the original placeholder PNGs (icons/icon{16,48,128}.png at 79/123/306 bytes) fail Chrome's notification API. Surfaces the visual decisions so any contributor (you, an agent, a future designer) can produce assets that fit the same language.

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

---

1. Brand voice

Mokosh is an operator's silent helper. It records continuously, surfaces itself only when needed, and stays out of the operator's way the rest of the time. The visual identity should reflect that:

• Quietly competent. Not playful, not flashy. Dependable industrial.
• Diagnostic, not decorative. Every visual choice serves an operator goal: is recording active? did the bug get captured? where do I click to save?
• Low chrome, high clarity. When the extension is invisible (recording silently), it should genuinely be invisible. When it shows itself (badge, notification, popup), it should be unambiguous about state.
• Russian-first wording, internationally legible visuals. Operators read Russian (per SPEC). Visuals must not depend on any language for legibility — symbols + color + position carry meaning.

Anti-patterns to avoid:

• Animated icons that draw attention during normal operation
• Decorative imagery in a tool that should fade into background
• Brand-marketing tone in operator-facing copy ("Hi there!", emojis)
• Color-only state indication (must pair color with text/shape)

---

2. Identity

Codename	Mokosh — Slavic goddess of fate, weaving, and the earth
User-facing display name	"AI Call Recorder" (Russian-speaking operator-tool name)
Tagline candidates (TBD)	"Записывает, чтобы вы могли воспроизвести." ("Records so you can reproduce.")
Mark concept	A thread/spool/weave motif evokes the codename without overpowering. Alternative: a simple recording dot inside a frame, more conventional. Decision deferred — see Section 10.

---

3. Color tokens

All extension surfaces draw from this palette. Color values are RGB; CSS variable names are how implementation references them.

3.1 Semantic state (operator-visible)

Token	Hex	Use
--mks-rec	#00C853	Recording active. Match BADGE_REC_COLOR in src/background/index.ts. Material Green A700; widely recognised "go/record" affordance.
--mks-off	#9E9E9E	Idle / not recording. Neutral gray, not red (red implies error). Material Gray 500.
--mks-error	#FFB300	Recoverable error (codec failure, buffer empty, etc.). Match BADGE_ERROR_COLOR. Material Amber 600 — caution not catastrophe.
--mks-fatal	#D32F2F	Unrecoverable state (rare). Material Red 700.

Accessibility constraint: All four colors must meet WCAG AA 4.5:1 contrast when paired with their badge text color. White text on --mks-rec and --mks-fatal; black text on --mks-off and --mks-error.

3.2 UI surfaces

Token	Hex	Use
--mks-surface-bg	#222222	Smoke-test page background (current); also acceptable for popup dark mode
--mks-surface-text	#EEEEEE	Text on dark surfaces
--mks-surface-code	#444444	Inline code background (dark theme)
--mks-popup-bg-light	#FFFFFF	Popup background, light Chrome theme
--mks-popup-bg-dark	#1F1F1F	Popup background, dark Chrome theme
--mks-popup-fg-light	#202124	Popup text, light theme (matches Chrome's Material 3)
--mks-popup-fg-dark	#E8EAED	Popup text, dark theme

3.3 Diagnostic / dev-only

Token	Hex	Use
--mks-diag-bg	#000000	Smoke-test timer overlay background
--mks-diag-fg	#00FF00	Smoke-test timer overlay text (high-contrast monospace)

---

4. Typography

System fonts only. No web-font loads — keeps the extension CSP simple and load-time near-zero. Falls back gracefully on every OS.

Family token	Stack	Use
--mks-font-ui	-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif	All UI text (popup, welcome page, notifications-rendered-as-pages)
--mks-font-mono	"SF Mono", Menlo, Consolas, "Courier New", monospace	Diagnostic overlays, code, timer

4.1 Type scale

Token	Size	Line-height	Use
--mks-text-xs	11px	1.3	Badge labels, status pills, footnotes
--mks-text-sm	13px	1.4	Secondary UI text, captions
--mks-text-base	15px	1.5	Body text, popup messages, notification body
--mks-text-lg	18px	1.4	Section headings within popup
--mks-text-xl	24px	1.3	Welcome page H1, primary call-to-action
--mks-text-xxl	32px	1.2	Diagnostic timer (smoke), large status

4.2 Weights

• 400 (regular): all body text
• 500 (medium): UI labels, badge text
• 700 (bold): primary CTAs, status indicators (REC/OFF/ERROR)

Avoid 600 / italic — keep the weight ladder tight.

---

5. Iconography

5.1 Style

• Solid filled (not outline). Solid icons read better at 16px/48px sizes where extension icons live; outline detail is lost at small sizes.
• 24×24 source grid with 2px padding (effective icon area 20×20). Standard Material/Apple icon-grid convention; ensures consistent visual weight.
• Single accent color or two-tone max. Reserve color complexity for badges and notifications.

5.2 Mark concept (action.default_icon)

The extension's primary mark serves 3 roles simultaneously:

• Browser toolbar icon (16/32 — tiny; needs immediately-readable silhouette)
• Extensions page icon (48 — moderate; can carry a bit more detail)
• Chrome Web Store + notification icon (128 — full detail)

Recommended motif: a "recording dot inside a thread spool / frame". A red-or-green circle inside a hexagonal/circular frame. Reads as: "this thing records." The frame nods at the Mokosh "weaving" theme without literally showing thread (which would be unreadable at 16px).

Alternative (cleaner, more conventional): just a filled red circle with a thin white inner ring — looks like a record button, no thematic baggage. Slightly less distinctive but immediately understood.

Color in the mark: the mark uses --mks-rec (green) when REC overlay would be added by Chrome's badge anyway, OR a neutral mark with state communicated purely via badge. Recommended: neutral mark, state via badge. Keeps the icon recognizable across all states.

5.3 Inline glyphs

For popup and welcome page:

Concept	Glyph	Notes
Save / download	⬇ filled-arrow-into-tray	20px in popup
Stop	■ filled-square	Reserved for explicit stop control (see Section 10)
Recording active	● solid-circle in --mks-rec	Pulsing optional (see Section 7)
Error	▲ filled-triangle with !	--mks-error background
Settings	⚙ filled-gear	Reserved; not currently surfaced
Welcome / intro	🧵 thread/spool emoji is currently used in smoke; replace with custom glyph at design time

---

6. Spacing

Base unit: 4px. All spacing values are multiples of this base.

Token	Value	Use
--mks-space-1	4px	Tight padding within badges
--mks-space-2	8px	Default padding inside controls
--mks-space-3	12px	Padding inside popup containers
--mks-space-4	16px	Section separation
--mks-space-6	24px	Welcome page section gaps
--mks-space-8	32px	Welcome page hero spacing

6.1 Surface sizing

Surface	Size	Notes
Popup default	320×200	Chrome auto-sizes; this is the comfortable target
Welcome page	full viewport, max-width 720px content column	Plan 01-10
Notification	Chrome-controlled (basic type, ~360px wide)	iconUrl + title + message
Toolbar badge text	max 4 chars	Chrome truncates beyond

---

7. Motion

Conservative. Motion draws attention; the extension should draw attention only on state change.

Motion	Duration	Easing	Use
Hover transitions	150ms	ease-out	Buttons, links
Badge state change	instant	—	REC/OFF/ERROR transitions; no animation
Recording pulse (optional)	1000ms loop	ease-in-out	Subtle 0.85→1.0 opacity loop on REC badge if surface allows. Currently used in smoke .flash class — adopt for badge if Chrome's badge API allows (it doesn't natively; would need an action.setIcon swap on interval, which has perf cost — recommend OFF for now).
Notification slide	Chrome default	—	We don't control
Welcome page CTA hover	200ms	ease-out	Background-color + scale 1.0→1.02

---

8. Component conventions

8.1 Toolbar action (chrome.action)

States:

• Idle — neutral mark, badge text empty (or ""), background transparent
• REC — neutral mark + badge text "REC" + background --mks-rec
• ERROR — neutral mark + badge text "ERR" + background --mks-error
• OFF (post-stop, awaiting restart) — neutral mark + badge text "OFF" + background --mks-off

Tooltip (chrome.action.setTitle) communicates current state in Russian:

• Idle: "Mokosh — щёлкните, чтобы начать запись"
• REC: "Mokosh — идёт запись (00:42)" (with live duration)
• ERROR: "Mokosh — ошибка записи, щёлкните для восстановления"
• OFF: "Mokosh — запись остановлена, щёлкните, чтобы начать снова"

8.2 Notification

Use chrome.notifications.create with type: 'basic':

{
  type: 'basic',
  iconUrl: chrome.runtime.getURL('icons/icon128.png'),  // hi-res required
  title: 'Mokosh',                                      // short, branded
  message: 'Recording started.' | 'Recording stopped.' | etc.,  // Russian
  priority: 1,                                          // default; 2 only for urgent
}

Notifications fire on:

• Startup prompt (every Chrome session) — until operator clicks once
• Recovery prompt (after user-stopped-sharing) — once
• Save complete (optional acknowledgement) — Phase 5 candidate

Avoid notification spam — at most one notification per state transition.

8.3 Popup (SAVE-only per Plan 01-09)

• Compact: 320×200 max
• Single primary CTA: "Сохранить отчёт об ошибке" (full-width)
• Status line above CTA: "Запись активна, последние 30 сек захвачены"
• Footer: small text with recording duration ("XX:XX") for trust
• No secondary actions in REC mode
• ERROR mode: replace CTA with restart-recording action; status line shows error reason

8.4 Welcome page (Plan 01-10)

• Full viewport, dark theme matching --mks-popup-bg-dark
• Hero: large mark + name + 1-line tagline
• Body: 2-3 short bullets explaining what Mokosh does (operator-readable Russian)
• Primary CTA: "Начать запись" button — large, --mks-rec background, white text
• Footer: privacy note ("Mokosh записывает только ваш экран; данные остаются у вас")

---

9. Accessibility & internationalization

• Contrast: WCAG AA (4.5:1 normal, 3:1 large text). All semantic-state pairings pre-validated above.
• Focus: visible focus rings on all interactive elements (popup buttons, welcome page CTA). Use Chrome's default outline: 2px solid auto.
• Color-independence: every color-coded state pairs with text (REC/OFF/ERR badge labels; never color alone).
• Localization: all user-facing strings are Russian per SPEC. UI scaffolding must support future English/other-locale strings via standard Chrome _locales/ mechanism (deferred — no MVP requirement).
• Reduced motion: if recording-pulse animation is ever enabled (see §7), honor prefers-reduced-motion: reduce by falling back to static.

---

10. Open design decisions

These are visual choices that need a human design pass before locking:

#	Question	Default if undecided
ODD-1	Mark concept: thread/spool motif OR clean record-button	Clean record-button (faster to produce; recognizable; no thematic risk)
ODD-2	Pulsing REC badge animation	OFF (Chrome badge API doesn't support; would need setIcon interval; perf cost)
ODD-3	Tagline final wording	"Записывает, чтобы вы могли воспроизвести." (above)
ODD-4	Welcome page hero illustration	None — type-only hero
ODD-5	Notification iconUrl: same as toolbar mark OR distinct?	Same — operator should recognise the source
ODD-6	Dark/light theme detection in popup	Auto via prefers-color-scheme (uses Chrome theme by default)

---

11. Implementation notes

• All extension contexts (SW, offscreen, popup, welcome page) share the same CSP. No external font/asset loads. Everything bundled or chrome.runtime.getURL.
• Icons must be in dist/icons/ and declared in both manifest.json icons AND action.default_icon.
• Notification iconUrl uses chrome.runtime.getURL('icons/icon128.png') — at least 128×128, ideally 192×192 for retina. Smaller icons silently fail Chrome's imageUtil validation.
• All popup HTML/CSS lives in src/popup/. All welcome HTML/CSS lives in src/welcome/ (Plan 01-10).
• Inline SVG preferred over PNG where the surface permits — sharper at all DPIs. Chrome's notification API REQUIRES PNG iconUrl though.

---

12. Related

• assets-spec.md — concrete deliverables list (specific files, sizes, formats) derived from this design system
• src/background/index.ts — implements toolbar action + notification per §8
• src/popup/index.html — implements popup per §8.3
• src/welcome/welcome.html — implements welcome per §8.4 (Plan 01-10)
• .planning/phases/01-stabilize-video-pipeline/01-CONTEXT.md D-16-toolbar, D-15-display-surface amendments — interaction model this design system visually realises