System Requirements Document for birthday-friendship

1. Introduction

THE MIDNIGHT BIRTHDAY EXPERIENCE is a premium, cinematic, interactive birthday surprise website built by Lakshana for her best friend. It is a single private gift: a mysterious, luxurious, emotional and entertaining digital celebration prepared exclusively for one special friend. The experience combines friendship memories, funny moments, heartfelt messages, unexpected surprises and magical animations into one continuous midnight-black-and-champagne-gold journey.

The product intent is emotional, not transactional. The visitor should move through three feelings in sequence: laugh at the funny memories, feel special because of the friendship messages, and be surprised by unexpected interactive reveals. The site must read as a luxury midnight celebration — a secret cultural artefact — and never as a childish birthday greeting page or a generic birthday template.

The audience is exactly two people: the Birthday Friend (Visitor), who receives and experiences the surprise, and the Creator, the best friend who prepares it by editing all images, messages and the letter text before the visit.

Success Criteria

• The visitor can enter the surprise, move through all eight sections, and reach the final message and replay without any broken button.
• Every image, message and the letter text can be replaced by the Creator without touching code.
• Music never autoplays before interaction and is fully user-controlled.
• The experience is responsive and readable on all devices, with smooth animations that do not degrade performance.
• The visual identity stays strictly midnight black and champagne gold across eight visually distinct sections.

2. System Overview

2a. Product Interpretation and Delivery Boundary

The experience is a first-party React web application delivered as a complete working website, not a static design or landing page. It is a single continuous experience composed of eight sections, each with its own composition but sharing one strict black-and-gold identity.

The Birthday Friend (Visitor) accesses the experience without an account: the secret entrance is a public, anonymous entry surface, and every visitor-facing section is reachable without identity establishment. The Creator prepares the experience through a first-party Creator Studio surface where all images, messages and the letter text are edited; the edited content is what the visitor later experiences. No differentiated permissions, role-based visibility or account management are introduced — the source establishes no such controls.

Audio is user-controlled: no sound plays before the visitor interacts, and the music toggle governs playback thereafter. The subtle celebration sound on entry and the celebration sound on the cake wish are triggered by explicit visitor interaction.

The provisioned infrastructure is a shared FastAPI backend for application APIs and domain modules, a MariaDB database for application-owned persistent data, and a React frontend. The backend and database support the Creator's editable content and the visitor's experience; they do not add product capabilities, authentication or domain entities beyond what the accepted workflows require.

Removed from scope: none. No concept from the authoritative requirement thread was removed or superseded.

2b. Source Content Inventory

Not applicable — no reference directive declares content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Completely black opening screen with tiny animated golden stars. Two lines: "Some people make life beautiful..." and "Tonight, this little world is only for YOU." A mysterious golden button labeled "ENTER YOUR SURPRISE". A small champagne-gold constellation diagram above the centre. A music toggle control (off by default; no autoplay).
• Primary action: Activate "ENTER YOUR SURPRISE" — triggers a cinematic transition, plays a subtle celebration sound, and reveals the main birthday experience.
• Supporting actions: Toggle music on/off (user-controlled; never autoplays before interaction).
• Domain entities: Entrance copy, star field, constellation diagram, music state.
• Component responsibilities: Star field renderer (HTML5 Canvas or CSS), constellation diagram, entrance headline block, entrance button with gold line-sweep state, music toggle.
• States: Loading — star field initializes; Empty — not applicable (entrance always has content); Success — transition plays and main experience reveals; Error/recovery — if the celebration sound cannot play, the transition and reveal still complete silently; the visitor can retry the button.

Birthday Reveal

• Information/state: Large animated heading "HAPPY BIRTHDAY, [FRIEND'S NAME]!" with glowing typography; subtitle "Another year older, another year more iconic!"; golden confetti; floating golden particles; animated birthday cake.
• Primary action: Observe the grand reveal (no required input).
• Supporting actions: Music toggle; continue scrolling to the next section.
• Domain entities: Friend's name (editable), heading, subtitle, confetti, particles, animated cake.
• Component responsibilities: Animated heading with glow, confetti layer, floating particle layer, animated cake illustration, subtitle block.
• States: Loading — reveal animation composes; Empty — not applicable; Success — heading, confetti, particles and cake animate in; Error/recovery — if particle rendering is unavailable, the heading, subtitle and cake still display; reduced-motion shows a static composed frame.

Friendship Story

• Information/state: Interactive timeline titled "From Random Moments to Unforgettable Memories" with customizable memory cards for: how we met, our funniest moments, our unforgettable memories, our craziest adventures, and moments that made our friendship special. Placeholder photos that can be replaced with personal photographs.
• Primary action: Explore the timeline and reveal memory cards.
• Supporting actions: Hover over cards for elegant hover effects; animated photo reveals; music toggle.
• Domain entities: Memory cards (title, description, photo), timeline order, placeholder photos.
• Component responsibilities: Timeline rail, memory card, photo frame with animated reveal, hover treatment.
• States: Loading — photos load with placeholder frames; Empty — a card without a replaced photo shows its placeholder; Success — cards and photos reveal on hover/scroll; Error/recovery — a failed photo load falls back to the placeholder frame and the card text remains readable.

Funny Side

• Information/state: Section titled "Things Only WE Understand\x20\xf0\x9f\x98\x82" with interactive cards for our funniest conversations, our inside jokes, most embarrassing memories, and unforgettable silly moments. A button labeled "REVEAL A RANDOM MEMORY".
• Primary action: Activate "REVEAL A RANDOM MEMORY" — reveals a different funny memory on every click with playful animations.
• Supporting actions: Interact with the funny cards; music toggle.
• Domain entities: Funny memory entries (conversations, inside jokes, embarrassing memories, silly moments), current revealed memory.
• Component responsibilities: Funny card grid, random-memory reveal panel, reveal button with playful animation.
• States: Loading — cards compose; Empty — if no funny memories are configured, the reveal button is disabled with a readable note; Success — a different memory appears on each click; Error/recovery — repeated clicks cycle through available memories without repeating the immediately previous one where more than one exists.

Letter

• Information/state: Luxurious black envelope with a golden wax seal; the line "A little something from my heart..."; button "OPEN YOUR LETTER".
• Primary action: Activate "OPEN YOUR LETTER" — animates the envelope opening, reveals the personalized heartfelt birthday letter, and displays it with a typing animation.
• Supporting actions: Music toggle; continue to the next section after the letter completes.
• Domain entities: Envelope, wax seal, letter text (editable).
• Component responsibilities: Envelope with square gold seal, seal-break animation, letter panel, typing animation renderer.
• States: Loading — envelope composes; Empty — if the letter text is not yet set, the envelope still opens and shows a readable placeholder; Success — seal breaks, envelope opens, letter types out in ivory; Error/recovery — the visitor can re-open or skip the typing animation to read the full letter; reduced-motion shows the full letter without typing.

Mystery Box

• Information/state: Three mysterious glowing golden gift boxes, each revealing something different: (1) a sweet friendship message, (2) a funny surprise, (3) a special birthday wish.
• Primary action: Click each gift box — it opens with a beautiful animation and reveals its content.
• Supporting actions: Music toggle; open the remaining boxes.
• Domain entities: Three gift boxes, each with its own content (friendship message, funny surprise, birthday wish).
• Component responsibilities: Gift box with glow, box-open animation, revealed content panel.
• States: Loading — boxes compose; Empty — an unopened box shows only its closed state; Success — each box opens and reveals its distinct content; Error/recovery — a box can be re-closed and reopened; each box's content is independent.

Cake Wish

• Information/state: A beautiful 3D-style golden birthday cake with interactive candles; a button labeled "MAKE A WISH\x20\xe2\x9c\xa8".
• Primary action: Activate "MAKE A WISH\x20\xe2\x9c\xa8" — triggers candle animation, a golden particle burst, a celebration sound, and a birthday message reveal.
• Supporting actions: Interact with the candles; music toggle.
• Domain entities: Cake, candles, wish message.
• Component responsibilities: 3D-style golden cake, interactive candles, wish button, particle burst layer, message reveal panel.
• States: Loading — cake composes; Empty — not applicable; Success — candles animate, particles burst, sound plays, message reveals; Error/recovery — if sound cannot play, the candle animation, particle burst and message still complete; the visitor can make the wish again.

Final Surprise

• Information/state: Cinematic black background with slowly appearing golden stars. The final message: "Life gives us many people, but only a few become unforgettable memories. Thank you for being one of those people. No matter where life takes us, I hope you always keep smiling, chasing your dreams, and making beautiful memories. HAPPY BIRTHDAY, [FRIEND'S NAME]!" Ending with "Forever grateful for this friendship.\x20\xe2\x9d\xa4️" and the final golden text animation "MADE WITH LOVE, JUST FOR YOU."
• Primary action: Read the final message as stars appear.
• Supporting actions: Replay the surprise; music toggle.
• Domain entities: Final message lines, star field, closing animation, replay control.
• Component responsibilities: Slowly appearing star field, final message block, closing gold text animation, replay control.
• States: Loading — stars begin to appear; Empty — not applicable; Success — stars appear one by one, message reads, closing line animates in gold; Error/recovery — replay returns the visitor to the entrance and resets the experience; reduced-motion shows the full message with a static star field.

Creator Studio

• Information/state: A first-party editing surface where the Creator replaces all images, edits all messages, and edits the letter text before the friend visits.
• Primary action: Edit and save content fields (friend's name, entrance copy, reveal subtitle, memory cards and photos, funny memories, letter text, gift box contents, wish message, final message).
• Supporting actions: Replace placeholder photos with personal photographs; preview saved content.
• Domain entities: Content fields per section, photo references, letter text.
• Component responsibilities: Field editors grouped by section, photo replacement control, save action, saved-state indicator.
• States: Loading — current content loads; Empty — fields without saved values show their defaults; Success — saved content is what the visitor experiences; Error/recovery — a failed save keeps the previous content and shows a readable error with retry.

3. Functional Requirements

FR-1 — Secret entrance. As the Birthday Friend (Visitor), I should see a completely black opening screen with tiny animated golden stars showing "Some people make life beautiful..." and "Tonight, this little world is only for YOU.", so that the experience begins as a mysterious secret. (explicit)

• Trigger: the visitor opens the site.
• Observable result: the black entrance with animated golden stars and both lines is displayed.
• Access: public, no identity.
• Failure/recovery: if the star animation cannot run, the lines and button still display.
• Continuation: the visitor can activate "ENTER YOUR SURPRISE".

FR-2 — Enter the surprise. As the Birthday Friend (Visitor), I should activate the golden "ENTER YOUR SURPRISE" button to trigger a cinematic transition, play a subtle celebration sound, and reveal the main birthday experience. (explicit)

• Trigger: the visitor activates the button.
• Observable result: cinematic transition plays, subtle celebration sound plays, main experience reveals.
• Access: public, no identity.
• Failure/recovery: if the sound cannot play, the transition and reveal still complete.
• Continuation: the visitor arrives at the Birthday Reveal.

FR-3 — Grand birthday reveal. As the Birthday Friend (Visitor), I should see the large animated heading "HAPPY BIRTHDAY, [FRIEND'S NAME]!" with golden confetti, floating golden particles, an animated birthday cake and glowing typography, so that the birthday is celebrated grandly. (explicit)

• Trigger: arrival at the Birthday Reveal.
• Observable result: animated heading, confetti, particles, cake and glow are displayed.
• Failure/recovery: if particles cannot render, heading, subtitle and cake still display.
• Continuation: the visitor scrolls to the Friendship Story.

FR-4 — Reveal subtitle. As the Birthday Friend (Visitor), I should see the subtitle "Another year older, another year more iconic!" beneath the heading. (explicit)

FR-5 — Friendship timeline. As the Birthday Friend (Visitor), I should explore an interactive timeline titled "From Random Moments to Unforgettable Memories" with customizable memory cards for how we met, our funniest moments, our unforgettable memories, our craziest adventures, and moments that made our friendship special. (explicit)

• Trigger: the visitor scrolls to and interacts with the timeline.
• Observable result: memory cards are displayed in timeline order.
• Failure/recovery: a failed photo load falls back to the placeholder frame.
• Continuation: the visitor moves to the Funny Side.

FR-6 — Placeholder photos and hover reveals. As the Birthday Friend (Visitor), I should see placeholder photos that can be replaced with personal photographs, with elegant hover effects and animated photo reveals. (explicit)

• Trigger: the visitor hovers over a memory card.
• Observable result: elegant hover effect and animated photo reveal.
• Failure/recovery: unreplaced photos show their placeholder.

FR-7 — Funny side cards. As the Birthday Friend (Visitor), I should see a section titled "Things Only WE Understand\x20\xf0\x9f\x98\x82" with interactive cards for our funniest conversations, our inside jokes, most embarrassing memories, and unforgettable silly moments. (explicit)

FR-8 — Reveal a random memory. As the Birthday Friend (Visitor), I should activate "REVEAL A RANDOM MEMORY" and see a different funny memory on every click with playful animations. (explicit)

• Trigger: each activation of the button.
• Observable result: a different funny memory is revealed with a playful animation.
• Failure/recovery: with more than one memory configured, consecutive clicks do not repeat the immediately previous memory; with none configured, the button is disabled with a readable note.
• Continuation: the visitor moves to the Letter.

FR-9 — Envelope and letter. As the Birthday Friend (Visitor), I should see a luxurious black envelope with a golden wax seal showing "A little something from my heart..." and an "OPEN YOUR LETTER" button. (explicit)

FR-10 — Open the letter. As the Birthday Friend (Visitor), I should activate "OPEN YOUR LETTER" to animate the envelope opening, reveal a personalized heartfelt birthday letter, and display it with a beautiful typing animation. (explicit)

• Trigger: the visitor activates the button.
• Observable result: envelope opens, letter reveals, text types out.
• Failure/recovery: the visitor can skip the typing animation to read the full letter; reduced-motion shows the full letter.
• Continuation: the visitor moves to the Mystery Box.

FR-11 — Editable letter text. As the Creator, I should be able to edit the letter text so that the letter is personalized. (explicit)

FR-12 — Mystery boxes. As the Birthday Friend (Visitor), I should see three mysterious glowing golden gift boxes, each revealing something different — a sweet friendship message, a funny surprise, and a special birthday wish — and each opening with a beautiful animation when clicked. (explicit)

• Trigger: the visitor clicks a gift box.
• Observable result: that box opens with an animation and reveals its distinct content.
• Failure/recovery: a box can be re-closed and reopened; each box is independent.
• Continuation: the visitor moves to the Cake Wish.

FR-13 — Cake and candles. As the Birthday Friend (Visitor), I should see a beautiful 3D-style golden birthday cake with interactive candles. (explicit)

FR-14 — Make a wish. As the Birthday Friend (Visitor), I should activate "MAKE A WISH\x20\xe2\x9c\xa8" to trigger a candle animation, a golden particle burst, a celebration sound, and a birthday message reveal. (explicit)

• Trigger: the visitor activates the button.
• Observable result: candles animate, particles burst, sound plays, message reveals.
• Failure/recovery: if sound cannot play, the animation, burst and message still complete; the visitor can make the wish again.
• Continuation: the visitor moves to the Final Surprise.

FR-15 — Final emotional surprise. As the Birthday Friend (Visitor), I should see a cinematic black background with slowly appearing golden stars and the final message ending with "Forever grateful for this friendship.\x20\xe2\x9d\xa4️", followed by the golden text animation "MADE WITH LOVE, JUST FOR YOU." (explicit)

• Trigger: arrival at the Final Surprise.
• Observable result: stars appear slowly, the message reads, the closing line animates in gold.
• Failure/recovery: reduced-motion shows the full message with a static star field.
• Continuation: the visitor can replay the surprise.

FR-16 — Every button works. As the Birthday Friend (Visitor), I should find that every button in the experience performs its stated action. (explicit)

FR-17 — Editable images and messages. As the Creator, I should be able to edit all images and messages so that the experience is personalized for my best friend. (explicit)

• Trigger: the Creator edits content in the Creator Studio.
• Observable result: saved content is what the visitor experiences.
• Failure/recovery: a failed save keeps the previous content and shows a readable error with retry.

FR-18 — Music toggle. As the Birthday Friend (Visitor), I should control music playback with a toggle, and music must not autoplay before interaction. (explicit)

• Trigger: the visitor toggles music.
• Observable result: music plays or stops according to the toggle; no music plays before interaction.
• Failure/recovery: if audio cannot play, the toggle reflects the state and the experience continues.

FR-19 — Replay surprise. As the Birthday Friend (Visitor), I should have a replay surprise option so that I can experience the celebration again. (explicit)

• Trigger: the visitor activates replay.
• Observable result: the experience returns to the entrance and resets.
• Continuation: the visitor can re-enter the surprise.

FR-20 — Responsive layouts. As the Birthday Friend (Visitor), I should experience responsive layouts on all devices. (explicit)

FR-21 — Smooth, performant animations. As the Birthday Friend (Visitor), I should experience smooth animations that do not affect performance. (explicit)

FR-22 — Accessibility and readable text. As the Birthday Friend (Visitor), I should have accessibility support and readable text throughout. (explicit)

FR-23 — No generic templates. As the Creator, I should have an experience that does not use generic birthday templates, so that it feels like a luxury midnight celebration. (explicit)

FR-24 — Distinct sections, one identity. As the Birthday Friend (Visitor), I should find every section visually different while maintaining the same midnight black and champagne gold identity. (explicit)

FR-25 — Creator prepares content. As the Creator, I should replace the placeholder images and messages before the visit so that the experience is ready for my best friend. (required_inference)

• Trigger: the Creator opens the Creator Studio before the visit.
• Observable result: replaced images and messages are what the visitor experiences.
• Failure/recovery: unsaved edits do not affect the visitor's experience.

4. User Personas

Birthday Friend (Visitor)

The Birthday Friend is the single special friend for whom the entire experience is prepared. She arrives at a completely black screen with tiny animated golden stars and two lines that address her directly — "Some people make life beautiful..." and "Tonight, this little world is only for YOU." Her primary goal is to receive and feel the surprise: to laugh at the funny memories, feel special because of the friendship messages, and be surprised by unexpected interactive reveals.

Her distinct responsibilities are experiential and interactive: she activates "ENTER YOUR SURPRISE" to begin; she explores the friendship timeline and hovers over memory cards; she presses "REVEAL A RANDOM MEMORY" repeatedly to see different funny memories; she opens the black envelope with the golden wax seal and reads the typed letter; she clicks each of the three golden gift boxes; she presses "MAKE A WISH\x20\xe2\x9c\xa8" on the cake; she reads the final message as stars appear; and she may replay the surprise. She also controls music with the toggle, and music never autoplays before she interacts.

Her inputs and decisions are simple: which sections to explore, when to reveal a random memory, which gift box to open, when to make a wish, whether to enable music, and whether to replay. She interacts with the Creator only indirectly — the Creator has prepared the content she experiences. Her observable success is a complete, unbroken journey through all eight sections in which every button works, the text is readable, and the experience feels like a luxury midnight celebration made just for her.

Creator (Best Friend Who Prepares the Surprise)

The Creator is the best friend who builds and personalizes the experience for one special friend. Her product context is preparation: she works before the visit, replacing placeholder photos with personal photographs and editing every message and the letter text so the experience is genuinely personal. Her primary goal is that the Birthday Friend feels the three intended emotions — laughter, feeling special, and surprise — through content that is unmistakably theirs.

Her distinct responsibilities are editorial: she edits the friend's name, the entrance copy, the reveal subtitle, the memory cards and their photos, the funny memories, the letter text, the gift box contents, the wish message and the final message. She replaces placeholder images with personal photographs. She does not experience the surprise as a recipient; her success is observable when the saved content is exactly what the visitor later experiences, with no broken buttons and no generic template feel.

Her inputs and decisions are which memories to include, which photos to use, what the letter says, and what each gift box reveals. She interacts with the Birthday Friend only through the content she prepares. Her observable success is a saved, personalized experience that runs correctly for the visitor.

5. Core User Flows

Flow A — The Birthday Friend enters and experiences the surprise

1. The Birthday Friend opens the site and lands on Landing: a completely black screen with tiny animated golden stars, a small champagne-gold constellation diagram, and the lines "Some people make life beautiful..." and "Tonight, this little world is only for YOU." Music is off; nothing autoplays.
2. She activates "ENTER YOUR SURPRISE". A cinematic transition plays, a subtle celebration sound plays, and the main experience reveals.
3. She arrives at Birthday Reveal and sees "HAPPY BIRTHDAY, [FRIEND'S NAME]!" with glowing typography, golden confetti, floating golden particles, an animated birthday cake, and the subtitle "Another year older, another year more iconic!" If particles cannot render, the heading, subtitle and cake still display.
4. She scrolls to Friendship Story and explores the timeline "From Random Moments to Unforgettable Memories", hovering over memory cards to trigger elegant hover effects and animated photo reveals. Unreplaced photos show their placeholders.
5. She continues to Funny Side, sees "Things Only WE Understand\x20\xf0\x9f\x98\x82" with cards for funniest conversations, inside jokes, most embarrassing memories and silly moments, and presses "REVEAL A RANDOM MEMORY". Each click reveals a different funny memory with a playful animation.
6. She moves to Letter, sees the luxurious black envelope with a golden wax seal and "A little something from my heart...", and presses "OPEN YOUR LETTER". The envelope opens, the personalized letter reveals, and the text types out. She can skip the typing to read the full letter.
7. She moves to Mystery Box and clicks each of the three glowing golden gift boxes. Each opens with a beautiful animation and reveals its distinct content: a sweet friendship message, a funny surprise, and a special birthday wish. She can re-close and reopen any box.

8. She moves to Cake Wish, sees the 3D-style golden cake with interactive candles, and presses "MAKE A WISH\x20\xe2\x9c\xa8". The candles animate, a golden particle burst fires, a celebration sound plays, and a birthday message reveals. If sound cannot play, the animation, burst and message still complete.
9. She reaches Final Surprise: golden stars appear slowly on the cinematic black background, the final message reads through to "Forever grateful for this friendship.\x20\xe2\x9d\xa4️", and "MADE WITH LOVE, JUST FOR YOU." animates in gold.
10. She may activate replay, which returns her to the entrance and resets the experience so she can re-enter the surprise.

Flow B — The Birthday Friend controls music

1. On Landing, before any interaction, no music plays.
2. She activates the music toggle. Music begins; the toggle reflects the on state.
3. She can toggle music off and on at any point during the experience. If audio cannot play, the toggle reflects the state and the experience continues.

Flow C — The Creator prepares the surprise

1. Before the visit, the Creator opens Creator Studio and loads the current content.
2. She edits the friend's name, the entrance copy, the reveal subtitle, the memory cards and their photos, the funny memories, the letter text, the gift box contents, the wish message and the final message.
3. She replaces placeholder photos with personal photographs.
4. She saves. Saved content becomes what the visitor experiences. If a save fails, the previous content is kept and a readable error with retry is shown.
5. She previews the saved content to confirm every button works and the experience reads as a luxury midnight celebration.

6. Visuals Colors and Theme

The creative direction is Austere midnight ritual, one code of gold, after the muse Peter Saville: a single artefact and a coded colour as the whole identity, read as a luxury cultural artefact rather than a party page. Tone: secret, tender, cinematic.

Colour tokens (dark mode):

Black #080808 holds roughly 80 percent of each screen. Charcoal #151515 marks panels and envelopes. Champagne gold #D4AF37 is the only signal colour, used on thin rules, seals and one word. Ivory #FFF5E6 carries all reading text. No blue or violet appears anywhere.

Typography: Headings in Playfair Display at light weights, wide tracking on small-caps labels, tight leading on huge lines. Body copy in Poppins, set small and calm. Modular scale 1.5: display sizes 44/64/96/128; text sizes 14/16/18; letterspaced labels at 11.

Shape language: Sharp corners, hairline gold rules, square envelope and seal, thin circular star field. No soft cards, no pills.

Layout: One centred artefact per screen with wide black margins. Sparse metadata blocks in the corners. Sections run as a gallery sequence, each with its own composition.

Imagery: A gold wax seal, a thin constellation diagram, a gold line-drawn cake, and monochrome photo placeholders cropped square.

Readability: Headlines, wordmarks, labels, numbers, card text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling (for example font-size: clamp(...)) to fit. Imagery and decoration may be cropped, bled or overlapped, but never cover readable text or controls.

7. Signature Design Concept

The public entry is a full black screen with a faint gold star field. A small champagne-gold constellation diagram sits above the centre — a thin circular star field drawn as a diagram, not a glow. Beneath it, the two entrance lines are set in Playfair Display at 44px to 96px, centred, with one word in gold: "Some people make life beautiful..." and "Tonight, this little world is only for YOU." The gold ENTER YOUR SURPRISE button is a thin outlined rule beneath the lines, with a short gold line sweep on hover and focus. No image, no gradient, no glow cloud.

The signature moves carry through the experience: every section opens with a letterspaced gold label and a hairline rule spanning the column; the letter is a black envelope with a square gold seal that breaks as the text types out in ivory; the cake is a flat gold line drawing on black, and the wish button sends one thin gold particle burst; the final screen fades stars in one by one above the closing lines, then "MADE WITH LOVE, JUST FOR YOU." in gold.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: still Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: the small champagne-gold constellation diagram above the centre of a full black screen, with the two entrance lines and the thin outlined ENTER YOUR SURPRISE rule beneath.
• Input → transformation → outcome thesis: the visitor's pointer or focus on the entrance button draws a short gold line sweep across the rule; activating it plays a cinematic transition and a subtle celebration sound, and the main birthday experience reveals. The stars drift without hurry throughout.
• Motion vocabulary: slow fades, a single type reveal, stars drifting without hurry, a short gold line sweep on button state change — no bounce, no springs, no confetti storm.
• Composed first frame: black field, faint gold star field, constellation diagram centred above, two ivory Playfair lines with one word in gold, thin gold outlined button beneath.
• Reduced-motion state: the star field is static, the lines and button are fully visible, and the transition to the main experience is an instant reveal without the sweep.

9. Non-Functional Requirements

• No autoplay audio. Music must not autoplay before interaction; the music toggle governs playback. (explicit)
• No generic templates. The experience must not use generic birthday templates; it must read as a luxury midnight celebration. (explicit)
• One special friend. The experience is prepared exclusively for one special friend. (explicit)
• Performance. Animations must be smooth without affecting performance; particle effects use HTML5 Canvas where required. (explicit)
• Accessibility and readability. Accessibility support and readable text are required throughout; readable text and controls stay whole at every viewport. (explicit)
• Responsive. Layouts are responsive on all devices. (explicit)
• Reduced motion. With prefers-reduced-motion, provide a usable static arrangement: static star fields, full letter without typing, full final message. (required_inference)
• Content persistence. Creator-edited content is stored in the application-owned MariaDB database and served to the visitor. (required_inference)

10. Tech Stack

• Frontend: React.js with Tailwind CSS, Framer Motion for animation, Lucide React icons, and HTML5 Canvas for particle effects if required. (explicit)
• Backend: Shared FastAPI process for application APIs and domain modules, serving Creator Studio content and the visitor experience. (provisioned infrastructure)
• Database: MariaDB for application-owned persistent data (edited content). (provisioned infrastructure)
• Deployment: Docker/docker-compose with the frontend, backend and database services. (provisioned infrastructure)

11. Assumptions and Constraints

• The experience is for exactly one Birthday Friend; no multi-recipient or sharing capability is assumed.
• The Creator prepares content before the visit; the visitor does not edit content.
• No account, login or differentiated permissions are required for either persona; the entrance is public and anonymous.
• Placeholder photos are provided and are replaced by the Creator with personal photographs.
• The subtle celebration sound on entry and the celebration sound on the cake wish are triggered only by explicit visitor interaction.
• The MariaDB database stores Creator-edited content; it does not imply additional domain entities or authentication.

12. Glossary

• Birthday Friend (Visitor): the one special friend for whom the surprise is prepared and who experiences it.
• Creator: the best friend who prepares and personalizes the experience before the visit.
• Creator Studio: the first-party editing surface where the Creator replaces images and edits all messages and the letter text.
• Secret Entrance: the completely black opening screen with animated golden stars and the ENTER YOUR SURPRISE button.
• Grand Birthday Reveal: the section with the animated birthday heading, confetti, particles and cake.
• Friendship Story: the interactive timeline of memory cards with replaceable photos.
• Funny Side: the section "Things Only WE Understand\x20\xf0\x9f\x98\x82" with the REVEAL A RANDOM MEMORY button.
• Letter: the black envelope with a golden wax seal that opens to a typed heartfelt letter.
• Mystery Box: the three glowing golden gift boxes revealing a friendship message, a funny surprise and a birthday wish.
• Cake Wish: the 3D-style golden cake with interactive candles and the MAKE A WISH\x20\xe2\x9c\xa8 button.
• Final Surprise: the closing cinematic section with slowly appearing stars, the final message and the closing gold animation.
• Replay: the option that returns the visitor to the entrance and resets the experience.