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

```css
/* 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

```css
: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