diff --git a/EXHAUSTIVE_TODO_LIST.md b/EXHAUSTIVE_TODO_LIST.md index d7cdfef5c..5e501be54 100644 --- a/EXHAUSTIVE_TODO_LIST.md +++ b/EXHAUSTIVE_TODO_LIST.md @@ -4029,11 +4029,20 @@ Critical path dependencies: ### Sub-Epic 11.5: Define Style Direction 🟢 #### Task 11.5.1: Choose Design Direction -- [ ] **Action 11.5.1.1**: Document "Surgical Minimalism" direction - - **Scope**: `apps/web/src/styles/DESIGN_DIRECTION.md` (create) - - **Dependencies**: None +- [x] **Action 11.5.1.1**: Document "Surgical Minimalism" direction + - **Scope**: `apps/web/docs/DESIGN_DIRECTION.md` (create) ✅ + - **Dependencies**: None ✅ - **Risk**: LOW 🔒 - - **Validation**: Direction documented with examples + - **Validation**: ✅ Design direction comprehensively documented: + - **Core principles**: 80/20 color rule, increased whitespace, subtle interactions, gradients used sparingly, 8px grid system, text color hierarchy + - **Design tokens**: Section spacing variables documented + - **Color usage guidelines**: When to use cyan vs steel, neutral backgrounds + - **Implementation checklist**: Practical checklist for applying principles to components/pages + - **Examples**: Good vs avoid examples with code snippets + - **Migration path**: Completed actions, in progress, future work + - **References**: Links to all related audit documents + - **Benefits**: User experience, developer experience, accessibility benefits + - **Result**: Comprehensive design direction document that serves as the foundation for all aesthetic improvements. Defines "Surgical Minimalism" as: purposeful design, increased whitespace, restrained color usage (80/20 rule), subtle functional interactions, visual clarity. Aligns with all completed actions (text colors, card padding, section spacing, hover effects, gradients, 8px grid). - **Rollback**: Delete file - [ ] **Action 11.5.1.2**: Create design direction checklist diff --git a/apps/web/docs/DESIGN_DIRECTION.md b/apps/web/docs/DESIGN_DIRECTION.md new file mode 100644 index 000000000..82fc95b4a --- /dev/null +++ b/apps/web/docs/DESIGN_DIRECTION.md @@ -0,0 +1,276 @@ +# 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 + + + Title + + +

Content

+
+
+ +// Button with cyan only for primary actions + + + +// Section with proper spacing +
+ + +
+``` + +### ❌ Avoid: Excessive Decoration + +```tsx +// Card with gradient, scale transform, decorative shadow + + {/* Avoid */} + + +// Button with cyan for secondary actions + + +// Section with insufficient spacing +
+ {/* Should be space-y-8 */} +
+``` + +## 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