353 lines
10 KiB
Markdown
353 lines
10 KiB
Markdown
# Design Audit Findings - Story 11.1
|
|
|
|
**Generated:** 2026-01-17
|
|
**Project:** Keep
|
|
|
|
## Executive Summary
|
|
|
|
This document outlines design inconsistencies found during the audit of the Keep application. The goal is to establish a consistent design system that improves visual hierarchy, usability, and maintainability.
|
|
|
|
---
|
|
|
|
## 1. Spacing Inconsistencies
|
|
|
|
### Current State
|
|
- **Padding inconsistencies across components:**
|
|
- NoteCard: `p-4` (16px)
|
|
- Card: `py-6 px-6` (24px/24px)
|
|
- Input: `px-3 py-1` (12px/4px)
|
|
- Badge: `px-2 py-0.5` (8px/2px)
|
|
- Button (sm): `px-3` (12px)
|
|
- Button (default): `px-4` (16px)
|
|
- Header search: `px-4 py-3` (16px/12px)
|
|
|
|
- **Margin/gap inconsistencies:**
|
|
- NoteCard: `mb-2`, `mt-3`, `gap-1`
|
|
- FavoritesSection: `mb-8`, `mb-4`, `gap-2`, `gap-4`
|
|
- Header: `space-x-3` (12px horizontal gap)
|
|
|
|
### Issues Identified
|
|
1. No consistent base unit usage (should be 4px)
|
|
2. Different padding values for similar components
|
|
3. Inconsistent gap/margin values between sections
|
|
|
|
### Recommended Standardization
|
|
```css
|
|
/* Tailwind spacing scale (4px base unit) */
|
|
p-1: 0.25rem (4px)
|
|
p-2: 0.5rem (8px)
|
|
p-3: 0.75rem (12px)
|
|
p-4: 1rem (16px)
|
|
p-6: 1.5rem (24px)
|
|
|
|
gap-1: 0.25rem (4px)
|
|
gap-2: 0.5rem (8px)
|
|
gap-3: 0.75rem (12px)
|
|
gap-4: 1rem (16px)
|
|
```
|
|
|
|
**Standard Components:**
|
|
- Cards: `p-4` (16px) for padding
|
|
- Buttons: `px-4 py-2` (16px/8px) default
|
|
- Inputs: `px-3 py-2` (12px/8px)
|
|
- Badges: `px-2 py-0.5` (8px/2px)
|
|
- Form sections: `gap-4` (16px)
|
|
|
|
---
|
|
|
|
## 2. Border Radius Inconsistencies
|
|
|
|
### Current State
|
|
- **Different border radius values:**
|
|
- NoteCard: `rounded-lg` (0.5rem/8px)
|
|
- Card: `rounded-xl` (0.75rem/12px)
|
|
- Button: `rounded-md` (0.375rem/6px)
|
|
- Input: `rounded-md` (0.375rem/6px)
|
|
- Badge: `rounded-full` (9999px)
|
|
- Header search: `rounded-2xl` (1rem/16px)
|
|
- FavoritesSection header: `rounded-lg` (0.5rem/8px)
|
|
- Grid view button: `rounded-xl` (0.75rem/12px)
|
|
- Theme toggle: `rounded-xl` (0.75rem/12px)
|
|
|
|
### Issues Identified
|
|
1. Inconsistent corner rounding across UI elements
|
|
2. Multiple radius values without clear purpose
|
|
|
|
### Recommended Standardization
|
|
```css
|
|
/* Standard border radius values */
|
|
rounded: 0.25rem (4px) - Small elements (icons, small badges)
|
|
rounded-md: 0.375rem (6px) - Inputs, small buttons
|
|
rounded-lg: 0.5rem (8px) - Cards, buttons, badges (default)
|
|
rounded-xl: 0.75rem (12px) - Large containers, modals
|
|
rounded-2xl: 1rem (16px) - Hero elements, search bars
|
|
rounded-full: 9999px - Circular elements (avatars, pill badges)
|
|
```
|
|
|
|
**Component Standards:**
|
|
- Cards/NoteCards: `rounded-lg` (8px)
|
|
- Buttons: `rounded-md` (6px)
|
|
- Inputs: `rounded-md` (6px)
|
|
- Badges (text): `rounded-full` (pills)
|
|
- Search bars: `rounded-lg` (8px)
|
|
- Icons: `rounded-full` (circular)
|
|
- Modals/Dialogs: `rounded-xl` (12px)
|
|
|
|
---
|
|
|
|
## 3. Shadow/Elevation Inconsistencies
|
|
|
|
### Current State
|
|
- **NoteCard:** `shadow-sm hover:shadow-md`
|
|
- **Card:** `shadow-sm`
|
|
- **Header search:** `shadow-sm`
|
|
- **Header buttons:** `hover:shadow-sm`
|
|
|
|
### Issues Identified
|
|
1. Limited use of elevation hierarchy
|
|
2. No clear shadow scale for different UI depths
|
|
|
|
### Recommended Standardization
|
|
```css
|
|
/* Tailwind shadow scale */
|
|
shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05)
|
|
shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1)
|
|
shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1)
|
|
shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1)
|
|
```
|
|
|
|
**Component Standards:**
|
|
- Cards: `shadow-sm` (base), `hover:shadow-md` (interactive)
|
|
- Buttons: No shadow (flat), `hover:shadow-sm` (optional)
|
|
- Modals: `shadow-lg` (elevated)
|
|
- Dropdowns: `shadow-lg` (elevated)
|
|
|
|
---
|
|
|
|
## 4. Typography Inconsistencies
|
|
|
|
### Current State
|
|
- **Font sizes vary:**
|
|
- NoteCard title: `text-base` (16px)
|
|
- NoteCard content: `text-sm` (14px)
|
|
- NoteCard badges: `text-xs`, `text-[10px]`
|
|
- Button: `text-sm`
|
|
- Input: `text-base` (mobile), `md:text-sm`
|
|
- Badge: `text-xs`
|
|
- FavoritesSection title: `text-xl` (20px)
|
|
- FavoritesSection subtitle: `text-sm`
|
|
- Header search: `text-sm`
|
|
- Header nav items: `text-sm`
|
|
|
|
- **Font weights:**
|
|
- NoteCard title: `font-medium`
|
|
- Button: `font-medium`
|
|
- Badge: `font-medium`
|
|
- FavoritesSection title: `font-semibold`
|
|
|
|
### Issues Identified
|
|
1. No clear typography hierarchy
|
|
2. Inconsistent font weights across headings
|
|
3. Custom font sizes (`text-[10px]`) instead of standard scale
|
|
|
|
### Recommended Standardization
|
|
```css
|
|
/* Typography scale (Tailwind defaults) */
|
|
text-xs: 0.75rem (12px) - Labels, small text, badges
|
|
text-sm: 0.875rem (14px) - Body text, buttons, inputs
|
|
text-base: 1rem (16px) - Card titles, emphasized text
|
|
text-lg: 1.125rem (18px) - Section headers
|
|
text-xl: 1.25rem (20px) - Page titles
|
|
text-2xl: 1.5rem (24px) - Large headings
|
|
|
|
/* Font weights */
|
|
font-normal: 400 - Body text
|
|
font-medium: 500 - Emphasized text, button labels
|
|
font-semibold: 600 - Section titles
|
|
font-bold: 700 - Major headings
|
|
```
|
|
|
|
**Typography Hierarchy:**
|
|
- Page titles: `text-2xl font-bold` (24px)
|
|
- Section headers: `text-xl font-semibold` (20px)
|
|
- Card titles: `text-lg font-medium` (18px)
|
|
- Body text: `text-sm text-gray-700` (14px)
|
|
- Button labels: `text-sm font-medium` (14px)
|
|
- Labels/badges: `text-xs font-medium` (12px)
|
|
- Metadata: `text-xs text-gray-500` (12px)
|
|
|
|
---
|
|
|
|
## 5. Color Usage Inconsistencies
|
|
|
|
### Current State
|
|
- **Hardcoded color classes in components:**
|
|
- NoteCard: `bg-blue-100`, `bg-purple-900/30`, `text-blue-600`, `text-purple-400`, `text-gray-900`, `text-gray-700`, `text-gray-500`
|
|
- Header: `bg-background-light/90`, `text-slate-500`, `text-amber-500`, `text-indigo-600`
|
|
- FavoritesSection: `text-gray-900`, `text-gray-500`
|
|
|
|
### Issues Identified
|
|
1. Colors not using CSS custom properties (variables)
|
|
2. Inconsistent color naming (gray vs slate vs zinc)
|
|
3. Mixed color semantics (functional vs semantic)
|
|
|
|
### Recommended Standardization
|
|
- Use CSS custom properties already defined in globals.css
|
|
- Apply semantic color naming through Tailwind utility classes
|
|
- Standardize color usage patterns:
|
|
```css
|
|
/* Use existing CSS variables */
|
|
--primary, --secondary, --accent, --destructive
|
|
--foreground, --muted-foreground, --card-foreground
|
|
--border, --input, --ring
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Transition/Animation Inconsistencies
|
|
|
|
### Current State
|
|
- **Transition values:**
|
|
- NoteCard: `transition-all duration-200`
|
|
- FavoritesSection: `transition-colors`
|
|
- Header buttons: `transition-all duration-200`
|
|
|
|
### Issues Identified
|
|
1. Inconsistent transition property usage
|
|
2. Varying durations without clear purpose
|
|
|
|
### Recommended Standardization
|
|
```css
|
|
/* Standard transitions */
|
|
transition-colors duration-200 - Color changes (hover states)
|
|
transition-all duration-200 - Multiple property changes
|
|
transition-opacity duration-150 - Fade in/out
|
|
transition-transform duration-200 - Movement/position
|
|
```
|
|
|
|
**Component Standards:**
|
|
- Buttons/hover states: `transition-colors duration-200`
|
|
- Cards: `transition-all duration-200`
|
|
- Modals/overlays: `transition-opacity duration-150`
|
|
|
|
---
|
|
|
|
## 7. Component-Specific Issues
|
|
|
|
### NoteCard Issues
|
|
- Hardcoded colors (`bg-blue-100`, etc.) not using theme variables
|
|
- Inconsistent padding (`p-4`) vs other cards (`py-6 px-6`)
|
|
- Badge with custom `text-[10px]` not following typography scale
|
|
|
|
### Button Issues
|
|
- Inconsistent padding between variants (sm vs default)
|
|
- Some buttons using hardcoded blue colors instead of theme colors
|
|
|
|
### Input Issues
|
|
- Inconsistent base font size (`text-base` vs `md:text-sm`)
|
|
|
|
### Header Issues
|
|
- Search bar uses `rounded-2xl` (16px) which is too round for search
|
|
- Inconsistent spacing (`px-6 lg:px-12`)
|
|
- Hardcoded colors (`bg-white dark:bg-slate-800/80`) not using theme variables
|
|
|
|
### Badge Issues
|
|
- `rounded-full` (pills) vs inconsistent usage elsewhere
|
|
- Good: Uses CSS variables for colors
|
|
|
|
---
|
|
|
|
## 8. Accessibility Concerns
|
|
|
|
### Current State
|
|
- **Touch targets:**
|
|
- Some buttons: `h-8 w-8` (32px) - below 44px minimum
|
|
- Header buttons: `p-2.5` (20px) - below 44px minimum
|
|
|
|
### Issues Identified
|
|
1. Touch targets below WCAG 2.1 AA minimum (44x44px)
|
|
2. Focus indicators inconsistent (some `focus-visible`, some not)
|
|
|
|
### Recommended Fixes
|
|
- Increase touch target size to minimum 44x44px on mobile
|
|
- Ensure all interactive elements have focus-visible states
|
|
- Use `min-h-[44px] min-w-[44px]` for mobile buttons
|
|
|
|
---
|
|
|
|
## 9. Component Priority Matrix
|
|
|
|
### High Priority (Core User Experience)
|
|
1. **NoteCard** - Primary UI component, seen frequently
|
|
2. **Button** - Used throughout app
|
|
3. **Input** - Form interactions
|
|
4. **Header** - Global navigation
|
|
|
|
### Medium Priority (Secondary UI)
|
|
1. **Card** - Container component
|
|
2. **Badge** - Status indicators
|
|
3. **Label/Badge components** - Filtering
|
|
4. **Modals/Dialogs** - User interactions
|
|
|
|
### Low Priority (Enhancements)
|
|
1. **Animations** - Motion design
|
|
2. **Loading states** - Skeleton screens
|
|
3. **Empty states** - Zero-state design
|
|
4. **Error states** - Error handling UI
|
|
|
|
---
|
|
|
|
## 10. Implementation Recommendations
|
|
|
|
### Phase 1: Foundation (Do First)
|
|
1. ✅ Create/update design system documentation
|
|
2. ✅ Standardize spacing scale (4px base unit)
|
|
3. ✅ Standardize border radius values
|
|
4. ✅ Standardize typography hierarchy
|
|
5. ✅ Update globals.css with design tokens if needed
|
|
|
|
### Phase 2: Core Components
|
|
1. Update Button component for consistent padding
|
|
2. Update Input component for consistent typography
|
|
3. Update Card component for consistent padding
|
|
4. Update Badge component (already good)
|
|
|
|
### Phase 3: Feature Components
|
|
1. Update NoteCard component
|
|
2. Update Header component
|
|
3. Update FavoritesSection component
|
|
4. Update other feature components
|
|
|
|
### Phase 4: Testing & Validation
|
|
1. Visual regression testing
|
|
2. Cross-browser testing
|
|
3. Accessibility testing (WAVE, axe DevTools)
|
|
4. Mobile responsive testing
|
|
|
|
---
|
|
|
|
## Summary of Changes Needed
|
|
|
|
### Files to Update
|
|
1. `keep-notes/app/globals.css` - Review and document design tokens
|
|
2. `keep-notes/components/ui/button.tsx` - Standardize padding
|
|
3. `keep-notes/components/ui/input.tsx` - Standardize typography
|
|
4. `keep-notes/components/ui/card.tsx` - Standardize padding/radius
|
|
5. `keep-notes/components/note-card.tsx` - Replace hardcoded colors
|
|
6. `keep-notes/components/header.tsx` - Replace hardcoded colors
|
|
7. `keep-notes/components/favorites-section.tsx` - Standardize typography
|
|
8. `keep-notes/components/ui/badge.tsx` - Review (already good)
|
|
|
|
### Design System Benefits
|
|
- ✅ Consistent visual appearance
|
|
- ✅ Improved developer experience
|
|
- ✅ Easier maintenance
|
|
- ✅ Better accessibility
|
|
- ✅ Scalable architecture
|
|
- ✅ Theme support (light/dark/custom)
|
|
|
|
---
|
|
|
|
**Document Status:** Complete
|
|
**Next Step:** Implement design system updates (see Story 11.1 Tasks)
|