# Design Guidelines

## Product Goal

Build a modern TeamSpeak 3 client for everyday users that feels clean, fast, minimal, and voice-first. The app should stay familiar to existing TeamSpeak users while adopting an Apple-style interface inspired by Finder, FaceTime, Apple Music, and System Settings.

The first version is a personal voice client, not a server administration tool.

## MVP Focus

The first version should prioritize:

- connecting to TeamSpeak 3 servers
- bookmarks and recent servers
- browsing and joining channels
- voice chat with push-to-talk and voice activation
- microphone mute and deafen
- input/output device selection
- global and per-user volume controls
- speaking, muted, deafened, and away indicators
- basic server, channel, and private chat
- identity management
- hotkeys
- notifications
- light and dark mode

The first version should explicitly exclude:

- server management
- permissions and group editors
- ban tools and logs
- file transfer
- plugin support
- whisper system
- advanced moderation flows
- overlays

## Core Design Principles

### Voice First

The UI should make the user's voice state obvious at all times.

Users should always be able to quickly understand:

- whether they are connected
- which channel they are in
- whether the microphone is live or muted
- whether output is deafened
- whether push-to-talk or voice activation is active
- whether audio devices are correctly selected

### Simple by Default

Default surfaces should stay compact and calm.

Prefer:

- clean navigation
- compact controls
- context menus
- popovers
- focused settings categories
- progressive disclosure for advanced options

Avoid:

- dense admin-style toolbars
- technical tables in primary flows
- large clusters of small icons
- exposing advanced TeamSpeak administration features in the core UI

### Apple-Style UI

The interface should use:

- soft backgrounds
- rounded cards and buttons
- subtle shadows
- thin dividers
- spacious padding
- calm accent colors
- strong typography hierarchy
- minimal visual noise

The app should feel lightweight and polished rather than industrial or admin-heavy.

## Visual System

### Colors

Light mode:

- Background: `#F5F5F7`
- Surface: `#FFFFFF`
- Elevated Surface: `#FBFBFD`
- Primary Accent: `#007AFF`
- Text Primary: `#1D1D1F`
- Text Secondary: `#6E6E73`
- Border: `#D2D2D7`
- Success: `#34C759`
- Warning: `#FF9500`
- Danger: `#FF3B30`
- Muted: `#8E8E93`

Dark mode:

- Background: `#000000`
- Surface: `#1C1C1E`
- Elevated Surface: `#2C2C2E`
- Primary Accent: `#0A84FF`
- Text Primary: `#F5F5F7`
- Text Secondary: `#AEAEB2`
- Border: `#38383A`
- Success: `#30D158`
- Warning: `#FF9F0A`
- Danger: `#FF453A`
- Muted: `#8E8E93`

### Typography

- Large Title: 32px, weight 700
- Title: 24px, weight 600
- Section Title: 17px, weight 600
- Body: 15px, weight 400
- Small: 13px, weight 400
- Caption: 11px, weight 500

Preferred family order:

- SF Pro Display
- SF Pro Text
- Inter
- system UI fallback

### Spacing And Sizing

- Tiny: 4px
- Small: 8px
- Medium: 12px
- Large: 16px
- XL: 24px
- XXL: 32px

Recommended component sizes:

- Sidebar width: 220px
- Channel row height: 36px
- User row height: 34px
- Card radius: 16px
- Button radius: 12px
- Popover radius: 18px
- Main content padding: 20px

## App Structure

The main information architecture should be:

- Home
- Servers
- Bookmarks
- Recent Servers
- Active Server
- Identities
- Settings

Settings should be organized into:

- General
- Audio
- Capture
- Playback
- Hotkeys
- Notifications
- Appearance
- Chat
- Identities
- Advanced

## Main Layout

Use a two-column structure:

- left sidebar for navigation, bookmarks, and recent servers
- main content area for home, active server, identities, and settings

### Sidebar

The sidebar should expose:

- Home
- Bookmarks
- Recent Servers
- Identities
- Settings

Server state indicators should be simple and readable:

- connected
- disconnected
- connecting
- error

### Active Server View

The active server view should emphasize:

- server name and connection state
- channel tree
- users inside channels
- current channel
- chat access
- compact persistent voice status

The layout should avoid looking like a legacy server management client.

## Persistent Voice Status

Voice controls must always be accessible, but they do not need to live in a large bottom bar.

Use a compact voice capsule near the bottom of the active server view.

The capsule should show:

- connection state
- current channel
- microphone state
- talk mode
- optional latency or quick device status

Selecting the capsule can open a lightweight popover with:

- microphone device
- output device
- talk mode
- volume
- mute mic
- deafen
- disconnect

## Home Screen

The home screen should help the user return to voice quickly.

Primary content:

- continue last server
- favorite servers
- recent servers
- current audio device
- current voice mode

## Connection Flow

The connect flow should support:

- server address
- nickname
- password
- default identity
- reconnect
- disconnect
- connection status
- ping and packet loss
- clear error states

Advanced connection options should stay behind a collapsed or secondary section.

Errors should use human-readable copy such as:

- unable to connect to server
- wrong server password
- server is full
- connection lost

## Bookmarks

Bookmarks should support:

- add
- edit
- delete
- reorder
- favorite servers
- recent servers
- default nickname per bookmark
- default identity per bookmark
- optional stored password
- optional default channel

The bookmark UI should be lightweight and optimized for quick connect.

## Channel Browser

The channel browser should support:

- nested channel tree
- expand and collapse
- current channel highlighting
- join on selection
- user counts
- locked, passworded, and full states
- channel and user search

The first version should not expose channel creation or editing flows.

## User Presence

Each user row should show, when available:

- nickname
- speaking state
- muted state
- deafened state
- away state
- idle state
- local mute state
- server group badge

User actions for the first version:

- view basic info
- adjust per-user volume
- mute locally
- send private message
- copy unique ID

Do not expose moderation actions in the primary first-version UI.

## Voice Features

Required voice modes:

- push-to-talk
- voice activation
- optional continuous transmission

Required controls:

- mute microphone
- deafen
- select input device
- select output device
- adjust output volume
- adjust microphone gain
- test microphone
- test speakers
- show microphone level
- show activation threshold
- adjust per-user volume

Default mode should be push-to-talk.

## Chat

The first version should support:

- server chat
- channel chat
- private messages

Chat should include:

- timestamps
- sender nickname
- basic formatting
- copy message
- clear local conversation
- unread indicators
- open links

Do not include threads, reactions, attachments, or rich embeds.

## Identities

Identity handling is part of the first version.

Support:

- create
- rename
- delete
- import
- export
- choose default identity
- assign identity per bookmark
- show unique ID
- show security level when available

## Hotkeys And Notifications

Hotkeys should cover:

- push-to-talk
- mute microphone
- deafen
- toggle away
- volume up and down
- open settings
- open search or command palette
- disconnect

The client should detect conflicts and support reset.

Notifications should cover:

- connected and disconnected
- connection lost
- current-channel join and leave events
- private messages
- mute and unmute state changes
- errors

## Appearance

Appearance options should include:

- light mode
- dark mode
- follow system
- compact mode
- comfortable mode
- avatar visibility
- group badge visibility
- font size adjustments

## Search And Command Palette

The app should include a simple command/search interface, opened by `Cmd+K` on macOS and `Ctrl+K` elsewhere.

Search targets:

- bookmarks
- recent servers
- channels
- users
- settings

Common actions:

- join channel
- search user
- mute microphone
- deafen
- open audio settings
- connect to server

## Accessibility

The client should support:

- full keyboard navigation
- screen reader labels
- high contrast mode
- reduce motion mode
- large text mode
- color-blind-safe indicators
- visible focus states
- text labels for important icons

Voice status must never rely on color alone.

## Performance

The app should remain responsive on large servers.

Design and implementation should aim for:

- 500+ visible users
- deep channel trees
- smooth scrolling
- lazy rendering for large trees
- fast search
- low idle CPU and memory use
- UI and audio work staying decoupled
- reconnect without freezing the UI

## Platform Notes

### macOS

Prefer macOS-style patterns such as:

- sidebar navigation
- system light and dark mode
- native-feeling shortcuts
- menu bar integration where useful

### Windows

Keep the visual style Apple-inspired, but respect Windows expectations such as:

- notifications
- tray support
- device switching
- game-friendly push-to-talk behavior

### Linux

Support:

- PipeWire
- PulseAudio
- desktop theme integration where practical
- global hotkeys where possible

## Implementation Priorities

### Must Have

- server connection
- bookmarks and recents
- channel tree
- voice chat
- push-to-talk and voice activation
- mute and deafen
- device selection
- speaking indicators
- chat and private messages
- identity import and export
- light and dark mode

### Should Have

- auto reconnect
- notification profiles
- hotkey editor
- microphone test
- speaker test
- level meter
- search
- compact mode
- command palette

### Later

- temporary channel creation
- basic moderation actions
- overlay
- server management
- permissions
- whisper
- file transfer
- plugin or theme extensions

## Final Standard

Every UI decision for the first version should reinforce one promise:

> A clean, modern, Apple-style TeamSpeak 3 client for joining servers, talking with people, and managing your own voice experience.