frontend/specs/002-youtube-design-preview/quickstart.md

Quickstart: YouTube Design Preview Replica

Prerequisites

• Node.js 20+
• pnpm or npm
• Playwright (for visual testing)

Setup

1. Install dependencies (if not already done):

   cd frontend
   npm install
   

2. Install Playwright browsers (for visual testing):

   npx playwright install chromium firefox webkit
   

3. Start development server:

   npm run dev
   

4. Access the app: Open http://localhost:5173 in your browser

Development Workflow

Working on Preview Components

The main component to modify is:

• frontend/src/components/YouTubeVideoCard.tsx

YouTube CSS variables are defined in:

• frontend/src/index.css (search for "YOUTUBE THEME VARIABLES")

Adding New Preview Modes

1. Update ViewMode type in frontend/src/types/index.ts
2. Add new variant case in YouTubeVideoCard.tsx
3. Update ViewSwitcher.tsx to include new option
4. Add visual test in frontend/tests/visual/

Testing Visual Accuracy

Manual Testing:

1. Open YouTube in a browser tab
2. Open the preview tool in another tab
3. Compare side-by-side at same zoom level

Automated Testing (Playwright):

cd frontend
npx playwright test tests/visual/

Updating Reference Screenshots

Reference screenshots are stored in: specs/002-youtube-design-preview/reference/

To capture new references:

# Using Playwright MCP or manual script
npx ts-node scripts/capture-youtube-reference.ts

Key Files

File	Purpose
src/components/YouTubeVideoCard.tsx	Main preview component
src/components/PreviewModeSelector.tsx	Desktop/Mobile/Sidebar switcher
src/components/ThemeToggle.tsx	Light/Dark mode toggle
src/store/previewStore.ts	Zustand state management
src/hooks/useLocalStorage.ts	Persistence hook
src/lib/youtube-styles.ts	YouTube CSS constants
src/index.css	YouTube CSS variables

CSS Variables Reference

Light Mode Colors

--yt-bg: #ffffff;
--yt-title: #0f0f0f;
--yt-meta: #606060;

Dark Mode Colors

--yt-bg: #0f0f0f;
--yt-title: #f1f1f1;
--yt-meta: #aaaaaa;

Dimensions

/* Desktop thumbnail */
width: 360px;
height: 202px;
border-radius: 12px;

/* Sidebar thumbnail */
width: 168px;
height: 94px;
border-radius: 8px;

/* Avatar */
width: 36px;
height: 36px;
border-radius: 50%;

/* Duration badge */
padding: 3px 4px;
border-radius: 4px;
font-size: 12px;

Common Tasks

Add support for new YouTube element

1. Capture reference from YouTube using Playwright
2. Extract computed styles using browser DevTools
3. Add CSS variables to index.css if new colors needed
4. Update component JSX and Tailwind classes
5. Run visual tests to verify accuracy

Debug visual differences

1. Run Playwright test to generate diff image
2. Check specs/002-youtube-design-preview/reference/ for comparison
3. Use browser DevTools to compare computed styles
4. Adjust Tailwind classes or CSS variables

Update for YouTube design changes

1. Capture new reference screenshots from YouTube
2. Run visual tests - they should fail showing differences
3. Update CSS values in component/styles
4. Re-run tests until passing
5. Commit new reference screenshots