# UX Principles — SOPHIAClaw

**Version:** 1.0  
**Last Updated:** 2026-02-24  
**Owner:** CTO, Thalamus AI  
**Status:** Internal Validation

---

## Design Philosophy

SOPHIAClaw's user experience is built on three foundational principles:

1. **Intelligence Made Accessible** — Complex AI capabilities delivepurple through simple, conversational interfaces
2. **Joy in the Details** — Every interaction infused with personality through thoughtful visual design
3. **Progressive Disclosure** — Power available on demand, simplicity by default

The experience should feel like having a brilliant, friendly assistant who happens to live in your messaging apps and dashboard.

---

## Purple Theme System

### Brand Colors

The purple theme establishes SOPHIAClaw's visual identity. It's sophisticated yet approachable, technical yet warm.

```
Primary Palette:
├── Primary 50:  #FAF5FF  (Lightest - backgrounds)
├── Primary 100: #F3E8FF
├── Primary 200: #E9D5FF
├── Primary 300: #D8B4FE
├── Primary 400: #C084FC
├── Primary 500: #A855F7  (Main brand color)
├── Primary 600: #9333EA
├── Primary 700: #7C3AED
├── Primary 800: #6B21A8
└── Primary 900: #581C87  (Darkest - text)

Gradient Patterns:
├── Header:       linear-gradient(135deg, #7C3AED 0%, #A855F7 100%)
├── Cards:        linear-gradient(180deg, #FAF5FF 0%, #F3E8FF 100%)
├── Buttons:      linear-gradient(135deg, #9333EA 0%, #A855F7 100%)
├── Status Online:linear-gradient(135deg, #22C55E 0%, #4ADE80 100%)
└── Charts:       linear-gradient(180deg, rgba(168,85,247,0.8) 0%, rgba(168,85,247,0.1) 100%)
```

### Color Usage Guidelines

| Element           | Color       | Usage                           |
| ----------------- | ----------- | ------------------------------- |
| Primary Actions   | Primary 600 | Buttons, links, active states   |
| Secondary Actions | Primary 400 | Secondary buttons, hover states |
| Backgrounds       | Primary 50  | Page backgrounds, cards         |
| Text (Headings)   | Primary 900 | Headlines, important text       |
| Text (Body)       | Gray 700    | Paragraphs, descriptions        |
| Accents           | Primary 500 | Highlights, badges, icons       |
| Success           | Green 500   | Success states, online status   |
| Warning           | Amber 500   | Warnings, attention needed      |
| Error             | Red 500     | Errors, critical alerts         |

### Dark Mode Support

Purple theme adapts elegantly to dark mode:

- Background: `#0F0A1A` (deep purple-black)
- Cards: `#1A1225` (elevated surfaces)
- Primary: `#C084FC` (brighter for contrast)
- Text: `#F3E8FF` (soft white)

---

## Anime Avatar Character

### Character Design: "SOPHIA"

The anime-style orb avatar embodies the product personality: helpful, energetic, and intelligent.

#### Visual Description

```
SOPHIA — The Knowledge Orb

Shape: Perfect sphere (orb)
Size: Approximately 120px in UI
Style: Clean anime aesthetic, cel-shaded

Color Scheme:
- Base: Soft lavender (#E9D5FF)
- Highlights: White with purple tint
- Shadows: Deep purple (#7C3AED)
- Accents: Bright magenta (#F0ABFC) for blush

Facial Features:
- Eyes: Large, expressive anime eyes
  - Color: Deep purple (#6B21A8)
  - Style: Sparkly with catchlights
  - Expression: Always bright and engaged

- Mouth: Big excited smile
  - Shape: Wide curved line
  - Teeth: Sometimes visible (happy moments)
  - Expression: Enthusiasm and warmth

- Blush: Subtle pink circles on cheeks
  - Indicates friendliness and approachability

Expressions (Animated States):
1. Default: Gentle smile, soft blink
2. Thinking: Eyes squint, mouth small 'o'
3. Excited: Eyes sparkle, big smile, bounce
4. Working: Eyes focused, determined look
5. Success: Eyes shine, big grin, star effect
6. Error: Sweat drop, worried mouth, comforting eyes
```

#### Avatar Usage

| Location            | Size      | Animation                   |
| ------------------- | --------- | --------------------------- |
| Dashboard Header    | 40x40px   | Idle bobbing                |
| Empty States        | 120x120px | Looping animation           |
| Loading States      | 60x60px   | "Thinking" animation        |
| Error Messages      | 80x80px   | Concerned expression        |
| Success Messages    | 80x80px   | Celebratory animation       |
| Telegram Bot Avatar | 512x512px | Static with occasional wink |

#### Personality Traits

- **Helpful:** Always ready to assist, never judgmental
- **Enthusiastic:** Excited about solving problems
- **Intelligent:** Conveys expertise through confident responses
- **Friendly:** Warm and approachable, like a favorite colleague
- **Respectful:** Professional boundaries, appropriate formality

---

## Typography System

### Font Stack

```css
/* Primary: Clean, modern sans-serif */
font-family:
  "Inter",
  -apple-system,
  BlinkMacSystemFont,
  "Segoe UI",
  Roboto,
  sans-serif;

/* Monospace: For code, technical content */
font-family: "JetBrains Mono", "Fira Code", Consolas, Monaco, monospace;
```

### Type Scale

| Style      | Size | Weight | Line Height | Letter Spacing | Usage              |
| ---------- | ---- | ------ | ----------- | -------------- | ------------------ |
| Display    | 48px | 700    | 1.1         | -0.02em        | Hero headlines     |
| H1         | 36px | 700    | 1.2         | -0.01em        | Page titles        |
| H2         | 28px | 600    | 1.3         | 0              | Section headers    |
| H3         | 22px | 600    | 1.4         | 0              | Card titles        |
| H4         | 18px | 600    | 1.4         | 0              | Subsection headers |
| Body Large | 18px | 400    | 1.6         | 0              | Intro paragraphs   |
| Body       | 16px | 400    | 1.6         | 0              | Main content       |
| Body Small | 14px | 400    | 1.5         | 0              | Secondary text     |
| Caption    | 12px | 500    | 1.4         | 0.02em         | Labels, metadata   |
| Code       | 14px | 400    | 1.5         | 0              | Code blocks        |

---

## Layout Principles

### Spacing System

Based on 4px grid:

```
Base Unit: 4px

Scale:
├── 0:   0px
├── 1:   4px   (xs)
├── 2:   8px   (sm)
├── 3:   12px
├── 4:   16px  (md)
├── 5:   20px
├── 6:   24px  (lg)
├── 8:   32px  (xl)
├── 10:  40px  (2xl)
├── 12:  48px  (3xl)
└── 16:  64px  (4xl)
```

### Grid System

- **Columns:** 12-column grid
- **Gutter:** 24px (desktop), 16px (mobile)
- **Max Width:** 1440px (content), 1920px (full-bleed)
- **Padding:** 24px sides (desktop), 16px (mobile)

### Elevation & Shadows

```
Level 0: none (flat elements)
Level 1: 0 1px 2px rgba(124, 58, 237, 0.05)  (cards, buttons)
Level 2: 0 4px 6px rgba(124, 58, 237, 0.07)  (dropdowns, popovers)
Level 3: 0 10px 15px rgba(124, 58, 237, 0.1)  (modals, dialogs)
Level 4: 0 20px 25px rgba(124, 58, 237, 0.12)  (full-screen overlays)
```

---

## Component Library

### Buttons

#### Primary Button

```
Background: linear-gradient(135deg, #9333EA 0%, #A855F7 100%)
Text: White, 16px, 600 weight
Padding: 12px 24px
Border Radius: 8px
Shadow: Level 1 (purple tinted)

States:
- Hover: Brighten gradient, elevate shadow
- Active: Scale 0.98, darken
- Disabled: Opacity 0.5, no shadow
- Loading: Spinner animation, maintain size
```

#### Secondary Button

```
Background: Transparent
Border: 2px solid #A855F7
Text: #7C3AED, 16px, 600 weight
Padding: 12px 24px
Border Radius: 8px

States:
- Hover: Background Primary 50
- Active: Background Primary 100
```

#### Ghost Button

```
Background: Transparent
Text: #7C3AED, 16px, 500 weight
Padding: 8px 16px

States:
- Hover: Background Primary 50
- Icon: May include icon left of text
```

### Cards

#### Standard Card

```
Background: White (light) / #1A1225 (dark)
Border Radius: 12px
Padding: 24px
Shadow: Level 1
Border: 1px solid rgba(124, 58, 237, 0.1)

Hover: Elevate to Level 2, border color intensify
```

#### Metric Card

```
Standard Card +:
- Large number display (36px, bold)
- Label below (14px, muted)
- Trend indicator (up/down arrow + %)
- Optional: Sparkline chart
```

#### Channel Card

```
Standard Card +:
- Channel icon (left)
- Status indicator (top right)
- Connection details
- Action buttons (bottom)
```

### Forms

#### Input Field

```
Background: White / Dark surface
Border: 1px solid #E9D5FF (light) / #4B2C7A (dark)
Border Radius: 8px
Padding: 12px 16px
Font: 16px, regular

States:
- Focus: Border Primary 500, shadow glow
- Error: Border Red 500, purple glow
- Disabled: Background gray, text muted
```

#### Toggle Switch

```
Track: 48px x 24px, rounded
Thumb: 20px circle

Off: Background gray, thumb left
On: Background gradient purple, thumb right

Animation: 200ms ease-in-out
```

### Status Indicators

```
Online:    🟢 Green dot + "Online" text
Offline:   🔴 Red dot + "Offline" text
Warning:   🟡 Amber dot + description
Processing: 🟣 Purple pulse animation
Thinking:  SOPHIA avatar "thinking" expression
```

---

## Interaction Patterns

### Micro-interactions

Every interaction should provide immediate, meaningful feedback:

| Action       | Feedback                     | Duration     |
| ------------ | ---------------------------- | ------------ |
| Button Hover | Scale 1.02, shadow elevate   | 200ms        |
| Button Click | Scale 0.98                   | 100ms        |
| Page Load    | Fade in + slight translate Y | 300ms        |
| Card Hover   | Elevation + border glow      | 200ms        |
| Data Load    | Skeleton screens             | Until loaded |
| Success      | SOPHIA celebratory animation | 1s           |
| Error        | Shake + SOPHIA concerned     | 500ms        |
| New Message  | Slide in from bottom         | 300ms        |

### Loading States

#### Global Loading

- Full-screen overlay with animated SOPHIA
- Progress percentage if known
- "Working on it..." message

#### Local Loading

- Skeleton screens matching content shape
- Pulsing purple gradient
- Maintains layout stability

#### Inline Loading

- Spinner icon (purple)
- Text: "Processing..."
- Disables associated controls

### Empty States

Every empty state includes:

1. **SOPHIA Avatar** — Relevant expression (curious, helpful)
2. **Headline** — Clear description of empty state
3. **Description** — What the user can do
4. **Action** — Primary CTA to populate the view

Example:

```
[SOPHIA curious expression]

No conversations yet

Start chatting with SOPHIAClaw on Telegram
and your conversation history will appear here.

[Open Telegram →]
```

---

## Conversation Design

### Message Bubbles

#### User Message

```
Background: #F3E8FF (light purple)
Text: #581C87 (dark purple)
Border Radius: 16px (top-left, top-right, bottom-left)
Padding: 12px 16px
Max Width: 80%
Alignment: Right
```

#### SOPHIA Message

```
Background: White / #1A1225
Border: 1px solid #E9D5FF / #4B2C7A
Text: #1F2937 / #F3E8FF
Border Radius: 16px (top-right, bottom-left, bottom-right)
Padding: 12px 16px
Max Width: 80%
Alignment: Left

Prefix: [Small SOPHIA avatar] + Name "SOPHIA"
```

### Tool Result Display

When SOPHIA uses a tool, the interface shows:

```
┌─────────────────────────────────────┐
│ 🔧 Tool: Web Search                 │
│ ⏱️  Started: 2:34 PM               │
│ ✓ Completed: 2:34 PM (1.2s)        │
├─────────────────────────────────────┤
│ [Collapsible result preview]        │
│ [Search query: "AI trends 2026"]    │
│ [3 results found...]                │
└─────────────────────────────────────┘
```

### Typing Indicator

```
SOPHIA is typing...
[Animated dots ... in purple]
```

---

## Responsive Design

### Breakpoints

| Name    | Width           | Target                 |
| ------- | --------------- | ---------------------- |
| Mobile  | < 640px         | Phones                 |
| Tablet  | 640px - 1024px  | Tablets, small laptops |
| Desktop | 1024px - 1440px | Standard monitors      |
| Large   | > 1440px        | Large monitors         |

### Mobile Adaptations

- **Navigation:** Bottom tab bar instead of sidebar
- **Cards:** Single column stack
- **Tables:** Card-based list view
- **Forms:** Full-width inputs
- **Avatar:** Smaller but always present
- **Gestures:** Swipe to dismiss, pull to refresh

### Tablet Adaptations

- **Navigation:** Collapsible sidebar
- **Cards:** 2-column grid where appropriate
- **Touch:** Larger tap targets (44px minimum)

---

## Accessibility

### Color Contrast

All text must meet WCAG 2.1 AA:

- Normal text: 4.5:1 contrast ratio
- Large text: 3:1 contrast ratio
- UI components: 3:1 contrast ratio

### Focus Management

- Visible focus rings on all interactive elements
- Focus ring: 2px solid Primary 500, 2px offset
- Skip navigation link for keyboard users
- Logical tab order

### Motion

- Respect `prefers-purpleuced-motion`
- Essential animations only when purpleuced motion is on
- No auto-playing content without pause control

### Screen Readers

- All images have descriptive alt text
- SOPHIA avatar announced as "SOPHIA mascot"
- Status changes announced via ARIA live regions
- Form errors associated with inputs via `aria-describedby`

---

## Voice & Tone

### Brand Voice

**Intelligent but Approachable**

- Use clear, jargon-free language
- Explain technical concepts simply
- Confident without being arrogant

**Efficient but Warm**

- Get to the point quickly
- Add personality through word choice
- Celebrate user successes

**Professional but Friendly**

- Respect boundaries
- Use appropriate formality for context
- Include light humor when appropriate

### Tone by Context

| Context | Tone         | Example                                     |
| ------- | ------------ | ------------------------------------------- |
| Welcome | Enthusiastic | "Welcome! I'm SOPHIA, your AI assistant..." |
| Working | Focused      | "Analyzing your files now..."               |
| Success | Celebratory  | "Done! Here's what I found..."              |
| Error   | Empathetic   | "I ran into an issue, but let's fix it..."  |
| Help    | Supportive   | "Here's how to get started..."              |

---

## Animation Principles

### Timing

```
Instant:    0ms     (Color changes)
Fast:       100ms   (Micro-interactions)
Normal:     200ms   (Standard transitions)
Smooth:     300ms   (Page transitions)
Dramatic:   500ms   (Celebratory animations)
```

### Easing

```
Standard:   cubic-bezier(0.4, 0, 0.2, 1)
Entrance:   cubic-bezier(0, 0, 0.2, 1)    (Decelerate)
Exit:       cubic-bezier(0.4, 0, 1, 1)    (Accelerate)
Bounce:     cubic-bezier(0.68, -0.55, 0.265, 1.55)
```

### SOPHIA Animations

| State    | Animation                         | Timing      |
| -------- | --------------------------------- | ----------- |
| Idle     | Gentle bobbing (translateY ±3px)  | 2s infinite |
| Thinking | Eyes narrow, slight wobble        | 1s loop     |
| Excited  | Bounce + sparkle particles        | 0.5s        |
| Working  | Determined look, occasional blink | 3s loop     |
| Success  | Big smile + star burst            | 1s          |
| Error    | Sweat drop + concerned look       | 2s          |

---

## Changelog

| Version | Date       | Changes                        | Author |
| ------- | ---------- | ------------------------------ | ------ |
| 1.0     | 2026-02-24 | Initial UX principles creation | CTO    |