sepehr/Keep
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Keep/_bmad-output/implementation-artifacts/11-1-design-audit-findings.md

10 KiB
Raw Blame History

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

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

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

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

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

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