commit

docs/ui-ux-audit-sprint-6.12.md

@@ -0,0 +1,337 @@
+# UI/UX Audit Sprint 6.12
+
+## Executive Summary
+
+- Audit type: code-and-structure review of current UI implementation before Sprint 7
+- Audit basis: current page composition, shared layout/components, responsive class behavior, table/form/dialog patterns
+- Overall UI score: 7.2/10
+- Overall UX score: 6.9/10
+- Overall Responsive score: 6.8/10
+
+The application already has a solid shared shell, reusable table layer, and consistent shadcn-based primitives. The main gaps are inconsistency between older page-specific patterns and newer shared components, mixed language/tone across screens, crowded dashboards, and form/table experiences that are functionally correct but still feel dense on mobile and mid-width screens.
+
+## Files Reviewed
+
+- `src/components/layout/page-container.tsx`
+- `src/components/layout/app-sidebar.tsx`
+- `src/components/layout/header.tsx`
+- `src/components/ui/table.tsx`
+- `src/components/ui/table/data-table.tsx`
+- `src/components/ui/table/data-table-toolbar.tsx`
+- `src/components/ui/table/data-table-pagination.tsx`
+- `src/components/ui/dialog.tsx`
+- `src/components/ui/drawer.tsx`
+- `src/components/ui/tanstack-form.tsx`
+- `src/features/overview/components/overview-filter-panel.tsx`
+- `src/app/dashboard/overview/layout.tsx`
+- `src/features/training-records/components/training-record-tables/index.tsx`
+- `src/features/training-records/components/training-record-tables/columns.tsx`
+- `src/features/training-records/components/training-record-form.tsx`
+- `src/features/training-records/components/training-record-view-page.tsx`
+- `src/features/training-records/components/pending-review-table.tsx`
+- `src/features/employee-directory/components/employee-directory-table.tsx`
+- `src/features/employee-directory/components/employee-directory-toolbar.tsx`
+- `src/features/employee-directory/components/employee-directory-detail-page.tsx`
+- `src/features/users/components/users-table/index.tsx`
+- `src/features/users/components/user-form-sheet.tsx`
+- `src/features/reports/components/reports-page-content.tsx`
+- `src/features/reports/components/report-table-card.tsx`
+
+## Components Reviewed
+
+- Sidebar
+- Header
+- Page container
+- DataTable
+- DataTable toolbar
+- DataTable pagination
+- Dialog
+- Drawer
+- Card patterns
+- Form patterns
+- Sheet form pattern
+- Report table cards
+
+## Screens Reviewed
+
+- Employee Dashboard
+- HRD Dashboard
+- Training Records
+- Create Training Record
+- Edit Training Record
+- Pending Review
+- Employee Directory
+- Employee Detail
+- Users
+- Reports
+
+## Page-by-Page Review
+
+### Dashboard
+
+#### Strengths
+
+- Shared `PageContainer` gives pages a predictable shell.
+- KPI cards are already separated from filter controls and chart sections.
+- Role-based dashboard branching is clear and prevents irrelevant content.
+
+#### Problems
+
+- Dashboard filter panels are built with native `select` controls and page-specific styling instead of a shared filter component.
+- KPI cards mix useful metrics with low-information badges; some badges render with little visual meaning.
+- The admin dashboard grid is content-heavy and risks weak hierarchy on tablet widths.
+- Chart and card density is high before enough whitespace separates sections.
+
+#### Suggested Improvements
+
+- Standardize dashboard filters into one reusable filter-bar component shared by Overview and Reports.
+- Reduce secondary badge noise on KPI cards and surface only one key supporting datum.
+- Increase sectional separation between cards, charts, and recent activity panels.
+- Introduce a consistent empty-state design for dashboard subpanels.
+
+#### Priority
+
+- Medium
+
+### Training Records
+
+#### Strengths
+
+- Reusable DataTable pattern is in place.
+- Status and training-type badges improve scannability.
+- Certificate preview has a dedicated component and modal flow.
+
+#### Problems
+
+- Table still depends on many medium-width columns, so discoverability on mobile remains limited even when overflow is contained.
+- Certificate column is useful but visually expensive relative to the information density of the row.
+- Search/filter controls are still form-like rather than “quick filter” optimized.
+- Empty-state quality is better than older pages, but the table view remains dense before interaction.
+
+#### Suggested Improvements
+
+- Collapse secondary row metadata into stacked cell layouts more aggressively on smaller breakpoints.
+- Consider moving certificate preview into row details or action menu on mobile.
+- Add a compact filter mode for narrow widths.
+- Normalize hours formatting and right-alignment across all numeric columns.
+
+#### Priority
+
+- High
+
+### Create Training Record
+
+#### Strengths
+
+- Form validation, required states, and permission messaging are present.
+- Scroll-to-first-error behavior improves usability.
+- Upload guidance and review status context are included.
+
+#### Problems
+
+- The form is long and visually uniform, making it hard to scan by section.
+- Inputs, selects, upload, and custom combobox patterns feel mixed rather than part of one clearly grouped form system.
+- The time-to-hours interaction is clever but not instantly obvious to first-time users.
+- Supporting text competes with labels because spacing and hierarchy are similar everywhere.
+
+#### Suggested Improvements
+
+- Break the form into named sections such as participant, course, schedule, evidence, and notes.
+- Add section separators or cards to reduce cognitive load.
+- Improve time input affordance with inline example formatting or helper chips.
+- Standardize textarea styling with shared form field components where possible.
+
+#### Priority
+
+- High
+
+### Edit Training Record
+
+#### Strengths
+
+- Existing status and reviewer note context reduce ambiguity.
+- Read-only guard for non-editable records is explicit.
+
+#### Problems
+
+- Edit mode and create mode share nearly the same visual treatment, so users get weak cues about record lifecycle.
+- Read-only state depends on warning copy more than structural UI changes.
+
+#### Suggested Improvements
+
+- Add stronger edit-state framing with status banner treatment and section locking visuals.
+- Visually disable non-editable zones instead of only relying on top-level alert copy.
+
+#### Priority
+
+- Medium
+
+### Pending Review
+
+#### Strengths
+
+- Purpose is clear and the empty state is task-appropriate.
+- Action column supports review workflow efficiently.
+
+#### Problems
+
+- The table is still the dominant interaction model on narrow screens despite workflow-oriented content.
+- Search plus multiple filters can become visually busy and difficult to parse quickly.
+
+#### Suggested Improvements
+
+- Consider a card-list fallback or row-detail preview pattern for mobile.
+- Group filters into primary and secondary tiers.
+- Surface status totals above the table for queue triage.
+
+#### Priority
+
+- High
+
+### Employee Directory
+
+#### Strengths
+
+- Search and faceted filters are relevant to the use case.
+- Detail page contains a strong breadth of information and summary metrics.
+
+#### Problems
+
+- List view is highly column-dense for the typical HR scan workflow.
+- Detail page combines summary, profile, K/S/A, and history into a long vertical stack with limited sectional differentiation.
+- The detail history table still uses a page-local table pattern instead of the shared table primitive style.
+
+#### Suggested Improvements
+
+- Reprioritize columns for the list page around primary identity and status first.
+- Convert the detail screen into clearer sections with stronger rhythm between summary and history.
+- Migrate the detail history table to the shared table system for consistency.
+
+#### Priority
+
+- High
+
+### Users
+
+#### Strengths
+
+- User creation/editing via sheet is efficient for admin workflows.
+- Table and form share reusable infrastructure.
+
+#### Problems
+
+- Users screen remains visually English-first while much of the application is Thai-first.
+- Sheet form is dense and can become cramped for long option labels.
+- Table columns are more operational than people-centric, which reduces scan speed.
+
+#### Suggested Improvements
+
+- Normalize content language strategy for admin screens.
+- Increase grouping inside the sheet form: identity, organization, role, access.
+- Shorten or visually tier organizer/account metadata in the list.
+
+#### Priority
+
+- Medium
+
+### Reports
+
+#### Strengths
+
+- Clear export intent and multiple report blocks are easy to understand.
+- Summary cards and data tables create a useful reporting structure.
+
+#### Problems
+
+- Reports page is one of the densest screens in the app.
+- Multiple large tables in sequence create fatigue and weak “at a glance” hierarchy.
+- Filter UI duplicates the dashboard filter style rather than sharing a standard analytics filter bar.
+- Table cards vary from core DataTable behavior and still feel visually separate from the rest of the system.
+
+#### Suggested Improvements
+
+- Add a report section navigator or tabs to reduce long-page fatigue.
+- Convert filter/header treatment into a shared analytics toolbar.
+- Tighten summary-card copy and increase visual hierarchy before tables.
+- Align report tables more closely with DataTable spacing, badges, and empty states.
+
+#### Priority
+
+- High
+
+## Global Design Issues
+
+- Native `select` usage and custom filter bars coexist with shadcn form patterns, creating inconsistent control styling.
+- Data tables are shared in many places, but several detail/report views still use page-local table markup.
+- Mixed Thai and English labels reduce product voice consistency.
+- Button hierarchy is inconsistent across admin screens: some pages lead with outline actions, others with filled primary actions without a clear pattern.
+- Dashboard KPI cards use inconsistent supporting content density.
+
+## Responsive Issues
+
+- Dashboard chart areas likely become visually crowded on tablet layouts before they become technically broken.
+- Long forms such as Training Record still feel mobile-heavy even without viewport overflow.
+- Pending Review and Training Records remain table-first on mobile and would benefit from alternate compact layouts.
+- Employee Detail history table still relies on a local scroll-area table pattern and may diverge from shared overflow fixes.
+- Header space is limited for future growth; breadcrumbs, trigger, theme toggle, and notifications already consume most of the row.
+
+## Accessibility Issues
+
+- Some flows still rely heavily on visual layout rather than explicit grouping or headings.
+- Mixed native and custom controls may create uneven keyboard and focus behavior across filters/forms.
+- Dense dashboard and report layouts risk poor focus traversal experience.
+- Language inconsistency may also affect assistive clarity if labels change idiom by screen.
+- More icon-only affordances should be audited for consistent accessible names, especially action menus and future toolbar actions.
+
+## Recommended Refactoring
+
+- Build a shared analytics filter panel used by Overview and Reports.
+- Build a shared sectioned form layout wrapper for long forms.
+- Standardize detail-page summary cards into a reusable metric-strip component.
+- Migrate page-local tables to the shared `Table` or `DataTable` conventions.
+- Standardize badge semantics for status, type, and progress across features.
+- Create a language/content guideline for Thai-first vs English admin terminology.
+
+## Suggested Improvements
+
+- Introduce a shared dashboard filter component with the same spacing, field height, and button grouping everywhere.
+- Add responsive “compact row” patterns for operational tables.
+- Use clearer section headers and dividers on long forms and detail pages.
+- Simplify KPI cards by limiting each to one primary metric and one supporting hint.
+- Standardize empty-state design across DataTable, reports, and detail history sections.
+- Normalize numeric formatting and alignment in all summary/table/report surfaces.
+
+## Refactoring Opportunities
+
+- Shared filter-bar abstraction for Overview and Reports
+- Shared admin metric card for Dashboard, Reports, Employee Detail
+- Shared detail-history table wrapper
+- Shared long-form section component
+- Shared status badge map component for approval, active/inactive, target status
+
+## UI Consistency Checklist
+
+- Typography: Partial pass
+- Buttons: Partial pass
+- Cards: Partial pass
+- Tables: Partial pass
+- Dialogs: Pass
+- Forms: Partial pass
+- Filters: Needs improvement
+- Pagination: Partial pass
+- Search: Partial pass
+
+## Final Score
+
+- UI: 7.2/10
+- UX: 6.9/10
+- Responsive: 6.8/10
+- Accessibility: 7.0/10
+- Performance: 7.6/10
+- Maintainability: 7.4/10
+- Overall Readiness: 7.1/10
+
+## Notes
+
+- This audit is based on the current code structure and component implementation patterns reviewed in Sprint 6.12.
+- Scores reflect product readiness for UI refinement work before Sprint 7, not business-logic completeness.