CShare/docs/superpowers/specs/2026-05-30-dashboard-polish-design.md

CShare Dashboard Enhancement & App Polish

Date: 2026-05-30 Status: Approved Approach: Parallel — backend analytics API built simultaneously with frontend enhancements

---

Context

CShare has a working frontend (12+ pages, React Router v7, dark theme design system) and a live backend (Express 5 + TypeScript, local JSON storage). The biggest gaps are in the dashboard experience and overall app polish. This spec covers both tracks.

Strategy: Start simple, grow. Focus on the dashboard (where returning users live) and app-wide polish (makes everything feel trustworthy). The backend analytics API is built in parallel, and the frontend starts with mock data then wires to real endpoints.

---

Track 1: Backend — Analytics & Dashboard API

New/Expanded Endpoints

Method	Endpoint	Purpose
GET	/api/v1/dashboard/stats	Aggregate: total files, storage used, total views, total downloads, active links, expiring soon count
GET	/api/v1/dashboard/activity	Recent activity feed: last 20 events (views, downloads, uploads) with timestamps
GET	/api/v1/files/:id/analytics	Per-file: view count, download count, daily breakdown (last 30 days), top referrers
POST	/api/v1/events	Record a view/download event (called when links are resolved)
GET	/api/v1/dashboard/storage	Storage breakdown by file type, monthly upload volume

Event Recording

• GET /api/v1/links/:linkId automatically records a view event
• GET /api/v1/links/:linkId/download records a download event
• Events include: timestamp, hashed IP, user agent
• Stored in the existing events table

Stats Computation

• Dashboard stats computed on-the-fly from DB (no caching initially)
• If performance becomes an issue, add Redis caching with 5-minute TTL
• Per-file analytics queries use a 30-day window by default

Files to Create/Modify

• backend/src/routes/analytics.ts — new file for analytics endpoints
• backend/src/routes/dashboard.ts — expand existing file
• backend/src/services/analytics.ts — new service for event recording and aggregation
• backend/src/routes/links.ts — modify to record events on link resolution

---

Track 2: Frontend — Dashboard Enhancement

Principle: Enhance the existing DashboardPage.jsx, do not rewrite.

Stat Cards Enhancement

• Animated count-up on first render (number rolls from 0 to actual value)
• Subtle gradient backgrounds per metric theme
• Trend indicators comparing to previous period (up/down arrow + percentage)

File Table Enhancement

• Inline file type icons with color coding (using existing getFileIcon and getFileIconColor)
• Quick-action buttons on hover: copy link, download, delete
• Click-to-expand row revealing file details: analytics preview, share link, expiry countdown
• Better sort controls: date, name, size, type with visual indicators

New Components (added within existing dashboard structure)

• Search + filters bar — above the table, type filter chips, date range, size range
• Storage usage bar — near stats cards, shows used vs. available
• Recent activity feed — compact section below stats, last 5-10 events with timestamps and badges
• File detail slide-over — triggered by clicking a file row, contains:
  • File info (name, size, type, upload date, expiry)
  • Share link with copy button
  • QR code for the share link
  • Analytics mini-chart (views/downloads over last 30 days)
  • Delete action with confirmation
• Batch operations — checkbox column, bulk delete, bulk copy links

Polish Details

• Smooth animations on card hover, row expand, filter changes
• Skeleton loading states while data loads
• Better empty state for new users with upload CTA

Files to Create/Modify

• cshare-app/src/pages/DashboardPage.jsx — enhance existing
• cshare-app/src/components/StatsCards.jsx — new, extracted stat cards section
• cshare-app/src/components/FileDetailSlideOver.jsx — new slide-over panel
• cshare-app/src/components/ActivityFeed.jsx — new activity feed component
• cshare-app/src/components/StorageBar.jsx — new storage usage indicator
• cshare-app/src/components/SkeletonLoader.jsx — new reusable skeleton

---

Track 3: Frontend — App-Wide Polish & Micro-Interactions

Animations & Transitions

• Page transitions: subtle fade + slide between route changes
• Staggered entrance animations on card grids and file lists (elements appear sequentially)
• Button press feedback: scale-down on mousedown, spring-back on release
• Card hover: gentle lift with shadow deepening

Loading States

• Skeleton screens for file lists, stat cards, and page content (no spinners)
• Upload progress: smoother easing curves on the progress bar
• File preview loading: blur-up placeholder technique

Mobile Refinements

• Swipe gestures on file cards (swipe left to reveal delete)
• Better touch targets: minimum 44px hit areas
• Bottom sheet for file details on mobile (instead of slide-over)
• Pull-to-refresh on dashboard

Micro-Interactions

• Copy-to-clipboard: checkmark animation + toast
• Delete confirmation: slide-in modal with undo option
• Share link generation: animated link appearance with "Copied!" feedback
• File type icons: subtle bounce on appearance

Other

• 404 page with CShare branding and "Upload a file" CTA
• Better scroll-to-top on navigation
• Enhance existing useScrollReveal for below-fold content

Files to Create/Modify

• cshare-app/src/pages/NotFoundPage.jsx — new 404 page
• cshare-app/src/components/PageTransition.jsx — new route transition wrapper
• cshare-app/src/hooks/useCountUp.js — new animated number hook
• cshare-app/src/hooks/useSwipe.js — new swipe gesture hook
• cshare-app/src/components/SkeletonLoader.jsx — reusable skeleton
• cshare-app/src/index.css — new animation keyframes and utility classes
• Various page files — apply transitions and polish

---

Implementation Order

1. Skeleton + loading states — immediately improves perceived performance
2. Dashboard stat cards enhancement — animated count-up, trend indicators
3. File table enhancements — hover actions, expand rows, sort controls
4. Backend analytics API — event recording, stats endpoints (parallel with #2-3)
5. File detail slide-over — info, share link, QR code, analytics chart
6. Activity feed + storage bar — new dashboard sections
7. Page transitions — route-level fade + slide
8. Micro-interactions — copy feedback, delete undo, icon bounce
9. Mobile refinements — swipe, bottom sheet, touch targets
10. 404 page — standalone task
11. Wire frontend to real API — swap mock data for analytics endpoints

---

Out of Scope

• Authentication pages (login/register/account) — separate effort
• Stripe payments integration
• PostgreSQL migration
• Cloudflare R2 storage migration
• Email verification flows