chore(docs): consolidate 22 audit files from root into docs/audits/

Root directory had accumulated audit/exploration markdown files cluttering the project root. Moved all audit-related files to docs/audits/ with a README.md index, and updated cross-references in K6_LOAD_TESTING_GUIDE.md and README_FRONTEND_DOCS.md. Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-10 23:16:00 +07:00
parent 68b65cb848
commit 59272e9321
26 changed files with 8500 additions and 189 deletions
--- a/docs/audits/ACCESSIBILITY_FINDINGS_SUMMARY.txt
+++ b/docs/audits/ACCESSIBILITY_FINDINGS_SUMMARY.txt
@@ -0,0 +1,436 @@
+================================================================================
+  GOODGO PLATFORM FRONTEND - ACCESSIBILITY AUDIT SUMMARY
+  Date: April 10, 2026 | Audited: apps/web (Next.js 14)
+================================================================================
+
+📊 OVERVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Current WCAG 2.1 AA Compliance: 70-75%
+📁 Total Files Analyzed: 90+ TSX/JSX files
+🏷️ ARIA Attributes Found: 75 instances across 14 files
+⏱️ Time to Full Compliance: 4-6 days (full-time development)
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1️⃣ CURRENT ARIA USAGE - DETAILED BREAKDOWN
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ARIA Attribute Distribution:
+├─ aria-label: 41 instances (Primary usage for icon-only buttons, form labels)
+├─ aria-hidden: 17 instances (For decorative icons, spinners, emojis)
+├─ aria-describedby: 10 instances (Linking error messages to form inputs)
+├─ aria-invalid: 10 instances (Marking invalid form fields)
+├─ aria-labelledby: 3 instances (Section labeling)
+├─ aria-pressed: 0 instances (Should add for toggle buttons)
+├─ aria-expanded: 0 instances (Should add for collapsible menus)
+└─ aria-modal: 0 instances (CRITICAL: Missing from dialog component)
+
+Files with ARIA Attributes (14 files):
+  ✅ apps/web/app/[locale]/layout.tsx - Root layout, skip-to-content
+  ✅ apps/web/app/[locale]/(public)/layout.tsx - Public layout (EXCELLENT)
+  ✅ apps/web/app/[locale]/(public)/page.tsx - Landing page
+  ✅ apps/web/app/[locale]/(dashboard)/layout.tsx - Dashboard layout
+  ✅ apps/web/app/[locale]/(admin)/layout.tsx - Admin layout (HAS ISSUE)
+  ✅ apps/web/app/[locale]/(auth)/login/page.tsx - Login form
+  ✅ apps/web/app/[locale]/(auth)/register/page.tsx - Register form
+  ✅ apps/web/components/ui/language-switcher.tsx - Language toggle
+  ✅ apps/web/components/search/filter-bar.tsx - Search filters
+  ✅ apps/web/components/search/property-card.tsx - Property cards
+  ✅ apps/web/components/listings/image-gallery.tsx - Image gallery (HAS ISSUE)
+  ✅ apps/web/app/[locale]/error.tsx - Error page
+  ✅ apps/web/app/[locale]/not-found.tsx - 404 page
+  ✅ components/ui/__tests__/select.spec.tsx - Component tests
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+2️⃣ ICON-ONLY BUTTONS ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Total Icon-Only Buttons Found: 15+
+Properly Labeled: 14/15 (93%)
+Missing Labels: 1 location (image gallery thumbnails)
+
+✅ PROPERLY LABELED:
+  • Mobile menu toggle buttons (3 instances)
+    └─ Files: (public), (dashboard), (admin) layouts
+    └─ Example: aria-label={mobileMenuOpen ? t('nav.closeMenu') : t('nav.openMenu')}
+  
+  • Theme toggle button (1 instance)
+    └─ File: (dashboard) layout, line 150
+    └─ Example: aria-label={theme === 'light' ? t('dashboard.darkMode') : ...}
+  
+  • Language switcher (1 instance)
+    └─ File: components/ui/language-switcher.tsx, line 29
+    └─ Example: aria-label={`${t('label')}: ${t(locale)} → ${t(nextLocale)}`}
+  
+  • Image gallery navigation (2 instances)
+    └─ File: components/listings/image-gallery.tsx, lines 47, 54
+    └─ Example: aria-label="Ảnh trước" (Previous image)
+  
+  • Password show/hide buttons (2 instances)
+    └─ Files: (auth) login and register pages
+    └─ Example: aria-label={showPassword ? t('hidePassword') : t('showPassword')}
+  
+  • Admin/Dashboard sidebar close buttons (2 instances)
+    └─ File: (admin) and (dashboard) layouts
+    └─ Example: aria-label={t('adminNav.closeMenu')}
+
+🔴 MISSING LABELS:
+  ❌ Image gallery thumbnail buttons (multiple)
+     └─ File: apps/web/components/listings/image-gallery.tsx:69-84
+     └─ Issue: No aria-label on <button> elements
+     └─ Impact: Screen reader only announces "button" without context
+     └─ Fix: Add aria-label={`Select image ${index + 1}`}
+     └─ Priority: CRITICAL
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+3️⃣ FORM INPUTS WITHOUT LABELS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Total Form Inputs: 25+
+Properly Labeled: 24/25 (96%)
+Missing Visible Labels: 1 input
+
+✅ PROPERLY LABELED FORMS:
+  ✅ Login Form (2 inputs)
+     File: apps/web/app/[locale]/(auth)/login/page.tsx
+     Pattern: <Label htmlFor="phone"> + <Input id="phone">
+     + Includes aria-describedby for errors
+     + Includes aria-invalid for invalid state
+  
+  ✅ Register Form (5 inputs)
+     File: apps/web/app/[locale]/(auth)/register/page.tsx
+     Pattern: Same as login form
+     All fields: fullName, phone, email, password, confirmPassword
+  
+  ✅ Valuation Form (8+ inputs)
+     File: apps/web/components/valuation/valuation-form.tsx
+     Pattern: Label with htmlFor attribute
+  
+  ✅ Search Filters (4 selects)
+     File: apps/web/components/search/filter-bar.tsx
+     Pattern: aria-label on select elements (acceptable for filters)
+     + transactionType, propertyType, city, priceRange
+
+🟡 NEEDS IMPROVEMENT:
+  ⚠️ Landing Page Search Input
+     File: apps/web/app/[locale]/(public)/page.tsx:87-92
+     Current: Only has aria-label, no visible label
+     Issue: Visual users don't see field purpose
+     Fix: Add <label htmlFor="search-input" className="sr-only">
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+4️⃣ SKIP-TO-CONTENT LINK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: ✅ PROPERLY IMPLEMENTED
+
+Location: apps/web/app/[locale]/layout.tsx:105-110
+
+Implementation Details:
+  <a
+    href="#main-content"
+    className="fixed left-2 top-2 z-[100] -translate-y-16 rounded-md..."
+  >
+    {t('skipToContent')}
+  </a>
+
+Features:
+  ✅ Hidden by default with -translate-y-16 (off-screen)
+  ✅ Visible on focus with focus:translate-y-0
+  ✅ High z-index (z-[100]) ensures visibility
+  ✅ Clear visual styling (primary color)
+  ✅ Internationalized text (English & Vietnamese)
+  ✅ Links to id="main-content" on main element
+  ✅ Proper link semantics using <a> tag
+
+Target Element Found:
+  Location: apps/web/app/[locale]/(public)/layout.tsx:148
+  Code: <main id="main-content" role="main">{children}</main>
+
+Additional Main Elements:
+  ✅ apps/web/app/[locale]/(public)/layout.tsx:148
+  ✅ apps/web/app/[locale]/(dashboard)/layout.tsx:141
+  ✅ apps/web/app/[locale]/(admin)/layout.tsx:141
+  ✅ apps/web/app/[locale]/(auth)/layout.tsx (implicit)
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+5️⃣ INTERACTIVE ELEMENTS WITHOUT ACCESSIBLE NAMES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Total Interactive Elements Reviewed: 50+
+Properly Named: 48/50 (96%)
+Missing Accessible Names: 2 locations
+
+✅ WELL-NAMED ELEMENTS:
+  ✅ All Primary Buttons: Have visible text
+  ✅ All Navigation Links: Have visible text
+  ✅ Most Icon-Only Buttons: Have aria-labels
+  ✅ All Form Controls: Have labels or aria-labels
+  ✅ Cards: Have article labels (property cards)
+
+🔴 NEEDING ATTENTION:
+  
+  ❌ CRITICAL: Image Gallery Thumbnail Buttons
+     File: apps/web/components/listings/image-gallery.tsx:69-84
+     Issue: No aria-label on thumbnail selection buttons
+     Impact: Screen readers say "button" with no context
+     Fix: Add aria-label={`Select image ${index + 1}`}
+  
+  ⚠️ MINOR: Navigation Links (redundant labels)
+     File: apps/web/app/[locale]/(dashboard)/layout.tsx:125
+     Issue: aria-label on links when text is visible
+     Recommendation: Remove aria-label (visible text is better)
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+6️⃣ LAYOUT STRUCTURE & LANDMARK REGIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Landmark Distribution:
+
+HEADERS (3/4 with role="banner")
+  ✅ Public Layout: role="banner"
+  ✅ Dashboard Layout: role="banner"
+  ❌ Admin Layout: MISSING role="banner" ← FIX NEEDED
+  ✅ Auth Layout: role="banner" (implicit)
+
+NAVIGATION (4/4 with aria-label)
+  ✅ Public Layout: <nav aria-label="Main navigation">
+  ✅ Dashboard Layout: <nav aria-label="Dashboard">
+  ✅ Admin Layout: <nav aria-label="Administration">
+  ✅ Auth Layout: Implicit in public/dashboard layouts
+
+MAIN CONTENT (4/4 with id + role)
+  ✅ Public Layout: <main id="main-content" role="main">
+  ✅ Dashboard Layout: <main id="main-content" role="main">
+  ✅ Admin Layout: <main id="main-content" role="main">
+  ✅ Auth Layout: <main id="main-content" role="main">
+
+FOOTERS (1/1 with role="contentinfo")
+  ✅ Public Layout: <footer role="contentinfo">
+
+NAVIGATION ASIDES (2/2 with role="navigation")
+  ✅ Dashboard Sidebar: <aside role="navigation">
+  ✅ Admin Sidebar: <aside role="navigation">
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+7️⃣ COLOR CONTRAST & THEME SYSTEM
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: ⚠️ NEEDS VERIFICATION
+
+Color System Implementation:
+  File: apps/web/tailwind.config.ts
+  Format: HSL CSS Variables
+  Theme: Light/Dark mode support
+
+CSS Variables Defined:
+  --border, --input, --ring
+  --background, --foreground
+  --primary, --primary-foreground
+  --secondary, --secondary-foreground
+  --destructive, --destructive-foreground
+  --muted, --muted-foreground
+  --accent, --accent-foreground
+  --card, --card-foreground
+
+Theme Implementation:
+  File: apps/web/components/providers/theme-provider.tsx
+  • Light/Dark mode toggle via class on document root
+  • localStorage persistence (key: 'goodgo-theme')
+  • System preference detection via matchMedia
+
+Color Values: NOT VERIFIED IN AUDIT
+  Issue: CSS variable values not checked from globals.css
+  Impact: Potential WCAG 1.4.3 contrast violations undetected
+  Recommendation: Extract and test all color combinations
+
+Testing Needed:
+  ❓ Primary text on primary background (4.5:1 minimum)
+  ❓ Primary text on white background (4.5:1 minimum)
+  ❓ Primary text on muted background (4.5:1 minimum)
+  ❓ Dark mode combinations
+  ❓ Links (4.5:1 minimum)
+  ❓ Disabled states
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+8️⃣ COMPONENT ACCESSIBILITY PATTERNS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Button Component ✅ GOOD
+  Location: apps/web/components/ui/button.tsx
+  Features:
+    ✅ Focus-visible: ring styling on focus
+    ✅ Disabled state: opacity-50, pointer-events-none
+    ✅ Variants: 6 (default, destructive, outline, secondary, ghost, link)
+    ✅ Sizes: 4 (default, sm, lg, icon)
+  Issue: Icon-only buttons need aria-label from parent
+  Status: ✅ Component working well
+
+Input Component ✅ GOOD
+  Location: apps/web/components/ui/input.tsx
+  Features:
+    ✅ Focus-visible: ring styling
+    ✅ Disabled state: opacity-50
+    ✅ Type support: all HTML input types
+    ✅ Props pass-through: {...props}
+  Status: ✅ Properly implemented
+
+Label Component ✅ GOOD
+  Location: apps/web/components/ui/label.tsx
+  Features:
+    ✅ Native <label> element
+    ✅ Peer-disabled styling
+    ✅ htmlFor support expected
+  Status: ✅ Properly implemented
+
+Select Component ✅ GOOD
+  Location: apps/web/components/ui/select.tsx
+  Features:
+    ✅ Native <select> element
+    ✅ Focus-visible styling
+    ✅ Disabled state
+  Status: ✅ Good component
+
+Dialog Component 🔴 CRITICAL ISSUES
+  Location: apps/web/components/ui/dialog.tsx
+  Issues:
+    ❌ Missing role="dialog"
+    ❌ Missing aria-modal="true"
+    ❌ No focus trap implemented
+    ❌ No escape key handling
+    ❌ Background not marked aria-hidden
+  Impact: WCAG 4.1.2 violation (Name, Role, Value)
+  Priority: CRITICAL - Must rewrite
+  Estimated Fix Time: 2-3 hours
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ISSUES PRIORITY MATRIX
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 CRITICAL (Must Fix Before Launch)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Dialog Component Missing Accessibility
+   File: apps/web/components/ui/dialog.tsx
+   Time: 2-3 hours
+   WCAG: 4.1.2 (Name, Role, Value)
+   Action: Rewrite with role="dialog", aria-modal, focus trap, escape handling
+
+2. Image Gallery Thumbnail Buttons Missing Labels
+   File: apps/web/components/listings/image-gallery.tsx:69-84
+   Time: 15-30 minutes
+   WCAG: 2.5.3 (Label in Name)
+   Action: Add aria-label={`Select image ${index + 1}`}
+
+
+🟡 MAJOR (Should Fix ASAP)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Admin Layout Header Missing Banner Role
+   File: apps/web/app/[locale]/(admin)/layout.tsx:134
+   Time: 2 minutes
+   WCAG: 1.3.1 (Info and Relationships)
+   Action: Add role="banner" to header
+
+2. Color Contrast Not Verified
+   Impact: Potential WCAG 1.4.3 violation
+   Time: 4-6 hours testing
+   Action: Extract CSS variables, test with WebAIM, document results
+
+3. Landing Page Search Missing Visible Label
+   File: apps/web/app/[locale]/(public)/page.tsx:87-92
+   Time: 30 minutes
+   WCAG: 3.3.2 (Labels or Instructions)
+   Action: Add visible label with sr-only utility class
+
+
+🟢 MINOR (Nice to Have)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Redundant aria-labels on Visible Text
+   File: apps/web/app/[locale]/(dashboard)/layout.tsx:125
+   Time: 15 minutes
+   Action: Remove redundant aria-labels where text is visible
+
+2. Additional Skip Links
+   Time: 2-3 hours
+   Recommendation: Add skip-to-nav, skip-to-footer links
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WCAG 2.1 LEVEL AA COMPLIANCE MATRIX
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1.1 Text Alternatives              ⚠️ PARTIAL    Images have alt text, icons hidden
+1.3.1 Info and Relationships       🔴 FAIL       Admin header missing role
+1.4.3 Contrast (Minimum)           ❓ UNKNOWN    CSS vars defined, not verified
+2.1.1 Keyboard                     ✅ PASS       All elements keyboard accessible
+2.1.2 No Keyboard Trap             ⚠️ PARTIAL    Dialogs don't trap focus
+2.4.1 Bypass Blocks                ✅ PASS       Skip-to-content link present
+2.4.3 Focus Order                  ✅ PASS       DOM order logical
+2.4.4 Link Purpose (In Context)    ⚠️ PARTIAL    Most clear, some icon needs label
+2.5.3 Label in Name                🔴 FAIL       Thumbnail buttons missing labels
+3.3.1 Error Identification         ✅ PASS       Errors properly announced
+3.3.2 Labels or Instructions       🟡 PARTIAL    Some inputs missing visible labels
+4.1.2 Name, Role, Value            🔴 FAIL       Dialog missing role/aria-modal
+4.1.3 Status Messages              ✅ PASS       Status/alert roles proper
+
+Overall Compliance: 70-75% (9/14 passing)
+
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+IMPLEMENTATION TIMELINE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+WEEK 1 (40 hours)
+  Day 1-2: Fix Dialog Component (2-3 hrs) + Add Thumbnail Labels (0.5 hrs)
+  Day 2: Fix Admin Header (0.1 hrs) + Color Testing (6-8 hrs)
+  Day 3-4: Landing Page Label (0.5 hrs) + Browser Testing (8 hrs)
+  Day 5: Integration & Additional Testing (8 hrs)
+
+WEEK 2 (20 hours)
+  Day 1: Remove Redundant Labels (0.5 hrs) + Additional Skip Links (2-3 hrs)
+  Day 2-4: Comprehensive Testing with Screen Readers (8-10 hrs)
+  Day 5: Fix Issues Found, Final Verification (5-6 hrs)
+
+Total: ~60 hours to achieve full WCAG 2.1 AA compliance
+
+
+DOCUMENTATION PROVIDED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. ACCESSIBILITY_AUDIT_2026-04-10.md (47 KB, 1552 lines)
+   ✅ Comprehensive 15-section report with:
+   - Detailed ARIA usage analysis
+   - Code examples and fixes
+   - File-by-file findings
+   - WCAG compliance matrix
+   - Resource references
+
+2. ACCESSIBILITY_AUDIT_QUICK_REFERENCE.md (8.6 KB)
+   ✅ Quick reference guide with:
+   - Issue summaries and quick fixes
+   - Priority roadmap
+   - Testing checklist
+   - Code examples
+
+3. ACCESSIBILITY_FINDINGS_SUMMARY.txt (This file)
+   ✅ Executive summary with:
+   - Key metrics and overview
+   - Detailed breakdown of all 8 sections
+   - Issue priority matrix
+   - Implementation timeline
+
+
+================================================================================
+END OF SUMMARY
+================================================================================