4.6 KiB
Implementation Plan: YouTube Design Preview Replica
Branch: 002-youtube-design-preview | Date: 2026-01-29 | Spec: 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)
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)
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 |