551 lines
10 KiB
Markdown
551 lines
10 KiB
Markdown
# 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.
|