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:

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

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