12 KiB
Feature Specification: YouTube Design Preview Replica
Feature Branch: 002-youtube-design-preview
Created: 2026-01-29
Status: Draft
Input: User description: "необходимо в превью полностью повторить дизайн youtube для десктопа, мобильной версии и sidebar, превью должно полностью повторять youtube 1 в 1, используй mcp playwright для проверки соответствия"
User Scenarios & Testing (mandatory)
User Story 1 - Desktop Video Preview (Priority: P1)
A content creator wants to preview how their thumbnail will appear in YouTube's desktop grid layout, including the video duration badge, channel avatar, video title, channel name, view count, and upload time - exactly as it appears on YouTube's homepage.
Why this priority: Desktop is the primary platform for content creators reviewing their work. The grid layout preview provides the most common context where thumbnails are seen by viewers.
Independent Test: Can be tested by uploading a thumbnail and verifying it renders in a pixel-perfect YouTube desktop grid card format with all metadata elements positioned correctly.
Acceptance Scenarios:
- Given a user has uploaded a thumbnail image, When they select desktop preview mode, Then they see their thumbnail displayed in an exact replica of YouTube's desktop video card with 16:9 aspect ratio, rounded corners, duration badge in bottom-right, and hover effects
- Given the desktop preview is displayed, When the user views the video metadata section, Then they see channel avatar (circular, left-aligned), title (multi-line truncation), channel name, view count, and relative upload time styled identically to YouTube
- Given the desktop preview is active, When the user hovers over the thumbnail, Then they see YouTube's hover state including preview animation placeholder and watch later/add to queue icons
User Story 2 - Mobile Video Preview (Priority: P1)
A content creator wants to see how their thumbnail appears on YouTube's mobile app layout, where the thumbnail takes full width and the metadata is displayed below in YouTube's mobile-specific format.
Why this priority: Mobile accounts for over 70% of YouTube views. Creators must verify their thumbnails are effective on mobile devices where layout and text sizes differ significantly.
Independent Test: Can be tested by switching to mobile preview mode and verifying the layout matches YouTube's mobile app exactly, including touch-friendly sizing and mobile-specific typography.
Acceptance Scenarios:
- Given a user has uploaded a thumbnail, When they select mobile preview mode, Then the thumbnail displays full-width with YouTube's mobile aspect ratio and rounded corners matching the app
- Given mobile preview is active, When viewing video metadata, Then the channel avatar, title, channel name, views, and time are displayed in YouTube's mobile typography and spacing
- Given mobile preview is active, When the preview is compared to actual YouTube mobile app, Then the layout, spacing, fonts, and element sizes match within 2px tolerance
User Story 3 - Sidebar/Related Videos Preview (Priority: P2)
A content creator wants to preview how their thumbnail will appear in YouTube's sidebar (related videos section) where thumbnails are displayed at a smaller size alongside video titles.
Why this priority: The sidebar is a major discovery surface for videos. Thumbnails must be legible and compelling at this smaller size to drive click-through from related videos.
Independent Test: Can be tested by selecting sidebar preview mode and verifying the thumbnail and title display match YouTube's sidebar format exactly.
Acceptance Scenarios:
- Given a user has uploaded a thumbnail, When they select sidebar preview mode, Then the thumbnail displays at YouTube's exact sidebar dimensions (168x94px) with correct aspect ratio
- Given sidebar preview is active, When viewing the video card, Then the title displays to the right of the thumbnail with proper truncation (2 lines), channel name below, and view count/time in YouTube's sidebar format
- Given sidebar preview mode, When multiple preview cards are shown, Then they stack vertically with YouTube's exact spacing between cards
User Story 4 - Visual Accuracy Validation with Playwright (Priority: P2)
The system uses automated visual comparison testing with Playwright MCP to ensure the preview components match YouTube's actual design with pixel-level accuracy.
Why this priority: Automated validation ensures design fidelity is maintained during development and catches visual regressions early. This supports the "1:1 replica" requirement.
Independent Test: Can be tested by running Playwright visual comparison tests against captured YouTube reference screenshots.
Acceptance Scenarios:
- Given a preview component is rendered, When Playwright captures a screenshot, Then the screenshot can be compared against a YouTube reference image with configurable threshold (default 98% match)
- Given a visual comparison test runs, When differences are detected above threshold, Then a diff image is generated highlighting discrepancies for developer review
- Given all three preview modes exist, When the full visual test suite runs, Then each mode (desktop, mobile, sidebar) passes the visual comparison against corresponding YouTube references
Edge Cases
- What happens when the thumbnail image has non-standard aspect ratio? System should crop/scale to 16:9 with preview of crop area
- How does system handle very long video titles? Truncation with ellipsis matching YouTube's exact behavior per view mode
- What happens when channel name contains special characters or emojis? Render identically to YouTube's handling
- How does system handle missing metadata fields (no view count yet, no upload time)? Display "No views" and "Just now" as YouTube does
- What happens on intermediate screen sizes between desktop and mobile breakpoints? Follow YouTube's responsive behavior
- What happens when uploaded thumbnail exceeds 5MB? Display error message and reject upload, prompting user to reduce file size
- What happens when user uploads unsupported image format (e.g., GIF, BMP)? Display error message listing accepted formats (JPG, PNG, WebP)
Requirements (mandatory)
Functional Requirements
- FR-001: System MUST render desktop video card preview matching YouTube's current design with pixel-level accuracy
- FR-002: System MUST render mobile video card preview matching YouTube's mobile app layout exactly
- FR-003: System MUST render sidebar video card preview matching YouTube's related videos section design
- FR-004: System MUST support real-time thumbnail image upload and preview update
- FR-005: System MUST display all YouTube video metadata elements: thumbnail, duration badge, channel avatar, title, channel name, view count, upload time
- FR-006: System MUST replicate YouTube's typography including font family, sizes, weights, and colors for each view mode
- FR-007: System MUST replicate YouTube's spacing, padding, and margins for all preview components
- FR-008: System MUST replicate YouTube's hover states and interactive elements on desktop preview
- FR-009: System MUST implement responsive breakpoints matching YouTube's desktop-to-mobile transitions
- FR-010: System MUST support Playwright MCP integration for automated visual comparison testing
- FR-011: System MUST generate visual diff reports when preview design deviates from YouTube reference
- FR-012: System MUST allow users to customize preview metadata (title, channel name, view count, etc.) for realistic previews
- FR-013: System MUST display duration badge with correct formatting (HH:MM:SS or MM:SS) positioned in bottom-right of thumbnail
- FR-014: System MUST render channel avatar as circular image with YouTube's exact sizing per view mode
- FR-015: System MUST persist preview data (thumbnail, metadata) in browser local storage, surviving page refresh without requiring server-side storage or user accounts
- FR-016: System MUST provide manual theme toggle allowing users to switch between light and dark modes matching YouTube's respective color schemes (no auto-detection of system preference)
- FR-017: System MUST automatically capture fresh reference screenshots from live YouTube on a weekly schedule for visual comparison baseline updates
- FR-018: System MUST store historical reference screenshots to enable rollback if automated capture produces invalid baselines
- FR-019: System MUST enforce 5MB maximum file size for thumbnail uploads, matching YouTube's actual limit, and display clear error message for oversized files
- FR-020: System MUST accept JPG, PNG, and WebP image formats for thumbnail upload, rejecting unsupported formats with clear error message
Key Entities
- ThumbnailPreview: Represents a preview instance containing user-uploaded image, selected view mode, and customizable metadata
- PreviewMode: Enumeration of view modes (Desktop, Mobile, Sidebar) each with distinct layout specifications
- VideoMetadata: User-customizable data including title, channel name, channel avatar, duration, view count, upload time
- VisualTestResult: Comparison result containing match percentage, diff image reference, and pass/fail status
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: All three preview modes (desktop, mobile, sidebar) achieve 98% or higher visual match when compared to YouTube reference screenshots via Playwright
- SC-002: Users can upload a thumbnail and see the preview render in under 2 seconds
- SC-003: Preview accurately reflects YouTube's current design as verified by side-by-side manual comparison
- SC-004: 90% of users can correctly identify the preview as "YouTube-like" in blind comparison tests
- SC-005: Visual regression tests pass with less than 2% pixel difference from established baseline
- SC-006: Preview maintains visual accuracy across Chrome, Firefox, and Safari browsers
- SC-007: Mobile preview renders correctly on actual mobile devices (iOS Safari, Android Chrome) matching the YouTube app appearance
Clarifications
Session 2026-01-29
- Q: Should previews be persisted for later access? → A: Local storage (preview persisted in browser, no server storage)
- Q: How should theme mode (light/dark) be handled? → A: Both themes available, user must manually select (no auto-detection)
- Q: How should reference screenshots be maintained for visual comparison? → A: Automated weekly capture from live YouTube
- Q: What is the maximum thumbnail file size for upload? → A: 5MB maximum (matches YouTube's actual limit)
- Q: Which image formats are supported for thumbnail upload? → A: JPG, PNG, and WebP (matches YouTube's supported formats)
Assumptions
- YouTube's current design (as of January 2026) serves as the reference baseline
- Font family uses YouTube's public-facing fonts (Roboto for body text)
- Color values will be extracted from YouTube's current production CSS
- Playwright MCP is available and configured in the development environment
- Reference screenshots will be automatically captured from live YouTube weekly and stored for comparison testing, with historical versions retained for rollback
- The preview tool focuses on static visual accuracy; video playback preview is out of scope
- Dark mode support follows YouTube's dark mode color scheme; users manually select theme via toggle (no system preference auto-detection)