# Implementation Plan: YouTube Design Preview Replica

**Branch**: `002-youtube-design-preview` | **Date**: 2026-01-29 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/002-youtube-design-preview/spec.md`

## Summary

Enhance the existing thumbnail preview tool to achieve pixel-perfect visual accuracy with YouTube's current design across three view modes (Desktop, Mobile, Sidebar). The implementation focuses on extracting exact CSS values from YouTube, implementing local storage persistence, adding a manual theme toggle, and integrating Playwright MCP for automated visual regression testing with weekly reference screenshot updates.

## Technical Context

**Language/Version**: TypeScript 5.9.x (frontend + backend)
**Primary Dependencies**: React 19.x, Tailwind CSS 4.x, shadcn/ui, Zustand, Playwright MCP
**Storage**: Browser localStorage (preview persistence), file system (reference screenshots)
**Testing**: Playwright visual comparison, Jest (unit tests)
**Target Platform**: Web browsers (Chrome, Firefox, Safari), responsive mobile views
**Project Type**: Monorepo (frontend + backend)
**Performance Goals**: Preview render < 2 seconds, 98% visual match with YouTube
**Constraints**: 5MB max thumbnail upload, JPG/PNG/WebP formats only
**Scale/Scope**: Single-user local tool, no concurrent users

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Principle | Status | Notes |
|-----------|--------|-------|
| I. Tech Stack | PASS | React 19.x, TypeScript 5.x, Tailwind CSS 4.x, shadcn/ui, Zustand - all aligned |
| II. Architecture | PASS | Feature code goes in existing frontend structure |
| III. Styling | PASS | YouTube CSS variables already defined in index.css; extend with Tailwind utilities |
| IV. Data Management | PASS | Zustand for preview state, localStorage for persistence (no backend changes needed) |
| V. Development Practices | PASS | TypeScript strict mode, ESLint, existing patterns followed |

**Gate Result**: PASS - All constitution principles satisfied.

## Project Structure

### Documentation (this feature)

```text
specs/002-youtube-design-preview/
├── plan.md              # This file
├── research.md          # Phase 0: YouTube design extraction research
├── data-model.md        # Phase 1: Data entities and storage schema
├── quickstart.md        # Phase 1: Development setup guide
├── contracts/           # Phase 1: API contracts (minimal - mostly frontend)
└── tasks.md             # Phase 2: Implementation tasks (created by /speckit.tasks)
```

### Source Code (repository root)

```text
frontend/
├── src/
│   ├── components/
│   │   ├── YouTubeVideoCard.tsx      # MODIFY: Enhance for pixel-perfect accuracy
│   │   ├── PreviewModeSelector.tsx   # NEW: Desktop/Mobile/Sidebar switcher
│   │   ├── ThemeToggle.tsx           # NEW: Light/dark mode toggle
│   │   ├── ThumbnailUploader.tsx     # MODIFY: Add file validation (5MB, formats)
│   │   └── ui/                       # shadcn/ui components (no changes)
│   ├── hooks/
│   │   └── useLocalStorage.ts        # NEW: Persist preview state
│   ├── store/
│   │   └── previewStore.ts           # MODIFY: Add persistence, theme state
│   ├── types/
│   │   └── index.ts                  # MODIFY: Add new type definitions
│   ├── lib/
│   │   └── youtube-styles.ts         # NEW: Extracted YouTube CSS constants
│   └── index.css                     # MODIFY: Add precise YouTube CSS variables
├── tests/
│   └── visual/
│       ├── desktop.spec.ts           # NEW: Playwright visual tests
│       ├── mobile.spec.ts            # NEW: Playwright visual tests
│       ├── sidebar.spec.ts           # NEW: Playwright visual tests
│       └── reference/                # NEW: YouTube reference screenshots
└── playwright.config.ts              # NEW: Playwright configuration

scripts/
└── capture-youtube-reference.ts      # NEW: Weekly reference screenshot capture
```

**Structure Decision**: Extending existing frontend structure. No backend changes required as persistence uses browser localStorage per clarification.

## Complexity Tracking

> No constitution violations to justify.

| Aspect | Decision | Rationale |
|--------|----------|-----------|
| Storage | localStorage only | Per clarification - no server persistence needed |
| Theme | Manual toggle | Per clarification - no system preference detection |
| Reference updates | Automated weekly | Per clarification - Playwright captures from live YouTube |