System Requirements Document for adopting-cats

1. Introduction

adopting-cats is a website for adopting cats. Its product intent, taken directly from the user's request, is to be "a web that supposed to be a adopting web for cats" — a place where everyday people can meet cats who need homes and take the first real step toward adopting one. The site's look and feel is derived from the image the user supplied as the visual and brand source.

The audience is two-sided but emotionally centred on one side:

• Adopters — everyday people, most often browsing on a phone, who arrive because of a photo of a particular cat and want to find a cat they can adopt. They are the emotional centre of the product.
• Shelter / Listing Managers — the practical backstage: the people responsible for keeping the site's cat listings current so that adopters see accurate cats who are actually available.

The register is warm, hopeful, playful and low-pressure. This is a place to meet a cat, not a form to survive. It should feel like a friendly community noticeboard, not a government portal or a SaaS dashboard.

2. System Overview

adopting-cats is a custom-UI web application with an application-owned backend. It presents a public, anonymous-facing surface where anyone can learn what the site is for and browse cats currently available for adoption, and a protected surface where a signed-in adopter can express interest in adopting a specific cat, and where a provisioned Shelter / Listing Manager can maintain the set of adoptable cat listings.

Current delivery. A responsive web application (mobile-first, 375px → 768px → 1280px) backed by a single application backend that owns cat listings, adopter accounts, manager accounts, and adoption-interest records. Cat photography appears inside listing cards and on Cat Details; the site's own voice is carried by modular vector illustration.

Actors.

• Adopter (human persona) — browses the public catalog, reviews a specific cat, enrolls or signs in, and expresses adoption interest in a selected cat.
• Shelter / Listing Manager (human persona) — signs in with provisioned access and maintains the set of adoptable cat listings.
• Application backend (non-persona system actor) — owns listing state, identity records, and adoption-interest records, and serves the pages above.

Accepted behavior at a glance. Public landing and catalog browsing; a focused per-cat view; adopter self-service enrollment and returning verification; a protected interest expression bound to the correct adopter and the correct cat; manager listing review, creation and editing.

Narrow exclusions. This document does not add adoption-application processing, messaging threads, payment or fee handling, transport or logistics, medical records, foster workflows, or any account-management capability beyond first-use enrollment and returning verification. Nothing in the source authorizes those, and they are not inferred here.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. The site is first-party: the application owns its pages, its identity, its listing state, and its adoption-interest records. There is no provider-owned or external-only surface in the accepted scope, and no headless delivery is requested. The backend is a single application service; the pages are custom UI, not a hosted third-party product.

Access ownership. The public entry, the catalog, and the individual cat view are reachable without an account — a visitor must be able to meet a cat before being asked for anything. Expressing adoption interest is a durable, adopter-specific commitment, so it is protected: it requires a signed-in adopter, and the resulting interest record stays bound to that adopter and to the specific cat. Manager listing work is likewise protected and requires provisioned manager access.

Identity boundary. Adopters establish their own identity through self-service enrollment on first use and verify it on return. Shelter / Listing Managers do not self-enroll into listing administration; their access is provisioned before they can reach listing work. The enrollment and verification interactions are anonymous entry points — a protected destination never owns the interaction that grants access to itself.

Current vs. future. Everything described in this document is current. No future-horizon requirements were stated by the user; the future section is therefore empty by design rather than by omission.

2b. Source Content Inventory

The user supplied an image as the visual and brand source for the site. No URL, metadata, textual content, factual entity, collection item, field, value, date, contact, link, or media reference was provided with it, and no content_source directive was declared. There is therefore no verified factual content to inventory, and no inventory is reproduced here. All cat listings, cat names, photographs and descriptions are authored through the manager listing workflow rather than imported from a source.

2c. Page Content and Component Coverage

Landing

• Information / state. Anonymous first impression. States the purpose of the site — a place to adopt cats — and directs visitors toward the cats currently available. No account required; no personal state shown.
• Primary action. Meet the cats — a tangerine pill CTA with an ink outline and a 4px bottom offset shadow, leading to Cats.
• Supporting actions. Sign up (to Sign Up) and Log in (to Login) for visitors who already know they want to act.
• Domain entities. None owned here; the page reads only the count of currently available cats to phrase its invitation truthfully.
• Component responsibilities. Asymmetric two-part hero: left 55% a hand-built vector illustration scene (a person crouching with an outstretched hand, a cat stepping forward to meet it) framed in a 40px-radius pastel butter block bleeding off the left viewport edge; right 45% a stacked Nunito 800 display headline reading "Find the cat who finds you." with the word cat in tangerine, one line of DM Sans body copy, and the pill CTA. A thin dotted hand-drawn path curves from the illustration into the headline area. A wavy divider leads into a short preview strip of available cats.
• States. Loading: the preview strip shows pastel skeleton cards in the card grid's shape. Empty: when no cats are currently listed, the preview strip is replaced by a friendly illustrated line inviting the visitor to check back soon, and the CTA still leads to Cats. Success: hero and preview render fully. Error: if the preview cannot load, the hero remains fully usable and the preview area shows a short retry line. Recovery: retry re-requests the preview without disturbing the hero.

Sign Up

• Information / state. Anonymous self-service enrollment for an adopter. Explains in one warm line why an account is needed: so the site can keep the adopter's interest in a cat and get back in touch.
• Primary action. Create my account — submits the enrollment form and, on success, signs the adopter in and returns them to the cat they were looking at, or to Cats if they arrived directly.
• Supporting actions. Log in instead (to Login); inline field-level correction.
• Domain entities. Adopter account (identity, display name, contact email, credential).
• Component responsibilities. Single-column form on cream ground with white card, pill inputs and pill submit button; inline validation messages in muted taupe beneath each field; a small vector cat peeking over the card edge as decoration only.
• States. Loading: submit button shows an in-button progress state and is disabled against double submission. Empty: pristine form with helper text. Success: adopter is signed in and forwarded to their intended destination with a brief confirmation. Error: an email already in use is reported on that field with a route to Login; a failed request preserves every entered value and offers retry. Recovery: all field values survive any failure; the adopter can correct and resubmit without re-entering anything.

Login

• Information / state. Anonymous returning verification for both Adopters and Shelter / Listing Managers. One form serves both; the destination after success depends on the account's access.
• Primary action. Log in — verifies the account and forwards the person to the work they came for: an Adopter to the cat they were viewing or to Cats; a Shelter / Listing Manager to Listings.
• Supporting actions. Create an account (to Sign Up) for adopters; a correction path when credentials are rejected.
• Domain entities. Adopter account; Shelter / Listing Manager account.
• Component responsibilities. Single-column form on cream ground with white card, pill inputs and pill submit button; a single generic failure message that does not disclose whether an account exists.
• States. Loading: submit disabled with in-button progress. Empty: pristine form. Success: signed in and forwarded to the correct destination for that account. Error: rejected credentials show one generic message and preserve the entered email; repeated failures do not lock the person out of retrying. Recovery: the person can retry immediately, or route to Sign Up if they have no account.

Cats

• Information / state. Public catalog of cats currently available for adoption. No account required. Shows each cat's photo, name, and a small set of at-a-glance attributes, with availability signalled in teal.
• Primary action. Open a cat — selecting a card leads to Cat Details for that cat.
• Supporting actions. Filter chips that narrow the visible set; clearing filters restores the full set.
• Domain entities. Cat listing (photo, name, at-a-glance attributes, availability status).
• Component responsibilities. Responsive card grid — 1 column at 375px, 2 at 768px, 3 at 1280px — of white cards with 28px radii and the soft offset printed shadow 0 8px 0 rgba(43,33,24,0.08), lifting 4px with the shadow compressing to 0 3px 0 on hover. Pill filter chips that wrap to multiple rows on mobile rather than scrolling horizontally, so every filter is always fully visible and tappable. The hand-drawn dotted path from the hero reappears as a connector between cards. Long cat names wrap rather than truncate.
• States. Loading: pastel skeleton cards in the grid's exact shape. Empty: two distinct empties — no cats listed at all, and no cats matching the active filters; the second offers a one-tap clear-filters action. Success: grid renders with the active filter set reflected in the chips. Error: a failed load shows a short retry line in place of the grid while the page frame and filters remain usable. Recovery: retry re-requests the catalog; filter state is preserved across the retry.

Cat Details

• Information / state. Focused view of one cat: photograph, name, the fuller story and attributes, and current availability. Public; no account required to read.
• Primary action. I'd like to adopt — the route toward expressing interest. If the visitor is not signed in, this leads to Login (with Sign Up offered) and returns them to this cat afterward; if signed in, it leads to Interest for this cat.
• Supporting actions. Back to Cats; move to another cat.
• Domain entities. Cat listing (photo, name, story, attributes, availability status).
• Component responsibilities. Two-column split at 1280px — photograph left, story and Interest CTA right — stacking to one column on mobile. Real cat photography is the emotional payoff here, presented warm and natural-light on cream or pastel ground. Availability is stated in words as well as teal colour, so it does not rely on colour alone.
• States. Loading: photo frame and text block placeholders in the page's own shapes. Empty: not applicable — this page always has a specific cat as its subject. Success: full cat detail renders with the correct availability. Error: an unknown or removed cat shows a friendly not-found state with a route back to Cats; a failed load offers retry. Recovery: retry re-requests this cat; the not-found state never dead-ends.

Interest

• Information / state. Protected focused interaction for expressing interest in adopting a selected cat. Requires a signed-in Adopter. Shows which cat the interest is about, so the commitment is unambiguous, and shows whether this adopter has already expressed interest in this cat.
• Primary action. Send my interest — records the adopter's interest in this specific cat and confirms it.
• Supporting actions. Add or adjust the short note that accompanies the interest; withdraw a previously expressed interest; return to Cat Details.
• Domain entities. Adoption interest (the adopter, the specific cat, the optional note, the time expressed, current status).
• Component responsibilities. Single focused column on cream ground with a white card; the cat's photo and name restated at the top as the subject of the commitment; a pill submit button; the confirmation state replaces the CTA with a small animated vector cat walking across a butter-coloured strip and a handwritten-style "We'll be in touch!" line, accompanied by a short confetti-of-paw-prints burst.
• States. Loading: the page resolves the cat and any existing interest before enabling the action. Empty: no interest yet — the form is presented ready to send. Success: the interest is recorded and the confirmation state plays; the page then shows the interest as already expressed, with the withdraw action available. Error: a failed submission preserves the note and offers retry; a cat that has become unavailable since the page loaded is reported plainly and the action is disabled rather than silently failing. Recovery: retry resubmits the same note; if the cat is no longer available, the adopter is routed back to Cat Details or Cats to find another cat.

Listings

• Information / state. Protected manager workspace for reviewing and maintaining the set of adoptable cat listings. Requires a signed-in Shelter / Listing Manager. Shows every listing with its current availability status.
• Primary action. Add a cat — leads to Listing Edit in create mode.
• Supporting actions. Open an existing listing in Listing Edit; change a listing's availability status directly from the row.
• Domain entities. Cat listing (photo, name, attributes, availability status, last-updated time).
• Component responsibilities. Same cream ground and pill controls as the public pages, but a tighter 8-pt spacing rhythm and a left rail of listing rows at 1280px, collapsing to a stacked list at 375px. Each row carries the cat's thumbnail, name, availability chip and last-updated time in muted taupe. Long cat names wrap rather than truncate.
• States. Loading: row skeletons in the rail's shape. Empty: no listings yet — an illustrated empty state with the Add a cat action front and centre. Success: the rail renders with current statuses. Error: a failed load shows a retry line in place of the rail while the page frame stays usable; a failed status change reverts the row to its previous status and reports the failure. Recovery: retry re-requests the rail; a reverted status change can be retried from the row.

Listing Edit

• Information / state. Protected manager workspace for creating a new cat listing or editing an existing one. Requires a signed-in Shelter / Listing Manager. In edit mode it loads the listing's current values; in create mode it starts blank.
• Primary action. Save listing — writes the listing and returns to Listings with the change reflected.
• Supporting actions. Upload or replace the cat's photograph; set availability status; cancel without saving.
• Domain entities. Cat listing (photograph, name, story, attributes, availability status).
• Component responsibilities. Single-column form on cream ground with a white card, pill inputs and pill controls, 28px card radius, and the same soft offset printed shadow as the public cards. Photograph upload shows a preview in the card's own image frame. Validation messages sit inline beneath their fields in muted taupe.
• States. Loading: in edit mode, field placeholders until the listing resolves. Empty: create mode presents a blank form with helper text. Success: the listing is saved and Listings shows it with its new values. Error: field-level validation blocks the save and names the offending field; a failed save preserves every entered value and offers retry; a listing deleted or changed elsewhere since load is reported plainly rather than overwriting silently. Recovery: all entered values survive any failure; cancel returns to Listings without writing.

3. Functional Requirements

Each requirement below is a distinct story point with its provenance, lifecycle facts, and observable acceptance.

FR-1 — Public entry to the adoption site (explicit) As a visitor, I should land on a page that tells me this is a place to adopt cats and points me at the cats who are available, so that I understand what the site is for and know where to go next.

• Trigger / input: an anonymous visit to the site root.
• Observable result: the Landing page renders its hero and a preview of currently available cats, with a Meet the cats action leading to Cats.
• Access state: none required.
• Failure / recovery: if the preview cannot load, the hero remains fully usable and the preview offers retry.
• Continuation: the visitor proceeds to Cats, or to Sign Up / Login if they already intend to act.

FR-2 — Browse cats available for adoption (explicit) As an Adopter, I should browse the cats currently available for adoption, so that I can find a cat I want to adopt.

• Trigger / input: opening Cats, optionally narrowing the set with filter chips.
• Observable result: a responsive card grid of available cats, each card showing the cat's photo, name and at-a-glance attributes, with availability signalled in teal and stated in words.
• Access state: none required.
• Failure / recovery: a failed load shows a retry line in place of the grid while the page frame and filters stay usable; retry preserves the active filters. An empty result set offers a one-tap clear-filters action.
• Continuation: selecting a card opens Cat Details for that cat.

FR-3 — Review a specific cat before deciding (explicit) As an Adopter, I should open a single cat and read their photograph, story and attributes, so that I can decide whether this is the cat I want to adopt.

• Trigger / input: selecting a cat from Cats.
• Observable result: Cat Details renders that cat's photograph, name, story, attributes and current availability, with the I'd like to adopt action.
• Access state: none required to read.
• Failure / recovery: an unknown or removed cat shows a friendly not-found state with a route back to Cats; a failed load offers retry. Neither dead-ends.
• Continuation: the adopter proceeds toward Interest, or returns to Cats to keep looking.

FR-4 — Adopter self-service enrollment (required_inference) As an Adopter, I should be able to create my own account on first use, so that the site can keep my interest in a cat and get back in touch with me.

• Trigger / input: choosing Sign up from Landing, Login, or the sign-in step of Cat Details.
• Observable result: Sign Up collects the adopter's details, creates the account, signs the adopter in, and returns them to the cat they were viewing — or to Cats if they arrived directly.
• Access state: the enrollment interaction itself is anonymous; it is the entry point that establishes access, not a protected destination.
• Failure / recovery: an email already in use is reported on that field with a route to Login; a failed request preserves every entered value and offers retry.
• Continuation: the adopter continues to the cat they came for, or to Cats.

FR-5 — Returning verification for adopters and managers (required_inference) As an Adopter or a Shelter / Listing Manager, I should be able to verify my identity on return, so that I can resume my own protected work.

• Trigger / input: choosing Log in from Landing, Sign Up, or the sign-in step of Cat Details.
• Observable result: Login verifies the account and forwards the person to the work they came for — an Adopter to the cat they were viewing or to Cats; a Shelter / Listing Manager to Listings.
• Access state: the verification interaction itself is anonymous.
• Failure / recovery: rejected credentials show one generic message that does not disclose whether an account exists, preserve the entered email, and allow immediate retry; adopters without an account are routed to Sign Up.
• Continuation: the person lands on the destination their account is entitled to reach.

FR-6 — Express interest in adopting a specific cat (explicit) As a signed-in Adopter, I should express my interest in adopting a specific cat, so that the shelter knows I want to adopt that cat and can get back in touch with me.

• Trigger / input: choosing I'd like to adopt on Cat Details for a specific cat, then confirming on Interest.
• Observable result: an adoption-interest record is created, bound to this adopter and this specific cat, with an optional short note and the time expressed; the confirmation state replaces the CTA with a small animated vector cat walking across a butter-coloured strip and a handwritten-style "We'll be in touch!" line, with a short confetti-of-paw-prints burst.
• Access state: protected — requires a signed-in Adopter. A visitor who is not signed in is routed through Login (with Sign Up offered) and returned to the same cat afterward.
• Failure / recovery: a failed submission preserves the note and offers retry; a cat that has become unavailable since the page loaded is reported plainly and the action is disabled rather than silently failing, with a route back to Cat Details or Cats.
• Continuation: the page shows the interest as already expressed, with the withdraw action available; the adopter can return to Cats to keep looking.

FR-7 — Withdraw a previously expressed interest (required_inference) As a signed-in Adopter, I should be able to withdraw an interest I previously expressed in a cat, so that my stated intentions stay accurate if I change my mind.

• Trigger / input: the withdraw action on Interest for a cat the adopter has already expressed interest in.
• Observable result: the interest record is withdrawn and the page returns to its ready-to-send state for that cat.
• Access state: protected — requires a signed-in Adopter, and only the adopter who expressed the interest can withdraw it.
• Failure / recovery: a failed withdrawal leaves the existing interest intact and reports the failure with retry.
• Continuation: the adopter may express interest again, or return to Cats.

FR-8 — Manager access is provisioned, not self-enrolled (required_inference) As a Shelter / Listing Manager, I should receive my access through provisioning rather than self-enrollment, so that listing administration stays with the people responsible for it.

• Trigger / input: a provisioned manager account verifying through Login.
• Observable result: the manager reaches Listings; an adopter account verifying through the same form reaches adopter destinations instead.
• Access state: protected — Listings and Listing Edit require a signed-in Shelter / Listing Manager.
• Failure / recovery: an unprovisioned person cannot reach listing work through Sign Up; they are routed to Login and, if they have no manager access, remain on adopter destinations.
• Continuation: the manager proceeds to Listings.

FR-9 — Review and maintain the set of adoptable cat listings (explicit) As a Shelter / Listing Manager, I should review and maintain the set of adoptable cat listings, so that adopters see accurate cats available for adoption.

• Trigger / input: opening Listings.
• Observable result: every listing appears with its thumbnail, name, availability chip and last-updated time; the manager can open any listing in Listing Edit or change its availability status directly from the row.
• Access state: protected — requires a signed-in Shelter / Listing Manager.
• Failure / recovery: a failed load shows a retry line in place of the rail while the page frame stays usable; a failed status change reverts the row to its previous status and reports the failure with retry.
• Continuation: the manager opens a listing to edit it, or adds a new one.

FR-10 — Create or edit an individual cat listing (explicit) As a Shelter / Listing Manager, I should create a new cat listing or edit an existing one, so that the cats shown to adopters are current and complete.

• Trigger / input: Add a cat on Listings, or opening an existing listing.
• Observable result: Listing Edit collects the cat's photograph, name, story, attributes and availability status; saving writes the listing and returns to Listings with the change reflected.
• Access state: protected — requires a signed-in Shelter / Listing Manager.
• Failure / recovery: field-level validation blocks the save and names the offending field; a failed save preserves every entered value and offers retry; a listing changed or deleted elsewhere since load is reported plainly rather than overwritten silently. Cancel returns to Listings without writing.
• Continuation: the manager returns to Listings and sees the updated set.

FR-11 — Availability status governs what adopters can act on (required_inference) As the site, I should reflect each cat's current availability in the catalog and in the interest interaction, so that an adopter never commits to a cat who is no longer available.

• Trigger / input: a manager changing a listing's availability status, or a cat becoming unavailable between page load and submission.
• Observable result: the catalog and Cat Details show the current availability in words and in teal; Interest disables its action and reports plainly when the cat is no longer available.
• Access state: the availability signal is public; the status change is protected.
• Failure / recovery: the adopter is routed back to Cat Details or Cats to find another cat rather than being left at a dead end.
• Continuation: the adopter continues browsing.

FR-12 — The site's look and feel follows the supplied image (explicit) As the site, I should present itself in the warm, illustrated, cream-grounded visual language derived from the image the user supplied, so that the adoption site feels like a friendly community noticeboard rather than a form to survive.

• Trigger / input: any page render.
• Observable result: the palette, typography, shape language, layout and motion described in sections 6–8 are applied consistently across every page.
• Access state: not applicable.
• Failure / recovery: under prefers-reduced-motion, all decorative motion is disabled and the layout remains static, fully usable, and identical in hierarchy.
• Continuation: not applicable.

4. User Personas

Adopter

Product context. An everyday person, most often on a phone, who arrives because of a photo of a particular cat. They are not filling in a form — they are meeting an animal. The site's whole emotional weight sits with them, and every public surface is built to keep the pressure low and the warmth high.

Primary goal. Find a cat they want to adopt, and take the first real step toward adopting that cat.

Distinct accepted responsibilities. The Adopter is the only persona who browses the public catalog, opens an individual cat to read their story, establishes their own account on first use, verifies it on return, and expresses — or withdraws — interest in adopting a specific cat. Their work is discovery and commitment, and it is theirs alone: no other persona browses or expresses interest.

Relevant inputs and decisions. Which filters to apply on Cats; which cat to open; whether this cat is the one; whether to create an account or sign in when the interest action requires it; what short note, if any, to send with their interest; whether to withdraw an interest they have changed their mind about.

Interactions with other accepted participants. The Adopter's expressed interest is the record a Shelter / Listing Manager's listings ultimately serve. The Adopter never administers listings and never sees manager surfaces; the manager never browses on the Adopter's behalf. The two personas meet only through the listing itself — the manager keeps it accurate, the Adopter acts on it.

Observable success. The Adopter has found a cat, read their story, and seen their interest confirmed with the "We'll be in touch!" state — and can see that interest recorded as already expressed when they return to that cat.

Source-backed constraints. The Adopter must be able to browse and read without an account; only the interest expression requires one. Their interest must remain bound to them and to the specific cat, so that a returning adopter sees their own commitment accurately.

Shelter / Listing Manager

Product context. The practical backstage. This person is responsible for keeping the adoption site's cat listings current so that adopters see accurate cats available for adoption. They work in the same warm visual language as the public site, but with a tighter, more workmanlike rhythm — a rail of listings rather than a browsing grid.

Primary goal. An up-to-date set of adoptable cats on the site.

Distinct accepted responsibilities. The Shelter / Listing Manager is the only persona who reviews the full set of listings, creates a new cat listing, edits an existing one, and changes a cat's availability status. Their work is maintenance and accuracy, and it is theirs alone: no other persona writes listing content.

Relevant inputs and decisions. Which listing to open; the cat's photograph, name, story and attributes; whether a cat is currently available; whether to add a new cat or update an existing one; whether to save or cancel.

Interactions with other accepted participants. Every listing this persona maintains is what an Adopter browses and acts on. Their accuracy decision — particularly availability — directly determines whether an Adopter can express interest in a given cat. They do not browse as an Adopter and do not see or act on adoption-interest records.

Observable success. Listings shows the current, complete set of adoptable cats, and a saved change is reflected there immediately.

Source-backed constraints. Manager access is provisioned, not self-enrolled. Listing work is protected and reachable only after verification. The manager's surfaces use the same cream ground and pill controls as the public site, with a tighter 8-pt spacing rhythm.

5. Core User Flows

Flow A — An Adopter finds a cat and expresses interest

1. Starting context. An anonymous visitor opens the site on a phone.
2. On Landing, they read the hero — "Find the cat who finds you." — and see a preview of cats currently available. They tap the tangerine pill Meet the cats.
3. On Cats, the responsive card grid shows available cats with photos, names and at-a-glance attributes. They tap a filter chip to narrow the set; the chips wrap to a second row rather than scrolling, so every filter stays visible and tappable. They tap a cat's card.
4. On Cat Details, they read that cat's photograph, story and attributes, and see the availability stated in words and in teal. They decide this is the cat. They tap I'd like to adopt.
5. Handoff — identity. Because expressing interest is a durable, adopter-specific commitment, they are routed to Login. They have no account, so they choose Create an account and land on Sign Up.
6. On Sign Up, they enter their details and tap Create my account. The account is created, they are signed in, and they are returned to the same cat they were viewing — not dropped somewhere generic.
7. Back on Cat Details for that cat, they tap I'd like to adopt again, now signed in, and land on Interest.
8. On Interest, the cat's photo and name are restated at the top, so the commitment is unambiguous. They add a short note and tap Send my interest.
9. Observable result. The interest is recorded, bound to them and to this specific cat. The confirmation state replaces the CTA: a small animated vector cat walks across a butter-coloured strip, a handwritten-style "We'll be in touch!" line appears, and a short confetti-of-paw-prints burst plays.
10. Continuation. The page now shows the interest as already expressed, with the withdraw action available. They can return to Cats to keep looking.

Material failure and recovery. If the submission fails, their note is preserved and they can retry without retyping. If the cat has become unavailable since the page loaded, the action is disabled and the page says so plainly, routing them back to Cat Details or Cats to find another cat — never a dead end. If they later change their mind, they return to Interest for that cat and withdraw the interest; a failed withdrawal leaves the existing interest intact and offers retry.

Flow B — A returning Adopter resumes their own commitment

1. Starting context. An Adopter who has already expressed interest returns to the site.
2. On Landing, they tap Log in.
3. On Login, they verify their identity. Rejected credentials show one generic message that does not disclose whether an account exists, preserve their email, and let them retry immediately.
4. Observable result. They are forwarded to the work they came for — the cat they were viewing, or Cats.
5. Continuation. On Interest for that cat, they see their interest recorded as already expressed, with the withdraw action available. Their commitment is still bound to them and to that cat.

Flow C — A Shelter / Listing Manager keeps the listings current

1. Starting context. A Shelter / Listing Manager has been provisioned with access and opens the site.
2. They tap Log in on Landing and verify through Login. Because their account is a manager account, they are forwarded to Listings rather than to adopter destinations.
3. On Listings, the left rail shows every listing with its thumbnail, name, availability chip and last-updated time. They scan for anything stale.
4. They open a listing and land on Listing Edit, which loads that listing's current values.
5. On Listing Edit, they replace the cat's photograph, correct the story, and set the availability status. They tap Save listing.
6. Observable result. The listing is written and they return to Listings, where the change is reflected immediately — including the updated availability chip.
7. Continuation. They tap Add a cat to create a new listing, which opens Listing Edit in create mode with a blank form. They fill it in and save, and the new cat appears in the rail.

Material failure and recovery. Field-level validation blocks a save and names the offending field. A failed save preserves every entered value and offers retry. If a listing was changed or deleted elsewhere since it loaded, that is reported plainly rather than silently overwritten. Cancel returns to Listings without writing anything. If a status change fails directly from a row, the row reverts to its previous status and reports the failure with retry.

Flow D — An Adopter browses without committing

1. Starting context. A visitor with no account and no intention of signing up opens the site.
2. On Landing, they read what the site is for and tap Meet the cats.
3. On Cats, they browse the grid and apply filter chips. If nothing matches, the empty state offers a one-tap clear-filters action rather than leaving them stuck.
4. They open several cats in turn on Cat Details, reading each one's photograph and story, and moving on to another cat from there.
5. Observable result. They have met the cats and understood what the site is for, without ever being asked for an account.
6. Continuation. They leave, or return later and begin Flow A when a cat finally finds them.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. Its muse is Pablo Stanley, and its headline idea is cat adoption as an illustrated welcome mat — warm, human, a little funny. The direction is applied as concrete tokens below.

Colour tokens — light mode.

The pastel support set is used only as illustration fills and section-block backgrounds, never as text grounds. Proportion across the site: 60% cream/white, 25% illustration pastels, 10% tangerine, 5% teal.

Typography.

• Headings — Nunito. 800 weight for headlines, 700 for subheads. Set in sentence case, never all-caps. Line-height 1.1 for display, 1.3 for subheads, so the rounded terminals read as friendly rather than shouty. Display clamp(44px, 9vw, 104px); section headings clamp(30px, 4.5vw, 52px); card titles 22–26px.
• Body — DM Sans. 1.333 modular scale: 104 / 78 / 52 / 32 / 24 / 18 / 16 / 14. Body copy at 17–18px with 1.6 line-height for a roomy, conversational read. Labels and chips at 14px with 0.02em tracking.

Shape language. Big soft radii everywhere: 28px on cards, 999px on buttons and chips, 40px on hero illustration frames. Blob and sticker shapes serve as section dividers and behind-copy accents. Cards carry a soft offset shadow — 0 8px 0 rgba(43,33,24,0.08) — rather than a blurred drop shadow, so they feel printed and tactile. Buttons are pills with a 2px solid ink or tangerine border and a 4px bottom offset that compresses on press. Hand-drawn squiggles, dotted paths and small star/tail flourishes sit between sections.

Layout. Mobile-first single column at 375px, expanding to a 12-column grid at 1280px with a max content width of 1180px and 24px gutters. The landing hero is asymmetric: illustration left, oversized headline and CTA stacked right, with a wavy divider into the cat grid. Cats is a responsive card grid — 1 column at 375px, 2 at 768px, 3 at 1280px — with filter chips that wrap rather than scroll. Cat Details is a two-column split at 1280px (photo left, story and Interest CTA right) that stacks to one column on mobile. Manager pages (Listings, Listing Edit) keep the same cream ground and pill controls but use a tighter 8-pt spacing rhythm and a left rail of listing rows at 1280px, collapsing to a stacked list at 375px. Every headline, label, number and control sits fully inside its container at all three widths; long cat names wrap rather than truncate.

Imagery. Modular vector illustration is the lead voice: rounded, flat, hand-built cats and people in the pastel support palette, with simple faces and a little humour — a cat sleeping on a laptop, a person kneeling to meet a cat at eye level. Real cat photography appears inside listing cards and on Cat Details as the emotional payoff: warm, natural-light photos on cream or pastel backgrounds, never stock-office imagery. Icons are chunky, 2px-stroked rounded pictograms. No gradient blobs, no glassmorphism, no 3D renders.

Explicitly avoided. Blue–indigo primary or accent colours (#0057FF, #2563EB, #6366F1 and neighbours) on white grounds; Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins or system-ui for headings or body; gradient-blob heroes, glassmorphism panels and blurred gradient backgrounds; a grid of identical hover-lift cards with blurred drop shadows; photography-heavy or stock-office heroes; all-caps display headlines and tight, aggressive tracking; truncated cat names, clipped labels or any readable text running off its container at 375px; confetti, bouncy easing or motion without a prefers-reduced-motion static alternative. The generic indigo/blue-on-white SaaS template is forbidden for this project.

7. Signature Design Concept

The welcome mat. The public entry is built as an illustrated welcome mat: a cream ground, a hand-built vector scene of a person crouching with an outstretched hand and a cat stepping forward to meet it, and an oversized rounded headline that talks like a person.

The hero is a two-part asymmetric composition on #FFF8EE.

• Left 55%. The vector illustration scene, framed in a 40px-radius pastel butter (#FFD9A0) block that bleeds off the left edge of the viewport. The cat steps forward; the person's hand is outstretched. This is the site's whole thesis in one image — meeting, not applying.
• Right 45%. A stacked headline in Nunito 800 at display size clamp(44px, 9vw, 104px), reading "Find the cat who finds you." with the word cat set in tangerine (#F26B3A) — the only colour in the type. Beneath it, a single line of DM Sans body copy, then a pill CTA Meet the cats in tangerine with an ink outline and a 4px bottom offset shadow.
• The connector. A thin dotted hand-drawn path curves from the illustration into the headline area, then loops through the wavy section divider and reappears on Cats as the connector between cat cards. It is the same gesture carried across the site, tying the welcome mat to the catalog.

No centred stack, no blue button, no gradient blob. The headline breaks across two lines at desktop and runs as one long line at 375px, wrapping rather than clipping. The concept recomposes only accepted content, states and controls — the hero's CTA leads to Cats, and the sign-in routes lead to Sign Up and Login. It introduces no new behaviour, page or destination.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief.

• Focal subject. The hand-built vector scene of a person crouching with an outstretched hand and a cat stepping forward to meet it, framed in a 40px-radius butter block bleeding off the left viewport edge.
• Input → transformation → outcome thesis. On first view, the illustration's characters wave or blink, and the cat takes its step forward as the dotted path draws itself from the illustration into the headline area. The visitor's eye is carried along that path to the headline and then to the Meet the cats pill — the motion's outcome is that the visitor knows exactly where to go next. The motion uses only accepted behaviour: it leads to Cats.
• Motion vocabulary. Expressive but purposeful. Illustration characters wave or blink on first view; cards lift 4px and their printed shadow compresses from 0 8px 0 to 0 3px 0 on hover; filter chips pop with a 120ms spring; section headings reveal with a 16px rise and fade as they enter the viewport; the interest-submitted state plays a short confetti-of-paw-prints burst.
• Composed first frame. Cream ground, butter block bleeding off the left edge with the illustration composed and still, the oversized Nunito 800 headline fully legible with cat in tangerine, the dotted path already curving into the headline area, and the tangerine pill CTA with its ink outline and 4px offset shadow sitting fully inside its container. Nothing is mid-animation in the first frame; the composition reads completely before any motion begins.
• Reduced-motion state. Under prefers-reduced-motion, all decorative motion is disabled: characters do not wave or blink, the path does not draw itself, cards do not lift, chips do not spring, headings do not rise, and the paw-print burst does not play. The layout is static, fully usable, and identical in hierarchy — the same hero, the same headline, the same CTA, the same path drawn in its final position.

No user-requested 3D or WebGL was specified, and the direction's hero dimensionality is layered_2d, so no Canvas/R3F/Drei scene is required.

9. Non-Functional Requirements

NFR-1 — Responsive integrity at three widths (explicit, from the creative direction) Every headline, wordmark, label, number, card's text and control stays entirely inside the viewport and its container at 375px, 768px and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit. No other element covers any part of them. Long cat names wrap rather than truncate. Rationale: the direction states this as a hard readability rule, and the audience browses on phones.

NFR-2 — Reduced-motion accessibility (explicit, from the creative direction) Under prefers-reduced-motion, all decorative motion is disabled, leaving a static, fully usable layout with the same hierarchy. Rationale: the direction requires a static alternative for every decorative motion, including the paw-print burst.

NFR-3 — Availability is not signalled by colour alone (required_inference) Availability status is stated in words as well as in teal on Cats, Cat Details, Interest and Listings. Rationale: availability governs whether an adopter can act, so it must be readable without relying on colour perception.

NFR-4 — Durable, correctly bound state (explicit, from the planning scope) Cat listings, adopter accounts, manager accounts and adoption-interest records persist across sessions. An adoption interest remains bound to the adopter who expressed it and to the specific cat it concerns, so a returning adopter sees their own commitment accurately and no adopter can act on another's. Rationale: the accepted journeys require resumable, correctly attributed state.

NFR-5 — Protected destinations require verified identity (required_inference) Interest, Listings and Listing Edit are reachable only by a verified account of the correct kind. Landing, Sign Up, Login, Cats and Cat Details are reachable anonymously. Rationale: expressing interest is a durable adopter-specific commitment, and listing administration is provisioned work; neither can be left open.

NFR-6 — Credential failures do not disclose account existence (required_inference) Login returns one generic failure message for rejected credentials and does not reveal whether an account exists. Rationale: the verification surface is anonymous and must not become an account-enumeration oracle.

NFR-7 — No dead ends (required_inference) Every failure and empty state offers a route forward: retry, clear filters, return to Cats, or return to Listings. Rationale: the accepted journeys each require a continuation, and the direction's low-pressure register is broken by a stuck screen.

NFR-8 — Entered values survive failure (required_inference) A failed Sign Up, Interest or Listing Edit submission preserves every value the person entered and offers retry. Rationale: losing a written note or a completed listing form would make the accepted journeys unusable in practice.

NFR-9 — Single application backend (required_inference) The site is served by one application backend that owns listings, identity records and adoption-interest records, alongside the custom web frontend. Rationale: the accepted scope is a single cohesive product with no independent worker, queue or third-party service requirement.

10. Tech Stack

No technology choices were stated by the user. The following are the minimal, coherent defaults for the accepted scope, labelled as defaults.

• Frontend — React web application, mobile-first, responsive at 375px / 768px / 1280px. [Default — not specified by user]
• Backend — Python with FastAPI, serving the catalog, identity, and adoption-interest APIs from a single application service. [Default — not specified by user]
• Storage — a relational database for cat listings, adopter accounts, manager accounts and adoption-interest records, with object storage for cat photographs. [Default — not specified by user]
• Local orchestration — Docker and docker-compose for the frontend, backend and database. [Default — not specified by user]
• Kubernetes — not included; the accepted scope does not require it. [Default — not specified by user]

Preserved source choices. The visual and brand source is the image supplied by the user, applied through the creative direction in sections 6–8. No other technology was specified.

11. Assumptions and Constraints

Assumptions.

• A-1. The user-supplied image is available as the visual and brand source for the site's look and feel. It carries no textual content, factual entities or metadata, so no content is imported from it. (explicit)
• A-2. Cat listings — photographs, names, stories and attributes — are authored by Shelter / Listing Managers through Listing Edit rather than imported from any source. (required_inference)
• A-3. Adopters self-enroll; Shelter / Listing Managers are provisioned. Neither persona self-selects the other's access. (required_inference)
• A-4. An adopter may express interest in more than one cat over time, and may withdraw an interest they have expressed. (required_inference)
• A-5. The site is delivered as a responsive web application; no native mobile application is in scope. (required_inference)

Constraints.

• C-1. The site must be a website for adopting cats. (explicit)
• C-2. The site's look and feel must follow the image the user supplied. (explicit)
• C-3. The palette, typography, shape language, layout and motion in sections 6–8 are binding, including the explicit avoid list. The generic indigo/blue-on-white SaaS template is forbidden. (explicit)
• C-4. Readable text and controls stay whole at 375px, 768px and 1280px; imagery and decoration may be cropped, bled, rotated or overlapped, but never over readable text or a control. (explicit)
• C-5. All decorative motion has a prefers-reduced-motion static alternative. (explicit)
• C-6. Interest, Listings and Listing Edit are protected; Landing, Sign Up, Login, Cats and Cat Details are anonymous. (required_inference)
• C-7. No adoption-application processing, messaging threads, payment or fee handling, transport or logistics, medical records, foster workflows, or account-management capability beyond first-use enrollment and returning verification is in scope. (explicit exclusion)
• C-8. No future-horizon requirements were stated. (explicit)

12. Glossary

• Adopter — the accepted persona who browses cats available for adoption, reviews a specific cat, enrolls or signs in, and expresses or withdraws interest in adopting a cat.
• Adoption interest — the durable record created when a signed-in Adopter expresses interest in adopting a specific cat. Bound to that adopter and that cat, with an optional short note and the time expressed, and withdrawable by that adopter.
• Availability status — whether a cat is currently available for adoption. Shown publicly in words and in teal, and set by a Shelter / Listing Manager. Governs whether an Adopter can express interest.
• Cat listing — the record of one cat offered for adoption: photograph, name, story, attributes and availability status. Authored and maintained by a Shelter / Listing Manager.
• Shelter / Listing Manager — the accepted persona responsible for keeping the site's cat listings current, with provisioned access to Listings and Listing Edit.
• Provisioning — the way a Shelter / Listing Manager receives access, as distinct from the self-service enrollment an Adopter uses.
• Printed shadow — the site's card shadow, 0 8px 0 rgba(43,33,24,0.08), which compresses to 0 3px 0 as the card lifts 4px on hover, giving cards a tactile, printed feel rather than a blurred drop shadow.
• Welcome mat — the signature design concept for the public entry: a cream ground, a hand-built vector scene of a person and a cat meeting, an oversized rounded headline, and a dotted hand-drawn path that carries the eye from the illustration to the CTA and onward through the site.