veza/apps/web/docs/DESIGN_DIRECTION.md

# Design Direction: Surgical Minimalism

**Last Updated**: 2025-01-27  
**Status**: Active Design Direction  
**Purpose**: Define the "Surgical Minimalism" design philosophy for the Veza application

## Overview

"Surgical Minimalism" is a design philosophy that emphasizes:
- **Purposeful design**: Every visual element serves a function
- **Increased whitespace**: More breathing room improves readability and hierarchy
- **Restrained color usage**: Color used strategically, not decoratively
- **Subtle interactions**: Hover effects and animations are functional, not excessive
- **Visual clarity**: Remove unnecessary decorative elements

## Core Principles

### 1. 80/20 Color Rule

**Principle**: 80% neutral colors, 20% accent colors

- **80% Neutral**: Dark backgrounds (`kodo-void`, `kodo-ink`, `kodo-graphite`), white text, subtle grays
- **20% Color**: Strategic use of `kodo-cyan` for primary actions only, sparing use of other accent colors

**Implementation**:
- Primary actions: Use `kodo-cyan` (buttons, active states, focus rings)
- Secondary actions: Use `kodo-steel` instead of cyan
- Decorative elements: Use neutral colors, avoid color backgrounds
- Status/info: Use semantic colors only when necessary

**Target**: Reduce cyan usage by 30-40% from current levels

### 2. Increased Whitespace

**Principle**: More breathing room improves visual hierarchy and reduces cognitive load

**Implementation**:
- **Card padding**: 32px (was 24px) - `p-8` instead of `p-6`
- **Section spacing**: 32px standard (was 24px) - `space-y-8` instead of `space-y-6`
- **Large sections**: 48px for major containers - `space-y-12` for DashboardPage
- **8px grid alignment**: All spacing values align to 8px multiples

**Benefits**:
- Improved readability
- Better visual hierarchy
- Reduced visual clutter
- More professional appearance

### 3. Subtle, Purposeful Interactions

**Principle**: Hover effects and animations should be functional, not decorative

**Keep** (Necessary):
- Background color changes: `hover:bg-white/5` for interactive feedback
- Opacity changes: `group-hover:opacity-100` for functional overlays (play buttons)
- Border color changes: `hover:border-white/10` for interactive elements
- Text color changes: `hover:text-white` for navigation links

**Remove** (Excessive):
- Scale transforms: `hover:scale-[1.02]`, `hover:scale-110` on cards
- Decorative shadows: `hover:shadow-neon-cyan/20`, `hover:shadow-lg` on cards
- Image zoom effects: `group-hover:scale-110` on decorative images
- Multiple simultaneous effects: Scale + shadow + border combinations

**Target**: Reduce hover effects by 30-40% (remove decorative effects)

### 4. Gradients Used Sparingly

**Principle**: Gradients reserved for hero sections and functional overlays

**Keep Gradients**:
- Hero sections: Featured content, landing sections
- Functional overlays: Text readability over images (`bg-gradient-to-t from-black/80`)
- Small decorative elements: Icon containers, visualizations (minimal)

**Remove Gradients**:
- Card backgrounds: Use solid colors (`bg-kodo-ink`, `bg-kodo-graphite`)
- Decorative sections: Replace with solid backgrounds
- Hover overlays: Use solid colors with opacity

**Result**: All card components use solid backgrounds

### 5. 8px Grid System

**Principle**: All spacing aligns to an 8px base grid for visual rhythm

**Preferred Values** (8px-aligned):
- `gap-2`, `p-2`, `m-2` (8px) - Base unit
- `gap-4`, `p-4`, `m-4` (16px) - Standard
- `gap-6`, `p-6`, `m-6` (24px) - Large
- `gap-8`, `p-8`, `m-8` (32px) - Extra large (card padding, section spacing)
- `gap-12`, `p-12`, `m-12` (48px) - Section spacing, large containers
- `gap-16`, `p-16`, `m-16` (64px) - Page-level spacing
- `gap-24`, `p-24`, `m-24` (96px) - Maximum spacing

**Avoid** (not 8px-aligned):
- `gap-1`, `p-1`, `m-1` (4px) - Use `gap-2` instead
- `gap-3`, `p-3`, `m-3` (12px) - Use `gap-2` or `gap-4` instead
- `gap-10`, `p-10`, `m-10` (40px) - Use `gap-8` or `gap-12` instead
- `gap-20`, `p-20`, `m-20` (80px) - Use `gap-16` or `gap-24` instead

### 6. Text Color Hierarchy

**Principle**: Use white for primary content, dim text sparingly for truly secondary information

**Primary Text**:
- Main content: `text-white` (was `text-kodo-text-main` with beige)
- Headings: `text-white`
- Interactive elements: `text-white` with opacity for hover states

**Secondary Text**:
- Truly secondary info: `text-kodo-secondary` or `text-white opacity-80`
- Metadata: `text-kodo-content-dim`
- Use sparingly: Only for information that is genuinely less important

**Result**: Better contrast, improved readability, WCAG AA compliant

## Design Tokens

### Section Spacing

```css
--section-spacing: 2rem; /* 32px - Standard section spacing (4× base) */
--section-spacing-lg: 3rem; /* 48px - Large section spacing (6× base) */
```

**Usage**:
- Standard sections: `space-y-8` (32px)
- Large containers: `space-y-12` (48px)
- Or use CSS variable: `space-y-[var(--section-spacing)]`

### Color Usage Guidelines

**Primary Actions** (Use Cyan):
- Primary buttons: `bg-kodo-cyan`
- Active navigation: `text-kodo-cyan`, `bg-kodo-cyan/10`
- Focus rings: `focus-visible:ring-kodo-cyan`
- Critical status indicators

**Secondary Actions** (Use Steel):
- Outline buttons: `border-kodo-steel`, `hover:border-kodo-steel/50`
- Secondary navigation: `text-kodo-steel`
- Non-primary interactive elements

**Neutral Backgrounds**:
- Cards: `bg-kodo-graphite` or `bg-kodo-ink`
- Elevated surfaces: `bg-kodo-ink`
- Main background: `bg-kodo-void`

## Implementation Checklist

When applying "Surgical Minimalism" to a component or page:

### Color
- [ ] Is cyan used only for primary actions?
- [ ] Are secondary actions using `kodo-steel` instead of cyan?
- [ ] Is the 80/20 rule followed (80% neutral, 20% color)?
- [ ] Are decorative color backgrounds removed?

### Spacing
- [ ] Does spacing align to 8px grid?
- [ ] Is card padding 32px (`p-8`)?
- [ ] Is section spacing 32px (`space-y-8`) or 48px (`space-y-12`) for large sections?
- [ ] Is there adequate whitespace between elements?

### Interactions
- [ ] Are hover effects subtle and functional?
- [ ] Are scale transforms removed from cards?
- [ ] Are decorative shadows removed?
- [ ] Are multiple simultaneous effects simplified?

### Visual Elements
- [ ] Are gradients removed from cards?
- [ ] Are gradients only in hero sections?
- [ ] Is text color hierarchy clear (white primary, dim secondary)?
- [ ] Are unnecessary decorative elements removed?

## Examples

### ✅ Good: Surgical Minimalism Applied

```tsx
// Card with solid background, subtle hover, adequate padding
<Card className="p-8 hover:bg-white/5 transition-colors">
  <CardHeader>
    <CardTitle className="text-white">Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p className="text-white opacity-80">Content</p>
  </CardContent>
</Card>

// Button with cyan only for primary actions
<Button variant="default" className="bg-kodo-cyan">Primary Action</Button>
<Button variant="outline" className="border-kodo-steel hover:border-kodo-steel/50">
  Secondary Action
</Button>

// Section with proper spacing
<div className="space-y-8">
  <Section1 />
  <Section2 />
</div>
```

### ❌ Avoid: Excessive Decoration

```tsx
// Card with gradient, scale transform, decorative shadow
<Card className="p-6 bg-gradient-to-r from-kodo-ink to-kodo-graphite hover:scale-[1.02] hover:shadow-neon-cyan/20">
  {/* Avoid */}
</Card>

// Button with cyan for secondary actions
<Button variant="outline" className="border-kodo-cyan hover:border-kodo-cyan/50">
  {/* Should use kodo-steel */}
</Button>

// Section with insufficient spacing
<div className="space-y-4">
  {/* Should be space-y-8 */}
</div>
```

## Migration Path

### Completed Actions

1. ✅ **Text Colors**: Changed primary text to white, use dim text sparingly
2. ✅ **Card Padding**: Increased from 24px to 32px
3. ✅ **Section Spacing**: Increased from 24px to 32px (standard), 48px (large)
4. ✅ **Hover Effects**: Removed excessive scale transforms and decorative shadows
5. ✅ **Gradients**: Removed from cards, kept only in hero sections
6. ✅ **8px Grid**: Documented and verified alignment

### In Progress

- **Color Reduction**: Audit complete, replacement in progress
- **Component Updates**: Applying principles to remaining components

### Future Work

- Apply to all remaining pages and components
- Create design system components that enforce principles
- Add linting rules to prevent violations

## References

- **8px Grid System**: `apps/web/src/styles/GRID_SYSTEM.md`
- **Cyan Usage Audit**: `apps/web/docs/CYAN_USAGE_AUDIT.md`
- **Hover Effects Audit**: `apps/web/docs/HOVER_EFFECTS_AUDIT.md`
- **Gradient Usage Verification**: `apps/web/docs/GRADIENT_USAGE_VERIFICATION.md`
- **Section Spacing Audit**: `apps/web/docs/SECTION_SPACING_AUDIT.md`
- **Design Tokens**: `apps/web/src/styles/design-tokens.css`

## Benefits

**User Experience**:
- Reduced cognitive load
- Improved readability
- Better visual hierarchy
- More professional appearance
- Faster information processing

**Developer Experience**:
- Clear design principles
- Consistent patterns
- Reusable utilities
- Easier maintenance
- Better scalability

**Accessibility**:
- WCAG AA compliant contrast ratios
- Clear focus states
- Reduced visual noise
- Better screen reader experience