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

Mokosh Design System

Cross-phase visual + interaction reference for the Mokosh extension (internal codename "Mokosh"; public display name currently "AI Call Recorder" — open per brand-identity.md). Authored 2026-05-17 in response to Plan 01-09's notification-icon discovery that the original placeholder PNGs failed Chrome's notification API.

This file mixes two kinds of content and the design team should treat them differently:

1. Engineering sketches — what the extension currently ships in placeholder builds (colors, fonts, sizes, voice). These exist so the extension runs; they are not direction. Override anything aesthetic.
2. Technical floors — what Chrome MV3, the notification API, MV3 CSP, or WCAG accessibility require. These are binding regardless of creative direction. Marked explicitly with (FLOOR) wherever they appear.

Status: draft — engineering sketch + binding floors. Both design and brand teams have full authority over everything not marked (FLOOR).

---

What's locked vs what's open

Decision	Status
Codename "Mokosh"	LOCKED (engineering — wired through code)
Public display name	OPEN (brand team)
All color hexes + token names	OPEN (design team)
Typography face(s) and scale	OPEN (design team) — must cover Cyrillic, must bundle locally (FLOOR)
Iconography style + mark concept	OPEN (design team) — must ship at 16/48/128 px PNG with file-size floors (FLOOR)
Spacing scale, corner radii, motion	OPEN (design team)
Brand voice, tagline, copy	OPEN (brand team)
Welcome-tab layout + treatment	OPEN (design team)
WCAG AA contrast	FLOOR (legal/accessibility — not creative)
Chrome notification API icon ≥ 128 px	FLOOR
MV3 CSP (no remote fonts/scripts, no unsafe-eval)	FLOOR
Toolbar badge text max 4 chars	FLOOR (Chrome truncates)
Russian-first audience	FLOOR (product, not visual) — visuals must work without depending on language for legibility

Everything below is engineering's current sketch, framed as starting options, unless explicitly tagged (FLOOR).

---

1. Brand voice (OPEN — brand team)

Engineering has no opinion. Axes to decide:

• Warmth — clinical / neutral / warm / friendly
• Formality — system-terse / professional / conversational / casual
• Humour — none / dry / occasional / playful
• Emoji policy — never / functional only (✓ × ⚠) / freely
• Two-register vs single-register — toolbar/notification copy can match welcome-tab copy, or diverge (e.g. terse system messages vs full-prose onboarding)

Engineering's current placeholder voice in shipped strings is calm, brief, operationally serious — chosen because the product runs for operators under stress. This is a defensible starting point and equally defensible to replace entirely.

---

2. Identity (OPEN except codename)

Codename (LOCKED)	Mokosh — Slavic goddess of weaving and fate
Public display name (OPEN — brand)	Currently placeholder "AI Call Recorder". See brand-identity.md §2 for options.
Tagline (OPEN — brand)	Currently placeholder "Записывает, чтобы вы могли воспроизвести." ("Records so you can reproduce.") Replace, translate, or drop.
Mark concept (OPEN — design)	See §5 below — engineering sketches one possible direction; design team picks from anything.

---

3. Color (OPEN — design team)

Engineering currently ships the placeholder palette below so the extension runs. Every hex is open. Every token name is open. The whole palette strategy is open.

3.1 Engineering's current placeholder palette

Token	Hex	Currently used for
--mks-rec	#00C853	Toolbar badge background when recording (Material Green A700)
--mks-off	#9E9E9E	Toolbar badge background when idle
--mks-error	#FFB300	Toolbar badge background on recoverable error (Material Amber 600)
--mks-fatal	#D32F2F	Toolbar badge background on unrecoverable state (Material Red 700)
--mks-surface-bg	#222222	Smoke-test page / dark popup surfaces
--mks-surface-text	#EEEEEE	Text on dark surfaces
--mks-popup-bg-light	#FFFFFF	Popup background, light Chrome theme
--mks-popup-bg-dark	#1F1F1F	Popup background, dark Chrome theme
--mks-diag-bg / --mks-diag-fg	#000000 / #00FF00	Smoke-test timer overlay (dev-only — keep monospace + high-contrast for legibility, but recolor freely)

3.2 Palette directions for the design team to choose from

Direction matters more than specific hexes. Options without ranking:

• Dark-mode-native, monochrome + single accent for "recording" (current placeholder)
• Light-mode primary with dark-mode variant
• Multi-accent — separate distinguishing color per state beyond just green/yellow/red
• Warm / earthy — browns, ochres, off-whites
• Cool / clinical — blues, grays, white
• High-contrast monochrome — pure black/white + one accent
• Whatever the design team coins

3.3 Mechanical hooks the palette has to fill

(Not creative — these are surfaces engineering wires colors into.)

• chrome.action.setBadgeBackgroundColor(...) — one color per toolbar badge state
• Popup background + text (two themes if supporting both Chrome light/dark)
• Welcome-tab background + text
• Smoke-test diagnostic overlay (dev-only — design team can ignore)

If the design team lands on N states beyond recording/idle/error, engineering adapts the badge wiring.

---

4. Typography (OPEN — design team, with one floor)

Engineering ships system stack as a placeholder. Open to replacement.

4.1 Technical floor (FLOOR — KEEP)

• Must cover Cyrillic glyphs. Russian operators are primary. Latin-only faces are non-starters.
• Must bundle locally. MV3 CSP forbids remote @font-face from external CDNs. Any custom face ships as a static asset in dist/.
• Should not block the service worker. The SW has no DOM and renders no text; this only matters for popup + welcome.

4.2 Engineering's current placeholder stack

Family token	Stack	Currently used for
--mks-font-ui	-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif	All UI text
--mks-font-mono	"SF Mono", Menlo, Consolas, "Courier New", monospace	Diagnostic overlays, code, timer

Chosen for zero-load, no FOUT, automatic Cyrillic coverage on every OS. Equally valid: a licensed custom face (Inter, IBM Plex Sans, JetBrains Mono, or anything), variable fonts, a type pair, a different system fallback chain.

4.3 Engineering's current type scale (placeholder)

Token	Size	Line-height	Currently used for
--mks-text-xs	11px	1.3	Badge labels, footnotes
--mks-text-sm	13px	1.4	Secondary UI text
--mks-text-base	15px	1.5	Body text
--mks-text-lg	18px	1.4	Section headings within popup
--mks-text-xl	24px	1.3	Welcome page H1
--mks-text-xxl	32px	1.2	Diagnostic timer, large status

Replace freely. Modular scale, fluid type, t-shirt sizes — design team picks.

4.4 Engineering's current weight ladder (placeholder)

• 400 (regular), 500 (medium), 700 (bold)

Replace freely.

---

5. Iconography (OPEN — design team, with floors)

5.1 Technical floors (FLOOR — KEEP)

• Sized PNGs at 16, 48, 128 px in dist/icons/, declared in manifest.json:icons and manifest.json:action.default_icon
• The 128 px is required for chrome.notifications.create({type:'basic'}) to render an iconUrl
• File-size minimums per assets-spec.md (Chrome silently rejects icons below ~200 B / 500 B / 1 KB at the three sizes)
• Optional 192 px variant for hi-DPI notification rendering
• Inline SVG preferred for popup/welcome surfaces where Chrome permits — sharper at all DPIs. Chrome's notifications.create REQUIRES PNG iconUrl though.

5.2 Engineering's current placeholder direction

Solid-filled, 24×24 source grid with 2 px padding, neutral mark + state via badge (the toolbar icon itself doesn't change between idle/recording — the chrome.action.setBadgeBackgroundColor does the state work).

This is one of many possible directions. Equally valid:

• Line-only icons
• Mixed (solid for primary, line for secondary)
• Per-state icon swaps via chrome.action.setIcon (adds perf cost — see §7)
• Animated SVG icons
• Illustrated mark (full scene rather than abstract glyph)

5.3 Mark concept (OPEN — design team)

Engineering's current placeholder is "dark square + green dot" via ImageMagick. No mark direction is implied. Possible directions:

• Recording-dot inside a frame (conventional, immediately readable as "records")
• Thread/spool/weave motif (leans into the Mokosh etymology)
• Abstract geometric mark (no figurative reference)
• Wordmark only (the letterforms are the mark)
• Illustrated mascot
• Whatever the design team coins

Constraints: must resolve at 16 px (a strong silhouette is hard at that size), must work neutral OR colored (depending on the team's badge-vs-icon-state decision).

5.4 Inline glyphs (OPEN — design team)

The popup and welcome surfaces need glyphs for actions and states. Concepts engineering currently shows:

Concept	Currently shown as	Design-team-owned
Save / download	⬇ filled-arrow-into-tray (Unicode, placeholder)	Replace with custom glyph or icon font
Stop	■ filled-square (placeholder)	—
Recording active	● solid-circle (placeholder)	—
Error	▲ filled-triangle with ! (placeholder)	—
Settings	⚙ filled-gear (placeholder; not currently surfaced)	—
Welcome / intro	🧵 thread emoji (smoke-test placeholder only)	Replace at design time

---

6. Spacing (OPEN — design team)

Engineering currently uses a 4 px base with the steps below as placeholders. Replace with any base (8 px, variable, t-shirt sizes, golden-ratio, etc.).

Token	Value	Currently used for
--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 — current placeholders + technical floors

Surface	Engineering's placeholder	Floor / mechanism
Popup	320 × 200 (comfortable; Chrome auto-sizes)	Chrome popups auto-size; no hard max
Welcome page	full viewport, content max-width 720 px	None — fully open
Notification	Chrome-controlled (~360 px wide)	(FLOOR) — not styleable
Toolbar badge text	max 4 chars	(FLOOR) — Chrome truncates beyond

---

7. Motion (OPEN — design team)

Engineering currently ships near-zero motion (200–300 ms opacity fades, no bounce) because the product promise is unobtrusiveness. Equally valid:

• Lively spring physics
• Fully static (no transitions at all)
• Cinematic entrances on welcome
• Subtle micro-interactions on every state change

Engineering's current placeholder durations:

Where	Duration	Easing	Notes
Hover transitions	150ms	ease-out	Buttons, links
Badge state change	instant	—	No animation (Chrome badge API doesn't support; setIcon swap interval would cost perf)
Welcome page CTA hover	200ms	ease-out	Background-color + slight scale
Notification slide	Chrome default	—	(FLOOR) — not controllable

Per-state icon swap animation (e.g. recording-pulse) is possible but adds setIcon interval cost; design team picks if worth it.

---

8. Component conventions

Two layers per component: functional contract (KEEP — comes from PLAN, not creative direction) and visual treatment (OPEN — design team).

8.1 Toolbar action (chrome.action)

Functional contract (KEEP):

• Three states surface to operators: IDLE, REC, ERROR (some teams add OFF as a distinct post-stop state)
• Click behavior depends on state — IDLE click starts recording; REC click opens SAVE popup; ERROR click opens RESTART popup
• Tooltip text changes per state via chrome.action.setTitle

Visual treatment (OPEN):

• Badge background color per state (currently mapped to --mks-rec / --mks-off / --mks-error)
• Badge text per state (currently "" / "REC" / "ERR" / "OFF")
• Tooltip wording (currently Russian, placeholder copy below — brand team rewrites)
  • IDLE: "Mokosh — щёлкните, чтобы начать запись"
  • REC: "Mokosh — идёт запись (00:42)"
  • ERROR: "Mokosh — ошибка записи, щёлкните для восстановления"

8.2 Notification

Functional contract (KEEP):

• Fired via chrome.notifications.create({type:'basic', iconUrl, title, message, priority})
• iconUrl must be a ≥128 px PNG via chrome.runtime.getURL (FLOOR)
• Fires on startup (until operator dismisses), on recovery (after user-stopped-sharing), optionally on save-complete (Phase 5 candidate)
• One notification per state transition (no spam)

Visual treatment (OPEN):

• Title text (currently "Mokosh")
• Message text (brand team rewrites)
• priority (1 default, 2 for urgent — design team can pick when to escalate)

8.3 Popup (current scope: SAVE-only per Plan 01-09)

Functional contract (KEEP):

• Represents the current toolbar state (REC / ERROR; IDLE shouldn't normally surface here)
• REC state offers a single primary action: save the buffered archive
• ERROR state offers a single primary action: restart recording
• No secondary actions in either state (Plan 01-09 scope decision)

Visual treatment (OPEN):

• Sizing (current placeholder 320 × 200)
• CTA wording (current placeholder Russian; brand team rewrites)
• Layout (CTA position, status line, footer)
• Status messaging copy
• Dark/light theme handling (current placeholder: auto via prefers-color-scheme)

8.4 Welcome page (Plan 01-10)

Functional contract (KEEP):

• Opens via chrome.tabs.create on first install
• Static HTML/CSS/JS in dist/ (no remote loads (FLOOR))
• Must communicate: what Mokosh does, how the operator triggers a save, privacy story

Visual treatment (OPEN — design team owns entirely):

• Layout (hero + steps, scrolling story, modal, video walkthrough, anything)
• Tone (welcome cheer vs sober briefing — brand team)
• Hero treatment (wordmark-only, mark + wordmark, illustrated scene, video)
• Primary CTA wording + placement
• Whether there's a CTA at all (some onboarding flows just inform)

---

9. Accessibility & internationalization (FLOORS — KEEP)

These are functional/legal floors, not creative:

• Contrast: WCAG AA (4.5:1 normal text, 3:1 large text). Any palette the design team lands on must validate against this for all state pairings. Engineering's current placeholder palette is pre-validated; new palettes need re-validation.
• Focus indicators: visible focus rings on all interactive elements (popup buttons, welcome CTA). Chrome's default outline works; custom focus styles welcome as long as they remain visible.
• Color-independence: every color-coded state must pair with text or shape. Color alone is not an accessible state indicator — pairs with badge labels, glyphs, or copy.
• Russian-first localization: all user-facing strings ship in Russian as the default locale. UI scaffolding must support future locales via Chrome's _locales/ mechanism.
• Reduced motion: if any animation is enabled, honor prefers-reduced-motion: reduce by falling back to static.

---

10. Open creative decisions

Non-exhaustive list for both teams. None block engineering today (placeholders ship); each unlocks a polish pass when answered.

1. Public display name (brand-identity.md §2)
2. Design system name (brand-identity.md §3)
3. Voice register — one tone or two (system-terse vs welcome-prose)
4. Tagline final wording (currently "Записывает, чтобы вы могли воспроизвести.")
5. Palette direction (§3.2) + specific hexes
6. Token naming convention (--mks-rec placeholder pattern)
7. Typography face(s) — system stack vs custom
8. Type scale + weight ladder
9. Spacing base + steps
10. Corner radii — sharp / soft / mixed
11. Iconography style — solid / line / mixed
12. Mark concept (§5.3)
13. Per-state icon swaps vs fixed mark + dynamic badge
14. Motion vocabulary — minimal / lively / static
15. Welcome-tab layout + treatment (§8.4)
16. Popup layout treatment (§8.3 visual)
17. Notification copy + tone (§8.2)
18. Tooltip wording per state (§8.1)
19. Dark/light theme strategy — auto-detect, follow-Chrome, force one, user-toggle

---

11. Implementation notes (TECHNICAL — KEEP)

• All extension contexts (SW, offscreen, popup, welcome page) share the same CSP. No external font/asset loads. Everything bundled or chrome.runtime.getURL. (FLOOR)
• Icons must be in dist/icons/ and declared in both manifest.json:icons AND manifest.json:action.default_icon. (FLOOR)
• 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. (FLOOR)
• All popup HTML/CSS lives in src/popup/. All welcome HTML/CSS lives in src/welcome/ (Plan 01-10). (file convention — easy to change)
• Inline SVG preferred over PNG where the surface permits — sharper at all DPIs. Notification API requires PNG. (FLOOR for notification only)

---

12. Related

• brand-identity.md — naming + blurb + voice (Brief #1)
• assets-spec.md — concrete file deliverables + technical floors
• 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-15/D-16/D-17 amendments — interaction model this design language sits inside