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

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

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

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