System Requirements Document for gemini-nexus

1. Introduction

gemini-nexus is a conversational AI chatbot product. The product intent, taken directly from the authoritative requirement thread, is to build a chatting AI chatbot with a modern look — a chat experience where a person types messages to an AI assistant and reads its replies, presented in a contemporary, motion-first interface rather than a conventional form-like chat template.

The audience is a broad consumer/prosumer audience: people who want intelligence on demand through natural conversation. The emotional register the product must hit is futuristic curiosity — talking to something that feels alive and advanced.

The product name gemini-nexus was chosen by the user and is the canonical product name.

2. System Overview

gemini-nexus is delivered as a first-party custom web application with two pages:

• Landing — an anonymous public entry surface that introduces the chatting AI chatbot and its modern chat experience before the user begins a conversation.
• Chat — the primary conversation workspace where the Chat User sends messages to the AI chatbot and reads its replies.

Both pages are application-owned and require no account or sign-in. The Chat User can open the product and begin conversing immediately; there is no identity establishment, invitation, or provisioning step in the current scope.

The product requires backend integration: submitted chat messages must be answered by AI response generation. The AI response generation capability is a required inference — it is the indispensable mechanism that makes the accepted chat journey executable. It does not introduce a separate user-invoked goal.

The interface is the product's imagery. There is no stock photography, no flat illustration, and no conventional white-card chat surface. The assistant is represented as a real-time refractive 3D orb, and the conversation is rendered as two distinct signals: assistant text streaming bare on the dark ground with a luminous cyan caret, and user messages as magenta-edged glass capsules aligned right.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. gemini-nexus is a first-party custom UI application. Both the Landing and Chat surfaces are owned and rendered by the application itself. The application owns the conversation workspace, the composer, the message stream rendering, and the visual presentation of the assistant.

Access ownership. Both accepted pages are publicly reachable with no access requirement. The Chat User does not create an account, sign in, or establish an identity to use the product. There is no application-owned identity, no session-bound private state, and no permission differentiation in the current scope. Conversation state is held for the duration of the user's visit to the Chat workspace; the product does not promise durable cross-visit conversation history.

AI response ownership. AI response generation is a backend capability that the application integrates. The Chat User's interaction with it is entirely through the Chat page: they submit a message and observe the streamed reply. The backend is not a human-facing destination and does not own any user interaction.

Current boundary. Current scope is: the Landing entry surface, the Chat conversation workspace, message submission, AI response generation and streaming, and the modern cinematic visual and motion system described in the creative direction.

Future boundary. Anything not listed above — including durable conversation history across visits, user accounts, multi-conversation management, model selection by the user, and sharing — is out of current scope and is not built, not navigable, and not part of current acceptance.

2c. Page Content and Component Coverage

Landing

• Information and state: The Landing page is an anonymous public entry surface. It presents the product's identity and its modern chat experience before the user begins a conversation. It holds no user-specific state and no conversation state.
• Primary action: Enter the chat experience and begin a conversation, which navigates the Chat User to the Chat page.
• Supporting actions: Scroll to explore the hero presentation; the scroll cue indicates further content below the fold.
• Domain entities: Product identity (gemini-nexus), the assistant orb as the visual representation of the AI, and the composer capsule as a preview of the conversation entry point.
• Component responsibilities:
  • Hero orb — a full-bleed real-time refractive 3D orb (≈55vw, positioned right-of-centre, cropped by the top and right edges) that glows cyan-to-magenta and drifts continuously. It is the assistant's visual body and the page's focal subject.
  • Hero headline — a 9-column, flush-left headline in Space Grotesk 600 at ~100px reading "TALK TO SOMETHING THAT THINKS", with the word "THINKS" set in outlined cyan stroke, sitting directly over the orb so type and 3D subject occupy the same space.
  • Composer capsule — a single-line glass capsule with a 1px cyan border and the placeholder "Ask anything…", with a magenta send node. It is the entry affordance into the conversation.
  • HUD block — a top-left 3-line block in JetBrains Mono 11px uppercase (MODEL / LATENCY / TOKENS) separated by 1px cyan rules, establishing the instrumented tone.
  • Scroll cue — a thin cyan vertical line at bottom-right that pulses downward.
• States:
  • Loading: the orb initializes; the page renders its dark ground and typography immediately while the 3D subject comes up.
  • Empty: not applicable — the Landing page has no user-populated content.
  • Success: the hero renders with the orb drifting, the headline legible over it, and the composer capsule available for entry.
  • Error / recovery: if the real-time 3D subject cannot initialize, the page retains its dark ground, headline, HUD block, and composer capsule so the Chat User can still enter the conversation; the orb degrades to a static luminous form rather than blocking entry.
  • Reduced motion: the orb's orbit freezes; the page remains fully usable and the composer capsule remains available.

Chat

• Information and state: The Chat page is the primary conversation workspace. It holds the current conversation: the ordered sequence of the Chat User's submitted messages and the assistant's replies. It also holds generation state — whether the assistant is currently producing a reply — and HUD instrumentation values (model name, latency, token count).
• Primary action: Submit a chat message to the AI chatbot and read the streamed reply.
• Supporting actions: Type into the composer; observe the assistant's streaming response; observe the orb's generation state; read HUD instrumentation.
• Domain entities: Conversation, message (with a role of user or assistant), message content, generation state, and HUD metrics (model, latency, tokens).
• Component responsibilities:
  • Left rail (72px, fixed) — holds the orb, the session list, and HUD stats. It is the persistent instrument column.
  • Assistant orb — the assistant's body. It continuously slow-orbits and breathes on a 60–90s loop. It brightens and its inner particles accelerate while the model is generating, then settles when the reply completes.
  • Conversation stage — the right region occupying the remaining viewport, holding the asymmetric message column.
  • Assistant message — bare text on the dark ground with a glowing cyan caret, no bubble, streamed token-by-token with a subtle particle trail behind each arriving token.
  • User message — a magenta-edged glass capsule aligned right.
  • Composer — a pill capsule for message entry, with a magenta send node.
  • Signal path — a 1px cyan connector line running from the composer to the orb. On send, a light sweep travels along it and the orb pulses once.
  • HUD strips — 1px-ruled rows along the top of the stage in JetBrains Mono 11px uppercase with 0.18em tracking (MODEL · LATENCY · TOKENS).
• States:
  • Loading: the Chat workspace initializes its dark ground, rail, HUD strips, and composer; the orb comes up as the assistant's body.
  • Empty: no messages yet. The conversation stage shows the bare dark ground with the orb present and the composer ready; the Chat User can type immediately.
  • Success: the submitted message appears as a right-aligned magenta-edged capsule, the light sweep travels the signal path, the orb pulses and brightens, and the assistant's reply streams token-by-token with a luminous cyan caret until complete, after which the orb settles.
  • Error / recovery: if AI response generation fails or is unavailable, the Chat User's submitted message remains visible in the conversation, the generation state ends, and the composer remains available so the Chat User can submit again. The failure is surfaced in the conversation stage rather than silently dropping the turn.
  • Reduced motion: the orb's orbit freezes and the particle trail is suppressed; the streaming caret is retained so the Chat User can still see the reply arriving.

3. Functional Requirements

FR-1 — Chat with an AI chatbot As a Chat User, I should send messages to an AI chatbot and read its replies, so that I can hold a conversation with an AI.

• Provenance: explicit
• Actor: Chat User
• Trigger / input: the Chat User types a message into the composer on the Chat page and submits it.
• Observable result / state change: the submitted message appears in the conversation as a right-aligned magenta-edged glass capsule; the assistant's reply appears in the conversation as bare text on the dark ground with a glowing cyan caret, streamed token-by-token until complete.
• Access state: no access requirement — the Chat page is publicly reachable.
• Material failure / recovery: if AI response generation fails or is unavailable, the Chat User's message remains visible, the generation state ends, and the composer remains available for another submission.
• Continuation: after the reply completes, the Chat User can submit another message and continue the conversation.
• Acceptance: a submitted message is visibly recorded in the conversation and a corresponding assistant reply is visibly produced in the conversation.

FR-2 — Modern chat interface As a Chat User, I should experience the chatbot through a modern-looking interface, so that the product feels like talking to something alive and advanced rather than filling in a form.

• Provenance: explicit
• Actor: Chat User
• Trigger / input: the Chat User opens the Landing page or the Chat page.
• Observable result / state change: the interface renders on a deep near-black navy ground (#05060E) with lifted panel surfaces (#0E1122), electric cyan (#00E5FF) as the assistant/primary glow, magenta (#FF3DF2) as the human/user signal, cool white (#EAF0FF) body text, and muted steel (#7A85A8) metadata; the assistant is represented by a real-time refractive 3D orb; assistant messages have no bubble and stream with a luminous cyan caret; user messages are magenta-edged glass capsules aligned right.
• Access state: no access requirement — both pages are publicly reachable.
• Material failure / recovery: if the real-time 3D subject cannot initialize, the interface retains its dark ground, typography, HUD block, and composer so the conversation remains usable.
• Continuation: the Chat User proceeds into the conversation from the Landing page or continues conversing on the Chat page.
• Acceptance: the rendered interface uses the specified dark palette, the specified type stack, the orb as the assistant's visual body, and the asymmetric two-signal message treatment.

FR-3 — AI response generation As a Chat User, I should receive an AI-generated answer to each message I submit, so that the conversation actually progresses.

• Provenance: required_inference
• Actor: Chat User (initiator); AI response generation (backend capability)
• Trigger / input: the Chat User submits a chat message on the Chat page.
• Observable result / state change: the assistant's reply is produced and streamed into the conversation stage; while generating, the orb brightens and its inner particles accelerate; when the reply completes, the orb settles.
• Access state: no access requirement — the Chat page is publicly reachable.
• Material failure / recovery: if generation fails or is unavailable, the generation state ends, the failure is surfaced in the conversation stage, and the Chat User's submitted message is not lost.
• Continuation: the Chat User reads the reply and can submit a further message.
• Acceptance: each submitted message results in an assistant reply rendered in the conversation, or a surfaced failure with the composer still available.

FR-4 — Enter the chat experience from the Landing page As a Chat User, I should be able to enter the chat experience from the Landing page, so that I can begin a conversation.

• Provenance: required_inference
• Actor: Chat User
• Trigger / input: the Chat User activates the composer capsule on the Landing page.
• Observable result / state change: the Chat User arrives at the Chat page with the conversation workspace ready and the composer available.
• Access state: no access requirement — the Landing page is anonymously reachable and the Chat page requires no identity.
• Material failure / recovery: if the 3D hero subject fails to initialize, the composer capsule remains available and entry still succeeds.
• Continuation: the Chat User types and submits their first message.
• Acceptance: activating the Landing composer capsule brings the Chat User to the Chat page with the composer ready for input.

4. User Personas

Chat User

Product context. The Chat User is the primary and only active human actor in gemini-nexus. They arrive at the product wanting intelligence on demand — to ask something and get an answer — without setup, sign-in, or configuration. They may arrive cold on the Landing page or go directly to the Chat workspace. They are a broad consumer/prosumer user, not a specialist operator; they judge the product by whether the conversation feels immediate, coherent, and alive.

Primary goal. Hold a conversation with the AI chatbot: send messages, receive coherent AI responses, and continue the exchange.

Distinct accepted responsibilities.

• Entering the chat experience from the Landing page.
• Composing and submitting chat messages in the Chat workspace.
• Reading the assistant's streamed replies as they arrive.
• Deciding what to ask next based on the reply received.
• Recovering from a failed or unavailable generation by submitting again.

Relevant inputs and decisions. The Chat User's inputs are their own typed messages. Their decisions are what to ask, when to submit, and whether to continue the conversation after reading a reply. They make no configuration, model-selection, or account decisions — none are in scope.

Interactions with other accepted participants. The Chat User's only counterparty is the AI assistant, which is not a human persona. The assistant's side of the exchange is expressed as observable product behaviour: the orb brightening and accelerating while generating, the reply streaming token-by-token with a luminous cyan caret, and the orb settling when the reply completes. The Chat User reads the assistant's reply and responds to it in turn.

Observable success. The Chat User submits a message and sees it recorded in the conversation as a right-aligned magenta-edged capsule; the assistant's reply streams into the conversation as bare text with a cyan caret; the orb visibly signals generation and then settles; the Chat User can immediately submit another message.

What makes this role's work different. The Chat User's work is conversational turn-taking, not task execution or administration. There is no data to manage, no configuration to set, and no state to own beyond the live conversation. Their entire responsibility is to initiate turns and read responses — which is why the product's visual and motion system carries the assistant's presence rather than any control surface.

5. Core User Flows

Flow 1 — Enter the chat experience from the Landing page

1. The Chat User opens gemini-nexus and lands on the Landing page. No account or sign-in is required.
2. The Landing page renders its full-viewport dark void (#05060E). The hero orb — a real-time refractive 3D sphere, ≈55vw, positioned right-of-centre and cropped by the top and right edges — glows cyan-to-magenta and drifts. The 9-column headline "TALK TO SOMETHING THAT THINKS" sits flush-left at ~100px in Space Grotesk 600, with "THINKS" in outlined cyan stroke, directly over the orb. A top-left HUD block in JetBrains Mono 11px uppercase shows MODEL / LATENCY / TOKENS separated by 1px cyan rules. A thin cyan vertical scroll cue pulses downward at bottom-right.
3. The Chat User reads the headline and sees the composer capsule — a single-line glass capsule with a 1px cyan border, the placeholder "Ask anything…", and a magenta send node.
4. The Chat User activates the composer capsule.
5. Observable result: the Chat User arrives at the Chat page. The conversation workspace is ready: the fixed 72px left rail holds the orb, the session list, and HUD stats; the HUD strips (MODEL · LATENCY · TOKENS) run as 1px-ruled rows along the top of the stage; the conversation stage is empty dark ground; the composer is available.
6. Failure / recovery: if the real-time 3D subject cannot initialize on the Landing page, the dark ground, headline, HUD block, and composer capsule still render, and entry into the Chat page still succeeds.
7. Next step: the Chat User types their first message (Flow 2).

Flow 2 — Hold a conversation with the AI chatbot

1. The Chat User is on the Chat page with the composer available. The conversation stage is empty dark ground with the orb present in the left rail, slowly orbiting and breathing on its 60–90s loop.
2. The Chat User types a message into the composer pill capsule.
3. The Chat User submits the message via the magenta send node.
4. Observable result (user's turn): the submitted message appears in the conversation as a magenta-edged glass capsule, aligned right. A light sweep travels along the 1px cyan signal path from the composer to the orb, and the orb pulses once.
5. Observable result (assistant's turn): the orb brightens and its inner particles accelerate, signalling that the model is generating. The assistant's reply streams into the conversation stage as bare text on the dark ground — no bubble — with a glowing cyan caret advancing token-by-token and a subtle particle trail behind each arriving token. The HUD strips update with model, latency, and token values.
6. When the reply completes, the orb settles back to its resting orbit and the cyan caret stops.
7. Failure / recovery: if AI response generation fails or is unavailable, the generation state ends, the failure is surfaced in the conversation stage, and the Chat User's submitted message remains visible. The composer stays available.
8. Continuation: the Chat User reads the reply and decides what to ask next. They type and submit another message, returning to step 3. The conversation continues as an alternating sequence of right-aligned magenta user capsules and left-aligned bare assistant text with cyan carets.
9. Reduced motion: if the Chat User's system requests reduced motion, the orb's orbit freezes and the particle trail is suppressed; the streaming cyan caret is retained so the reply is still visibly arriving.

Flow 3 — Recover from a failed generation

1. The Chat User is on the Chat page and has submitted a message.
2. AI response generation fails or is unavailable.
3. Observable result: the generation state ends — the orb stops signalling generation and settles. The failure is surfaced in the conversation stage. The Chat User's submitted message remains visible in the conversation as a right-aligned magenta-edged capsule; it is not silently dropped.
4. The composer remains available and the Chat User's typed context is not lost.
5. Continuation: the Chat User submits again, returning to Flow 2 step 3. If generation succeeds, the reply streams normally.

6. Visuals, Colors and Theme

The creative direction is authoritative for this section. Muse: Gleb Kuznetsov. Headline concept: a conversation inside a living data space — cinematic future tech, where the assistant is an intangible luminous intelligence and the chat stream is a data stream.

Color tokens (dark mode)

Color rules. Electric cyan (#00E5FF) is the assistant/primary glow — used for the AI orb, the streaming cursor, focus rings, and active states. Magenta (#FF3DF2) is the human/user signal and appears only in the user's own message rail, the send button, and one gradient stop of the orb. Body text is cool white (#EAF0FF); metadata and timestamps use muted steel (#7A85A8). Glows are always low-opacity (8–20%) so text contrast stays above 4.5:1 — never place body copy directly on a glow.

Typography

• Headings: Space Grotesk. Wide geometric grotesk. Uppercase for micro-labels at 11–12px with 0.18em tracking. Hero headline at 600 weight, tight −0.02em tracking, sized 72–120px so it spans the viewport.
• Body / chat text: Space Grotesk at 400 weight, 16–17px, 1.6 line-height.
• Data and token counters: JetBrains Mono at 12px uppercase for HUD labels.
• Type scale (1.333 modular): 96 / 72 / 48 / 32 / 24 / 17 / 14 / 12. Hero display 96–120px, section heads 48px, chat message 17px, HUD micro-label 11px.
• Forbidden type stack: Inter, Roboto, Arial, Helvetica, Poppins, or system-ui anywhere in the type stack.

Shape language

Full-bleed dark canvas with floating glass panels. 1px luminous borders at rgba(0,229,255,0.25). 16–24px radii on panels. Pill capsules for message bubbles and the composer. Thin concentric rings and radial tick marks around the assistant orb. Hairline circuit-like connector lines (1px, cyan at 20% opacity) linking the composer to the orb to imply a live signal path. No hard drop shadows — depth comes from glow bloom and layered translucency.

Layout

Split-stage layout: a fixed left rail (72px) holding the orb, session list, and HUD stats, and a right conversation stage occupying the remaining viewport. The orb sits top-left of the stage, half-cropped by the viewport edge. Messages flow in an asymmetric column — user messages right-aligned in a magenta-edged capsule, assistant messages left-aligned on bare dark ground with a cyan caret, no bubble. HUD strips (token count, latency, model name) run as 1px-ruled rows along the top of the stage. The Landing page uses the same grid with the orb promoted to full-bleed hero.

Imagery style

No stock photography, no flat illustration. The visual subject is a procedural 3D orb — a refractive, glowing volumetric sphere with an inner particle field and orbiting data rings, rendered in real time with React Three Fiber. Secondary imagery is generative: particle streams, thin luminous wireframes, topographic data lines. The interface itself is the imagery.

Avoid

White or near-white chat surfaces with blue/indigo user bubbles; centred headline + subheadline + blue CTA hero composition; gradient-blob backgrounds or animated mesh gradients behind the hero; a grid of identical rounded cards with hover-lift on the landing page; Inter, Roboto, Arial, Helvetica, Poppins, or system-ui anywhere in the type stack; flat vector robot/chat illustrations or stock photography of people at laptops; bouncy spring easings, emoji-heavy UI, or playful mascot characters; placing body copy directly on top of a glow or particle field without a darkened scrim. The generic indigo/blue-on-white SaaS template is forbidden for this project.

7. Signature Design Concept

The orb is the assistant's body, and the composer is wired to it.

The public entry is a full-viewport dark void (#05060E). A single large refractive orb — approximately 55vw, positioned right-of-centre and cropped by the top and right edges — glows cyan-to-magenta and drifts continuously. Over it, a 9-column headline in Space Grotesk 600 at ~100px sits flush-left reading "TALK TO SOMETHING THAT THINKS", with the word THINKS set in outlined cyan stroke. Type and 3D subject occupy the same space; the headline is not stacked above the orb but laid across it.

Below the headline, a single-line composer capsule — glass, 1px cyan border, placeholder "Ask anything…" — carries a magenta send node. There is no subheadline, no blue button, and no gradient blob. Top-left, a 3-line HUD block in JetBrains Mono 11px uppercase (MODEL / LATENCY / TOKENS) is separated by 1px cyan rules. Bottom-right, a scroll cue is a thin cyan vertical line that pulses downward.

The concept is implementable with accepted content and controls only: the orb, the headline, the composer capsule, the HUD block, and the scroll cue. It introduces no new behaviour, page, or destination. The composer capsule is the same entry affordance that carries the Chat User into the Chat page; the HUD block previews the same instrumentation that runs above the conversation stage; the orb is the same assistant body that appears in the Chat rail.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: webgl

Landing Hero Motion Brief

Focal subject. The real-time refractive 3D orb — a glowing volumetric sphere with an inner particle field and orbiting data rings, rendered with React Three Fiber, positioned right-of-centre at ≈55vw and cropped by the top and right edges.

Input → transformation → outcome thesis. The Chat User's attention and scroll are the input. As they scroll the Landing page, the camera performs a dolly across the orb and its particle field, scrubbing the viewpoint through the volumetric form. The outcome is that the Chat User arrives at the composer capsule having moved through the assistant's body rather than past a static image — the assistant reads as a place, not a picture. The composer capsule remains the single accepted entry control throughout.

Motion vocabulary. Cinematic and continuous. The orb slow-orbits and breathes on a 60–90s loop. Particle streams drift within and around it. Thin luminous wireframes and topographic data lines move at low opacity. Hairline circuit-like connector lines (1px, cyan at 20% opacity) imply a live signal path. Hover on any panel raises its border glow from 20% to 45% over 220ms with no lift. No b