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, use this comprehensive checklist:

### Color (80/20 Rule)

#### Primary Actions (Use Cyan)
- [ ] Primary buttons use `bg-kodo-cyan` (not outline/secondary buttons)
- [ ] Active navigation states use `text-kodo-cyan` or `bg-kodo-cyan/10`
- [ ] Focus rings use `focus-visible:ring-kodo-cyan`
- [ ] Critical status indicators use cyan appropriately
- [ ] No cyan on decorative elements or backgrounds

#### Secondary Actions (Use Steel)
- [ ] Outline buttons use `border-kodo-steel` (not `border-kodo-cyan`)
- [ ] Outline button hover states use `hover:border-kodo-steel/50` (not cyan)
- [ ] Secondary navigation items use `text-kodo-steel` (not cyan)
- [ ] Non-primary interactive elements use steel colors
- [ ] Icon buttons (non-primary) use steel, not cyan

#### Neutral Backgrounds
- [ ] Cards use `bg-kodo-graphite` or `bg-kodo-ink` (solid colors, no gradients)
- [ ] Elevated surfaces use `bg-kodo-ink`
- [ ] Main backgrounds use `bg-kodo-void`
- [ ] No decorative color backgrounds (use neutral colors)

#### Color Ratio Check
- [ ] Approximately 80% of the component uses neutral colors (void, ink, graphite, steel, white)
- [ ] Approximately 20% uses accent colors (cyan for primary actions only)
- [ ] No excessive color usage that breaks the 80/20 rule

### Spacing (8px Grid Alignment)

#### Grid Alignment
- [ ] All spacing values are multiples of 8px (0, 8, 16, 24, 32, 48, 64, 96px)
- [ ] No use of non-8px values (4px, 12px, 40px, 80px) unless absolutely necessary
- [ ] Preferred values: `gap-2` (8px), `gap-4` (16px), `gap-6` (24px), `gap-8` (32px), `gap-12` (48px), `gap-16` (64px), `gap-24` (96px)

#### Card Padding
- [ ] Card padding is 32px (`p-8`) - increased from previous 24px (`p-6`)
- [ ] CardHeader, CardContent, CardFooter all use `p-8` (not `p-6`)
- [ ] Custom cards follow the same 32px padding standard

#### Section Spacing
- [ ] Standard section spacing is 32px (`space-y-8`) - increased from 24px (`space-y-6`)
- [ ] Large section containers use 48px (`space-y-12`) for major sections
- [ ] Page-level spacing uses 64px (`space-y-16`) or 96px (`space-y-24`) for maximum separation
- [ ] CSS variables can be used: `space-y-[var(--section-spacing)]` (32px) or `space-y-[var(--section-spacing-lg)]` (48px)

#### Whitespace Assessment
- [ ] Adequate breathing room between major sections
- [ ] Sufficient spacing between related elements (not cramped)
- [ ] Visual hierarchy is clear through spacing (not just color)
- [ ] No excessive spacing that creates disconnected feeling

### Interactions (Subtle & Functional)

#### Hover Effects - Keep (Functional)
- [ ] Background color changes: `hover:bg-white/5` for interactive feedback
- [ ] Opacity changes: `group-hover:opacity-100` for functional overlays (play buttons, tooltips)
- [ ] Border color changes: `hover:border-white/10` or `hover:border-kodo-steel/50` for interactive elements
- [ ] Text color changes: `hover:text-white` for navigation links
- [ ] Transition duration is reasonable: `transition-colors duration-200` or `transition-opacity duration-200`

#### Hover Effects - Remove (Excessive)
- [ ] No scale transforms on cards: Remove `hover:scale-[1.02]`, `hover:scale-110`, `hover:scale-105`
- [ ] No decorative shadows: Remove `hover:shadow-neon-cyan/20`, `hover:shadow-lg` on cards
- [ ] No image zoom effects: Remove `group-hover:scale-110` on decorative images
- [ ] No multiple simultaneous effects: Simplify combinations of scale + shadow + border
- [ ] No excessive glow effects: Remove `hover:shadow-[0_0_15px_rgba(255,255,255,0.5)]`

#### Animation Assessment
- [ ] All animations serve a functional purpose (feedback, state changes)
- [ ] No purely decorative animations
- [ ] Transitions are smooth but not distracting
- [ ] Performance is maintained (no janky animations)

### Visual Elements (Clarity & Purpose)

#### Gradients
- [ ] No gradients on card backgrounds (use solid `bg-kodo-graphite` or `bg-kodo-ink`)
- [ ] Gradients only in hero sections or featured content sections
- [ ] Functional overlay gradients for text readability are acceptable: `bg-gradient-to-t from-black/80`
- [ ] Small decorative gradients on icon containers are minimal and acceptable
- [ ] No decorative gradient overlays on cards (e.g., `bg-gradient-to-b from-white/5 to-transparent`)

#### Text Color Hierarchy
- [ ] Primary text uses `text-white` (not beige or dim colors)
- [ ] Headings use `text-white` for maximum contrast
- [ ] Secondary text uses `text-white opacity-80` or `text-kodo-content-dim` sparingly
- [ ] Metadata uses dim text only when genuinely less important
- [ ] Text contrast meets WCAG AA standards

#### Decorative Elements
- [ ] Unnecessary decorative elements are removed
- [ ] Every visual element serves a purpose (functional, not just aesthetic)
- [ ] No excessive borders, shadows, or highlights
- [ ] Visual clutter is minimized

### Component-Specific Checks

#### Buttons
- [ ] Primary buttons: `bg-kodo-cyan` with `text-black` or `text-white`
- [ ] Secondary/outline buttons: `border-kodo-steel` (not cyan)
- [ ] Hover states are subtle: `hover:opacity-90` or `hover:bg-white/5`
- [ ] No scale transforms on hover
- [ ] Focus states are clear: `focus-visible:ring-kodo-cyan`

#### Cards
- [ ] Padding is 32px (`p-8`)
- [ ] Background is solid color (`bg-kodo-graphite` or `bg-kodo-ink`)
- [ ] No gradients on background
- [ ] Hover effect is subtle: `hover:bg-white/5 transition-colors duration-200`
- [ ] No scale transforms or decorative shadows
- [ ] Border uses `border-kodo-steel` if needed (not cyan)

#### Navigation
- [ ] Active states use `text-kodo-cyan` or `bg-kodo-cyan/10`
- [ ] Inactive states use `text-kodo-steel` or `text-white`
- [ ] Hover states are subtle: `hover:text-white` or `hover:bg-white/5`
- [ ] No scale transforms on icons or text

#### Forms
- [ ] Input focus states use `focus-visible:ring-kodo-cyan`
- [ ] Labels use `text-white` for primary text
- [ ] Helper text uses dim text sparingly
- [ ] Error states use appropriate semantic colors
- [ ] Spacing between form fields aligns to 8px grid

#### Pages
- [ ] Main container spacing is 32px (`space-y-8`) or 48px (`space-y-12`) for large sections
- [ ] Page padding is 32px (`p-8`) or appropriate for layout
- [ ] Section hierarchy is clear through spacing
- [ ] No excessive decorative elements
- [ ] Color usage follows 80/20 rule

### Final Validation

#### Overall Assessment
- [ ] Component/page follows all "Surgical Minimalism" principles
- [ ] Visual hierarchy is clear and purposeful
- [ ] Whitespace is adequate and improves readability
- [ ] Color usage is restrained and strategic
- [ ] Interactions are subtle and functional
- [ ] No unnecessary decorative elements remain
- [ ] Component is accessible (WCAG AA compliant)
- [ ] Performance is maintained (no excessive animations or effects)

#### Documentation
- [ ] Component is documented if it's a reusable component
- [ ] Design decisions are clear and align with this direction
- [ ] Future maintainers can understand the design choices

## 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