System Requirements Document for birthday-best-friend

1. Introduction

Project Bestie Forever is a personalized, interactive birthday surprise website built as a digital gift from one best friend to another. It is not a generic birthday template and not a static mockup: it is a fully functional, animated, mobile-first journey in which the recipient opens a welcome invitation, unwraps a 3D-style gift box, browses a scrapbook of Polaroid memories, reads a heartfelt letter that types itself out, plays a five-question friendship quiz, lights up ten constellation stars, blows out birthday candles, and lands on a full-bleed final birthday message.

The product intent is emotional: to make the recipient feel loved, special, happy, and emotional, and to read as a crafted personal artifact rather than an ordinary birthday website. The audience is two people. The Best Friend (Birthday Recipient) is the sole visitor of the surprise experience. The Creator (Site Owner / Bestie's Friend) authors all personal content — photos, captions, inside jokes, the letter, the quiz, the ten reasons, the name, the birthday date, and the final message — and publishes a shareable link.

Everything the recipient sees is content the Creator has supplied. No login is required for either person, no sample photo is ever presented as a real memory, and personal photos and messages stay private with no unnecessary data collection.

2. System Overview

Project Bestie Forever is delivered as a responsive web experience that runs in the browser on mobile phones, tablets, and computers. The recipient's journey is a single continuous vertical sequence of nine acts — Welcome screen, Interactive gift box, Friendship memories gallery, Secret letter, Friendship quiz, Ten reasons why you are special, Birthday cake surprise, and Final screen — each rendered as a frosted glass card floating over one continuous, never-resetting aurora background. A slim frosted top bar carries the wordmark "Project Bestie Forever" and the music play/pause pill, and a quiet progress rail shows which act the recipient is in.

The Creator's work happens in a separate Content Editor destination where the personal content is authored and saved before publishing. The published site is then shared as a link, and the Creator can hand the recipient a working, shareable URL together with instructions for replacing any placeholder content with personal content.

Actors. The Best Friend (Birthday Recipient) is the visitor who experiences the journey. The Creator (Site Owner / Bestie's Friend) authors content and publishes. No other human actor participates.

Ownership. All nine destinations are first-party application surfaces. There is no provider-owned or external destination in the current scope. The optional background soundtrack is a first-party control over an audio asset; it is never autoplayed.

Narrow exclusions. No login or account is required for either persona. No sample photograph is displayed as if it were a real memory — Polaroid frames ship empty with an "Add your photo here" placeholder. No unnecessary data collection is added. Audio never autoplays before the recipient interacts with the site.

2a. Product Interpretation and Delivery Boundary

The current delivery is a single published, shareable website. The recipient opens it anonymously — there is no sign-in, no account creation, and no gate of any kind before the welcome screen. The Creator's authoring work is likewise not gated by an account system; the Content Editor is a first-party destination where content is prepared and saved before the site is published.

The boundary between current and future work is narrow and explicit. Everything listed in Section 3 is current. Nothing in this document commits the product to accounts, social features, analytics, or any capability the Creator did not ask for. The only durable state the product holds is the authored content itself — the photos, captions, letter, quiz, reasons, name, birthday date, and messages that the Creator supplies — and that content is kept private and is not collected from or about the recipient.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source, so no external factual inventory is carried into this document. All content is authored by the Creator.

2c. Page Content and Component Coverage

Welcome screen

• Information and state. Displays "Hey, my favorite human!\x20\xf0\x9f\x92\x97", "I made something special just for you.", and "Are you ready for your surprise?" over the continuous aurora background. The act is the public entry surface and requires no identity.
• Primary action. The glowing "Open Your Surprise\x20\xe2\x9c\xa8" button, which starts the magical animation with floating hearts and confetti and advances the journey.
• Supporting actions. Music play/pause pill in the top bar; progress rail indicating the current act.
• Domain entities. Authored greeting copy; the recipient's name as configured by the Creator.
• Component responsibilities. Hero glass card (tilted, luminous top edge, hand-drawn underline that draws itself in over the words "favorite human"); the CTA pill that deliberately overflows the card's bottom edge and breathes a pink halo; the decorative 3D-style gift box bobbing half-cropped at the viewport edge, foreshadowing the Interactive gift box act; floating hearts and sparkling stars layer.
• States. Loading: aurora and card fade in, CTA disabled until fonts and hero assets settle. Empty: not applicable — the greeting is authored content and always present. Success: CTA press triggers hearts-and-confetti burst and transitions to the Interactive gift box. Error/recovery: if the animation layer fails to initialize, the CTA still advances the journey with a static transition so the recipient is never blocked.

Interactive gift box

• Information and state. A 3D-style animated birthday gift box in a closed state, awaiting a tap.
• Primary action. Tapping the box opens it with an animation and reveals the personalized birthday message.
• Supporting actions. Continue control to the next act; music play/pause pill; progress rail.
• Domain entities. The personalized birthday message authored by the Creator.
• Component responsibilities. CSS 3D gift cube with rounded edges, lilac ribbon and hot-pink bow; lid that lifts and rotates on a spring before the message pops out; message pane nested as a more opaque, more blurred glass layer inside the act card.
• States. Loading: box renders closed with a gentle bob. Empty: if no personalized message has been authored, the box shows a neutral prompt directing the Creator to add one rather than inventing text. Success: lid opens, message appears, and the recipient can continue. Error/recovery: if the 3D transform is unsupported, the box opens with a flat crossfade and the message still appears.

Friendship memories gallery

• Information and state. A scrapbook-style gallery of Polaroid-framed photos with captions, memorable moments, and inside jokes, plus a slideshow view.
• Primary action. Browsing and opening individual Polaroids; starting and controlling the slideshow.
• Supporting actions. Slideshow play/pause and next/previous navigation; smooth cross-dissolve transitions; continue control to the next act.
• Domain entities. Photo entries (image, caption, date, inside-joke note) authored by the Creator.
• Component responsibilities. Polaroid cards — the only sharp-cornered, opaque-white objects in the app — scattered as a scrapbook; slideshow stage that cross-dissolves at 700ms with a 1.02→1.00 scale settle; empty-frame placeholder reading "Add your photo here".
• States. Loading: frames fade in with staggered rise. Empty: every frame shows the dashed "Add your photo here" placeholder with a one-line note; no stock or sample photograph is ever shown as a memory. Success: photos display with captions and the slideshow advances through them. Error/recovery: if an individual image fails to load, that frame keeps its placeholder and caption while the rest of the gallery and slideshow continue.

Secret letter

• Information and state. An animated envelope in a closed state with the button "Open My Letter\x20\xf0\x9f\x92\x8c".
• Primary action. Pressing "Open My Letter\x20\xf0\x9f\x92\x8c" opens the envelope and displays the heartfelt letter with a typewriter text animation.
• Supporting actions. Skip-to-full-letter control for recipients who prefer not to wait for the typing; continue control to the next act.
• Domain entities. The letter text authored and edited by the Creator before publishing.
• Component responsibilities. Envelope flap animation; letter sheet rendered in italic Fraunces; typewriter engine at 28ms per character with a blinking caret; reduced-motion path that reveals the letter immediately.
• States. Loading: envelope rests closed. Empty: if no letter has been authored, the envelope shows a neutral prompt to add one rather than placeholder prose. Success: envelope opens, letter types out, and the recipient can continue. Error/recovery: if the typewriter animation is interrupted or unsupported, the full letter renders at once.

Friendship quiz

• Information and state. A fun five-question quiz about the friendship, presented one question at a time with cute animations.
• Primary action. Selecting an answer to each of the five customizable questions.
• Supporting actions. Progress indication across the five questions; continue control to the next act after the result.
• Domain entities. Five customizable questions with their answer options; the funny or sweet result text keyed to the recipient's answers.
• Component responsibilities. Question card with animated option buttons; answer-selection feedback animation; result card that resolves to a funny or sweet message based on the answers given.
• States. Loading: first question rises into place. Empty: if fewer than five questions are authored, the quiz presents only the authored questions and states plainly that the quiz is not yet complete rather than fabricating questions. Success: all five answered, result displayed. Error/recovery: if the recipient abandons mid-quiz, returning to the act resumes at the first unanswered question.

Ten reasons why you are special

• Information and state. Ten glowing stars arranged as a constellation, each concealing a different reason the recipient is special; a secret final message is locked until all ten are opened.
• Primary action. Opening individual stars to reveal their reason.
• Supporting actions. Continue control to the next act, available after the constellation is complete.
• Domain entities. Ten authored reasons; the secret final message.
• Component responsibilities. Constellation layout with stars positioned as a star map rather than a grid; each opened star lights up and draws a faint lilac line to the next; the completed constellation reveals the secret message.
• States. Loading: stars render dim and unopened. Empty: if fewer than ten reasons are authored, only the authored stars are shown and the secret message stays locked with a clear indication of how many remain. Success: all ten opened, constellation complete, secret final message revealed. Error/recovery: opening state persists per star so a recipient who leaves and returns does not lose progress within the act.

Birthday cake surprise

• Information and state. A beautiful animated birthday cake with lit candles.
• Primary action. Tapping the candles to turn them off.
• Supporting actions. Continue control to the Final screen after the celebration.
• Domain entities. The full-screen birthday message revealed by the celebration.
• Component responsibilities. Cake illustration with individually tappable candle flames; 180ms flame-scale-to-zero with a rising smoke wisp; celebration layer firing confetti, fireworks, and glowing hearts together; full-screen birthday message overlay.
• States. Loading: cake renders with all candles lit. Empty: not applicable — the cake is a fixed illustrated component. Success: all candles extinguished, celebration fires, full-screen birthday message appears. Error/recovery: if the celebration layer fails, the full-screen birthday message still appears so the moment is never lost.

Final screen

• Information and state. Displays "Happy Birthday, Bestie!\x20\xf0\x9f\x8e\x82\xf0\x9f\x92\x96" and the message "No matter how life changes, you will always have a special place in my heart. Thank you for being part of my story. Here's to more memories, laughter, and adventures together!" — with the final message editable by the Creator.
• Primary action. Reading the closing message.
• Supporting actions. The clear restart control that returns the recipient to the beginning of the birthday experience; music play/pause pill.
• Domain entities. The authored final message.
• Component responsibilities. Full-bleed typographic composition that breaks the glass-card system entirely — no card, just type on the aurora; restart control; music pill.
• States. Loading: type fades in over the aurora. Empty: if no final message has been authored, the default closing text is shown and the Creator is prompted to personalize it. Success: message read, restart available. Error/recovery: restart always works even if the celebration layer or audio failed earlier in the journey.

Content Editor

• Information and state. The Creator-facing authoring destination where all personal content is prepared before publishing: photos, name, birthday date, captions, memorable moments, inside jokes, the letter, the five quiz questions, the ten reasons, the secret final message, and the final screen message.
• Primary action. Editing and saving authored content fields.
• Supporting actions. Adding and removing gallery photos with their captions; editing the letter; editing the five quiz questions and their results; editing the ten reasons and the secret message; editing the name and birthday date; editing the final message; previewing the experience; publishing and obtaining the shareable link; reading the instructions for replacing sample content with personal content.
• Domain entities. Content records for gallery entries, letter, quiz questions, reasons, secret message, identity details (name, birthday date), and final message.
• Component responsibilities. Field editors per content type; photo upload and caption fields; preview surface; publish action that produces the shareable website link; instructions panel describing how to replace placeholder content.
• States. Loading: existing authored content loads into the editors. Empty: fields show their placeholders and the gallery shows empty Polaroid frames with "Add your photo here". Success: content saves and the published site reflects it. Error/recovery: unsaved edits are preserved in the editor and the Creator is told which field failed to save, so no authored work is lost.

3. Functional Requirements

FR-1 — Fully functional interactive website. As the Creator, I should get a fully functional, interactive, mobile-friendly birthday surprise website named "Project Bestie Forever" for my best friend, not a static mockup, so that every button, animation, quiz answer, gallery control, and surprise reveal actually works. (explicit)

• Lifecycle: Trigger — the Creator publishes the site. Result — the recipient can complete the entire journey with all controls functional. Failure/recovery — any non-functional control is a defect against this requirement. Continuation — the recipient reaches the Final screen.

FR-2 — Dreamy pastel design and theme. As the Creator, I should have the experience rendered in a dreamy pastel pink, lavender, white, and soft purple palette with floating hearts, sparkling stars, glowing buttons, smooth animations, beautiful transitions, elegant fonts, cute illustrations, glassmorphism cards, and a magical background, so that it looks premium, modern, cute, and emotional. (explicit)

• Lifecycle: Trigger — any act renders. Result — the palette, motion, glass surfaces, and magical background are present throughout. Failure/recovery — reduced-motion and low-capability fallbacks preserve the look with static equivalents. Continuation — the visual language stays constant across all acts.

FR-3 — Responsive layouts and optimized loading. As the Best Friend (Birthday Recipient), I should be able to use the experience perfectly on a mobile phone, tablet, or computer, with responsive layouts and optimized loading speed, so that the gift feels right on whatever device I open it on. (explicit)

• Lifecycle: Trigger — the site is opened at any viewport. Result — layout adapts and content loads promptly. Failure/recovery — slow assets degrade to placeholders rather than blocking the journey. Continuation — the recipient can proceed through every act at any viewport.

FR-4 — Welcome screen with surprise button. As the Best Friend (Birthday Recipient), I should see "Hey, my favorite human!\x20\xf0\x9f\x92\x97", "I made something special just for you.", and "Are you ready for your surprise?" on the Welcome screen, with a glowing button called "Open Your Surprise\x20\xe2\x9c\xa8" that starts a magical animation with floating hearts and confetti when clicked, so that the experience opens with anticipation. (explicit)

• Lifecycle: Trigger — the recipient opens the site. Result — the greeting and glowing CTA are visible; pressing the CTA fires hearts and confetti and advances the journey. Failure/recovery — if the animation layer fails, the CTA still advances with a static transition. Continuation — the recipient moves to the Interactive gift box.

FR-5 — Interactive 3D-style gift box. As the Best Friend (Birthday Recipient), I should see a 3D-style animated birthday gift box that opens with an animation when I tap it and reveals a personalized birthday message, so that the first surprise feels physical and personal. (explicit)

• Lifecycle: Trigger — the recipient taps the gift box. Result — the box opens with an animation and the personalized birthday message is revealed. Failure/recovery — if 3D transforms are unsupported, the box opens with a flat crossfade and the message still appears. Continuation — the recipient moves to the Friendship memories gallery.

FR-6 — Scrapbook memories gallery. As the Best Friend (Birthday Recipient), I should browse a scrapbook-style photo gallery with Polaroid frames containing our real photos, captions, memorable moments, and inside jokes, with smooth transitions and a beautiful slideshow, so that our shared history is the centerpiece of the gift. (explicit)

• Lifecycle: Trigger — the recipient opens the gallery act. Result — Polaroids display with captions and the slideshow cross-dissolves through them. Failure/recovery — a failed image keeps its placeholder and caption while the rest continue. Continuation — the recipient moves to the Secret letter.

FR-7 — Secret letter with typewriter animation. As the Best Friend (Birthday Recipient), I should see an animated envelope with a button called "Open My Letter\x20\xf0\x9f\x92\x8c" that opens the envelope and displays a heartfelt letter with a typewriter text animation, so that the words feel like they are being written to me in the moment. (explicit)

• Lifecycle: Trigger — the recipient presses "Open My Letter\x20\xf0\x9f\x92\x8c". Result — the envelope opens and the letter types out. Failure/recovery — if the animation is interrupted or unsupported, the full letter renders at once. Continuation — the recipient moves to the Friendship quiz.

FR-8 — Letter editable before publishing. As the Creator, I should be able to edit the letter before publishing the website, so that the recipient reads my own words. (explicit)

• Lifecycle: Trigger — the Creator edits the letter in the Content Editor. Result — the saved letter is what the recipient reads in the Secret letter act. Failure/recovery — unsaved edits are preserved and the failing field is identified. Continuation — the Creator publishes with the edited letter.

FR-9 — Five-question friendship quiz. As the Best Friend (Birthday Recipient), I should play a fun quiz with five customizable questions about our friendship, with cute animations and a funny or sweet result based on my answers, so that the quiz feels like it was written about us. (explicit)

• Lifecycle: Trigger — the recipient opens the quiz act. Result — five questions are answered and a funny or sweet result is displayed based on the answers. Failure/recovery — abandoning mid-quiz resumes at the first unanswered question. Continuation — the recipient moves to Ten reasons why you are special.

FR-10 — Ten glowing stars with secret message. As the Best Friend (Birthday Recipient), I should see ten glowing stars, each revealing a different reason why I am special to you, and after all ten stars are opened I should see a secret final message, so that the act builds to a hidden payoff. (explicit)

• Lifecycle: Trigger — the recipient opens stars one by one. Result — each star reveals its reason; opening all ten reveals the secret final message. Failure/recovery — per-star opened state persists within the act so progress is not lost. Continuation — the recipient moves to the Birthday cake surprise.

FR-11 — Birthday cake surprise. As the Best Friend (Birthday Recipient), I should see a beautiful animated birthday cake with candles, tap the candles to turn them off, and then see confetti, fireworks, glowing hearts, and a full-screen birthday message, so that the celebration lands as a peak moment. (explicit)

• Lifecycle: Trigger — the recipient taps the candles. Result — candles extinguish and confetti, fireworks, glowing hearts, and the full-screen birthday message fire together. Failure/recovery — if the celebration layer fails, the full-screen birthday message still appears. Continuation — the recipient moves to the Final screen.

FR-12 — Optional background music with visible control. As the Best Friend (Birthday Recipient), I should have an optional soft, cheerful birthday soundtrack with a visible play/pause button, and audio must not autoplay before I interact with the website, so that music is available without ever surprising me. (explicit)

• Lifecycle: Trigger — the recipient presses the visible play/pause button. Result — the soundtrack plays or pauses on demand. Failure/recovery — if audio cannot load, the control reflects the unavailable state and the journey continues silently. Continuation — the recipient can toggle music at any point in the journey.

FR-13 — Final screen with editable message. As the Best Friend (Birthday Recipient), I should see "Happy Birthday, Bestie!\x20\xf0\x9f\x8e\x82\xf0\x9f\x92\x96" and the message "No matter how life changes, you will always have a special place in my heart. Thank you for being part of my story. Here's to more memories, laughter, and adventures together!" on the Final screen, with the final message editable so the Creator can write her own words, so that the closing words are personal. (explicit)

• Lifecycle: Trigger — the recipient reaches the Final screen. Result — the greeting and the authored final message are displayed. Failure/recovery — if no custom message is authored, the default closing text is shown. Continuation — the recipient can restart the experience.

FR-14 — All controls and reveals work. As the Creator, I should have all buttons, animations, quiz answers, photo gallery controls, and surprise reveals working, so that the gift never breaks in the recipient's hands. (explicit)

• Lifecycle: Trigger — any interaction in any act. Result — the interaction produces its intended animation, reveal, or state change. Failure/recovery — a failed interaction degrades to a static but functional equivalent. Continuation — the recipient can always reach the next act.

FR-15 — Easy customization of personal content. As the Creator, I should be able to easily customize the photos, name, birthday date, captions, quiz questions, letter, and messages, so that the site reflects my own content rather than placeholders. (explicit)

• Lifecycle: Trigger — the Creator edits content in the Content Editor. Result — the published site reflects the authored content. Failure/recovery — failed saves are reported per field and edits are preserved. Continuation — the Creator publishes the customized site.

FR-16 — Restart the birthday experience. As the Best Friend (Birthday Recipient), I should have a clear way to restart the birthday experience, so that I can relive it from the beginning. (explicit)

• Lifecycle: Trigger — the recipient uses the restart control on the Final screen. Result — the experience returns to the Welcome screen with the journey reset. Failure/recovery — restart works even if earlier animation or audio layers failed. Continuation — the recipient can replay the full journey.

FR-17 — No login required. As the Best Friend (Birthday Recipient), I should never be asked to log in, so that opening the gift is immediate. (explicit)

• Lifecycle: Trigger — the recipient opens the site. Result — the Welcome screen is reachable with no authentication step. Failure/recovery — not applicable; there is no auth path to fail. Continuation — the recipient proceeds directly into the journey.

FR-18 — No sample photos presented as real memories. As the Best Friend (Birthday Recipient), I should never see sample photos displayed as if they were our real memories, so that the gift never feels fake. (explicit)

• Lifecycle: Trigger — the gallery renders without authored photos. Result — empty Polaroid frames show an "Add your photo here" placeholder instead of stock imagery. Failure/recovery — a failed image load falls back to the placeholder, never to a substitute photo. Continuation — the gallery remains usable with placeholders until the Creator adds real photos.

FR-19 — Privacy of personal photos and messages. As the Creator, I should have my personal photos and messages kept private with no unnecessary data collection, so that the gift stays between the two of us. (explicit)

• Lifecycle: Trigger — content is authored and the site is published. Result — personal content is not exposed beyond the published experience and no unnecessary data is collected. Failure/recovery — no collection path exists to fail. Continuation — the published site continues to serve only the authored content.

FR-20 — Shareable published link and replacement instructions. As the Creator, I should receive a working, shareable published website link and instructions for replacing the sample content with my personal content, so that I can send the gift and keep it up to date. (explicit)

• Lifecycle: Trigger — the Creator publishes from the Content Editor. Result — a working shareable link is produced along with instructions for replacing placeholder content. Failure/recovery — if publishing fails, the Creator is told what failed and can retry without losing authored content. Continuation — the Creator shares the link with the recipient.

FR-21 — Replace content before publishing. As the Creator, I should replace the placeholder content with my personal photos and messages before publishing, so that no placeholder is ever presented to the recipient as a real memory. (required_inference)

• Lifecycle: Trigger — the Creator finishes authoring in the Content Editor. Result — placeholder content is replaced by personal content before the site goes live. Failure/recovery — unreplaced placeholders remain visibly marked as placeholders rather than reading as real memories. Continuation — the Creator publishes the personalized site.

FR-22 — Publish and obtain the shareable link. As the Creator, I should publish the configured experience and obtain a shareable website link before delivery, so that the recipient can actually open the gift. (required_inference)

• Lifecycle: Trigger — the Creator publishes from the Content Editor. Result — the configured experience is live at a shareable URL. Failure/recovery — a failed publish reports the cause and preserves authored content for retry. Continuation — the Creator sends the link to the recipient.

FR-23 — Audio stays paused until interaction. As the Best Friend (Birthday Recipient), I should have audio remain paused until I interact with the website, so that nothing plays unexpectedly. (required_inference)

• Lifecycle: Trigger — the site loads. Result — the soundtrack is paused and the play/pause control shows the paused state. Failure/recovery — if the browser blocks audio, the control reflects the blocked state and the journey continues. Continuation — the recipient may start music at any time by pressing play.

FR-24 — Edit letter and final message before publishing. As the Creator, I should be able to edit the letter and the final message before publishing, so that both the intimate letter and the closing words are mine. (required_inference)

• Lifecycle: Trigger — the Creator edits the letter and final message in the Content Editor. Result — the saved text is what the recipient reads in the Secret letter act and on the Final screen. Failure/recovery — failed saves are reported per field and edits are preserved. Continuation — the Creator publishes with the edited text.

4. User Personas

Best Friend (Birthday Recipient)

Product context. She is the single intended visitor of the surprise site. She opens it on a phone, probably late at night, with no prior explanation beyond the fact that her best friend made something for her. She has no account, no onboarding, and no instructions — the experience must explain itself through its own sequence.

Primary goal. To feel loved, special, happy, and emotional, and to move through a personalized, magical journey that feels like a gift made only for her.

Distinct accepted responsibilities. She is the one who opens the surprise: she presses "Open Your Surprise\x20\xe2\x9c\xa8", taps the 3D gift box to reveal her birthday message, browses the Polaroid scrapbook and its slideshow, presses "Open My Letter\x20\xf0\x9f\x92\x8c" and reads the letter as it types itself out, answers the five friendship quiz questions and receives her result, opens the ten glowing stars one by one until the secret final message unlocks, taps the candles to extinguish them and trigger the celebration, and reads the final birthday message. She also controls the optional soundtrack and can restart the whole experience.

Relevant inputs and decisions. Her taps and presses drive every reveal. Her quiz answers determine whether she receives a funny or a sweet result. Her choice to press play determines whether music accompanies the journey.

Interactions with other accepted participants. She never interacts with the Creator directly inside the product. Every interaction is with content the Creator authored — the message in the gift box, the captions and inside jokes in the gallery, the letter, the quiz questions, the ten reasons, and the final message. The Creator's authorship is what makes her journey personal.

Observable success. She completes the full sequence of surprises, reaches the Final screen, reads the closing message, and can restart the experience to relive it.

Creator (Site Owner / Bestie's Friend)

Product context. She is the requester and the author of the gift. She works in the Content Editor before publishing, assembling the personal material that the recipient will encounter. Her work is invisible to the recipient but determines everything the recipient sees.

Primary goal. To deliver a working, shareable published site that reflects her own words and photos, so that her best friend receives something that could only have come from her.

Distinct accepted responsibilities. She adds real photos with captions, memorable moments, and inside jokes to the gallery; edits the heartfelt letter; customizes the five quiz questions and their results; writes the ten reasons and the secret final message; sets the name and birthday date; writes the final screen message; replaces placeholder content with personal content before publishing; publishes the experience; and obtains the shareable link together with instructions for replacing sample content with personal content.

Relevant inputs and decisions. Her authored text and photos are the product's content. Her decision about when to publish determines when the gift goes live. Her decision to replace placeholders before publishing determines whether the recipient ever sees a placeholder.

Interactions with other accepted participants. She never interacts with the recipient inside the product. Her entire relationship to the recipient's journey is authorship: what she writes and uploads is what the recipient reads, sees, and answers.

Observable success. A published, shareable link that opens the personalized experience, with all her content in place and no placeholder presented as a real memory.

5. Core User Flows

Flow A — The Best Friend opens and completes the birthday journey

1. Starting context. The recipient receives a link from the Creator and opens it on her phone. She is not logged in and is not asked to log in. The Welcome screen loads over the continuous aurora background.
2. She reads "Hey, my favorite human!\x20\xf0\x9f\x92\x97", "I made something special just for you.", and "Are you ready for your surprise?".
3. She presses the glowing "Open Your Surprise\x20\xe2\x9c\xa8" button. Floating hearts and confetti burst across the screen and the journey advances.
4. Interactive gift box. She taps the 3D-style animated gift box. The lid lifts and rotates on a spring, and her personalized birthday message pops out. She reads it and continues.
5. Friendship memories gallery. She browses the scrapbook of Polaroid frames, reading captions, memorable moments, and inside jokes. She starts the slideshow and watches the Polaroids cross-dissolve one into the next. She continues.
6. Secret letter. She presses "Open My Letter\x20\xf0\x9f\x92\x8c". The envelope opens and the heartfelt letter types itself out at 28ms per character with a blinking caret. She reads it to the end and continues.
7. Friendship quiz. She answers the five customizable questions about the friendship, one at a time, with cute animations on each selection. After the fifth answer, she receives a funny or sweet result based on her answers. She continues.
8. Ten reasons why you are special. She opens the ten glowing stars one by one. Each star lights up and draws a faint lilac line to the next, and each reveals a different reason she is special. When all ten are open, the completed constellation reveals the secret final message. She continues.

9. Birthday cake surprise. She sees the animated birthday cake with lit candles and taps the candles to turn them off. Each flame scales to zero in 180ms with a rising smoke wisp. When the candles are out, confetti, fireworks, and glowing hearts fire together and a full-screen birthday message appears. She continues.
10. Final screen. She reads "Happy Birthday, Bestie!\x20\xf0\x9f\x8e\x82\xf0\x9f\x92\x96" and the closing message: "No matter how life changes, you will always have a special place in my heart. Thank you for being part of my story. Here's to more memories, laughter, and adventures together!"
11. Music, at any point. Whenever she wants, she presses the visible play/pause pill in the top bar. Music never starts on its own; it begins only after she presses play.
12. Restart. From the Final screen she uses the clear restart control, and the experience returns to the Welcome screen so she can relive it.
13. Failure and recovery along the way. If an image fails to load, that Polaroid keeps its placeholder and caption while the rest of the gallery and slideshow continue. If the typewriter animation is interrupted, the full letter renders at once. If the celebration layer fails, the full-screen birthday message still appears. If audio cannot load, the music control reflects that and the journey continues silently. In every case she can still reach the next act.

Flow B — The Creator authors content and publishes the gift

1. Starting context. The Creator opens the Content Editor to prepare the gift before the recipient ever sees it.
2. She adds her real photos to the gallery and writes the caption, memorable moment, or inside joke for each one. Empty Polaroid frames show "Add your photo here" until she does.
3. She edits the heartfelt letter that the recipient will read in the Secret letter act.
4. She customizes the five quiz questions about the friendship and the funny or sweet results tied to the answers.
5. She writes the ten reasons why her best friend is special and the secret final message that unlocks after all ten stars are opened.
6. She sets the name and birthday date used by the experience.
7. She writes the final screen message in her own words, replacing the default closing text.
8. She previews the experience to confirm the content reads the way she intends.
9. She replaces any remaining placeholder content with her personal content, so that no placeholder is presented to the recipient as a real memory.
10. She publishes the experience. The Content Editor produces a working, shareable website link along with instructions for replacing sample content with personal content.
11. Failure and recovery. If a save fails, the editor tells her which field failed and preserves her unsaved edits. If publishing fails, she is told what failed and can retry without losing authored content.
12. Continuation. She shares the published link with her best friend, who then begins Flow A.

6. Visuals, Colors, and Theme

The visual direction is Layered translucency, maximal cuteness — a glass-and-pastel birthday world after Michal Malewicz. The register is dreamy, cute, premium, and overwhelming-in-a-good-way: floating hearts, glowing buttons, confetti, and a letter that types itself out. The emotional arc is anticipation → delight → tears → celebration.

Palette (light mode).

The ground is a whisper-lavender white carrying a slow drifting four-stop aurora at 55–70% opacity, blurred 120px, never a hard blob. Glass surfaces are rgba(255,255,255,0.62) with a 1px rgba(255,255,255,0.85) top-light border, 20px backdrop-blur, and a 0 18px 40px rgba(199,125,255,0.18) shadow — cards float, they do not sit. Proportion is 70% pastel ground and glass, 20% lilac and pink gradients, 10% hot accent; the accent must feel like a jewel, not a wash. Gold appears only as candle flame and star fill, never as a UI colour.

Typography. Headings use Fraunces at weight 600–700 with SOFT 60 and WONK 1, optical size pushed large (opsz 144) so terminals go plump and romantic; italic Fraunces is used for the letter and for inside-joke captions. Body uses Plus Jakarta Sans. The scale is a 1.333 modular with a display extension on a 16px base: 22 / 26 / 34 / 46 / clamp(46px, 9vw, 104px) / clamp(64px, 12vw, 148px). Mobile hero is 46px, tablet 72px, desktop 104–148px. Body is 17px/1.75 on mobile and 18px/1.8 on desktop. Section labels are 12px uppercase with 0.14em letter-spacing. Display tracking is -0.02em.

Shape language. Everything is curved and inflated: cards at 28–36px radii, buttons as full pills, the gift box as a CSS 3D cube with 24px rounded edges. Polaroids are 4px-radius white cards — deliberately sharper than everything else so they read as physical objects inside the soft world. Blobs, hearts, and stars are organic SVGs with no straight lines. Depth comes from stacked translucency, not borders: each layer is a little more opaque and a little more blurred than the one beneath it.

Layout. A single vertical journey of nine full-viewport acts, each a glass card floating over the same continuous aurora so the background never resets. Mobile-first single column with 20px gutters; at 768px the gallery and the ten stars go to two columns; at 1280px a 12-column grid with content max-width 1120px and acts alternating left and right of centre for rhythm. A slim frosted top bar holds the wordmark "Project Bestie Forever" in Fraunces italic and the play/pause music pill, and never grows taller than 56px. A quiet 3-dot progress rail on the right edge (bottom on mobile) shows which act the recipient is in. The Final screen breaks the card system entirely: full-bleed, no glass, just type on the aurora.

Imagery. No stock photography of strangers, ever. Instead: custom flat-vector cute illustration (two best-friend characters with no facial detail so they can be "us", a cake, a gift, an envelope, a cassette of inside jokes); glossy 3D-render-feel primitives (heart, star, balloon, ribbon) built as CSS/SVG with soft inner shadows and a specular highlight; and Polaroid frames shipped empty with a friendly dashed placeholder reading "Add your photo here". Sparkles are four-point SVG stars at 8–16px scattered at 0.3–0.7 opacity. The aurora background is the only "image" that is always full-bleed.

7. Signature Design Concept

The public entry is a full-viewport aurora — pink → lilac → sky, blurred and slowly drifting — with a single tall glass card floating slightly off-centre to the right on desktop and centred on mobile. The card is 62vw wide, max 560px, tilted -1.5°, with a 1px luminous top edge.

Inside the card, "Hey, my favorite human!\x20\xf0\x9f\x92\x97" is set in Fraunces italic at clamp(46px, 9vw, 104px) in #3B2A55, with the words "favorite human" wrapped in a hand-drawn pink underline that draws itself in over 700ms. Beneath it, "I made something special just for you." sits at 20px in muted #8B7AA8, then "Are you ready for your surprise?" at 22px.

The "Open Your Surprise\x20\xe2\x9c\xa8" pill sits at the card's bottom edge, half-overlapping it, glowing #FF6FB5 with a 2.6s breathing halo. Behind the card, a 3D-style gift box — CSS cube, #C77DFF ribbon, #FF6FB5 bow — bobs on a 9s sine loop at 0.45 opacity, cropped by the right viewport edge. It becomes the real gift box in the Interactive gift box act, so the hero is already promising the next scene.

There is no centred headline stack, no subtext-button-blue-button, and no gradient blob. The composition is an off-axis glass panel over a living aurora with the CTA breaking its own container. All readable text and the CTA remain whole and inside the viewport at 375px, 768px, and 1280px; the gift box and aurora carry the cropping and bleed.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject. The off-axis glass hero card with its self-drawing pink underline, the breathing "Open Your Surprise\x20\xe2\x9c\xa8" pill overflowing the card's bottom edge, and the half-cropped 3D gift box bobbing behind it.
• Input → transformation → outcome thesis. The recipient's press on the glowing pill transforms the hero from a held invitation into a celebration: floating hearts and confetti burst across the aurora, the hero card crossfades upward, and the journey advances to the Interactive gift box — the same box that was bobbing half-cropped behind the card, now the real subject of the next act.
• Motion vocabulary. Act transitions crossfade the outgoing card up 24px over 420ms with cubic-bezier(0.22, 1, 0.36, 1) while the incoming card rises from 40px with a 120ms stagger on its children. Hearts and stars drift on independent 8–14s sine loops with random phases so nothing syncs. Buttons breathe a 2.6s glow pulse (box-shadow spread 0→18px) and squash to 0.96 on press. The gift box lid lifts and rotates -28° on a spring (stiffness 180, damping 14). The letter types at 28ms per character with a caret blink. Candles extinguish with a 180ms flame-scale-to-zero plus a smoke wisp rising 90px and fading, then confetti, fireworks, and hearts fire together. The gallery slideshow cross-dissolves at 700ms with a 1.02→1.00 scale settle.
• Composed first frame. The aurora fills the viewport, drifting slowly. The glass card floats off-centre right (centred on mobile), tilted -1.5°, its top edge luminous. The greeting sits large in Fraunces italic, the underline mid-draw. The CTA pill glows at the card's bottom edge, half outside it. The gift box bobs at 0.45 opacity, cropped by the right edge. Sparkles sit scattered at 0.3–0.7 opacity.
• Reduced-motion state. All motion collapses to simple opacity fades. The underline is already drawn, the CTA halo is static, the gift box rests still and fully composed, and every reveal has an immediate static end-state. The recipient can still complete the entire journey.

9. Non-Functional Requirements

NFR-1 — Responsive across devices. The experience must work perfectly on mobile phones, tablets, and computers, with layouts that adapt at 375px, 768px, and 1280px. (explicit) Rationale: the recipient may open the gift on any device.

NFR-2 — Optimized loading speed. Assets, fonts, and animations must be optimized so the experience loads promptly. (explicit) Rationale: a slow first impression undermines the emotional opening.

NFR-3 — No login. No authentication step may be required for the recipient or the Creator. (explicit) Rationale: the gift must open immediately.

NFR-4 — No sample photos presented as real memories. Placeholder Polaroid frames must read as placeholders, never as the user's memories. (explicit) Rationale: fake memories would break the emotional premise.

NFR-5 — Privacy and minimal data collection. Personal photos and messages must remain private, and no unnecessary data collection may be added. (explicit) Rationale: the gift is between two people.

NFR-6 — No audio autoplay. Audio must not play before the recipient interacts with the website. (explicit) Rationale: unexpected sound would break the intimate, late-night context.

NFR-7 — Fully functional, not a mockup. Every button, animation, quiz answer, gallery control, and surprise reveal must actually work. (explicit) Rationale: the gift must not break in the recipient's hands.

NFR-8 — Readable text and controls stay whole. Headlines, wordmarks, labels, numbers, card text, and controls must stay entirely inside the viewport and their container at every breakpoint, wrapping or scaling to fit, with no other element covering them. Imagery, decoration, and motion may be cropped, bled, rotated, or overlapped as the direction asks. (explicit, from the creative direction) Rationale: the emotional impact depends on the recipient being able to read every word.

NFR-9 — Reduced-motion support. Under prefers-reduced-motion, all motion must collapse to simple opacity fades with immediate static end-states, and every act must remain fully usable. (required_inference) Rationale: the journey must be completable by recipients who cannot tolerate expressive motion.

NFR-10 — Shareable published link. The Creator must receive a working, shareable published website link. (explicit) Rationale: without a link, the gift cannot be delivered.

10. Tech Stack

• Frontend: React, built as a responsive single-page experience with a component per act (hero card, gift cube, Polaroid gallery and slideshow, envelope and typewriter, quiz, constellation, cake and celebration layer, final screen, content editor). Animation via CSS transitions and a spring-capable animation library for the gift-box lid and act transitions. (Default — not specified by user)
• Backend: Python with FastAPI, serving the authored content (gallery entries, letter, quiz questions, reasons, secret message, identity details, final message) and the publish action that produces the shareable link. (Default — not specified by user)
• Storage: A lightweight persistent store for authored content records and uploaded photos. (Default — not specified by user)
• Packaging and deployment: Docker with docker-compose for the frontend, backend, and storage services, so the published site is reproducible and shareable. (Default — not specified by user)

No source-specified technology was overridden; the user named no stack, so these are labeled defaults.

11. Assumptions and Constraints

Assumptions.

• The Creator authors all personal content before publishing, and the published site reflects that authored content. (required_inference)
• The recipient opens the site anonymously; no identity is established at any point in the journey. (explicit — no login required)
• The optional soundtrack is a first-party audio asset controlled by the visible play/pause pill. (explicit)
• Placeholder Polaroid frames remain visible as placeholders until the Creator supplies real photos. (explicit)

Constraints.

• Do not require users to log in. (explicit)
• Do not display sample photos as if they are the user's real memories. (explicit)
• Keep personal photos and messages private; do not add unnecessary data collection. (explicit)
• Do not autoplay audio before the user interacts with the website. (explicit)
• Build a fully functional website, not just a static mockup. (explicit)
• Provide a working, shareable published website link and instructions for replacing the sample content with personal content. (explicit)
• The letter must be editable before publishing the website. (explicit)
• The final message must be editable so the Creator can write her own words. (explicit)
• The palette is restricted to pastel pink, lavender, white, and soft purple; blue–indigo primaries and accents are excluded. (explicit, from the creative direction)
• Headings and body use Fraunces and Plus Jakarta Sans only; Inter, Roboto, Arial, Helvetica, Poppins, and system-ui are excluded for headings and body. (explicit, from the creative direction)
• No stock photography of strangers may be presented as the user's memories. (explicit)
• Confetti must not fire on page load. (explicit, from the creative direction)

12. Glossary

• Act — One of the nine full-viewport sections of the recipient's journey, each rendered as a glass card over the continuous aurora.
• Aurora — The single continuous, slowly drifting four-stop gradient background (pink, lilac, sky, blush) that never resets between acts.
• Best Friend (Birthday Recipient) — The sole visitor of the surprise experience.
• Constellation — The star-map arrangement of the ten glowing stars in the Ten reasons why you are special act, where each opened star draws a faint lilac line to the next.
• Content Editor — The Creator-facing destination where all personal content is authored, previewed, and published.
• Creator (Site Owner / Bestie's Friend) — The requester who authors the content and publishes the gift.
• Glassmorphism — The layered translucent surface treatment used for act cards and nested panes: semi-opaque white, backdrop blur, luminous top border, soft lilac shadow.
• Polaroid — The sharp-cornered, opaque-white photo frame used in the Friendship memories gallery, deliberately sharper than the surrounding soft world so it reads as a physical object.
• Secret final message — The message revealed in the Ten reasons why you are special act only after all ten stars have been opened.
• Shareable link — The published website URL the Creator sends to the recipient.
• Typewriter animation — The letter reveal that types at 28ms per character with a blinking caret.