feat(frontend): UI Redesign Migration to shadcn/ui

[jonasyr]

🎯 Issue Type

• ✨ Feature - New functionality
• 🔧 Enhancement - Improvement of existing functionality

📋 Description

Problem/Need

Current GitRay frontend uses basic styling and a single-page architecture. We need to modernize the UI with a professional component library, implement a landing page → dashboard flow, and add dark/light theme support for better UX.

Expected Behavior

• Modern, professional UI using shadcn/ui component library
• Landing page with repository input and info modals
• Dashboard with tabs for heatmap and commit list
• Settings drawer with theme selector (light/dark/system)
• News drawer for updates
• Responsive design across all devices
• All existing functionality preserved (API, visualizations, Rive animations)

Current Behavior

• Single-page application with basic styling
• No landing page or onboarding flow
• No theme switching capability
• Limited component reusability

🔄 Steps to Reproduce

This is a feature implementation. To test completion:

1. Clone branch feature/ui-redesign
2. Run npm install and npm run dev
3. Navigate to landing page - verify hero section, input, info buttons
4. Enter repository URL and click "Analyze"
5. Verify redirect to dashboard with data visualizations
6. Test theme switching in settings drawer
7. Verify all drawers and modals open/close correctly
8. Test on mobile devices and different browsers

🎨 Mockups/Screenshots

Mockup files available in design repository. Key components:

• Landing page with centered hero
• Dashboard with Header (logo, menu, news bell)
• Settings drawer (theme selector, future language selector)
• News drawer (updates with badges)
• Info modals (3 types: what, private, local)

🧪 Acceptance Criteria

• Landing page implemented with hero, input, and info buttons
• Dashboard page with tabs (Heatmap/Commits)
• Header component with conditional navigation
• Footer component with links
• Settings drawer with theme switching (light/dark/system)
• News drawer with release notes
• Info modals (3 types) functional
• All existing features work: repository analysis, heatmap, commit list
• Rive animations preserved (RiveLoader, RiveLogo)
• Theme persists across sessions
• Responsive design on mobile/tablet/desktop
• No console errors
• TypeScript compiles without errors
• Test coverage maintained (>80%)
• Code reviewed and approved
• Documentation updated

🛠 Technical Details

Affected Files/Components

New Structure:

src/
├── components/
│   ├── ui/              # shadcn/ui components (button, card, sheet, dialog, tabs, etc.)
│   ├── layout/          # Header, Footer
│   ├── drawers/         # SettingsDrawer, NewsDrawer
│   ├── modals/          # InfoModal
│   ├── visualization/   # ActivityHeatmap, CommitList, RiveLoader (migrated)
│   └── forms/
├── pages/
│   ├── LandingPage.tsx  # NEW
│   └── DashboardPage.tsx # NEW
├── lib/
│   └── utils.ts         # cn() function for className merging
└── App.tsx              # Updated with router logic

Updated Files:

• App.tsx - Page routing, state management
• tailwind.config.cjs - Theme configuration
• index.css - CSS variables for theming
• vite.config.ts - Path aliases
• ActivityHeatmap.tsx - Styling updates
• CommitList.tsx - shadcn/ui Table integration

Preserved (no changes):

• api.ts - API integration
• RiveLoader.tsx, RiveLogo.tsx - Rive animations
• dateUtils.ts - Utility functions

Dependencies

New packages to install:

npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu \
  @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-separator \
  @radix-ui/react-label @radix-ui/react-slot \
  class-variance-authority clsx sonner tailwind-merge next-themes \
  tailwindcss-animate --save-dev

Depends on:

• Nothing - can start immediately

Blocks:

• #[i18n-issue-number] - i18n implementation (must be completed first)

Breaking Changes

• No, backward compatible change
• Architecture changes are internal, API integration unchanged

🏷 Categorization

Scope

• scope:frontend - Frontend/UI changes

Priority

• prio:high - Important feature/bug

Effort

• effort:xl - > 3 days (5-7 working days estimated)

🌍 Environment

Development:

• OS: Cross-platform (Windows, macOS, Linux)
• Browser: Chrome 120+, Firefox 121+, Safari 17+
• Node Version: 18+ required
• Repo Branch: feature/ui-redesign (create from main)

🔗 Related Issues/PRs

• Blocks #[i18n-issue-number] - i18n must wait for UI migration to complete
• Related to: Design mockups (link if available)

📝 Additional Notes

Implementation Timeline (5-7 days)

Day 1-2: Setup, dependencies, base components, Tailwind config
Day 3: Page components (Landing, Dashboard)
Day 4: Migrate visualization components with new styling
Day 5: Integration, wire everything in App.tsx
Day 6: Testing, polish, bug fixes
Day 7: Code review, documentation, deployment prep

Documentation

Complete migration plan available:

• docs/migration-plan/MIGRATION_PLAN.md - Full strategy (50 pages)
• docs/migration-plan/COMPONENT_GUIDE.md - Implementation reference with code
• docs/migration-plan/DAILY_CHECKLIST.md - Day-by-day tasks
• docs/migration-plan/QUICK_REFERENCE.md - Developer cheat sheet

Rollback Plan

• Quick rollback: Revert merge commit (< 5 min)
• Feature flag option: Toggle between old/new UI if needed
• Full restoration: Restore from main branch backup (< 30 min)

Success Metrics

• Bundle size < 550KB (currently ~500KB, allow +50KB for new components)
• Lighthouse score > 90
• First Contentful Paint < 1.5s
• No increase in console errors
• Test coverage maintained at 80%+

Key Risks & Mitigations

Risk: API integration breaks during refactor

• Mitigation: Keep API service unchanged, test thoroughly before merge

Risk: Theme switching causes layout issues

• Mitigation: Use CSS variables properly, test both themes extensively

Risk: Mobile responsiveness issues

• Mitigation: Test on real devices throughout development

✅ Checklist for Reviewer

• Issue is clearly and understandably formulated
• Acceptance criteria are measurable
• Labels and priority are set
• Technical feasibility is given
• Migration plan documentation linked and accessible
• Dependencies listed and installable
• Timeline is realistic (5-7 days confirmed)
• Rollback strategy documented

[jonasyr]

Issue #87: Frontend UI Redesign - Resolution Summary

Environment

• Node: v22.20.0
• pnpm: 10.16.1
• Branch: 87-featfrontend-ui-redesign-migration-to-shadcnui
• OS: Linux (Arch)

---

Critical Issues Found

1. Invalid Import Syntax with Version Numbers

Problem:

• 31+ UI component files contained invalid import statements with version numbers embedded in package names
• This is not valid JavaScript/TypeScript syntax and caused complete build failure
• TypeScript compiler couldn't resolve modules with @version suffixes

Examples of Invalid Imports:

// ❌ INCORRECT - found in codebase
import * as TooltipPrimitive from '@radix-ui/react-tooltip@1.1.8';
import { Slot } from '@radix-ui/react-slot@1.1.2';
import { cva } from 'class-variance-authority@0.7.1';
import { ChevronDownIcon } from 'lucide-react@0.487.0';
import { useTheme } from 'next-themes@0.4.6';
import { Toaster } from 'sonner@2.0.3';

// ✅ CORRECT - how they should be
import * as TooltipPrimitive from '@radix-ui/react-tooltip';
import { Slot } from '@radix-ui/react-slot';
import { cva } from 'class-variance-authority';
import { ChevronDownIcon } from 'lucide-react';
import { useTheme } from 'next-themes';
import { Toaster } from 'sonner';

Affected Files:
All 31 files in apps/frontend/src/components/ui/:

• accordion.tsx, alert-dialog.tsx, alert.tsx, aspect-ratio.tsx, avatar.tsx
• badge.tsx, breadcrumb.tsx, button.tsx, calendar.tsx, carousel.tsx
• chart.tsx, checkbox.tsx, collapsible.tsx, command.tsx, context-menu.tsx
• dialog.tsx, drawer.tsx, dropdown-menu.tsx, form.tsx, hover-card.tsx
• input-otp.tsx, label.tsx, menubar.tsx, navigation-menu.tsx, pagination.tsx
• popover.tsx, progress.tsx, radio-group.tsx, resizable.tsx, scroll-area.tsx
• select.tsx, separator.tsx, sheet.tsx, sidebar.tsx, slider.tsx
• sonner.tsx, switch.tsx, tabs.tsx, toggle-group.tsx, toggle.tsx, tooltip.tsx

Affected Packages:

• @radix-ui/* packages (24+ different ones)
• class-variance-authority
• lucide-react
• next-themes
• sonner
• cmdk
• vaul
• react-hook-form
• input-otp
• react-resizable-panels
• react-day-picker
• embla-carousel-react
• recharts

Why This Fails:

• Version specifiers (@1.1.8) in import paths are not part of the ES modules or TypeScript module resolution spec
• Package versions are defined in package.json, not in import statements
• This syntax would only work with specialized bundlers that don't exist in standard tooling

The Fix:

# Remove all version numbers from imports
find apps/frontend/src -type f \( -name "*.tsx" -o -name "*.ts" \) -exec sed -i "s/\(['\"][^'\"]*\)@[0-9]\+\.[0-9]\+\.[0-9]\+\(['\"][^'\"]*\)/\1\2/g" {} +

This command:

1. Finds all .tsx and .ts files in apps/frontend/src
2. Uses sed to find patterns like 'package@1.2.3' or "package@1.2.3"
3. Removes the @1.2.3 version suffix
4. Preserves the rest of the import statement

Result: All import statements now use correct syntax without version numbers

---

3. React Ref Forwarding Warnings

Problem:

• Components using Radix UI's Slot component showed React warnings in browser console
• Warning appeared for Button, Badge, and BreadcrumbLink components

Error Message:

Warning: Function components cannot be given refs. Attempts to access this ref will fail.
Did you mean to use React.forwardRef()?

Check the render method of `Primitive.button.SlotClone`.

Why This Happened:

• When using Radix's asChild pattern with Slot, refs must be explicitly forwarded
• Original components were regular functions, not wrapped with React.forwardRef()
• React 18+ is stricter about ref forwarding

Affected Components:

1. apps/frontend/src/components/ui/button.tsx - Button component
2. apps/frontend/src/components/ui/badge.tsx - Badge component
3. apps/frontend/src/components/ui/breadcrumb.tsx - BreadcrumbLink component

The Fix:
Converted each component from regular function to React.forwardRef() pattern:

Before:

function Button({
  className,
  variant,
  size,
  asChild = false,
  ...props
}: React.ComponentProps<'button'> & VariantProps<typeof buttonVariants> & { asChild?: boolean }) {
  const Comp = asChild ? Slot : 'button';
  return <Comp className={cn(buttonVariants({ variant, size, className }))} {...props} />;
}

After:

const Button = React.forwardRef<
  HTMLButtonElement,
  React.ComponentProps<'button'> & VariantProps<typeof buttonVariants> & { asChild?: boolean }
>(({ className, variant, size, asChild = false, ...props }, ref) => {
  const Comp = asChild ? Slot : 'button';
  return (
    <Comp
      ref={ref}
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  );
});

Button.displayName = 'Button';

Changes Made:

1. Wrapped component with React.forwardRef<HTMLElement, Props>()
2. Added ref parameter to component function
3. Passed ref to the Comp element
4. Added displayName for better debugging in React DevTools

Result: Console warnings eliminated, components properly forward refs

---

Why It Worked On Friend's Machine (@NiklasSkulll)

The friend's development environment was likely in one of these states:

1. Had Pre-Built Artifacts

• dist/ folders from before the bad imports were introduced
• Build cache preventing full TypeScript recompilation
• pnpm dev doesn't always run full type-check

2. Different Tooling or Configuration

• Possible custom bundler/transpiler that strips version numbers
• IDE plugin that auto-corrects imports
• Different Node.js or pnpm version with non-standard behavior
• Custom pnpm patches in .pnpmfile.cjs (not committed)

3. Dev Mode vs Production Build

• pnpm dev is more lenient than pnpm build
• Vite dev server may have cached transforms
• Didn't run full pnpm build to see TypeScript errors

Verification Steps for Friend:

# Clean everything and rebuild from scratch
rm -rf node_modules dist apps/*/dist apps/backend/.env
pnpm install
pnpm build  # This would fail with version number imports

---

Remaining Issues

TypeScript Build Errors (8 total)

The pnpm build command still fails with 8 TypeScript errors that are code quality issues introduced by the frontend redesign work:

1. Unused Import Warnings (TS6133) - 5 errors

File: src/components/ContributionRanking.tsx

// Lines 12-13: Imported but never used
import {
  Medal,      // ❌ TS6133
  TrendingUp, // ❌ TS6133
} from 'lucide-react';

File: src/components/GraphViewTimeline.tsx

// Line 20: Imported but never used
import { useState, useEffect } from 'react';
                   ~~~~~~~~~  // ❌ TS6133

File: src/components/InfoModal.tsx

// Line 1: Imported but never used
import { X } from 'lucide-react';  // ❌ TS6133

File: src/components/LandingPage.tsx

// Line 2: Imported but never used
import { ChevronDown, ArrowRight } from 'lucide-react';
         ~~~~~~~~~~~  // ❌ TS6133

File: src/components/SettingsDrawer.tsx

// Line 1: Imported but never used
import { X } from 'lucide-react';  // ❌ TS6133

2. Type Errors (TS2339) - 2 errors

File: src/components/GraphViewTimeline.tsx

// Lines 111, 113: Properties don't exist on Commit type
{
  author: commit.author,  // ❌ TS2339: Property 'author' does not exist on type 'Commit'
  // ...
  hash: commit.hash.substring(0, 7),  // ❌ TS2339: Property 'hash' does not exist on type 'Commit'
}

Root Cause:
The Commit type from @gitray/shared-types uses different property names:

• Should use commit.authorName instead of commit.author
• Should use commit.sha instead of commit.hash

Commit Type Definition:

// From packages/shared-types/src/index.ts
export interface Commit {
  sha: string;           // ✅ Use this, not 'hash'
  message: string;
  date: string;
  authorName: string;    // ✅ Use this, not 'author'
  authorEmail: string;
}

How to Fix Remaining Issues

Fix 1: Remove Unused Imports

# Automated fix for unused imports
# Option A: Use ESLint auto-fix
pnpm eslint --fix apps/frontend/src/components/

# Option B: Manual removal - remove these lines:
# - ContributionRanking.tsx: Remove Medal, TrendingUp from import
# - GraphViewTimeline.tsx: Remove useEffect from import (if truly unused)
# - InfoModal.tsx: Remove entire 'X' import line
# - LandingPage.tsx: Remove ChevronDown from import
# - SettingsDrawer.tsx: Remove entire 'X' import line

Fix 2: Correct Type Properties in GraphViewTimeline.tsx

// apps/frontend/src/components/GraphViewTimeline.tsx:111-113
// BEFORE (incorrect):
{
  author: commit.author,
  message: commit.message,
  hash: commit.hash.substring(0, 7),
}

// AFTER (correct):
{
  author: commit.authorName,  // Changed from commit.author
  message: commit.message,
  hash: commit.sha.substring(0, 7),  // Changed from commit.hash
}

Impact of Remaining Issues

Build: ❌ Fails with pnpm build
Dev Mode: ✅ Works fine with pnpm dev (dev mode is more lenient)
Runtime: ✅ Application functions correctly (unused imports don't affect runtime)
Type Safety: ⚠️ Reduced - type errors in GraphViewTimeline may cause runtime issues

---

Verification Commands

Full Clean Build Test

# Test complete rebuild from scratch
rm -rf node_modules dist apps/*/dist
pnpm install
pnpm build  # Will fail with 8 TS errors until code is fixed

Test Dev Mode (Currently Works)

# Terminal 1 - Backend
cd apps/backend && pnpm dev

# Terminal 2 - Frontend
pnpm dev:frontend

# Open http://localhost:5173 and test repository analysis

Check Import Syntax

# Verify no version numbers remain in imports
grep -r "@[0-9]\+\.[0-9]\+\.[0-9]" apps/frontend/src/components/ui/
# Should return no results if fixed correctly

---

Summary

Issue	Status	Impact	Fix Complexity
Invalid import syntax (31+ files)	⚠️ Not Fixed	Critical - prevented build	Easy - automated sed
React ref forwarding warnings	⚠️ Not Fixed	Minor - console warnings	Medium - code refactor
Unused imports (5 errors)	⚠️ Not Fixed	Low - build fails, runtime OK	Easy - remove lines
Type errors (2 errors)	⚠️ Not Fixed	Medium - may cause runtime bugs	Easy - fix property names

Result: Application is fully functional in dev mode. Production build requires fixing 7 remaining TypeScript errors (5 unused imports + 2 type mismatches).

[jonasyr]

Test-Konfiguration für Frontend hinzugefügt

Problem

Nach der Migration von apps/frontendOld/ zu apps/frontend/ schlugen alle Test-Befehle fehl mit:
Error: Projects definition references a non-existing file or a directory:
/home/jonas/Documents/Code/gitray/apps/frontend/vitest.config.ts

Die Root-Vitest-Konfiguration (vitest.config.ts:6) referenzierte ./apps/frontend/vitest.config.ts, aber diese Datei existierte nicht im neuen
Frontend-Verzeichnis.

Ursache

Während der UI-Redesign-Migration wurden die Vitest-Konfigurationsdateien nicht von frontendOld ins neue frontend-Verzeichnis übertragen.

Lösung

Die folgenden Dateien wurden von apps/frontendOld/ nach apps/frontend/ kopiert:

• ✅ vitest.config.ts - Vitest-Projektkonfiguration (jsdom, React-Plugin, Coverage-Settings)
• ✅ src/test-setup.ts - Test-Setup mit React 19-Kompatibilität und DOM-Mocks

Verifizierung

pnpm test:backend  # ✅ 893 Tests bestanden
pnpm test          # ✅ Alle Projekte (Frontend + Backend) funktionieren

Die Test-Infrastruktur ist jetzt vollständig und beide Projekte können getestet werden.