Apple-Quality Design System for V5

Version: 1.0.0 Date: 2025-10-08 Philosophy: "Design is how it works" - Steve Jobs

🎯 Design Philosophy

Core Principles (Steve Jobs & Jony Ive)

Seamless Integration - No visible boundaries between components
Self-Explanatory - UI explains itself through visual hierarchy
Intuitive Interaction - Users understand without instructions
Minimal Cognitive Load - One clear action path
Beautiful Simplicity - Remove everything unnecessary
Purposeful Motion - Animation guides, never decorates
Consistent Behavior - Learn once, use everywhere

The Goal

Zero onboarding required. Users of all skill levels feel confident and understand tools/features immediately through design alone.

🎨 Visual Unity

No Component Seams

Every element flows as ONE unified system:

theia widgets → Look native to V5 (not embedded)
React components → Match theia styling perfectly
Light/Dark modes → Seamless transition, no jarring changes
Touch/Mouse → Same visual feedback, optimized for input
Mobile/Desktop → layout adapts, appearance stays consistent

How We Achieve This

Unified Theme System (unified-theme.ts)
- Single color palette for all components
- Consistent spacing (8px base unit)
- Matching typography (San Francisco-inspired)
- Shared shadows, radii, transitions
Global CSS Integration (global.css)
- Removes theia's default borders/backgrounds
- Injects V5 theme variables into theia widgets
- Ensures smooth transitions everywhere
- Touch-friendly sizing on all interactive elements
Seamless theia Styling
- theia widgets inherit Chakra UI theme
- No visual boundaries (borders/shadows removed)
- Same fonts, colors, spacing as React components
- Perfect theme sync (light/dark)

🎨 Color System

Philosophy: Calm, Professional, Never Jarring

Primary Blue - Trustworthy, professional (Apple-style)

#2A90FF - Main brand color

Neutral Grays - Soft, premium feel

Light Mode BG: #F8F9FA (warm white)
Dark Mode BG:  #212529 (deep charcoal)

Success Green - Natural, reassuring (Apple Health style)

Light: #34C759
Dark:  #30D158

Warning Amber - Clear without alarm

Light: #FF9500
Dark:  #FF9F0A

Error Red - Obvious but not aggressive

Light: #FF3B30
Dark:  #FF453A

Color Usage

Element	Light Mode	Dark Mode	Purpose
Background	#F8F9FA	#212529	Canvas
Surface	#FFFFFF	#343A40	Cards, panels
Border	#E9ECEF	#495057	Subtle separation
Text Primary	#212529	#F8F9FA	Main content
Text Secondary	#868E96	#ADB5BD	Supporting text
Accent	#2A90FF	#2A90FF	Interactive elements

📐 Spacing & layout

8px Base Unit (Consistent Rhythm)

All spacing uses multiples of 8px:

4px   - Tight (half unit)
8px   - Base unit
16px  - Comfortable (double)
24px  - Spacious (triple)
32px  - Section gap
48px  - Major separation

Touch Targets

Minimum: 44x44px (WCAG AAA) Recommended: 56px (V5 standard)

Every interactive element (buttons, inputs, switches, links) meets this standard on all devices.

Responsive Breakpoints

320px  - Mobile (iPhone SE)
480px  - Small mobile landscape
768px  - Tablet portrait
992px  - Tablet landscape
1280px - Desktop
1536px - Large desktop

Mobile-First: Design for 320px first, enhance for larger screens.

🔤 Typography

San Francisco Inspired

Headings: SF Pro Display

font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display"

Body: SF Pro Text

font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text"

Code: SF Mono

font-family: "SF Mono", "Monaco", "Inconsolata"

Hierarchy

Level	Size	Weight	Usage
H1	32px	600	Page titles
H2	24px	600	Section headers
H3	20px	600	Subsections
Body	16px	400	Main content
Small	14px	400	Supporting text
Caption	12px	400	Metadata

Key Rule: Size difference creates hierarchy, not decoration.

🎭 Light & Dark Modes

Seamless Theme Switching

Light Mode - Clean, airy, productive

Background: Warm white (#F8F9FA)
Text: Deep charcoal (#212529)
Shadows: Soft, subtle

Dark Mode - Comfortable, focused, modern

Background: Deep charcoal (#212529)
Text: Soft white (#F8F9FA)
Shadows: None (use subtle borders instead)

Auto-Sync

Theme changes propagate instantly to:

✅ React components (Chakra UI)
✅ theia widgets (via CSS variables)
✅ Monaco editor
✅ terminal (xterm.js)
✅ File explorer
✅ Chat interface

Result: One unified appearance, zero visual seams.

🎬 Motion & Animation

Philosophy: Purposeful, Never Decorative

Easing: Natural, physics-based

cubic-bezier(0.4, 0, 0.2, 1) - Default (ease-out)

Duration: Quick, responsive

200ms - UI state changes
300ms - Component transitions
500ms - Page transitions

When to Animate

✅ DO animate:

Hover states (subtle lift)
Focus indicators (gentle pulse)
Panel expansion (smooth reveal)
Theme switching (fade)
Navigation (slide)

❌ DON'T animate:

Text changes
Data updates
Scrolling
Resize operations

Reduced Motion

Respect user preferences:

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

🖱️ Interaction Patterns

Self-Explanatory Through Design

Buttons

Visual Cues:

Primary action: Filled blue, prominent
Secondary action: Outline, subtle
Destructive action: Red fill
Hover: Slight lift + shadow
Active: Press down effect
Disabled: 40% opacity, no pointer

User understands: Color = importance, elevation = interactivity

Inputs

Visual Cues:

Empty: Light border, placeholder text
Focus: Blue border + subtle shadow
Filled: Text appears, placeholder fades
Error: Red border + helper text
Success: Green checkmark

User understands: Border color = state, icon = validation

Switches

Visual Cues:

Off: Gray track, thumb left
On: Blue track, thumb right
Transition: Smooth slide (200ms)

User understands: Position = state, color = active

Cards

Visual Cues:

Clickable: Hover lift + shadow
Selected: Blue border
Expanded: Chevron rotates down
Collapsed: Chevron rotates right

User understands: Elevation = clickable, chevron = expandable

📱 Mobile-First Responsive Design

Adaptive layout (Not Hidden)

Bad ❌:

Desktop: Show sidebar
Mobile: Hide sidebar

Good ✅:

Desktop: Side-by-side panels
Mobile: Stack vertically (both visible)

Touch Optimization

All interactive elements:

Minimum 56px tall
Minimum 56px wide
8px padding around tap area
Visual feedback on touch

Gestures:

Tap - Activate
Swipe - Navigate (panels)
Pinch - Zoom (code editor)
Drag - Resize (desktop only)

Mobile Considerations

Font size: Never below 16px (prevents iOS zoom)
Input height: 56px (comfortable thumb reach)
Scrolling: Momentum scrolling enabled
Orientation: Works in portrait and landscape

🎯 Self-Explanatory UI Elements

Visual Hierarchy Tells the Story

Example: AI Studio Tab

Without reading any text, users understand:

Left panel (chat interface):
- Large input box → "Type here"
- Send button (blue, prominent) → "Primary action"
- Agent selector → "Choose assistant"
- Message history → "Previous conversations"
Right panel (preview):
- Code display → "Generated output"
- Syntax highlighting → "This is code"
- Scroll bar → "More content below"
Resizer (between panels):
- 8px gray bar → "Draggable"
- Hover changes to blue → "Interactive"
- Cursor changes → "Drag to resize"

Result: User knows what to do without instructions.

🔧 Component Consistency

Every Component Follows Same Rules

Component	Touch Target	Border Radius	Shadow	Hover Effect
Button	56px	16px	sm	Lift + shadow
Input	56px	16px	none → focus shadow	Border color
Card	-	20px	sm	Lift + shadow
Switch	32px (track)	full	none	Track color
Select	56px	16px	none → focus shadow	Border color

Consistency = Predictability = Confidence

♿ Accessibility (WCAG AAA)

Built-In, Not Added On

✅ Touch Targets: All ≥ 56px ✅ Color Contrast: 7:1 (AAA standard) ✅ Focus Indicators: 3px blue ring ✅ Keyboard Navigation: Full support ✅ Screen Readers: ARIA labels on all interactive elements ✅ No Color-Only: Icons + text for all actions ✅ Reduced Motion: Respects user preference

Focus Management

Visible focus ring on all interactive elements:

box-shadow: 0 0 0 3px rgba(42, 144, 255, 0.3)

Tab order: Logical, top-to-bottom, left-to-right

Skip links: Available for keyboard users

🎨 Design Tokens (Single Source of Truth)

All values defined in unified-theme.ts:

// Colors
colors.primary[500]    // #2A90FF
colors.neutral[50]     // #F8F9FA

// Spacing
space[2]               // 16px
space[4]               // 32px

// Shadows
shadows.md             // 0 4px 6px rgba(0,0,0,0.1)

// Radii
radii.lg               // 16px
radii.xl               // 20px

// Fonts
fonts.body             // -apple-system, ...

Usage in code:

<Button
  bg="primary.500"
  px={space[2]}
  borderRadius="lg"
  boxShadow="md"
>
  Click Me
</Button>

🔄 theia Integration (Seamless)

Before (Visible Seams)

┌─────────────────────┐
│ V5 React Header     │ ← One theme
├─────────────────────┤
│ ┌─────────────────┐ │
│ │ theia Widget    │ │ ← Different theme (jarring)
│ │ (borders, bg)   │ │
│ └─────────────────┘ │
└─────────────────────┘

After (Seamless)

┌─────────────────────┐
│ V5 React Header     │ ← Unified theme
│                     │
│ theia Widget        │ ← Same theme (seamless)
│ (no borders/bg)     │
│                     │
└─────────────────────┘

How It's Done

Remove theia defaults (global.css):

.theia-widget {
  border: none !important;
  background: transparent !important;
}

Inject V5 theme (CSS variables):

.theia-light {
  --theia-ui-background: #F8F9FA;
  --theia-accent-color: #2A90FF;
}

Sync theme changes:
- Chakra UI theme change → Update theia CSS variables
- Result: Instant theme sync across all components

📋 Implementation Checklist

For Every New Component

For Every Page

🎯 Success Metrics

User Experience

Goal: Users feel confident without training

Metrics:

Time to first action: < 10 seconds
Error rate: < 5%
Support requests: Minimal
User satisfaction: > 90%

Visual Quality

Goal: Apple-level polish

Metrics:

No visible component seams
Smooth 60fps animations
Instant theme switching
Pixel-perfect alignment
Consistent spacing everywhere

📚 Resources

Design References

Code Files

src/theme/unified-theme.ts - Design tokens
src/theme/global.css - Seamless integration
src/components/theia/ - Widget wrappers
docs/mobile-first-design-system.md - Touch guidelines

✅ Summary

The V5 Design System Ensures:

✅ Seamless visual integration - No component boundaries ✅ Self-explanatory UI - Visual hierarchy tells the story ✅ Intuitive interactions - Users understand without instructions ✅ Minimal cognitive load - One clear action path ✅ Beautiful simplicity - Nothing unnecessary ✅ Consistent behavior - Learn once, use everywhere ✅ Apple-quality polish - Attention to every detail

The Result:

A unified system so seamless, users never notice the components—they just experience a beautiful, intuitive tool that works exactly as expected.

"Design is not just what it looks like and feels like. Design is how it works." - Steve Jobs

Document Version: 1.0.0 Last Updated: 2025-10-08 Status: ✅ PRODUCTION STANDARD

🎯 Design Philosophy​

Core Principles (Steve Jobs & Jony Ive)​

The Goal​

🎨 Visual Unity​

No Component Seams​

How We Achieve This​

🎨 Color System​

Philosophy: Calm, Professional, Never Jarring​

Color Usage​

📐 Spacing & layout​

8px Base Unit (Consistent Rhythm)​

Touch Targets​

Responsive Breakpoints​

🔤 Typography​

San Francisco Inspired​

Hierarchy​

🎭 Light & Dark Modes​

Seamless Theme Switching​

Auto-Sync​

🎬 Motion & Animation​

Philosophy: Purposeful, Never Decorative​

When to Animate​

Reduced Motion​

🖱️ Interaction Patterns​

Self-Explanatory Through Design​

Buttons​

Inputs​

Switches​

Cards​

📱 Mobile-First Responsive Design​

Adaptive layout (Not Hidden)​

Touch Optimization​

Mobile Considerations​

🎯 Self-Explanatory UI Elements​

Visual Hierarchy Tells the Story​

🔧 Component Consistency​

Every Component Follows Same Rules​

♿ Accessibility (WCAG AAA)​

Built-In, Not Added On​

Focus Management​

🎨 Design Tokens (Single Source of Truth)​

🔄 theia Integration (Seamless)​

Before (Visible Seams)​

After (Seamless)​

How It's Done​

📋 Implementation Checklist​

For Every New Component​

For Every Page​

🎯 Success Metrics​

User Experience​

Visual Quality​

📚 Resources​

Design References​

Code Files​

✅ Summary​

The V5 Design System Ensures:​

The Result:​

🎯 Design Philosophy

Core Principles (Steve Jobs & Jony Ive)

The Goal

🎨 Visual Unity

No Component Seams

How We Achieve This

🎨 Color System

Philosophy: Calm, Professional, Never Jarring

Color Usage

📐 Spacing & layout

8px Base Unit (Consistent Rhythm)

Touch Targets

Responsive Breakpoints

🔤 Typography

San Francisco Inspired

Hierarchy

🎭 Light & Dark Modes

Seamless Theme Switching

Auto-Sync

🎬 Motion & Animation

Philosophy: Purposeful, Never Decorative

When to Animate

Reduced Motion

🖱️ Interaction Patterns

Self-Explanatory Through Design

Buttons

Inputs

Switches

Cards

📱 Mobile-First Responsive Design

Adaptive layout (Not Hidden)

Touch Optimization

Mobile Considerations

🎯 Self-Explanatory UI Elements

Visual Hierarchy Tells the Story

🔧 Component Consistency

Every Component Follows Same Rules

♿ Accessibility (WCAG AAA)

Built-In, Not Added On

Focus Management

🎨 Design Tokens (Single Source of Truth)

🔄 theia Integration (Seamless)

Before (Visible Seams)

After (Seamless)

How It's Done

📋 Implementation Checklist

For Every New Component

For Every Page

🎯 Success Metrics

User Experience

Visual Quality

📚 Resources

Design References

Code Files

✅ Summary

The V5 Design System Ensures:

The Result: