-
-
-
-
-
-
+
+ {popularTags.map((tag) => (
+
+ ))}
diff --git a/components/right-sidebar/tag-link.tsx b/components/right-sidebar/tag-link.tsx
new file mode 100644
index 0000000..22da077
--- /dev/null
+++ b/components/right-sidebar/tag-link.tsx
@@ -0,0 +1,23 @@
+import Link from "next/link";
+import { Badge } from "@/components/ui/badge";
+
+type TagLinkProps = {
+ name: string;
+ questionCount?: number;
+};
+
+export function TagLink({ name, questionCount }: TagLinkProps) {
+ return (
+
+
+ {name}
+
+ {questionCount !== undefined && (
+
{questionCount}
+ )}
+
+ );
+}
diff --git a/components/ui/badge.tsx b/components/ui/badge.tsx
new file mode 100644
index 0000000..ccfa4e7
--- /dev/null
+++ b/components/ui/badge.tsx
@@ -0,0 +1,46 @@
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+import type * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+const badgeVariants = cva(
+ "inline-flex items-center justify-center rounded-full border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden",
+ {
+ variants: {
+ variant: {
+ default:
+ "border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90",
+ secondary:
+ "border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",
+ destructive:
+ "border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+ outline:
+ "text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
+ },
+ },
+ defaultVariants: {
+ variant: "default",
+ },
+ },
+);
+
+function Badge({
+ className,
+ variant,
+ asChild = false,
+ ...props
+}: React.ComponentProps<"span"> &
+ VariantProps
& { asChild?: boolean }) {
+ const Comp = asChild ? Slot : "span";
+
+ return (
+
+ );
+}
+
+export { Badge, badgeVariants };
diff --git a/e2e/right-sidebar.desktop.spec.ts b/e2e/right-sidebar.desktop.spec.ts
new file mode 100644
index 0000000..fd126e7
--- /dev/null
+++ b/e2e/right-sidebar.desktop.spec.ts
@@ -0,0 +1,70 @@
+import { expect, test } from "@playwright/test";
+
+test.describe("Right Sidebar - Desktop", () => {
+ test("displays questions and tags with working navigation and responsive scroll", async ({
+ page,
+ }) => {
+ // Start at short viewport (1280x650) - triggers scrollbar
+ await page.setViewportSize({ width: 1280, height: 650 });
+ await page.goto("/");
+
+ // Sidebar should be visible at xl breakpoint
+ const sidebar = page.getByRole("complementary", {
+ name: "Top questions and popular tags",
+ });
+ await expect(sidebar).toBeVisible();
+
+ // Count exactly 5 question links and 5 tag links
+ const questionLinks = sidebar.locator('a[href^="/question/"]');
+ const tagLinks = sidebar.locator('a[href^="/tags/"]');
+ await expect(questionLinks).toHaveCount(5);
+ await expect(tagLinks).toHaveCount(5);
+
+ // Verify scrollbar IS present at short viewport
+ const hasScrollAtShortHeight = await page.evaluate(() => {
+ const container = document.querySelector(
+ '#right-sidebar [data-sidebar="content"]',
+ );
+ return container
+ ? container.scrollHeight > container.clientHeight
+ : false;
+ });
+ expect(
+ hasScrollAtShortHeight,
+ "Sidebar should have vertical scroll at 650px height",
+ ).toBe(true);
+
+ // Click first question link and verify URL pattern
+ await questionLinks.first().click();
+ await expect(page).toHaveURL(/\/question\/\d+/);
+
+ // Navigate back to homepage
+ await page.goto("/");
+
+ // Click first tag link and verify URL pattern
+ await tagLinks.first().click();
+ await expect(page).toHaveURL(/\/tags\/[a-z-]+/);
+
+ // Navigate back to homepage
+ await page.goto("/");
+
+ // Resize to tall viewport (1280x1000) - no scrollbar needed
+ await page.setViewportSize({ width: 1280, height: 1000 });
+ const hasScrollAtTallHeight = await page.evaluate(() => {
+ const container = document.querySelector(
+ '#right-sidebar [data-sidebar="content"]',
+ );
+ return container
+ ? container.scrollHeight > container.clientHeight
+ : false;
+ });
+ expect(
+ hasScrollAtTallHeight,
+ "Sidebar should not have vertical scroll at 1000px height",
+ ).toBe(false);
+
+ // Resize to below xl breakpoint (1279px) - sidebar should be hidden
+ await page.setViewportSize({ width: 1279, height: 650 });
+ await expect(sidebar).not.toBeVisible();
+ });
+});
diff --git a/lib/data/questions.test.ts b/lib/data/questions.test.ts
new file mode 100644
index 0000000..a5c61ea
--- /dev/null
+++ b/lib/data/questions.test.ts
@@ -0,0 +1,19 @@
+import { getTopQuestions } from "@/lib/data/questions";
+
+describe("getTopQuestions", () => {
+ it("returns 5 questions by default", async () => {
+ const questions = await getTopQuestions();
+ expect(questions).toHaveLength(5);
+ });
+
+ it("respects custom limit parameter", async () => {
+ const questions = await getTopQuestions(3);
+ expect(questions).toHaveLength(3);
+ });
+
+ it("returns questions with required properties", async () => {
+ const questions = await getTopQuestions(1);
+ expect(questions[0]).toHaveProperty("_id");
+ expect(questions[0]).toHaveProperty("title");
+ });
+});
diff --git a/lib/data/questions.ts b/lib/data/questions.ts
new file mode 100644
index 0000000..fdc5c6e
--- /dev/null
+++ b/lib/data/questions.ts
@@ -0,0 +1,33 @@
+export type Question = {
+ _id: string;
+ title: string;
+};
+
+const MOCK_QUESTIONS: Question[] = [
+ {
+ _id: "1",
+ title:
+ "How to Ensure Unique User Profile with ON CONFLICT in PostgreSQL Using Drizzle ORM?",
+ },
+ {
+ _id: "2",
+ title:
+ "What are the benefits and trade-offs of using Server-Side Rendering (SSR) in Next.js?",
+ },
+ { _id: "3", title: "How to centre a div?" },
+ {
+ _id: "4",
+ title:
+ "Node.js res.json() and res.send(), not working but still able to change status code",
+ },
+ { _id: "5", title: "ReactJs or NextJs for beginners i ask for advice" },
+];
+
+/**
+ * Fetch top questions sorted by votes/engagement.
+ * TODO: Replace with MongoDB query when database is set up.
+ */
+export async function getTopQuestions(limit = 5): Promise {
+ // Future: return await db.collection('questions').find().sort({ votes: -1 }).limit(limit)
+ return MOCK_QUESTIONS.slice(0, limit);
+}
diff --git a/lib/data/tags.test.ts b/lib/data/tags.test.ts
new file mode 100644
index 0000000..d3f65e5
--- /dev/null
+++ b/lib/data/tags.test.ts
@@ -0,0 +1,19 @@
+import { getPopularTags } from "@/lib/data/tags";
+
+describe("getPopularTags", () => {
+ it("returns 5 tags by default", async () => {
+ const tags = await getPopularTags();
+ expect(tags).toHaveLength(5);
+ });
+
+ it("respects custom limit parameter", async () => {
+ const tags = await getPopularTags(3);
+ expect(tags).toHaveLength(3);
+ });
+
+ it("returns tags with required properties", async () => {
+ const tags = await getPopularTags(1);
+ expect(tags[0]).toHaveProperty("name");
+ expect(tags[0]).toHaveProperty("questions");
+ });
+});
diff --git a/lib/data/tags.ts b/lib/data/tags.ts
new file mode 100644
index 0000000..fe9eb04
--- /dev/null
+++ b/lib/data/tags.ts
@@ -0,0 +1,21 @@
+export type Tag = {
+ name: string;
+ questions: number;
+};
+
+const MOCK_TAGS: Tag[] = [
+ { name: "nextjs", questions: 320 },
+ { name: "reactjs", questions: 244 },
+ { name: "javascript", questions: 83 },
+ { name: "react", questions: 30 },
+ { name: "postgres", questions: 89 },
+];
+
+/**
+ * Fetch popular tags sorted by question count.
+ * TODO: Replace with MongoDB query when database is set up.
+ */
+export async function getPopularTags(limit = 5): Promise {
+ // Future: return await db.collection('tags').find().sort({ questions: -1 }).limit(limit)
+ return MOCK_TAGS.slice(0, limit);
+}
diff --git a/lib/formatPrice.test.ts b/lib/formatPrice.test.ts
deleted file mode 100644
index 8080ad4..0000000
--- a/lib/formatPrice.test.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-/**
- * Demo test for CI/CD purposes - can be safely deleted.
- * This file demonstrates Vitest unit testing setup.
- */
-
-import { describe, expect, it } from "vitest";
-import { formatPrice } from "@/lib/formatPrice";
-
-describe("formatPrice", () => {
- it("formats basic prices with pounds and pence", () => {
- expect(formatPrice(1234.5)).toBe("£1,234.50");
- });
-
- it("formats zero correctly", () => {
- expect(formatPrice(0)).toBe("£0.00");
- });
-
- it("formats large numbers with proper thousand separators", () => {
- expect(formatPrice(1000000)).toBe("£1,000,000.00");
- });
-
- it("formats decimals to two decimal places", () => {
- expect(formatPrice(99.9)).toBe("£99.90");
- });
-});
diff --git a/lib/formatPrice.ts b/lib/formatPrice.ts
deleted file mode 100644
index 372d8ef..0000000
--- a/lib/formatPrice.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-/**
- * Demo utility for CI/CD purposes - can be safely deleted.
- * This file demonstrates a testable utility function.
- *
- * Formats a number as a British pound price with thousand separators.
- * @param price - The price value to format
- * @returns Formatted price string (e.g., "£1,234.50")
- */
-export function formatPrice(price: number): string {
- return new Intl.NumberFormat("en-GB", {
- style: "currency",
- currency: "GBP",
- }).format(price);
-}
diff --git a/x_docs/mine/2026-01-01-right-sidebar/current.jpg b/x_docs/mine/2026-01-01-right-sidebar/current.jpg
new file mode 100755
index 0000000..a926794
Binary files /dev/null and b/x_docs/mine/2026-01-01-right-sidebar/current.jpg differ
diff --git a/x_docs/mine/2026-01-01-right-sidebar/handover.md b/x_docs/mine/2026-01-01-right-sidebar/handover.md
new file mode 100644
index 0000000..8f152c6
--- /dev/null
+++ b/x_docs/mine/2026-01-01-right-sidebar/handover.md
@@ -0,0 +1,131 @@
+# Right Sidebar Handover - STALE DOCUMENTATION - FOR HISTORICAL PURPOSES ONLY
+
+Target audience: Claude Code
+
+## What's Been Implemented — ✅ Done
+
+The right sidebar displays **Top Questions** and **Popular Tags** sections with clickable links to placeholder pages.
+
+### Components Created
+
+| File | Purpose |
+|------|---------|
+| `components/right-sidebar/right-sidebar.tsx` | Async Server Component container |
+| `components/right-sidebar/question-link.tsx` | Clickable question title + ChevronRight icon |
+| `components/right-sidebar/tag-link.tsx` | Tag link + optional question count |
+| `components/ui/badge.tsx` | shadcn Badge with custom `toptag` variant |
+| `app/(root)/question/[id]/page.tsx` | Placeholder page — `/question/123` |
+| `app/(root)/tags/[slug]/page.tsx` | Placeholder page — `/tags/nextjs` |
+
+> **URL strategy:** Questions use numeric IDs (database keys); tags use name slugs for SEO-friendly URLs.
+
+### Data Layer
+
+| File | Purpose |
+|------|---------|
+| `lib/data/questions.ts` | `Question` type + `getTopQuestions(limit)` |
+| `lib/data/tags.ts` | `Tag` type + `getPopularTags(limit)` |
+
+Mock data with async functions ready for MongoDB migration. `RightSidebar` fetches via `Promise.all()`.
+
+### Design Reference
+
+Target design: `pic1-target.jpg` (dark mode Figma mockup in repo root)
+
+### Verifications
+
+- ✅ `npm run check` passes
+- ✅ `npm run test` passes
+- ✅ Dev server runs on port 3000
+
+- ✅ E2E test: `e2e/right-sidebar.desktop.spec.ts`
+- ✅ Unit tests: `lib/data/questions.test.ts`, `lib/data/tags.test.ts`
+
+---
+
+## Align Tag Styling to `pic1-target.jpg` — ✅ Done
+
+### Goal
+
+Align visual appearance of `components/right-sidebar/tag-link.tsx` to the target design. Use recommended best pragmatic practice of centralised theming (CSS custom properties in `app/globals.css`)
+
+### Context & Visual Analysis
+
+Current approach: Both `QuestionLink` and `TagLink` are server components using Next.js `Link` with hover states (`hover:bg-accent/50`). The `TagLink` renders a Badge for the tag name and a separate span for the count, with the entire row wrapped in a Link for clickability.
+
+Visual comparison:
+
+| Screenshot | File |
+|------------|------|
+| Target design | `pic1-target.jpg` |
+| Current implementation | `pic2-current.jpg` |
+
+Current: `TagLink` uses `Badge variant="toptag"` (`components/ui/badge.tsx`).
+
+Reference: `h_tagstyle.md` contains extracted styling from the course project (older conventions — Next.js 15, Tailwind config). Examine centralised theming in `app/globals.css` and evaluate fit before adopting. Specifically: are there existing semantic colour variables that closely match? Report findings before defining new variables.
+
+---
+
+## Restyle QuestionLink Microinteractions — ✅ Done
+
+Component: `components/right-sidebar/question-link.tsx`
+Screenshot (current): `current.jpg`
+Reference: `x_docs/mine/micro-interactions.md`
+
+### Goal
+
+Replace the dated `hover:bg-accent/50` overlay with Linear-style microinteractions using Tailwind only.
+
+### Requirements
+
+- Remove background hover overlay
+- Add subtle hover feedback (choose 1-2):
+- Chevron: translate right ~2px then return
+- Text: underline or subtle colour shift
+- Other: suggest if better suited
+
+### Constraints
+
+- Tailwind CSS only (no Motion library)
+- Must work in both light and dark modes
+
+---
+
+## Later: Devicon Integration
+
+### Goal
+
+Add technology icons to tag badges using the [Devicon](https://devicon.dev/) font library. Icons should render automatically for user-created tags (normalised) when a matching devicon exists. If no match, render the devicon's generic icon or a lucide react icon (to be confirmed).
+
+These are preliminary draft details in `` tags, will be formalised later:
+
+
+
+### Approach (to be determined)
+
+Both approaches use the [Devicon font](https://raw.githubusercontent.com/devicons/devicon/refs/heads/master/README.md). The difference is how class names are resolved:
+
+1. **Convention-based** — dynamically build class name from tag name using pattern `devicon-{name}-plain colored`, validate against a `Set` of known icon names, with alias map for variations
+
+2. **Mapping table** — lookup full class string from a large object (`techMap`) as implemented in `~/projects/nextjs/jsmasterypro_devflow`
+
+Investigate both approaches and recommend the simplest, most maintainable solution.
+
+### Success Criteria
+
+Functional:
+
+- [ ] Devicon font installed and loading
+- [ ] Utility function `getDeviconClassName(tagName: string)` created in `lib/utils.ts`
+- [ ] Tag name normalization works (lowercase, remove dots/spaces)
+- [ ] Tag badges display correct icons for known technologies
+- [ ] Unknown tags display fallback icon (not blank)
+
+Verified:
+
+- [ ] Icons render correctly for: nextjs, react, javascript, postgres
+- [ ] Alias resolution works: js → javascript, ts → typescript
+- [ ] Fallback renders for unknown tag name (e.g., "madeuptag")
+- [ ] UI aligns with `pic1-target.jpg`
+
+
diff --git a/x_docs/mine/2026-01-01-right-sidebar/pic1-target.jpg b/x_docs/mine/2026-01-01-right-sidebar/pic1-target.jpg
new file mode 100755
index 0000000..ccbc921
Binary files /dev/null and b/x_docs/mine/2026-01-01-right-sidebar/pic1-target.jpg differ
diff --git a/x_docs/mine/micro-interactions.md b/x_docs/mine/micro-interactions.md
new file mode 100644
index 0000000..d6c0fa7
--- /dev/null
+++ b/x_docs/mine/micro-interactions.md
@@ -0,0 +1,399 @@
+# Microinteractions for Next.js 16
+
+This document explains how to add microinteractions to your Next.js 16 application using **Tailwind CSS** and **Motion** (formerly Framer Motion), with specific guidance for shadcn/ui integration and centralised theming.
+
+---
+
+## The Recommended Stack
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| **Base** | Tailwind CSS | Hover, focus, simple transitions (0kb added) |
+| **Advanced** | Motion (motion.dev) | Gestures, exit animations, layout, scroll effects |
+
+This two-layer approach covers 95%+ of microinteraction needs for production web applications.
+
+---
+
+## Motion (motion.dev)
+
+Motion is the evolution of Framer Motion, now an independent project with 12+ million monthly npm downloads. It's the industry standard for React animations.
+
+### Why Motion?
+
+**Declarative API:** You animate by passing props, not by writing imperative code. Motion handles the complexity of enter/exit animations, layout shifts, gestures, and scroll-linked effects whilst you focus on *what* you want to animate.
+
+**The philosophy:** "Describe the end state, let Motion figure out how to get there." This matches React's declarative model perfectly.
+
+### Key Features for DevFlow
+
+| Feature | What It Does | DevFlow Use Case |
+|---------|--------------|------------------|
+| `whileTap` / `whileHover` | Gesture-triggered states | Vote buttons, interactive cards |
+| `AnimatePresence` | Exit animations for unmounting elements | Toasts, modals, notifications |
+| `layout` | Smooth layout transitions | List reordering, expanding cards |
+| `useScroll` / `useInView` | Scroll-linked animations | Reveal effects, parallax |
+| `drag` | Draggable elements | Reorder answers, dismiss actions |
+| Springs | Physics-based motion | Natural, interruptible animations |
+
+### Bundle Size
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Motion Bundle Size (minified + gzipped) │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ Full import ████████████████████████████████░░ 34kb │
+│ LazyMotion (m) █████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 4.6kb│
+│ Single hook ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ~1kb │
+│ │
+│ Tailwind (CSS) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0kb │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Motion provides `LazyMotion` for code-splitting and the `m` component for minimal bundles. You can start at ~4.6kb and only load features you use.
+
+### Ecosystem Alignment
+
+The shadcn/ui ecosystem heavily uses Motion. These libraries are designed to work with shadcn/ui and are built on Motion:
+
+| Library | Description | URL |
+|---------|-------------|-----|
+| **Magic UI** | 20+ animated components, shadcn-compatible | magicui.design |
+| **Aceternity UI** | High-impact hero sections, copy-paste ready | ui.aceternity.com |
+| **Motion Primitives** | Animated primitives for common patterns | motion-primitives.com |
+| **Animate UI** | Full library with Motion at its core | animate-ui.com |
+
+### Production Track Record
+
+Motion is used by Linear, Vercel, Stripe, and thousands of production applications. It's mature, well-maintained, and has excellent performance characteristics including GPU acceleration and 120fps support.
+
+---
+
+## Integrating with shadcn/ui Components
+
+Microinteractions work beautifully with shadcn/ui components. There are three integration patterns:
+
+### Pattern 1: Wrapper Approach
+
+Wrap any shadcn/ui component in a motion element. This is non-invasive and preserves the original component:
+
+```
+┌─────────────────────────────────────────────┐
+│ motion.div (handles animation) │
+│ ┌───────────────────────────────────────┐ │
+│ │ shadcn Button (unchanged) │ │
+│ │ - All original props work │ │
+│ │ - Styling preserved │ │
+│ │ - Accessibility intact │ │
+│ └───────────────────────────────────────┘ │
+└─────────────────────────────────────────────┘
+```
+
+**When to use:** Quick enhancements, one-off animations, prototyping.
+
+### Pattern 2: Motion Component Approach
+
+Convert the shadcn component itself into a motion component. This provides more control and better performance for complex animations:
+
+```
+┌─────────────────────────────────────────────┐
+│ MotionButton = motion(Button) │
+│ ┌───────────────────────────────────────┐ │
+│ │ Single element (no wrapper) │ │
+│ │ - Direct animation props │ │
+│ │ - Better performance │ │
+│ │ - Cleaner DOM │ │
+│ └───────────────────────────────────────┘ │
+└─────────────────────────────────────────────┘
+```
+
+**When to use:** Reusable animated variants, performance-critical components.
+
+### Pattern 3: Pre-built Animated Libraries
+
+Use component libraries specifically designed for shadcn/ui + Motion (see table above).
+
+**When to use:** When you want production-ready animated components without building from scratch.
+
+### Radix UI Consideration
+
+Since shadcn/ui is built on Radix UI primitives, you get additional animation hooks. Radix components expose data attributes like `data-state="open"` and `data-side="bottom"` that you can use for CSS animations or Motion's conditional animations.
+
+---
+
+## Centralised Theming in globals.css
+
+### The Question
+
+Should microinteraction timings, easings, and animation values be defined centrally in `globals.css` using CSS custom properties?
+
+### The Answer: It Depends on Scope
+
+**Legitimate and recommended for:**
+
+- Consistent timing across the application (e.g., `--duration-fast: 150ms`)
+- Standard easing curves (e.g., `--ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55)`)
+- Reduced motion preferences (single source of truth)
+- Brand-aligned motion values
+
+**Over-engineering for:**
+
+- Every individual animation's parameters
+- Complex choreography that varies by context
+- Physics-based values (spring tension/friction)
+
+### Recommended Approach
+
+Define a minimal set of motion tokens in `globals.css`:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ globals.css - Motion Tokens │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ :root { │
+│ /* Durations */ │
+│ --duration-instant: 100ms; │
+│ --duration-fast: 150ms; │
+│ --duration-normal: 300ms; │
+│ --duration-slow: 500ms; │
+│ │
+│ /* Easings */ │
+│ --ease-out: cubic-bezier(0.22, 1, 0.36, 1); │
+│ --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1); │
+│ --ease-bounce: cubic-bezier(0.68, -0.55, 0.27, 1.55); │
+│ │
+│ /* Scales */ │
+│ --scale-pressed: 0.97; │
+│ --scale-hover: 1.02; │
+│ } │
+│ │
+│ @media (prefers-reduced-motion: reduce) { │
+│ :root { │
+│ --duration-instant: 0ms; │
+│ --duration-fast: 0ms; │
+│ --duration-normal: 0ms; │
+│ --duration-slow: 0ms; │
+│ } │
+│ } │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### How This Works with Motion
+
+Motion can read CSS custom properties. You reference them in your animation definitions, creating a bridge between your central theme and component-level animations.
+
+### Benefits of This Approach
+
+| Benefit | Explanation |
+|---------|-------------|
+| 🎯 **Consistency** | All buttons press at the same rate, all modals open at the same speed |
+| ♿ **Accessibility** | Single place to respect reduced motion preferences |
+| 🎨 **Brand alignment** | Motion becomes part of your design system |
+| 🔧 **Easy tuning** | Adjust timing globally without touching components |
+| 📦 **Not over-engineering** | You're defining tokens, not implementing animations |
+
+### What NOT to Centralise
+
+Avoid putting these in globals.css:
+
+- Complex spring configurations (keep with the component using them)
+- Stagger delays (context-dependent)
+- Gesture thresholds (interaction-specific)
+- Scroll offsets (layout-dependent)
+
+---
+
+## Decision Tree: Tailwind CSS vs Motion
+
+Use this flowchart to decide whether Tailwind's built-in animations are sufficient or if you need Motion:
+
+```
+ ┌─────────────────────────┐
+ │ What do you need to │
+ │ animate? │
+ └───────────┬─────────────┘
+ │
+ ┌─────────────────────┼─────────────────────┐
+ ▼ ▼ ▼
+ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+ │ Hover/Focus │ │ Loading │ │ Enter/Exit │
+ │ states only? │ │ indicators? │ │ (mount/unmount)│
+ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘
+ │ │ │
+ ▼ ▼ ▼
+ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+ │ ✅ TAILWIND │ │ ✅ TAILWIND │ │ 🎬 MOTION │
+ │ │ │ │ │ │
+ │ transition-* │ │ animate-spin │ │ AnimatePresence │
+ │ hover:scale-105 │ │ animate-pulse │ │ for unmount │
+ │ duration-300 │ │ animate-ping │ │ animations │
+ └─────────────────┘ └─────────────────┘ └─────────────────┘
+
+ ┌─────────────────────────┐
+ │ Do you need gestures │
+ │ or complex motion? │
+ └───────────┬─────────────┘
+ │
+ ┌─────────────────────┼─────────────────────┐
+ ▼ ▼ ▼
+ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+ │ Drag/swipe? │ │ Layout changes │ │ Scroll-linked │
+ │ │ │ (reorder)? │ │ animations? │
+ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘
+ │ │ │
+ ▼ ▼ ▼
+ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+ │ 🎬 MOTION │ │ 🎬 MOTION │ │ 🎬 MOTION │
+ │ │ │ │ │ │
+ │ drag prop │ │ layout prop │ │ useScroll │
+ │ gesture hooks │ │ layoutId │ │ useInView │
+ └─────────────────┘ └─────────────────┘ └─────────────────┘
+```
+
+### Quick Reference Table
+
+| Scenario | Tool | Why |
+|----------|------|-----|
+| Button hover effect | ✅ Tailwind | `hover:scale-105 transition-transform` |
+| Loading spinner | ✅ Tailwind | `animate-spin` |
+| Skeleton loader | ✅ Tailwind | `animate-pulse` |
+| Notification badge | ✅ Tailwind | `animate-ping` |
+| Focus ring | ✅ Tailwind | `transition-shadow focus:ring-2` |
+| Colour transitions | ✅ Tailwind | `transition-colors` |
+| Toast enter/exit | 🎬 Motion | AnimatePresence for unmount animations |
+| Drag to reorder | 🎬 Motion | Built-in drag gesture |
+| Modal with backdrop | 🎬 Motion | Coordinated enter/exit |
+| Scroll reveal | 🎬 Motion | useInView + useScroll |
+| Vote button bounce | 🎬 Motion | whileTap + spring physics |
+| Shared layout | 🎬 Motion | layoutId for smooth transitions |
+| Number counting | 🎬 Motion | useSpring or useMotionValue |
+| SVG path animation | 🎬 Motion | pathLength + motion.path |
+
+### The DevFlow Animation Stack
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ DevFlow Animation Stack │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ Layer 2: MOTION (motion.dev) │
+│ ├── Complex interactions (drag, gestures) │
+│ ├── Enter/exit animations (modals, toasts) │
+│ ├── Scroll-linked effects (parallax, reveals) │
+│ └── Shared layout transitions │
+│ │
+│ Layer 1: TAILWIND (base layer) │
+│ ├── Hover/focus states │
+│ ├── Colour transitions │
+│ ├── Loading spinners │
+│ └── Simple scale/opacity effects │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Getting Started
+
+### Step 1: Master Tailwind First
+
+Before adding Motion, ensure you're using Tailwind's animation utilities effectively:
+
+- `transition-*` for state changes
+- `hover:` and `focus:` for interactions
+- `animate-*` for continuous animations
+- `motion-safe:` and `motion-reduce:` for accessibility
+
+### Step 2: Add Motion for Complex Needs
+
+Install Motion when you need:
+
+- Exit animations (elements leaving the DOM)
+- Gesture-based interactions (drag, swipe)
+- Scroll-triggered animations
+- Coordinated multi-element choreography
+- Physics-based motion (springs, damping)
+
+```bash
+npm install motion
+```
+
+```ts
+import { motion } from "motion/react"
+```
+
+### Step 3: Centralise Your Timing Tokens
+
+Add motion tokens to `globals.css` early. This ensures consistency as you build out animations and makes future adjustments trivial.
+
+---
+
+## Appendix: v0 Compatibility
+
+v0 currently uses the legacy `framer-motion` package. Both packages have identical APIs:
+
+| Package | Installation | When to Use |
+|---------|--------|-------------|
+| `motion` | `npm install motion` | New projects (recommended) |
+| `framer-motion` | `npm install framer-motion` | v0 projects, existing codebases |
+
+If you copy animated components from v0, simply change the import from `framer-motion` to `motion/react` — no other changes needed.
+
+The following was a response from v0 AI assistant, included for reference between `` tags:
+
+
+
+💡 **Decision Tree for Micro Interactions:**
+
+```text
+┌─────────────────────────────────────────┐
+│ What kind of interaction do you need? │
+└──────────────┬──────────────────────────┘
+ │
+ ▼
+ ┌──────────────────────┐
+ │ Simple hover/focus │ ───YES──► Use Tailwind utilities only
+ │ Color/scale changes │ (no package needed)
+ │ Basic transitions │
+ └──────────┬───────────┘
+ │ NO
+ ▼
+ ┌──────────────────────┐
+ │ Layout animations? │ ───YES──► Framer Motion
+ │ (items moving, │ (layout prop, AnimatePresence)
+ │ reordering, etc.) │
+ └──────────┬───────────┘
+ │ NO
+ ▼
+ ┌──────────────────────┐
+ │ Gesture-based? │ ───YES──► Framer Motion
+ │ (drag, swipe, etc.) │ (drag, pan, tap handlers)
+ └──────────┬───────────┘
+ │ NO
+ ▼
+ ┌──────────────────────┐
+ │ Scroll-triggered? │ ───YES──► Framer Motion + useScroll
+ │ Complex timelines? │ OR GSAP (for very complex)
+ └──────────┬───────────┘
+ │ NO
+ ▼
+ ┌──────────────────────┐
+ │ 3D transforms or │ ───YES──► GSAP or Three.js
+ │ WebGL animations? │ (specialized use case)
+ └──────────────────────┘
+```
+
+**Start with Tailwind-only** → Add **Framer Motion** when you need:
+
+- Entrance/exit animations for modals, dropdowns, toasts
+- Layout animations (smooth reordering, expanding/collapsing)
+- Gesture interactions (drag, swipe)
+- Scroll-based animations
+
+This covers 95% of modern web app needs. Only reach for GSAP or React Spring if you have very specific requirements like complex timeline orchestration or physics simulations.
+
+