diff --git a/docs/superpowers/specs/2026-05-30-dashboard-polish-design.md b/docs/superpowers/specs/2026-05-30-dashboard-polish-design.md
new file mode 100644
index 0000000..a2f5e49
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-30-dashboard-polish-design.md
@@ -0,0 +1,167 @@
+# 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