# Design System

## Visual Direction

Target: visually inspired by `happy.engineering` and the Happy app: polished, playful, soft, modern, high-motion, emotionally warm, and app-like.

Not a terminal dashboard. Not a generic ChatGPT clone. It should feel like a friendly command center for a personal agent.

## Keywords

- Native Android feel
- Playful but competent
- Soft cards
- Friendly gradients
- Rounded app surfaces
- Large touch targets
- Motion-rich microinteractions
- Calm dark mode
- “Agent is alive” status cues

## Initial Theme Direction

Because Zeb likes both stark terminal aesthetics and polished UIs, Hermes Mobile should combine:

- Happy-style colorful/soft app surfaces
- Hermes identity through icons, agent activity, and subtle terminal/tool-call details
- Dark-first interface for phone use
- Optional light mode later

## Color Palette Draft

```text
Background:        #080A0F
Surface:           #10141D
Elevated surface:  #171D29
Card border:       rgba(255,255,255,0.08)
Text primary:      #F7F8FC
Text secondary:    #AAB2C5
Muted:             #687085

Hermes gold:       #F2C14E
Happy blue:        #6EA8FF
Happy purple:      #A78BFA
Happy green:       #63E6BE
Danger coral:      #FF6B6B
Warning amber:     #FFD166
```

Gradients:

```css
--gradient-orb: radial-gradient(circle at 30% 20%, #6EA8FF 0%, #A78BFA 45%, #080A0F 100%);
--gradient-action: linear-gradient(135deg, #6EA8FF, #A78BFA, #63E6BE);
--gradient-hermes: linear-gradient(135deg, #F2C14E, #FF8A65);
```

## Typography

Primary UI:
- Inter, Geist, or system Android sans.

Mono/details:
- JetBrains Mono for tool outputs, command snippets, paths, logs.

Type scale:
- Screen title: 28-34px, 700
- Section title: 18-20px, 650
- Body: 15-16px
- Metadata: 12-13px
- Tool output: 12-13px mono

## Layout

### Mobile shell

- Full-screen app layout.
- Safe-area aware.
- Bottom navigation with 4-5 tabs:
  - Ask
  - Activity
  - Cron
  - Files
  - Settings

### Ask screen

```text
┌─────────────────────────┐
│ Hermes        status orb │
│                         │
│  Recent / current task   │
│  ┌───────────────────┐  │
│  │ assistant answer  │  │
│  └───────────────────┘  │
│  ┌───────────────────┐  │
│  │ tool timeline     │  │
│  └───────────────────┘  │
│                         │
│ [ + ] [ hold voice ]    │
│ [ prompt input      ↑ ] │
└─────────────────────────┘
```

Input should be thumb-first:
- Attachment left
- Voice pill / mic
- Send button right
- Input grows to 4-6 lines max

## Components

### Agent Status Orb

A small animated orb/avatar indicating:
- idle
- thinking
- using tools
- waiting for approval
- done
- error

This gives the app life without pretending to be a person.

### Tool Card

States:
- queued
- running
- success
- failed
- cancelled

Collapsed view:
```text
[terminal icon] terminal • 2.4s • success
npm test
```

Expanded view:
- Arguments summary
- Output preview
- Copy button
- Open file if applicable
- Error highlighting

### Timeline

Vertical event feed with icons and subtle connecting line.

Events:
- Prompt received
- Tool started
- Tool output
- File generated
- Notification sent
- Final answer

### Approval Card

Should feel serious but not scary.

```text
Approval required
Hermes wants to run:
rm -rf /tmp/build-cache

Risk: destructive file operation
[ Deny ] [ Approve once ]
```

### Cron Job Card

```text
Homelab health check
Every day 09:00
Last run: success · 2h ago
[Run now] [Pause]
```

### Upload Tray

Shows selected files before sending:
- thumbnail for images
- file icon for zip/pdf/log
- remove button
- total size

## Motion

Use motion sparingly but meaningfully:
- status orb breathing while thinking
- tool card expands smoothly
- file upload progress liquid/soft bar
- send button morphs to spinner
- completion haptic-like visual pulse

Prefer CSS transitions and Framer Motion if bundle size acceptable.

## Android-native Feeling

- Capacitor Android APK with adaptive icon and native splash.
- PWA manifest retained for fallback web install.
- No browser chrome in the primary Android app.
- Bottom nav like native Material apps.
- Pull-to-refresh disabled in fallback web mode; in-app refresh buttons where needed.
- Android back gesture/button should close panels before navigating away.
- Add Android share target so user can share files/text to Hermes.

## Accessibility

- Minimum 44px tap targets.
- Color is not the only status indicator.
- Reduced motion support.
- Good contrast in dark mode.
- Voice actions have text alternatives.

## Design TODO

- Capture screenshots/references from happy.engineering and Happy app.
- Build a visual moodboard.
- Design first mockups for Ask, Tool Timeline, Cron, Settings.
- Decide exact logo/avatar direction.