aesthetic-improvements: document Surgical Minimalism design direction
- Created comprehensive design direction document - Defined 6 core principles: 80/20 color rule, increased whitespace, subtle interactions, gradients used sparingly, 8px grid system, text color hierarchy - Documented design tokens and color usage guidelines - Added implementation checklist for applying principles - Included good vs avoid examples with code snippets - Documented migration path and references to audit documents - Aligns with all completed aesthetic improvement actions - Serves as foundation for future design work - Action 11.5.1.1 complete
This commit is contained in:
senke
parent
a1bc64606a
commit
c34a3d0170
2 changed files with 289 additions and 4 deletions
|
|
@ -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
|
||||
|
|
|
|||
276
apps/web/docs/DESIGN_DIRECTION.md
Normal file
276
apps/web/docs/DESIGN_DIRECTION.md
Normal file
|
|
@ -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
|
||||
<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
|
||||
Loading…
Reference in a new issue