Files

T

swanadiva 8ebdebedc8 chore: V2 planning docs + template discovery

2026-07-07 11:53:16 +07:00

13 KiB

Raw Blame History

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

Content-first — Terminal/SFTP content takes maximum space
Sidebar minimal — Thin sidebar, collapsible, icons + labels
Tab bar compact — Small tab height, status dots, close buttons
Forms clean — Labeled inputs, generous spacing, clear validation
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

13 KiB Raw Blame History