chore: V2 planning docs + template discovery

2026-07-07 11:53:16 +07:00
parent 4a8b4a2bc4
commit 8ebdebedc8
31 changed files with 9304 additions and 0 deletions
@@ -0,0 +1,558 @@
+# 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