HostKeeper/docs/UI_TERMIUS_REFERENCE.md

Hostkeeper V2 — Termius UI Reference

Status: V2 Planning Complete Last Updated: 2026-06-29 Purpose: Visual reference for replicating Termius-like UI in Hostkeeper V2.

---

1. Termius Design Analysis

Design Philosophy

Termius follows a dark-first, minimal, professional design language:

• Dark backgrounds with muted colors
• High contrast for active elements
• Subtle hover states (no harsh highlights)
• Generous padding and whitespace
• Rounded corners (subtle, not bubbly)
• Consistent iconography (Feather-style line icons)

Key Design Principles

1. Content-first — Terminal/SFTP content takes maximum space
2. Sidebar minimal — Thin sidebar, collapsible, icons + labels
3. Tab bar compact — Small tab height, status dots, close buttons
4. Forms clean — Labeled inputs, generous spacing, clear validation
5. Modals focused — Centered, focused, one task at a time

---

2. Color Palette

Dark Theme (Default)

Element	Color	Hex
Background (main)	Deep navy	#0d1117
Surface (cards, sidebar)	Slightly lighter	#161b22
Surface hover	Subtle highlight	#1c2128
Surface active	Selected state	#21262d
Border	Muted line	#30363d
Text primary	White	#e6edf3
Text secondary	Muted gray	#8b949e
Text tertiary	Dim	#484f58
Accent (primary)	Blue	#58a6ff
Accent hover	Lighter blue	#79c0ff
Success	Green	#3fb950
Warning	Yellow	#d29922
Error	Red	#f85149
Info	Blue	#58a6ff

Light Theme

Element	Color	Hex
Background (main)	White	#ffffff
Surface	Light gray	#f6f8fa
Surface hover	Slightly darker	#eaeef2
Border	Light line	#d0d7de
Text primary	Dark	#1f2328
Text secondary	Gray	#656d76
Accent (primary)	Blue	#0969da

High Contrast Theme

Element	Color	Hex
Background	Pure black	#000000
Surface	Near black	#0a0a0a
Border	Bright white	#ffffff
Text primary	Pure white	#ffffff
Accent	Bright blue	#4da6ff

---

3. Typography

Font Stack

/* UI text */
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

/* Terminal / code */
font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace;

Font Sizes

Element	Size	Weight
App title	16px	600 (semibold)
Section heading	14px	600 (semibold)
Body text	13px	400 (regular)
Small text	12px	400 (regular)
Caption	11px	400 (regular)
Terminal default	14px	400 (regular)
Terminal small	12px	400 (regular)

Line Heights

Element	Line Height
Headings	1.3
Body	1.5
Terminal	1.2

---

4. Spacing System

Based on 4px grid:

Token	Value	Usage
--space-1	4px	Tight spacing (icon gaps)
--space-2	8px	Default spacing (inline elements)
--space-3	12px	Component padding
--space-4	16px	Section padding
--space-5	20px	Card padding
--space-6	24px	Section gaps
--space-8	32px	Page padding

---

5. Component Specs

5.1 Sidebar

Width: 240px (default), min 180px, max 400px
Background: var(--surface)
Border-right: 1px solid var(--border)
Padding: 12px (top, bottom)

Sections:
  1. Header (h-9 = 36px)
     - App name (14px, semibold)
     - Collapse button (right-aligned)
  2. Search bar
     - Height: 32px
     - Border-radius: 6px
     - Background: var(--background)
     - Icon: search (left), clear (right)
     - Padding: 0 12px
  3. Group tree
     - Item height: 32px
     - Padding: 0 12px
     - Indent: 16px per level
     - Hover: var(--surface-hover)
     - Active: var(--surface-active)
     - Chevron icon: 14px, muted color
     - Color dot: 8px circle
     - Host count badge: 11px, muted text
  4. Quick actions
     - Fixed at bottom
     - Buttons: icon + label
     - Height: 32px

5.2 Tab Bar

Height: 36px
Background: var(--surface)
Border-bottom: 1px solid var(--border)

Tab:
  - Padding: 0 12px
  - Height: 36px
  - Border-right: 1px solid var(--border)
  - Hover: var(--surface-hover)
  - Active: var(--background)
  - Status dot: 6px circle, left of title
  - Title: 13px, max-width 120px, truncate
  - Close button: 14px, visible on hover, X icon
  - New tab button: + icon, 36px width

5.3 Host List

Background: var(--background)
Padding: 16px

Header:
  - Title: 20px, semibold
  - Actions row: filter chips + view toggle + add button

Host item (list view):
  - Height: 48px
  - Padding: 0 16px
  - Border-bottom: 1px solid var(--border)
  - Hover: var(--surface-hover)
  - Active: var(--surface-active)
  - Left: status dot (6px) + server icon (16px)
  - Center: name (14px, medium) + hostname (12px, muted)
  - Right: favorite star (16px) + last used (12px, muted)

Host item (grid view):
  - Card size: 200x120px
  - Border: 1px solid var(--border)
  - Border-radius: 8px
  - Padding: 12px
  - Hover: border-color changes to accent

5.4 Terminal

Background: #0d1117 (dark) or #ffffff (light)
Font: JetBrains Mono 14px
Cursor: block, blinking

Toolbar (top):
  - Height: 32px
  - Background: var(--surface)
  - Border-bottom: 1px solid var(--border)
  - Left: host name (14px, medium) + status dot
  - Right: reconnect button, snippet toggle, settings

Status bar (bottom):
  - Height: 24px
  - Background: var(--surface)
  - Border-top: 1px solid var(--border)
  - Left: connection status text (12px)
  - Right: cols x rows (12px, muted)

5.5 SFTP Browser

Background: var(--background)

Pane:
  - Width: 50% (side-by-side) or 100% (stacked)
  - Header: 32px, path breadcrumb
  - Content: file list (table)
  - Footer: 24px, transfer status

File list columns:
  - Name: flex-1, 13px
  - Size: 80px, right-aligned, 12px, muted
  - Date: 120px, 12px, muted
  - Permissions: 80px, 12px, monospace, muted

Row:
  - Height: 32px
  - Padding: 0 12px
  - Hover: var(--surface-hover)
  - Selected: var(--surface-active)
  - Folder icon: yellow
  - File icon: default color

5.6 Forms

Input:
  - Height: 36px
  - Border: 1px solid var(--border)
  - Border-radius: 6px
  - Padding: 0 12px
  - Font: 13px
  - Background: var(--background)
  - Focus: border-color: var(--accent)
  - Error: border-color: var(--error)

Label:
  - Font: 12px, medium
  - Color: var(--text-secondary)
  - Margin-bottom: 4px

Error message:
  - Font: 12px
  - Color: var(--error)
  - Margin-top: 4px

Select:
  - Same as input
  - Dropdown: 200px max-height, scrollable
  - Option: 32px height, hover highlight

Button (primary):
  - Height: 36px
  - Padding: 0 16px
  - Border-radius: 6px
  - Background: var(--accent)
  - Color: #ffffff
  - Font: 13px, 500 (medium)
  - Hover: brightness 1.1

Button (ghost):
  - Same dimensions
  - Background: transparent
  - Color: var(--text-primary)
  - Hover: var(--surface-hover)

5.7 Modals

Overlay: rgba(0, 0, 0, 0.5)
Container:
  - Width: 400px (default), max 560px
  - Background: var(--surface)
  - Border-radius: 12px
  - Border: 1px solid var(--border)
  - Shadow: 0 8px 32px rgba(0, 0, 0, 0.3)
  - Padding: 24px
  - Centered on screen

Title:
  - Font: 16px, semibold
  - Margin-bottom: 16px

Actions:
  - Right-aligned
  - Gap: 8px
  - Cancel (ghost) + Confirm (primary)

5.8 Toast Notifications

Position: bottom-right
Width: 360px
Height: auto (min 48px)
Background: var(--surface)
Border: 1px solid var(--border)
Border-radius: 8px
Shadow: 0 4px 12px rgba(0, 0, 0, 0.2)
Padding: 12px 16px

Left: icon (color-coded)
  - Success: green check
  - Error: red X
  - Warning: yellow triangle
  - Info: blue circle
Center: message (13px)
Right: close button (X)

Animation: slide in from right, fade out after 5s

---

6. Layout Breakpoints

Name	Width	Behavior
Mobile	< 600px	Sidebar collapsed, stacked panes, full-width terminal
Tablet	600-1024px	Sidebar narrow (180px), stacked SFTP panes
Desktop	> 1024px	Sidebar normal (240px), side-by-side SFTP panes
Wide	> 1440px	Sidebar wider (300px), more content visible

---

7. Animations

Element	Animation	Duration
Sidebar toggle	Width transition	200ms ease
Tab switch	Background fade	150ms ease
Modal open	Scale from 0.95 + fade	200ms ease
Modal close	Fade out	150ms ease
Toast enter	Slide from right	300ms ease
Toast exit	Fade out	200ms ease
Hover states	Background color	100ms ease
Button press	Scale 0.98	100ms ease

---

8. Iconography

Icon set: Lucide React (MIT license, Feather-compatible)

Common icons:

Icon	Usage
Server	Host item, host form
Globe	Network, hostname
Key	SSH keys
Lock	Vault, security
Folder	Groups, directories
File	Files, snippets
Terminal	Terminal sessions
Search	Search bar
Plus	Add new item
Edit	Edit item
Trash	Delete item
Star	Favorite
ChevronRight	Tree expand
ChevronDown	Tree collapse
X	Close, clear
Check	Success, confirm
AlertTriangle	Warning
Info	Information
Settings	Settings screen
Download	Download file
Upload	Upload file
Refresh	Refresh/reload
PanelLeftClose	Collapse sidebar
PanelLeftOpen	Expand sidebar

Icon sizes:

• Inline text: 14px
• Button icon: 16px
• Navigation icon: 20px
• Large feature icon: 48px

---

9. CSS Variables

:root {
    /* Colors - Dark theme */
    --bg-primary: #0d1117;
    --bg-secondary: #161b22;
    --bg-tertiary: #1c2128;
    --bg-active: #21262d;
    
    --border-primary: #30363d;
    --border-secondary: #21262d;
    
    --text-primary: #e6edf3;
    --text-secondary: #8b949e;
    --text-tertiary: #484f58;
    
    --accent-primary: #58a6ff;
    --accent-hover: #79c0ff;
    
    --success: #3fb950;
    --warning: #d29922;
    --error: #f85149;
    --info: #58a6ff;
    
    /* Spacing */
    --space-1: 4px;
    --space-2: 8px;
    --space-3: 12px;
    --space-4: 16px;
    --space-5: 20px;
    --space-6: 24px;
    --space-8: 32px;
    
    /* Border radius */
    --radius-sm: 4px;
    --radius-md: 6px;
    --radius-lg: 8px;
    --radius-xl: 12px;
    
    /* Shadows */
    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.2);
    --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.3);
    --shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.4);
    
    /* Transitions */
    --transition-fast: 100ms ease;
    --transition-normal: 200ms ease;
    --transition-slow: 300ms ease;
    
    /* Typography */
    --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
    --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
    
    --text-xs: 11px;
    --text-sm: 12px;
    --text-base: 13px;
    --text-lg: 14px;
    --text-xl: 16px;
    --text-2xl: 20px;
    
    /* Layout */
    --sidebar-width: 240px;
    --sidebar-min: 180px;
    --sidebar-max: 400px;
    --tab-height: 36px;
    --status-height: 24px;
    --toolbar-height: 32px;
}

/* Light theme override */
[data-theme="light"] {
    --bg-primary: #ffffff;
    --bg-secondary: #f6f8fa;
    --bg-tertiary: #eaeef2;
    --bg-active: #d0d7de;
    
    --border-primary: #d0d7de;
    --border-secondary: #eaeef2;
    
    --text-primary: #1f2328;
    --text-secondary: #656d76;
    --text-tertiary: #8c959f;
    
    --accent-primary: #0969da;
    --accent-hover: #0550ae;
    
    --success: #1a7f37;
    --warning: #9a6700;
    --error: #cf222e;
    --info: #0969da;
}

/* High contrast theme override */
[data-theme="high-contrast"] {
    --bg-primary: #000000;
    --bg-secondary: #0a0a0a;
    --bg-tertiary: #141414;
    --bg-active: #1a1a1a;
    
    --border-primary: #ffffff;
    --border-secondary: #666666;
    
    --text-primary: #ffffff;
    --text-secondary: #cccccc;
    --text-tertiary: #888888;
    
    --accent-primary: #4da6ff;
    --accent-hover: #80c8ff;
}

---

10. Responsive Behavior

Mobile (< 600px)

• Sidebar: collapsed by default, hamburger menu to open
• SFTP: stacked panes (one at a time)
• Terminal: full-width, custom keyboard toolbar
• Forms: full-width inputs
• Modals: full-width bottom sheet

Tablet (600-1024px)

• Sidebar: narrow (180px), icons + truncated labels
• SFTP: stacked or side-by-side (user choice)
• Terminal: normal width
• Forms: two-column where possible

Desktop (> 1024px)

• Sidebar: normal (240px)
• SFTP: side-by-side panes
• Terminal: normal
• Everything as designed

Wide (> 1440px)

• Sidebar: wider (300px) or user-resized
• SFTP: side-by-side with more space
• Terminal: extra wide
• Settings: side navigation visible