Ui Design

• Skeleton loaders (not spinners) for content that has a known layout.
• Match skeleton dimensions to the content they replace.
• Shimmer animation: left-to-right gradient, 1.5s, infinite loop.
• Use loading.tsx route files for page-level loading.

Error States

• Friendly error messages, not stack traces.
• Suggest an action: "Try uploading a smaller file" not just "Upload failed."
• Use the --destructive color token for error states.
• Always provide a way to retry or dismiss.

Animations (Framer Motion)

• Page transitions: fade + slight y-translate (8px), 250ms.
• Score reveals: radial gauge fills on mount, 400ms with ease-out.
• Chat messages: fade-in + slide from bottom, staggered by 50ms.
• Typing indicator: 3 dots with staggered opacity pulse, 150ms delay between dots.
• Upload progress: smooth width transition on progress bar.

Reduced Motion

Always wrap animations:

const prefersReducedMotion = useReducedMotion();
// Skip animation if user prefers reduced motion

Responsive Design

• Mobile-first: start with mobile layout, add complexity at breakpoints.
• Sidebar collapses to hamburger menu below md (768px).
• Chat input fixed to bottom on mobile.
• Score cards stack vertically on mobile, grid on desktop.
• Touch targets: minimum 44x44px on mobile.

Accessibility Checklist

• All buttons and links have descriptive text (not just icons)
• Images have alt text
• Icons use aria-label or paired sr-only span
• Color contrast meets WCAG AA (4.5:1 for text)
• Focus ring visible on all interactive elements (2px primary, 2px offset)
• Semantic HTML: <nav>, <main>, <section>, <button>
• Form inputs have associated <label> elements
• Keyboard navigation works for all interactive flows