sojorn/sojorn_docs/design/DESIGN_SYSTEM.md

# Sojorn Visual Design System

## Design Philosophy

Sojorn's visual system creates a **warm, welcoming, friends-first** experience through intentional design choices that prioritize human connection.

### Core Principles

1. **Warm, Not Overwhelming**
   - Warm neutrals (beige/paper tones) instead of cold grays
   - Soft shadows, never harsh
   - Muted semantic colors that inform without alarming

2. **Modern, Not Trendy**
   - Timeless color palette
   - Classic typography hierarchy
   - Subtle animations and transitions

3. **Connection-Focused**
   - Generous line height (1.6-1.65 for body text)
   - Optimized for reading and engagement
   - Clear hierarchy without relying on color

4. **Intentionally Smooth**
   - Animation durations: 300-400ms
   - Ease curves that feel natural
   - No jarring transitions

---

## Color Palette

### Background System
```dart
background        = #F8F7F4  // Warm off-white (like paper)
surface           = #FFFFFD  // Barely warm white
surfaceElevated   = #FFFFFF  // Pure white for cards
surfaceVariant    = #F0EFEB  // Subtle warm gray (inputs)
```

**Usage:**
- `background`: Main app background
- `surface`: App bars, bottom navigation
- `surfaceElevated`: Cards, dialogs, elevated content
- `surfaceVariant`: Input fields, disabled states

### Border System
```dart
borderSubtle      = #E8E6E1  // Barely visible dividers
border            = #D8D6D1  // Default borders
borderStrong      = #C8C6C1  // Emphasized borders
```

**Visual Hierarchy:**
- Use `borderSubtle` for dividers between list items
- Use `border` for cards, inputs, default separators
- Use `borderStrong` for focused/active states (rare)

### Text Hierarchy
```dart
textPrimary       = #1C1B1A  // Near-black with warmth
textSecondary     = #6B6A68  // Medium warm gray
textTertiary      = #9C9B99  // Light warm gray
textDisabled      = #BDBBB8  // Very light gray
textOnAccent      = #FFFFFD  // For buttons/accents
```

**Usage:**
- `textPrimary`: Headlines, body text, primary content
- `textSecondary`: Metadata, labels, secondary info
- `textTertiary`: Placeholders, timestamps, tertiary info
- `textDisabled`: Disabled button text, inactive states
- `textOnAccent`: White text on colored backgrounds

### Accent Colors
```dart
accent            = #5D6B7A  // Muted slate (primary)
accentLight       = #8A95A1  // Lighter slate
accentDark        = #3F4A56  // Darker slate
accentSubtle      = #E8EAED  // Barely visible accent
```

**Usage:**
- `accent`: Primary buttons, links, active states
- `accentLight`: Hover states, dark mode primary
- `accentDark`: Pressed states (rare)
- `accentSubtle`: Background for subtle accent areas

### Interaction Colors
```dart
appreciate        = #7A8B6F  // Muted sage green (likes)
save              = #6F7F92  // Muted blue-gray (saves)
share             = #8B7A6F  // Muted warm gray (shares)
```

### Semantic Colors
```dart
success           = #7A8B6F  // Soft sage (not bright green)
warning           = #B89F7D  // Soft amber (not orange alarm)
error             = #B07F7F  // Soft terracotta (not red alarm)
info              = #7A8B9F  // Soft blue
```

**Why Muted?**
Bright red errors create anxiety. Soft terracotta communicates the same information with less stress.

### Trust Tier Colors
```dart
tierNew           = #9C9B99  // Light gray
tierTrusted       = #7A8B6F  // Sage green
tierEstablished   = #5D6B7A  // Slate blue
```

---

## Typography

### Font Stack
```dart
Primary:  'SF Pro Text' → system-ui → sans-serif
Monospace: 'SF Mono' → 'Courier New' → monospace
```

**Why System Fonts?**
- Free, pre-installed, optimized for each platform
- SF Pro Text is warm and highly readable
- No network requests, instant loading

### Type Scale

#### Display (Rare - Only for Large Headings)
```dart
displayLarge:  32px / 600 / 1.2 line-height / -0.8 tracking
displayMedium: 28px / 600 / 1.25 line-height / -0.6 tracking
```

#### Headlines (Section Titles, Screen Titles)
```dart
headlineLarge:  24px / 600 / 1.3 line-height / -0.4 tracking
headlineMedium: 20px / 600 / 1.3 line-height / -0.3 tracking
headlineSmall:  17px / 600 / 1.35 line-height / -0.2 tracking
```

#### Body (Reading-Optimized)
```dart
bodyLarge:  17px / 400 / 1.65 line-height  ← GENEROUS for readability
bodyMedium: 15px / 400 / 1.6 line-height
bodySmall:  13px / 400 / 1.5 line-height
```

**Why 1.65 line-height?**
Research shows 1.5-1.6 is optimal for readability. We use 1.65 to reinforce comfortable spacing.

#### Labels (UI Elements, Buttons, Metadata)
```dart
labelLarge:  15px / 500 / 1.4 line-height / 0.1 tracking
labelMedium: 13px / 500 / 1.35 line-height / 0.1 tracking
labelSmall:  11px / 500 / 1.3 line-height / 0.3 tracking
```

### Typography Guidelines

**DO:**
- Use `bodyLarge` for post content
- Use `headlineMedium` for screen titles
- Use `labelMedium` for metadata (timestamps, handles)
- Use `mono` for technical data (@handles, IDs)

**DON'T:**
- Mix font weights excessively (400 for body, 500 for labels, 600 for headings)
- Use font sizes outside the scale
- Override line-height without good reason

---

## Spacing System

Based on **4px grid**:

```dart
spacing2xs  = 2px   // Rare, internal component spacing
spacingXs   = 4px   // Tight spacing
spacingSm   = 8px   // Small gaps
spacingMd   = 16px  // Default spacing
spacingLg   = 24px  // Large gaps (card padding)
spacingXl   = 32px  // Extra large (section gaps)
spacing2xl  = 48px  // Huge gaps
spacing3xl  = 64px  // Screen-level spacing
spacing4xl  = 96px  // Rare, dramatic spacing
```

### Semantic Spacing
```dart
spacingCardPadding    = 24px  // Internal card padding
spacingScreenPadding  = 16px  // Screen edge padding
spacingSectionGap     = 32px  // Between major sections
```

### Spacing Guidelines

**DO:**
- Use `spacingLg` (24px) for card padding
- Use `spacingMd` (16px) for screen padding
- Use `spacingXl` (32px) between sections

**DON'T:**
- Use arbitrary spacing values (stick to the scale)
- Create cramped UIs (when in doubt, use more space)

---

## Border Radius

```dart
radiusXs   = 4px    // Chips, badges
radiusSm   = 8px    // Small buttons
radiusMd   = 12px   // Inputs, buttons
radiusLg   = 16px   // Cards, dialogs
radiusXl   = 24px   // Large containers
radiusFull = 9999px // Pills, circular elements
```

**Consistency:**
- Cards: `radiusLg` (16px)
- Buttons: `radiusMd` (12px)
- Inputs: `radiusMd` (12px)
- Trust badges: `radiusXs` (4px)

---

## Elevation & Shadows

All shadows use **warm black** (`#1C1B1A`) at very low opacity:

```dart
shadowSm:  4% opacity, 4px blur, 1px offset
shadowMd:  6% opacity, 8px blur, 2px offset
shadowLg:  8% opacity, 16px blur, 4px offset
```

**Usage:**
- `shadowSm`: Default for cards
- `shadowMd`: Elevated cards, modals
- `shadowLg`: Floating action button, dialogs

**Why So Subtle?**
Heavy shadows create visual noise. Soft shadows suggest elevation without aggression.

---

## Animation

### Durations
```dart
durationFast:   200ms  // Hovers, subtle transitions
durationMedium: 300ms  // Default
durationSlow:   400ms  // Modal entrance, page transitions
```

### Curves
```dart
curveDefault: easeInOutCubic  // Most animations
curveEnter:   easeOut         // Elements appearing
curveExit:    easeIn          // Elements leaving
```

**Why Slow?**
Fast animations feel rushed. 300-400ms feels intentional and smooth.

---

## Custom Widgets

### SojornButton
Replaces `ElevatedButton`, `OutlinedButton`, `TextButton`

**Variants:**
- `primary`: Filled accent button
- `secondary`: Outlined button
- `tertiary`: Text-only button
- `destructive`: Filled error button

**Sizes:**
- `small`: 40px height
- `medium`: 48px height
- `large`: 56px height

**Example:**
```dart
SojornButton(
  label: 'Sign In',
  onPressed: _handleSignIn,
  variant: SojornButtonVariant.primary,
  size: SojornButtonSize.large,
  isFullWidth: true,
  isLoading: _isLoading,
)
```

### SojornInput
Replaces `TextField` with consistent styling

**Example:**
```dart
SojornInput(
  label: 'Email',
  hint: 'your@email.com',
  controller: _emailController,
  prefixIcon: Icons.email_outlined,
  keyboardType: TextInputType.emailAddress,
)
```

### SojornTextArea
For long-form content (posts, comments)

**Example:**
```dart
SojornTextArea(
  label: 'Write your post',
  hint: 'Share something thoughtful...',
  controller: _postController,
  maxLength: 500,
  showCharacterCount: true,
)
```

### SojornCard
Replaces `Card` with consistent elevation and borders

**Example:**
```dart
SojornCard(
  onTap: () => navigateToPost(),
  child: Column(
    children: [
      Text('Card title'),
      Text('Card content'),
    ],
  ),
)
```

### SojornDialog
Replaces `showDialog` with friendly styling

**Static Methods:**
```dart
// Confirmation
SojornDialog.showConfirmation(
  context: context,
  title: 'Delete post?',
  message: 'This cannot be undone.',
  isDestructive: true,
)

// Info
SojornDialog.showInfo(
  context: context,
  title: 'Account created',
  message: 'Welcome to Sojorn!',
)

// Error
SojornDialog.showError(
  context: context,
  title: 'Connection failed',
  message: 'Please check your internet.',
)
```

### SojornSnackbar
Replaces `ScaffoldMessenger.showSnackBar`

**Static Methods:**
```dart
SojornSnackbar.show(context: context, message: 'Post saved')
SojornSnackbar.showSuccess(context: context, message: 'Post published')
SojornSnackbar.showError(context: context, message: 'Failed to load')
SojornSnackbar.showWarning(context: context, message: 'Slow connection')
```

---

## Visual Friendliness Enforcement

### How the System Enforces Friendliness

1. **No Hardcoded Colors**
   - All colors come from `AppTheme`
   - Impossible to use bright red/blue by accident

2. **No Arbitrary Spacing**
   - All spacing uses the 4px grid constants
   - Creates visual rhythm

3. **Generous Defaults**
   - Card padding: 24px (not 16px)
   - Line height: 1.65 (not 1.4)
   - Animation: 300ms (not 150ms)

4. **Soft Shadows**
   - Maximum 8% opacity
   - Warm black, never pure black

5. **Warm Tint**
   - All grays have warm undertones
   - Avoids clinical/sterile feel

6. **Limited Font Weights**
   - 400 (regular), 500 (medium), 600 (semibold)
   - No bold (700) or black (900)

---

## Before/After Comparison

### Before (Material Default)
- Cold grays (#FAFAFA, #F5F5F5)
- Bright blue accent (#2196F3)
- Harsh shadows (24% opacity)
- Tight spacing (8px padding)
- Fast animations (100-150ms)
- Narrow line-height (1.4)

### After (Sojorn System)
- Warm neutrals (#F8F7F4, #F0EFEB)
- Muted slate accent (#5D6B7A)
- Soft shadows (4-8% opacity)
- Generous spacing (24px padding)
- Slow animations (300-400ms)
- Reading line-height (1.65)

**Result:** Feels like reading a book, not using an app.

---

## Testing Checklist

- [ ] All screens use `AppTheme` constants (no hardcoded colors)
- [ ] All spacing uses the 4px grid
- [ ] All buttons use `SojornButton` variants
- [ ] All inputs use `SojornInput` or `SojornTextArea`
- [ ] All cards use `SojornCard`
- [ ] All dialogs use `SojornDialog`
- [ ] All snackbars use `SojornSnackbar`
- [ ] Text hierarchy follows the type scale
- [ ] Shadows use the predefined shadow helpers
- [ ] Border radius uses the radius constants

---

## Dark Mode (Optional)

Dark theme uses the same warm philosophy:

```dart
darkBackground      = #1C1B1A  // Warm near-black
darkSurface         = #252422  // Warm dark gray
darkSurfaceElevated = #2E2C2A  // Lighter warm gray
darkTextPrimary     = #ECEBE8  // Warm off-white
```

**Key Difference:**
- No pure black (#000000)
- No pure white (#FFFFFF)
- Reduced contrast for less eye strain

---

## Resources

- [Type Scale Calculator](https://type-scale.com/)
- [Color Palette Generator](https://coolors.co/)
- [Material Design 3 Guidelines](https://m3.material.io/)
- [iOS Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)

---

**Last Updated:** 2026-01-06
**Maintained By:** Sojorn Design Team