# MUST OBEY — Mobile-first build requirements This app's PRIMARY surface is a mobile phone. Build it impeccably on mobile FIRST, then verify on tablet and desktop. Treat the rules below as non-negotiable hard constraints, not suggestions. ## Viewports to verify (every screen, every state) - 320 px, 360 px, 375 px, 390 px, 414 px, 480 px - 768 px, 834 px (iPad portrait / Pro 11) - 1024 px, 1280 px, 1440 px, 1920 px, 2560 px - Plus: 200% browser zoom, landscape orientation on every mobile width, iPhone with safe-area insets visible ## Hard layout rules - Mobile-first CSS. Default styles target mobile; `@media (min-width: ...)` for larger viewports. - Use `dvh` and `svh` instead of `vh` for full-height surfaces (iOS Safari URL-bar bug). - Use `clamp()` for fluid typography across all viewports. - Prefer container queries (`@container`) over media queries for component-level responsiveness. - Use `min(100%, ...)` widths so content never overflows. Zero horizontal overflow at any viewport. - Add `` to every page. - Apply `padding: max(safe-area-inset-X, fallback)` on every edge-bleeding container so notched iPhones in landscape never clip content. - Wide tables and code blocks scroll INSIDE their container (`overflow-x: auto`), never push the body. - Use `background-attachment: scroll` on mobile, not `fixed` (iOS Safari repaint bug). - Avoid `backdrop-filter` on animated elements. Use it sparingly on static surfaces only. - **Canvas Scaling**: Canvases must dynamically scale with window resize events and properly handle high-DPI screens (`window.devicePixelRatio`). Set physical dimensions (`canvas.width`/`canvas.height`) using pixel ratio and render relative to this grid, using CSS to control responsive viewport scaling. - **Robust Storage**: Every access to `localStorage`/`sessionStorage` (especially `JSON.parse` of loaded state or writes) MUST be wrapped in a `try-catch` block to handle disabled storage, private browsing mode, quota limits, or corrupted JSON gracefully. Fall back to a robust in-memory object store. ## Touch & accessibility - Tap targets ≥ 44 × 44 px on touch (Apple HIG). Increase to 48 px under `@media (hover: none) and (pointer: coarse)`. - All interactive controls reachable by keyboard with a visible focus ring; respect `:focus-visible`. - Color contrast ≥ 4.5:1 for body text, 3:1 for UI components. - All images have meaningful `alt`. Decorative images use `alt=""`. - Respect `prefers-reduced-motion: reduce` — zero animation durations under that query. - Forms validate inline; error messages are specific, not "Invalid input". - Modals: focus trap, `Esc` closes, `role="dialog"`, `aria-modal="true"`, focus restored on close. ## Performance bar (Lighthouse mobile, throttled 3G/4G) - LCP < 2.5 s · INP < 200 ms · CLS < 0.1 - JS bundle gzip < 200 KB mobile-first; lazy-load non-critical screens via `React.lazy` / dynamic imports. - No render-blocking resources above the fold. - Images: WebP/AVIF preferred, `loading="lazy"`, explicit `width`/`height` attributes (zero CLS), `srcset` for retina. - Videos: `preload="metadata"`, low-resolution poster, max 720p mobile fallback. Never autoplay with audio. - Fonts: `font-display: swap`; preload only the one used above the fold. - Smooth scroll honoured via CSS `scroll-behavior: smooth` with reduced-motion fallback. ## Pre-ship mobile checklist (the deployer MUST verify before declaring done) 1. Open at 375 px in DevTools — every screen scrolls vertically only; zero horizontal scroll. 2. Browser zoom 200% — layout reflows without overlap. 3. iPhone Safari with the URL bar visible AND landscape — no content under the home indicator; no notch clipping. 4. iPad portrait (768 px) and landscape (1024 px) — no awkward gaps; tablet-specific breakpoints land cleanly. 5. Tap every interactive element with a thumb at real-device size — every target is easy to hit. 6. `prefers-reduced-motion: reduce` — every transition / animation skips cleanly, scroll-behavior becomes instant. 7. Lighthouse mobile score ≥ 90 across all 4 categories. 8. Zero `console.error` and zero CLS shift in real-device testing on a mid-tier Android (e.g. Pixel 6a) and an iPhone SE. --- The original template starts below. All rules above apply on TOP of whatever this template specifies. --- # Build Prompt — Vinyl Record Store Paste this into Google AI Studio's **Build** function. It is self-contained — every section below is part of the instructions. _Source reference: https://lovable.dev/templates/websites/ecommerce/wax-vinyl-record-store-template_ --- ## 1. Project Build a **Ecommerce** named **Vinyl Record Store**. One-line description: _Brutalist vinyl store with animations_ **What it is:** Wax — Vinyl Record Store Template This template gives you a vinyl record store that looks like it belongs in a design magazine—and you don't need design skills or coding knowledge to make it work. The brutalist monochrome aesthetic, interactive vinyl animations, and tight product grid create a shopping experience that feels intentional and premium. The technical parts are already handled. Product grid layouts, cart functionality, quantity controls, and Stripe-powered checkout—all done. You can focus on curating your catalog and getting records into the hands of customers. Four views come ready to go: a homepage with a mosaic product grid, individual product detail pages with large vinyl visuals and tracklists, a slide-in cart drawer with live subtotals, and a checkout success confirmation page. The signature feature is a vinyl disc animation—hover over any record and the disc slides out of the sleeve and rotates, in black, white, or silver variants. Instead of paying monthly fees for a generic storefront that looks like every other online shop, you get a distinctive record store with real payment processing, a memorable visual identity, and full control over every detail—no recurring platform costs eating into your margins. This Template Typical Paid Tools Cost Free to start $30–100/month Setup time Hours Days to weeks Customization Full control Limited to plan tier Lock-in None—export anytime Subscription required ## 2. Target audience - Record store owners who need an online presence that matches their in-store vibe—not a cookie-cutter shop that looks like everyone else's - Independent music sellers tired of marketplace fees eating their profits—this gives you a storefront you own completely - Vinyl collectors turning their hobby into a side business—get a professional shop running without hiring a developer - Music-focused agencies building client storefronts—the brutalist design and interactive details win pitches other templates can't - Solopreneurs launching a curated record label—the premium aesthetic justifies premium pricing from day one - Small batch pressing companies who need to sell direct—Stripe checkout means real transactions, not just a catalog ## 3. Core value propositions Surface these clearly through copy, visual emphasis, and section ordering — they are the reasons users pick this product. - **Real Stripe-Powered Checkout** — Accept real payments from day one with built-in checkout—no payment infrastructure to build. - **Signature Vinyl Disc Animation** — Interactive hover effects slide and rotate discs from sleeves, creating memorable browsing experiences. - **Brutalist Premium Aesthetic** — Monochrome palette and monospace typography create a distinctive look that justifies premium pricing. - **Complete Store in Hours** — Homepage, product pages, cart drawer, and checkout confirmation ready to customize immediately. - **No Recurring Platform Fees** — Own your storefront completely—no monthly subscriptions eating into your record sale margins. ## 4. Features to build **Product features:** Production-ready features built with modern tech stack for exceptional performance and user experience - Mosaic Product Grid - Slide-In Cart Drawer - Product Detail Pages - Three Disc Color Variants - Monospace Typography System - Exclusive Product Flags - Checkout Success Page - Digital Product Support - Interactive Album Covers - Quantity Management - Fixed Navigation Header - Supabase Integration Ready ## 4b. Required services & integrations List the back-end services this template needs to function. If a service is not needed, say so explicitly — silence is ambiguous. - **Auth — Required.** Customer accounts for order history + wishlist; guest checkout also supported. Admin auth separate. - **Database — Required.** Products, variants, inventory, orders, customers, addresses. - **Image CDN — Required.** Product photos at multiple sizes, optimised via Cloudinary/Imgix. - **Payments — Required.** Stripe (cards + Apple Pay + Google Pay + Klarna where appropriate). Tax via Stripe Tax. Address validation. - **Transactional email — Required.** Order confirmation, shipping notification, delivery confirmation, abandoned cart. - **External APIs / third-party services:** - Shipping (EasyPost / ShipStation) - Inventory (or self-host) - Analytics - Reviews (Yotpo/Trustpilot if added) **Environment variables to expose in the build:** mark every secret (API key, DB URL, JWT secret, Stripe key, S3 credential) as a clearly named `.env` variable — never hard-code. Include a `.env.example` with the full list. **Auth + data privacy reminders:** never log secrets · never store passwords in plain text · use HTTPS everywhere · hash + salt with bcrypt or argon2 · refresh tokens with rotation · honor a 'delete my account' request inside the UI. ## 5. Use cases & content to include Build dedicated UI sections or pages for each of these — they tell you what content the page must support. - **Independent Vinyl Shops** — Bring your physical record store online with a digital storefront that feels as curated as your shelves. The tight mosaic product grid mimics the experience of flipping through crates—dense, visual, and browsable. With Stripe checkout built in, you can take real payments from day one and start generating online revenue alongside your in-store sales. - **Limited Edition Drops** — Launch exclusive pressings and special releases with a store that creates urgency through design. The minimalist layout keeps all attention on the records themselves, and the product detail pages show specs, tracklists, and pricing clearly. The exclusive flag on products lets you highlight limited runs—driving faster purchase decisions. - **Curated Music Marketplaces** — Build a boutique marketplace for hand-picked vinyl selections across genres. The product grid scales from a small catalog to a larger collection while maintaining the clean mosaic aesthetic. Each record gets its own detail page with the interactive vinyl animation—black, white, or silver disc variants that make browsing feel like handling physical records. - Label Direct-to-Fan Sales - Sell your label's catalog directly to fans without giving up a cut to distributors. The monospace typography and monochrome design create a brand-forward identity that reinforces your label's aesthetic. The cart drawer with quantity controls and live subtotals makes multi-record purchases smooth—encouraging larger orders. - See yourself in one of these? Remix this template and start building. - What You Can Build - This template gives you the foundation for: - A vinyl record storefront with interactive disc animations, Stripe checkout, and a cart system that handles real transactions—not just a product gallery - A music store homepage where the brutalist design and tight grid layout create the kind of visual impact that moves product fast - A music label's direct sales channel with product detail pages featuring tracklists, specs, and quantity selectors—everything fans need to buy confidently ## 6. Recommended page structure Generate the following sections in this order. Adjust labels to fit the brand voice, but keep the structural intent. 1. Hero with a single hero product / collection. 2. Curated collection grids. 3. Product detail page with gallery, variant picker, price, add-to-cart. 4. Mini cart drawer. 5. Checkout (single page, 3 steps). 6. About / story page. 7. Footer with policies. ## 6b. First-visit onboarding Show a **first-visit onboarding** the first time a visitor lands on the site (detect via `localStorage` flag; do not show on return visits). Keep it short — three steps maximum — and respectful: visitors can dismiss at any time and revisit later from a `?` icon in the header. **Format:** a polished modal *or* a 3-step inline tour, designed to match the overall visual style of the template (don't bolt on a generic stepper UI). On mobile, full-screen sheet that slides up. **Required content — three slides:** 1. **What this is.** - One-line headline: "Welcome to *Vinyl Record Store* — a template for Brutalist vinyl store with animations." - One paragraph (max 60 words) explaining what the template demonstrates, who it's for, and what you'd typically use it for. - Visual: a small annotated screenshot of the page they're about to see, OR a 4-frame storyboard of key sections. 2. **What to try.** - 2–3 specific things the visitor should look at to understand the design (e.g. "Open a section to see the booking flow", "Hover the gallery for captions", "Resize the window — every layout is fluid"). - Reference real elements on the actual page so the visitor learns by doing, not by reading. 3. **How to remix this.** - A direct CTA: "Use this template" → links to Lovable / AI Studio Build remix entry point. - Below: 3 short bullets on how to make it yours — e.g. • "Swap the copy in `data/content.{ts,json}` for your own." • "Replace the imagery in `/public/images/` (we use AVIF + WebP)." • "Connect your services using the env-var list in section 4b above." - Plus a quieter secondary action: "Just looking — close" (closes modal, remembers preference in localStorage, never auto-shows again). **Persistent re-entry point:** A small "?" icon in the top-right header next to the primary nav. Click → reopens the onboarding from slide 1. Tooltip: "How this template works". **Accessibility:** - Trap focus inside the modal while open - `Esc` closes - All controls reachable by keyboard, visible focus ring - Heading hierarchy: modal title is `h1` inside the dialog - `role="dialog"` + `aria-modal="true"` + `aria-labelledby` - Restore focus to the trigger (or to `
`) on close - Respect `prefers-reduced-motion` — fade in/out only, no large transforms **Copy tone:** Warm and direct, not corporate. Avoid "Welcome to your dashboard" language. Avoid all caps. Use the same voice as the rest of the template's copy. **Don't:** - Don't gate content behind the modal. The page below must be fully scrollable. - Don't show the modal again on return visits. Use `localStorage['onboarding-seen']`. - Don't include marketing CTAs unrelated to remixing (no newsletter signup, no "follow us on X" — those live elsewhere). ## 7. Design language - **Mood:** Product-forward, tactile, retail-grade. - **Typography:** A confident display + clean body sans. Use a clear modular scale (e.g. 12 / 14 / 16 / 20 / 24 / 32 / 48 / 64 px) and tight tracking on display sizes. - **Palette:** Brand-color-led; high-contrast product cards. - **Spacing:** consistent 4-px base. Generous whitespace — let the content breathe. - **Radius:** consistent token set (e.g. 6 / 12 / 20 px). Don't mix arbitrary values. - **Shadows:** subtle, layered. Avoid heavy drop-shadows. - **Imagery:** Realistic product photography. Multiple angles. Lifestyle shots. - **Motion:** purposeful — entrance fades, hover lifts, page transitions. Respect `prefers-reduced-motion`. No bouncing splash animations. ## 8. Content generation rules - Write **realistic, specific copy**. NO Lorem Ipsum. NO generic placeholders like 'Your tagline here'. - Invent plausible names, dates, locations, prices, quotes, testimonials and product details that fit the domain. - Tone should match the audience above — confident, specific, free of buzzwords. - Headlines: punchy and concrete. No 'Empower your business' filler. - Body copy: short paragraphs (2–4 sentences). Use lists where appropriate. - All numbers, stats, and metrics must look plausible for the domain. ## 8a. Seed content (use these specific examples) Anchor the generated copy in the concrete data below. Use these names, numbers, dates, and snippets verbatim where helpful, or generate close variants that sit in the same world. **Store identity:** Spindle Records · Brooklyn · vinyl, vintage gear, books · since 2018 **Hero release (this week's pick):** "Kiasmos — *II* (2025, gatefold 2LP, 180g) — $42 · in stock" **Featured collection grid (8 LPs):** 1. **Caroline Polachek — Desire I Want to Turn Into You** · 2023 · 1LP · $28 · 4 in stock 2. **Floating Points — Crush** · 2019 · 1LP · $26 · 2 in stock 3. **FKA twigs — Magdalene (deluxe)** · 2019 · 1LP cream · $44 · last copy 4. **Aphex Twin — Selected Ambient Works Vol II (4LP reissue)** · 2024 · 180g · $84 5. **The Soft Pink Truth — Was It Ever Real?** · 2024 · 1LP · $24 6. **Tim Bernardes — Mil Coisas Invisíveis** · 2022 · 1LP · $28 7. **Hania Rani — On Giacometti** · 2024 · 1LP · $30 8. **The Smile — Wall of Eyes** · 2024 · 1LP yellow · $34 **Categories:** New arrivals · Pre-orders · Used (graded) · Soundtracks · Jazz · Electronic · Indie · Hip-hop · World · 7" singles · Equipment · Books · Gift cards **Used vinyl grading shown on cards:** "M / NM / VG+ / VG / G+ / G" **Free shipping:** "Free US shipping on orders over $75 · international from $24" **Subscription:** "Spindle Club — $42/mo, hand-picked LP each month, member discount 10% on shop" **Store info:** "142 Wythe Ave, Brooklyn NY · Tue-Sun 11-20 · listening bar Thu-Sat evenings" ## 9. Media & assets Every ``, `background-image`, gallery tile, thumbnail, and decorative figure on the page must come from ONE of the three buckets below. Do NOT reference any image path that is not specified here. Do NOT ship stock-photo placeholders. ### Bucket 1 — Runtime-generated via Nano Banana Pro (`gemini-3-pro-image`) Generate at build time, cache to Firebase Storage at the path listed, serve via signed URL. Each call uses model `gemini-3-pro-image`, output format `image/webp`, dimensions as listed. The visual register matches section 7 (Design language) and the specific seed content in section 8a. - **Hero image** → `/public/generated/hero.webp` · 2400×1500 · prompt: "Editorial hero shot of the hero product or collection named in section 8a, in the visual register of section 7. Single subject, generous negative space, palette consistent with the brand. Real-photo aesthetic, 35mm or medium-format look. No on-image text, no logos overlaid." - **Product images (4-6 angles per product in section 8a's catalogue)** → `/public/generated/products/{product-slug}/p-01.webp … p-06.webp` · 1500×1875 · prompt: "Per-product prompt template: white-seamless or styled-context studio shot of the product named in section 8a, angle index {01 = front · 02 = three-quarter · 03 = back · 04 = detail · 05 = lifestyle in-use · 06 = scale-with-hand}. No on-image text. One full set per product." - **Collection-page banner (one per collection in section 8a)** → `/public/generated/collections/{collection-slug}.webp` · 2400×900 · prompt: "Wide editorial banner for the collection, evoking its season/material/mood from section 8a. No on-image text." - **Lookbook / lifestyle tiles (8 images)** → `/public/generated/lookbook/l-01.webp … l-08.webp` · 1600×2000 · prompt: "Per-tile editorial lifestyle photograph showing the product in its real context (e.g. a leather tote on a café table, a ceramic mug on a windowsill at dawn). No on-image text." - **Brand story / about images (3 tiles)** → `/public/generated/about/a-01.webp … a-03.webp` · 1600×1200 · prompt: "Documentary photographs of the studio / workshop / maker named in section 8a — bench, materials, hands at work. No on-image text." - **Wordmark / monogram** → `/public/generated/wordmark.svg` · prompt: "A simple brand wordmark for the store named in section 8a, set in the display font of section 7, suitable for both shopfront header and order-confirmation email." Favicon export to `/public/generated/favicon-256.webp` (256×256). ### Bucket 2 — Seed assets shipped with the deliverable Static files committed to `/public/samples/` as fallbacks when generation fails. Generated once via Nano Banana 2 (`gemini-3.1-flash-image`), 1024×1024 WebP unless noted. - `/public/samples/empty-state-cart.webp` — 1024×1024 — prompt: "Minimal hand-drawn line illustration of an empty shopping bag with handles slack, single-stroke outline, no colour fill." - `/public/samples/empty-state-wishlist.webp` — 1024×1024 — prompt: "Minimal hand-drawn line illustration of a single empty bookmark, single-stroke outline, no colour fill." - `/public/samples/empty-state-search.webp` — 1024×1024 — prompt: "Minimal hand-drawn line illustration of a magnifying glass over a folded receipt, single-stroke outline, no colour fill." - `/public/samples/hero-fallback.webp` — 1600×1000 — same prompt as the Bucket-1 hero, encoded once at build and committed so the page renders identically if Gemini quota is exhausted. ### Bucket 3 — User-supplied (when the template is remixed) Onboarding modal surfaces a "Replace with your photos" hint. Uploads land via the file input → Firebase Storage path `stores/{storeSlug}/products/{productSlug}/uploads/`. The build ships with Bucket-1 + Bucket-2 only; no user-supplied images at first paint. ### Hard rules - Every `` tag MUST have a `src` that resolves to a path listed above. Any `` referencing a path not in this section is a build error. - No bare `image.jpg` / `hero.jpg` / `placeholder.png` references anywhere in the code. - Icons: `lucide-react` only; use sparingly and consistently — never decorative-only. - Optimisation: WebP or AVIF, `loading="lazy"` on everything below the fold, explicit `width`/`height` to prevent layout shift. ## 10. Interactivity & states - Every interactive element has a hover, focus, active, and disabled state. - Forms validate inline and show specific error messages. - Loading states (skeletons, not spinners where possible). - Empty states with helpful next-action guidance. - Smooth scroll for in-page anchors. ## 11. Tech & responsive requirements - **Stack:** React + TypeScript + Tailwind CSS. Use functional components and hooks. - **Mobile-first.** Verify layouts at 375 px (iPhone SE), 768 px (iPad), 1024 px, 1440 px+. - Use `clamp()` for fluid typography where appropriate. - Prefer container queries over media queries for component-level responsiveness. - Use `dvh` / `svh` units instead of `vh` to handle mobile viewport chrome. - Zero horizontal overflow at any width. Zero layout shift on load. - Respect safe-area insets on iOS. ## 12. Accessibility (WCAG 2.2 AA) - Semantic HTML — `header`, `nav`, `main`, `section`, `article`, `footer`. - All interactive controls reachable by keyboard with a visible focus ring. - Color contrast ≥ 4.5:1 for body, 3:1 for large text and UI components. - All images have meaningful `alt` text. Decorative images use `alt=""`. - Form fields have associated `