openhuman/docs/DESIGN_GUIDELINES.md

# Crypto Platform Design Guidelines

## Design Philosophy

Our design system embodies three core principles that align with the needs of crypto professionals:

### 1. **Calm Sophistication**
- Soft, muted color palettes that reduce visual noise
- Generous whitespace for breathing room
- Subtle animations that feel natural, not jarring

### 2. **Trust Through Clarity**
- Clear information hierarchy
- Consistent component patterns
- Professional typography that's easy to scan

### 3. **Functional Beauty**
- Every aesthetic choice serves a functional purpose
- Data visualization that's both beautiful and informative
- Interactions that feel intuitive and responsive

## Color System

### Primary Palette

#### Canvas (Backgrounds)
- **Canvas-50** (#FAFAF9): Primary background, slight warmth prevents sterility
- **Canvas-100** (#F5F5F4): Secondary surfaces, cards, elevated elements
- **Canvas-200** (#E5E5E3): Tertiary backgrounds, hover states

#### Ocean Blue (Primary Actions)
- **Primary-500** (#5B9BF3): Main brand color, CTAs, active states
- **Primary-600** (#4A83DD): Hover states for primary elements
- **Why**: Blue conveys trust, stability, and professionalism - crucial for financial platforms

#### Sage Green (Success/Growth)
- **Sage-500** (#4DC46F): Positive changes, success states, gains
- **Sage-600** (#3BA858): Hover states for success elements
- **Why**: A sophisticated green that feels less aggressive than typical "success" greens

#### Coral Red (Errors/Losses)
- **Coral-500** (#F56565): Errors, losses, critical actions
- **Why**: Softer than harsh reds, maintains professionalism even in negative states

### Psychology Behind Color Choices

1. **Warm Neutrals Over Cold Grays**: Creates a more welcoming, less clinical environment
2. **Muted Accent Colors**: Reduces cognitive load during long trading sessions
3. **High Contrast for Data**: Ensures critical information is immediately visible

## Typography

### Font Stack

```css
font-sans: 'Inter', -apple-system, system-ui
font-display: 'Cabinet Grotesk', 'Inter'
font-mono: 'JetBrains Mono'
```

### Type Scale & Usage

- **Display (4.5rem)**: Hero sections, major announcements
- **H1 (3rem)**: Page titles, primary headings
- **H2 (1.875rem)**: Section headers
- **Body (1rem)**: General content, -0.01em letter-spacing for clarity
- **Small (0.875rem)**: Secondary information, metadata
- **Micro (0.625rem)**: Tiny labels, timestamps

### Typography Rules

1. **Line Height**: 1.5-1.6 for body text, 1.1-1.2 for headings
2. **Letter Spacing**: Negative for larger sizes, neutral for body
3. **Font Weight**: Use 400-600 primarily, 700 sparingly for emphasis
4. **Monospace**: Always for prices, percentages, numerical data

## Spacing System

### Base Unit: 0.25rem (4px)

- **Micro**: 4px, 8px (tight groupings)
- **Small**: 12px, 16px (related elements)
- **Medium**: 24px, 32px (sections)
- **Large**: 48px, 64px (major sections)
- **XLarge**: 96px+ (hero areas)

### Spacing Psychology

- **Tight spacing** (4-8px): Creates relationships between elements
- **Medium spacing** (16-24px): Standard breathing room
- **Generous spacing** (48px+): Creates focus and hierarchy

## Component Patterns

### Cards

#### Elevated Card
```jsx
<div className="card-elevated">
  // Shadow creates depth, white bg provides focus
</div>
```
- Use for primary content containers
- Subtle shadow creates hierarchy without borders

#### Interactive Card
```jsx
<div className="card-interactive">
  // Hover state with top border animation
</div>
```
- Use for clickable items
- Progressive disclosure through hover states

#### Glass Card
```jsx
<div className="glass-surface">
  // Backdrop blur for overlay contexts
</div>
```
- Use for floating elements, overlays
- Creates depth while maintaining context

### Buttons

#### Hierarchy
1. **Premium Button**: Primary CTAs, most important actions
2. **Glass Button**: Secondary actions, less emphasis
3. **Outline Button**: Tertiary actions, minimal visual weight

#### Button Psychology
- **Rounded corners** (0.75rem): Feels approachable, modern
- **Subtle shadows**: Creates tactile feeling, encourages clicks
- **Hover animations**: Provides feedback, builds confidence

### Forms

#### Input Design
```jsx
<input className="input-elevated" />
```
- **White background**: Maximum contrast for readability
- **Subtle border**: Defines boundaries without heaviness
- **Focus ring**: Clear feedback for keyboard navigation

## Motion & Animation

### Timing Functions
```css
--transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
--transition-base: 250ms cubic-bezier(0.4, 0, 0.2, 1);
--transition-slow: 350ms cubic-bezier(0.4, 0, 0.2, 1);
```

### Animation Principles

1. **Purpose**: Every animation serves a functional purpose
2. **Subtlety**: Movements should feel natural, not dramatic
3. **Performance**: Prefer transform and opacity for 60fps
4. **Consistency**: Same elements animate the same way

### Common Animations

- **Fade In**: Content appearing (0.5s)
- **Scale In**: Modals, popups (0.3s)
- **Slide In**: Panels, drawers (0.3s)
- **Shimmer**: Loading states (2s loop)

## Data Visualization

### Market Data Display

1. **Monospace fonts** for all numbers
2. **Color coding**: Green (up), Red (down), Gray (neutral)
3. **Tabular alignment** for easy scanning
4. **Real-time updates** with subtle transitions

### Chart Guidelines

- **Muted gridlines**: Don't compete with data
- **High contrast** for data points
- **Interactive tooltips** on hover
- **Responsive scaling** for all screen sizes

## Accessibility

### WCAG 2.1 AA Compliance

1. **Color Contrast**: 4.5:1 for normal text, 3:1 for large
2. **Focus Indicators**: Visible keyboard navigation
3. **Touch Targets**: Minimum 44x44px
4. **Screen Readers**: Semantic HTML, ARIA labels

### Inclusive Design

- **Color-blind safe**: Don't rely solely on color
- **Keyboard navigable**: All interactions keyboard accessible
- **Reduced motion**: Respect prefers-reduced-motion
- **Clear language**: Avoid jargon in critical flows

## Responsive Design

### Breakpoints
```css
sm: 640px
md: 768px
lg: 1024px
xl: 1280px
2xl: 1536px
```

### Mobile-First Principles

1. **Essential information** visible without scrolling
2. **Touch-friendly** tap targets (min 44px)
3. **Simplified navigation** for small screens
4. **Performance optimized** for mobile networks

## Implementation Guidelines

### Component Usage

1. **Consistency**: Use existing components before creating new
2. **Composition**: Build complex UIs from simple components
3. **Customization**: Extend through composition, not modification
4. **Documentation**: Document any deviations from guidelines

### Performance Considerations

1. **Lazy load** non-critical components
2. **Optimize images** (WebP, proper sizing)
3. **Code split** by route
4. **Cache aggressively** for repeat visits

### Testing Checklist

- [ ] Responsive on all breakpoints
- [ ] Accessible via keyboard
- [ ] Color contrast passes
- [ ] Animations respect reduced motion
- [ ] Forms have proper validation
- [ ] Loading states implemented
- [ ] Error states handled gracefully

## Summary

This design system creates a premium experience that:
- **Builds trust** through consistency and clarity
- **Reduces cognitive load** with calm aesthetics
- **Enhances usability** through thoughtful interactions
- **Scales elegantly** across devices and contexts

The result is a platform that feels sophisticated yet approachable, powerful yet simple - perfect for crypto professionals who demand both functionality and aesthetic excellence.