System Requirements Document for sparx-reader

1. Introduction

Sparx Reader is a reading-assistance bot. It exists so that a learner who is working through reading material — during homework, quiet study, or independent reading practice — has a patient companion that stays with them inside the text rather than sending them away to a dashboard. A reader brings reading material or a reading question to the bot and receives assistance in the same conversation.

The product serves two audiences. Readers are students and learners who want reading practice or help with reading tasks. Bot Operators are the people who set up and run the bot so that readers can use it: they configure the bot's behaviour and maintain the reading-assistance content it draws on.

The register of the product is deliberately calm and slightly private. It is closer to a well-set book than to a dashboard: text is the product, and the interface is built to respect it. The emotional job is confidence and momentum — the reader should feel accompanied, not audited.

2. System Overview

Sparx Reader is delivered as a first-party web application with application-owned identity and custom UI. It comprises five pages:

• Landing — an anonymous public entry surface that explains Sparx Reader and introduces its reading-assistance purpose before any identity establishment or protected work.
• Login — a shared returning-verification surface for readers and bot operators who need continued access to their protected application journeys.
• Sign Up — a self-service enrollment surface providing a truthful first-use path for readers independently beginning to use Sparx Reader.
• Reader Chat — the conversation workspace where a reader sends reading-related requests or material and receives assistance in the same conversation.
• Bot Settings — the operator workspace for setting up and maintaining the Sparx Reader bot's behaviour and reading-assistance content.

Actors. Two active human personas use the product: the Reader and the Bot Operator. The bot itself is a system actor, not a persona; it produces assistance inside Reader Chat and is configured through Bot Settings.

Accepted behaviour. The bot provides reading assistance to users. Readers enroll themselves, verify on return, and conduct reading conversations. Bot Operators are invited or provisioned before they can reach operator-only bot configuration, and they verify on return like readers.

Ownership. All five pages are application-owned custom pages. Landing, Login, and Sign Up are anonymously reachable. Reader Chat and Bot Settings are role-restricted to their respective personas. The bot's reading-assistance behaviour is application-owned and executed by the system; it has no separate human-facing surface of its own.

Narrow exclusions. This document does not introduce grading, assessment scoring, class rosters, teacher dashboards, progress analytics, social or sharing features, content marketplaces, or any adjacent education-platform capability. Nothing in the accepted requirements calls for them.

2a. Product Interpretation and Delivery Boundary

Sparx Reader is delivered entirely as a first-party web application. There is no provider-owned surface, no external destination, and no headless delivery mode in the accepted scope. Every human-facing interaction happens on an application-owned page.

Access is split across two boundaries. The anonymous boundary covers Landing, Login, and Sign Up: a visitor can read what Sparx Reader is, a returning reader or operator can verify, and a new reader can enroll — all without being signed in. The protected boundary covers Reader Chat and Bot Settings: these hold durable, actor-specific state (a reader's conversation history; the operator's bot configuration) and therefore require an established identity before they can be used. A protected destination never owns the interaction that establishes access to itself; Login and Sign Up are the anonymous entry points that do.

Identity is application-owned. Readers establish it themselves through Sign Up. Bot Operators do not self-enroll: they are invited or provisioned before they can reach operator-only bot configuration. Both personas verify on return through the shared Login surface.

Current horizon. Everything described in this document — the bot's reading assistance, reader self-service enrollment, returning verification for both personas, operator invitation or provisioning, Reader Chat, and Bot Settings — is current.

Future horizon. No future requirements have been accepted. Nothing is deferred.

2b. Source Content Inventory

No reference directive in this project declares content_source. There is no verified factual inventory to preserve, and none is invented here.

2c. Page Content and Component Coverage

Landing

• Information and state. Anonymous public entry. Presents Sparx Reader's identity and reading-assistance purpose. No user-specific state is held; the page is identical for every visitor.
• Primary action. "Start reading" — a single rust primary button that leads an unenrolled visitor into Sign Up.
• Supporting action. "I already have an account" — an ink hairline text link beside the primary button that leads a returning reader or operator into Login.
• Domain entities. None. Landing reads no reader, conversation, or configuration data.
• Component responsibilities.
  • Hero essay opener. Left two-thirds: a small-caps eyebrow reading SPARX READER · READING ASSISTANCE, a 1px ink rule running the full viewport width beneath it, then an oversized Literata headline spanning the full reading column and wrapping to 2–3 lines at clamp(2.75rem, 7vw, 6rem). Beneath the headline, one paragraph at a 62–68ch measure, then the primary button and the hairline text link.
  • Hero illustration. Right one-third, bleeding slightly off the right edge: a warm flat illustration of an open book with a small ink bird perched on the page, mustard highlights on the text lines, drawn on cream with no frame.
  • Chapter rail. Left rail carrying the section number 01 in tabular Literata over a small-caps section label and a hairline ink rule.
  • Essay-opener sequence. Below the hero, a repeating sequence of full-width illustrated rule → headline → paragraph → illustration plate, with one deliberate full-bleed illustration between sections. Each section carries its own chapter number (02, 03, …) in the left rail.
  • Right margin. Marginalia column holding pull quotes, spot illustrations, and tip notes.
• States.
  • Loading. Static content; no loading state is required. If illustrations are deferred, the text column renders first and the illustration area holds its reserved space so no readable text reflows.
  • Empty. Not applicable — the page has no data-driven collections.
  • Success. The visitor understands what Sparx Reader is and chooses either "Start reading" or "I already have an account".
  • Error. Not applicable — no data operation is performed on this page.
  • Recovery. Not applicable.

Login

• Information and state. Anonymous shared returning-verification surface for both Readers and Bot Operators. Holds only the in-progress credential entry; no protected state is displayed before verification succeeds.
• Primary action. Submit credentials to verify and continue to the persona's protected journey.
• Supporting action. A hairline text link to Sign Up for a visitor who has not yet enrolled as a reader.
• Domain entities. Account identity (the credential record that binds a returning person to their reader or operator role).
• Component responsibilities.
  • Chapter rail. Section number and small-caps label over a hairline ink rule, consistent with every other page.
  • Headline. Literata headline set as a chapter title, sentence case, no all-caps.
  • Credential fieldset. Grouped fields with hairline rules, label above value, 4px radii on inputs, 1px warm-grey borders.
  • Primary submit. One rust button with a 2px offset ink shadow that compresses to 0px on press.
  • Route continuation. On success, the verified person continues to the protected journey that matches their role — Reader Chat for a reader, Bot Settings for an operator.
• States.
  • Loading. Submit button enters a pending state while verification is in flight; the form remains legible and the fields are not cleared.
  • Empty. The form renders with empty fields and no error text.
  • Success. Verification succeeds and the person is taken to their role's protected destination.
  • Error. Verification fails. A plain-language message appears in the muted metadata colour adjacent to the fieldset, the entered identifier is preserved, and the credential field is cleared for re-entry. No protected state is revealed.
  • Recovery. The person may retry immediately, or follow the link to Sign Up if they have not enrolled as a reader.

Sign Up

• Information and state. Anonymous self-service enrollment for Readers. Holds only the in-progress enrollment entry. Bot Operators do not enroll here; they arrive through invitation or provisioning.
• Primary action. Create a reader account and continue into Reader Chat.
• Supporting action. A hairline text link to Login for a visitor who already has an account.
• Domain entities. Reader account identity — the durable record that lets a reader's conversations remain bound to them across sessions.
• Component responsibilities.
  • Chapter rail. Section number and small-caps label over a hairline ink rule.
  • Headline. Literata headline set as a chapter title, sentence case.
  • Enrollment fieldset. Grouped fields with hairline rules, label above value, 4px radii, 1px warm-grey borders.
  • Primary submit. One rust button with the 2px offset ink shadow that compresses on press.
  • Continuation. On success, the new reader continues directly into Reader Chat.
• States.
  • Loading. Submit button enters a pending state while the account is created; fields remain legible and populated.
  • Empty. The form renders with empty fields and no error text.
  • Success. The reader account is created, the reader is verified, and they continue into Reader Chat.
  • Error. Enrollment fails — for example, the chosen identifier is already in use or a required field is missing. A plain-language message appears in the muted metadata colour, the entered values are preserved except where the failure makes a value unusable, and the reader may correct and resubmit.
  • Recovery. The reader may retry, or follow the link to Login if it turns out they already have an account.

Reader Chat

• Information and state. Protected conversation workspace, restricted to the Reader role. Holds the reader's conversation with the bot: the sequence of reader turns and bot turns, plus the margin column's current passage, saved highlights, and suggested prompts. Conversation history is durable and bound to the reader's identity so it can be resumed on return.
• Primary action. Send a reading-related request or reading material to the bot and receive assistance in the same conversation.
• Supporting actions. Select a suggested prompt from the margin column; save a highlight from the current passage; open a saved highlight; bring a passage into the margin column.
• Domain entities. Conversation; reader turn; bot turn; current passage; saved highlight; suggested prompt.
• Component responsibilities.
  • Chapter rail. Section number and small-caps label over a hairline ink rule.
  • Conversation pane (left, reading measure). Reader turns sit flush-left on cream with a 1px hairline and a small-caps YOU label. Bot turns sit on #FFFCF5 with a 3px mustard left border and a small-caps SPARX label, so the conversation reads as a two-column annotated text.
  • Margin column (right, ≥1024px). Holds the current passage, saved highlights, and three suggested prompts, separated from the conversation by a hairline vertical rule. Below 1024px the margin column becomes a horizontally scrollable strip beneath the composer.
  • Composer. The reader's input for a reading-related request or reading material, with one rust send button carrying the 2px offset ink shadow.
  • Bot response rendering. Bot turns render as printed passages on the brighter surface, with mustard rules marking quoted or annotated material.
• States.
  • Loading. While the bot is composing a response, a bot turn placeholder occupies its final position on #FFFCF5 with the mustard left border and the SPARX label, so the conversation does not jump when the response arrives. The composer remains usable.
  • Empty. A reader with no prior conversation sees an empty conversation pane with a short orientation line and the three suggested prompts in the margin column, so there is always a way to begin.
  • Success. The reader's turn appears flush-left on cream; the bot's assistance appears as a bot turn on the brighter surface. The reader can continue the conversation, save a highlight, or select a suggested prompt.
  • Error. The bot cannot produce assistance — for example, the request cannot be served. The failed bot turn is marked plainly in the muted metadata colour with a short explanation, the reader's original turn remains intact and readable, and the composer retains the reader's unsent text if any.
  • Recovery. The reader may resend, rephrase, or select a suggested prompt. Nothing already in the conversation is lost, and the reader's saved highlights remain available in the margin column.

Bot Settings

• Information and state. Protected operator workspace, restricted to the Bot Operator role. Holds the bot's current behaviour configuration and reading-assistance content. Configuration is durable and bound to the operator's identity so it can be resumed on return.
• Primary action. Save changes to the bot's behaviour and reading-assistance content.
• Supporting actions. Edit a configuration field; add or revise reading-assistance content; discard unsaved edits.
• Domain entities. Bot behaviour configuration; reading-assistance content; operator account identity.
• Component responsibilities.
  • Chapter rail. Section number and small-caps label over a hairline ink rule, so the page reads as a chapter rather than a dashboard.
  • Grouped fieldsets. Configuration grouped into fieldsets separated by hairline rules, label above value, 4px radii on inputs, 1px warm-grey borders. No KPI tiles.
  • Tabular figures. Any numeric operator value is set in tabular figures.
  • Status chips. Dusty blue #3E5C6B is permitted here and only here, as a rare third accent for status chips.
  • Primary save. One rust button with the 2px offset ink shadow that compresses on press.
  • Monospace allowance. JetBrains Mono is permitted solely for code-like operator values.
• States.
  • Loading. Fieldsets render in a legible pending arrangement while the current configuration is retrieved; no field is editable until its value is present, so an operator cannot overwrite a value they have not seen.
  • Empty. An operator whose bot has no reading-assistance content yet sees the configuration fieldsets with their current values and an empty content group with a plain orientation line, not a blank page.
  • Success. Saved changes are confirmed plainly in the muted metadata colour, and the bot subsequently serves readers with the updated behaviour and content.
  • Error. A save fails. A plain-language message appears in the muted metadata colour, the operator's unsaved edits remain in the fields, and nothing is silently discarded.
  • Recovery. The operator may retry the save, correct the offending field, or discard the unsaved edits and return to the last saved configuration.

3. Functional Requirements

FR-1 — Reading assistance from the bot (explicit) As a Reader, I should bring reading material or a reading question to the Sparx Reader bot and receive reading assistance in the same conversation, so that I get help without leaving the text.

• Trigger/input: the reader submits a reading-related request or reading material in Reader Chat.
• Observable result: a bot turn appears in the conversation containing reading assistance.
• Access state: protected; the reader must be verified.
• Failure/recovery: if assistance cannot be produced, the failed bot turn is marked plainly, the reader's original turn remains intact, and the reader may resend, rephrase, or select a suggested prompt.
• Continuation: the reader may continue the conversation, save a highlight, or select a suggested prompt.

FR-2 — Reader self-service enrollment (required_inference) As a Reader, I should be able to enroll myself before my first protected use, so that I can begin using Sparx Reader without waiting for someone else to create my access.

• Trigger/input: an unenrolled visitor chooses "Start reading" on Landing and completes the enrollment fieldset on Sign Up.
• Observable result: a reader account is created and the reader continues into Reader Chat.
• Access state: anonymous entry on Sign Up; the resulting identity is application-owned.
• Failure/recovery: if enrollment fails, a plain-language message appears, entered values are preserved except where unusable, and the reader may correct and resubmit or follow the link to Login.
• Continuation: the reader arrives in Reader Chat with an established identity.

FR-3 — Returning verification for readers and bot operators (required_inference) As a returning Reader or Bot Operator, I should verify my identity on return, so that I can resume my own protected work.

• Trigger/input: a returning person submits credentials on Login.
• Observable result: verification succeeds and the person continues to the protected journey matching their role — Reader Chat for a reader, Bot Settings for an operator.
• Access state: anonymous entry on Login; protected destinations remain unavailable until verification succeeds.
• Failure/recovery: if verification fails, a plain-language message appears, the entered identifier is preserved, the credential field is cleared, no protected state is revealed, and the person may retry or follow the link to Sign Up.
• Continuation: the verified person resumes their role's protected work.

FR-4 — Bot Operator invitation or provisioning (required_inference) As a Bot Operator, I should be invited or provisioned before I can reach operator-only bot configuration, so that the bot's behaviour and content are controlled only by people who are meant to control them.

• Trigger/input: an operator receives an invitation or is provisioned by the application.
• Observable result: the operator holds an operator identity that grants access to Bot Settings.
• Access state: Bot Settings is role-restricted to the Bot Operator role; operators do not self-enroll through Sign Up.
• Failure/recovery: an operator who has not been invited or provisioned cannot reach Bot Settings; they may verify on Login if they already hold an operator identity.
• Continuation: the operator verifies on return through Login and continues into Bot Settings.

FR-5 — Configure the bot's behaviour and reading-assistance content (required_inference) As a Bot Operator, I should set up and maintain the bot's behaviour and reading-assistance content, so that the bot reliably serves readers' reading requests.

• Trigger/input: the operator edits configuration fieldsets or reading-assistance content in Bot Settings and saves.
• Observable result: the changes are persisted and the bot subsequently serves readers with the updated behaviour and content.
• Access state: protected; role-restricted to the Bot Operator role.
• Failure/recovery: if a save fails, a plain-language message appears, unsaved edits remain in the fields, nothing is silently discarded, and the operator may retry, correct the offending field, or discard the edits.
• Continuation: the operator continues editing or leaves Bot Settings with the last saved configuration in effect.

FR-6 — Resume durable reader conversation history (required_inference) As a Reader, I should find my conversation with the bot intact when I return, so that reading help accumulates rather than restarting.

• Trigger/input: a verified reader opens Reader Chat.
• Observable result: the reader's prior turns and the bot's prior turns are present in the conversation pane, and saved highlights are present in the margin column.
• Access state: protected; the history is bound to the reader's identity.
• Failure/recovery: if history cannot be retrieved, the conversation pane presents the empty-conversation orientation with suggested prompts so the reader can still begin, and no prior content is falsely shown.
• Continuation: the reader continues the existing conversation.

FR-7 — Save and revisit highlights from the current passage (required_inference) As a Reader, I should save a highlight from the current passage and find it again in the margin column, so that the parts of the text I care about stay with me.

• Trigger/input: the reader saves a highlight from the current passage in Reader Chat.
• Observable result: the highlight appears in the margin column and remains available on return.
• Access state: protected; highlights are bound to the reader's identity.
• Failure/recovery: if a highlight cannot be saved, the reader is told plainly and the passage remains readable; the reader may try again.
• Continuation: the reader may open the saved highlight or continue the conversation.

FR-8 — Begin from suggested prompts (required_inference) As a Reader, I should be offered suggested prompts in the margin column, so that I always have a way to start or continue when I am unsure what to ask.

• Trigger/input: the reader opens Reader Chat, including when the conversation is empty.
• Observable result: three suggested prompts are present in the margin column; selecting one places it into the conversation as the reader's turn.
• Access state: protected.
• Failure/recovery: if suggested prompts are unavailable, the composer remains fully usable and the reader can type a request directly.
• Continuation: the reader's selected prompt becomes a reader turn and the bot responds.

4. User Personas

Reader

Product context. A student or learner working through reading material during homework, quiet study, or independent reading practice. They arrive with text in front of them and a question or a passage they are stuck on. The setting is often private and unhurried, and the register they need is calm and encouraging rather than evaluative.

Primary goal. To get useful reading assistance without leaving the chat — to keep momentum in the text rather than being sent away to another tool.

Distinct accepted responsibilities.

• Enroll themselves through Sign Up before their first protected use (FR-2).
• Verify on return through Login to resume their own work (FR-3).
• Bring reading material or reading questions to the bot in Reader Chat and act on the responses (FR-1).
• Resume their own conversation history when they return (FR-6).
• Save highlights from the current passage and revisit them in the margin column (FR-7).
• Begin or continue from suggested prompts when unsure what to ask (FR-8).

Relevant inputs and decisions. What to bring to the bot — a passage, a question, or a request for practice. Whether to accept a suggested prompt or type their own. Which parts of the current passage are worth saving as highlights. Whether to continue the conversation or stop.

Interactions with other accepted participants. The Reader's counterpart in every conversation is the bot, which is a system actor rather than a persona. The Reader does not interact with the Bot Operator directly; the operator's configuration shapes the assistance the Reader receives, but the Reader never sees the operator's workspace and the operator never sees the Reader's conversation. The Reader's own identity is what binds their history and highlights to them.

Observable success. The Reader gets reading assistance inside the conversation, their history and highlights are still there when they return, and they can always find a way to begin or continue.

What makes this role different. The Reader is the only persona who produces reading content and consumes assistance. Their work is conversational and cumulative — it is measured in a growing annotated text, not in settings changed. Their access is self-established, and everything they own is private to them.

Bot Operator

Product context. The person who sets up and runs the Sparx Reader bot so that readers can use it. Their work is a workshop: settings, tone, and content, handled practically and legibly. They are not a reader and do not use Reader Chat; they work on the bot rather than with it.

Primary goal. To make the bot reliably serve readers' reading requests.

Distinct accepted responsibilities.

• Hold an operator identity established by invitation or provisioning rather than self-enrollment (FR-4).
• Verify on return through Login to resume their own configuration work (FR-3).
• Set up and maintain the bot's behaviour and reading-assistance content in Bot Settings (FR-5).

Relevant inputs and decisions. What the bot's behaviour should be. What reading-assistance content the bot should draw on. When a configuration change is complete enough to save, and whether to keep or discard unsaved edits.

Interactions with other accepted participants. The Bot Operator does not interact with Readers directly and never sees a Reader's conversation. Their configuration is what shapes the assistance Readers receive, so their work reaches Readers only through the bot's behaviour. They share the Login surface with Readers but land in a different protected destination.

Observable success. Saved configuration takes effect, and the bot serves readers' reading requests with the behaviour and content the operator set.

What makes this role different. The Bot Operator is the only persona whose access is not self-established — they arrive through invitation or provisioning. Their work is configuration rather than conversation, it is durable and resumable, and its effect is indirect: they succeed when someone else's reading session goes well.

5. Core User Flows

Flow A — A new Reader enrolls and gets their first reading assistance

1. The Reader arrives at Landing as an anonymous visitor and reads the essay-opener sequence explaining what Sparx Reader is and what reading assistance it provides.
2. The Reader chooses the rust primary button, "Start reading", and is taken to Sign Up.
3. On Sign Up, the Reader completes the enrollment fieldset — grouped fields with hairline rules, label above value — and submits.
4. The application creates the Reader's account. The Reader is now verified and continues directly into Reader Chat.
   • If enrollment fails (for example the chosen identifier is already in use), a plain-language message appears in the muted metadata colour, the Reader's entered values are preserved except where unusable, and the Reader corrects and resubmits. If it turns out they already have an account, they follow the hairline link to Login instead.
5. In Reader Chat, the Reader sees an empty conversation pane with a short orientation line and three suggested prompts in the margin column.
6. The Reader selects a suggested prompt, or types a reading-related request or pastes reading material into the composer, and sends it with the rust send button.
7. The Reader's turn appears flush-left on cream with a 1px hairline and a small-caps YOU label. While the bot composes, a bot-turn placeholder holds its final position on #FFFCF5 with the mustard left border and the small-caps SPARX label.
8. The bot's assistance arrives as a bot turn on the brighter surface, marked with the mustard left border.
   • If the bot cannot produce assistance, the failed bot turn is marked plainly in the muted metadata colour with a short explanation, the Reader's original turn remains intact and readable, and the Reader may resend, rephrase, or select a suggested prompt.
9. The Reader continues the conversation, or saves a highlight from the current passage, which appears in the margin column.
10. Next step: the Reader keeps reading with the bot, or leaves and returns later.

Flow B — A returning Reader resumes their reading work

1. The Reader arrives at Landing and follows the ink hairline text link, "I already have an account", to Login.
2. On Login, the Reader submits their credentials.
3. Verification succeeds and the Reader continues to Reader Chat, their role's protected destination.
   • If verification fails, a plain-language message appears, the entered identifier is preserved, the credential field is cleared, and no protected state is revealed. The Reader retries, or follows the link to Sign Up if they have not enrolled.
4. In Reader Chat, the Reader's prior turns and the bot's prior turns are present in the conversation pane, and their saved highlights are present in the margin column.
   • If history cannot be retrieved, the conversation pane presents the empty-conversation orientation with suggested prompts so the Reader can still begin; no prior content is falsely shown.
5. The Reader opens a saved highlight, or continues the conversation by sending a new reading-related request.
6. The bot responds in the same conversation, and the Reader acts on the assistance.
7. Next step: the Reader continues reading, saves further highlights, or leaves and returns again.

Flow C — A Bot Operator is provisioned, configures the bot, and returns to maintain it

1. The Bot Operator receives an invitation or is provisioned by the application. They do not enroll through Sign Up.
2. The Bot Operator verifies on Login and continues to Bot Settings, their role's protected destination.
   • If verification fails, a plain-language message appears, the entered identifier is preserved, the credential field is cleared, and no protected state is revealed. The Operator retries.
   • If the Operator has not been invited or provisioned, they cannot reach Bot Settings.
3. In Bot Settings, the Operator sees the configuration fieldsets rendered as a chapter — grouped fieldsets separated by hairline rules, label above value, tabular figures for numeric values, and dusty blue status chips.
   • While the current configuration is being retrieved, fieldsets render in a legible pending arrangement and no field is editable until its value is present, so the Operator cannot overwrite a value they have not seen.
   • If the bot has no reading-assistance content yet, the content group shows a plain orientation line rather than a blank page.
4. The Operator edits the bot's behaviour configuration and its reading-assistance content, then saves with the single rust button.
5. The save is confirmed plainly in the muted metadata colour, and the bot subsequently serves readers with the updated behaviour and content.
   • If the save fails, a plain-language message appears, the Operator's unsaved edits remain in the fields, nothing is silently discarded, and the Operator may retry, correct the offending field, or discard the edits and return to the last saved configuration.
6. Next step: the Operator leaves Bot Settings with the last saved configuration in effect, and returns later through Login to maintain the bot further.

Flow D — A Reader's assistance is shaped by the Operator's configuration

1. The Bot Operator saves updated behaviour or reading-assistance content in Bot Settings (Flow C, steps 3–5).
2. A Reader, verified and in Reader Chat, sends a reading-related request.
3. The bot produces its assistance using the behaviour and content the Operator set, and the assistance appears as a bot turn on #FFFCF5 with the mustard left border.
4. The Reader acts on the assistance.
5. Next step: the Reader continues the conversation. The Reader never sees the Operator's workspace, and the Operator never sees the Reader's conversation; the Operator's work reaches the Reader only through the bot's behaviour.

6. Visuals, Colors and Theme

The creative direction is authoritative for this section. It is applied as given.

Muse and headline. Frank Chimero — warm editorial pages for a reading companion. The product reads as essays-as-interfaces: readable measure, warm cream grounds, illustrated section openers, and humane rhythm. The register is a well-set book, not a dashboard.

Palette (light mode).

Proportion: 70% cream/paper, 20% ink text and rules, 8% rust, 2% mustard.

Typography.

• Headings: Literata, medium weight (500–600), sentence case, tracking −0.01em, leading 1.05–1.15 at display sizes and 1.3 for section heads. No all-caps, no letterspacing tricks. Headlines are the loudest thing on the page and behave like book chapter titles.
• Quotes and pull-lines: Literata italic.
• Body: Source Serif 4.
• Scale: 1.333 modular on a 16px base. Display 44px mobile → 96px desktop (clamp(2.75rem, 7vw, 6rem)); H1 32→52; H2 24→34; H3 19→24; body 17→19 with 1.7 line-height and a 62–68ch measure; small/meta 14→15.
• Numerals in the operator surface use tabular figures.
• JetBrains Mono is permitted solely for code-like operator values.

Shape language. Soft, paper-like and almost square: 4px radii on buttons and inputs, 8px on cards and chat bubbles, 16px only on the hero's illustrated panel. Borders are 1px hairlines in warm grey #DCD2C0. Depth is paper-on-paper layering — a slightly warmer card on a cream ground — plus a 1px ink underline for emphasis, never shadows-as-depth. Buttons are rectangles with a 4px radius and a 2px offset ink shadow that compresses on press. No pills, no blobs, no glossy surfaces.

Layout. A single-column reading measure (max 68ch) is the spine of every page, with an asymmetric editorial grid around it: a narrow left rail for chapter-style numbering (01 / 02 / 03) and section labels set in small caps, and a wide right margin used for marginalia — pull quotes, illustrations, tip notes. Landing runs as a sequence of essay openers: a full-width illustrated rule, then a headline, then a paragraph, then a plate of illustration, repeating down the page, with one deliberate full-bleed illustration between sections. Reader Chat is a two-pane book spread at ≥1024px: conversation on the left at reading measure, a margin column on the right holding the current passage, saved highlights and suggested prompts; below 1024px the margin column becomes a horizontally scrollable strip beneath the composer. Bot Settings uses the same rail-and-measure grid so it reads as a chapter, not a dashboard: grouped fieldsets with hairline rules, label above value, tabular figures for anything numeric.

Imagery. Warm flat illustration and hand-drawn diagrams in a two-ink palette — ink #241F1A lines, rust #8C3A1E fills, mustard #C97B2A highlights — on cream: books, bookmarks, pencils, speech ribbons, a reading lamp, an open door, marginal doodles. Spot illustrations sit inside the right margin or as section openers, never as a photographic hero. Where photography is used at all it is documentary and warm: a hand holding a paperback, a desk with a notebook, natural light, no stock-model eye contact. Textures are subtle paper grain (a 3% noise overlay), never gradients.

Avoid. Gradient-blob heroes and any soft multicolour gradient ground; a grid of identical hover-lift cards; blue/indigo primary or accent colours anywhere in the UI; Inter, Roboto, Arial, Helvetica, Poppins, system-ui, or any geometric sans as heading or body; photographic stock heroes of smiling students; frosted glass, blur panels, glossy 3D primitives and parallax depth; dashboards built from KPI tiles; marquees, tickers, bouncing or springy micro-interactions. The generic indigo/blue-on-white SaaS template is forbidden for this project.

Readable text and controls. Headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration and motion may be cropped, bled off an edge, rotated, overlapped or cut exactly as the direction asks, as long as they cover no readable text or control. The horizontally scrollable margin strip on mobile may cross the container edge by design; every item becomes fully readable as it is brought into view. With prefers-reduced-motion, the margin strip wraps into rows or remains horizontally scrollable so each item can be brought fully into view.

7. Signature Design Concept

The essay opener. The Landing hero is not a SaaS banner; it is the first page of an essay.

Left two-thirds of the viewport: a small-caps eyebrow reading SPARX READER · READING ASSISTANCE, with a 1px ink rule running the full viewport width directly beneath it. Below the rule, an oversized Literata headline spans the full reading column and wraps to 2–3 lines at clamp(2.75rem, 7vw, 6rem) — for example, "A patient reading companion that stays in the margins with you." Beneath the headline sits one paragraph at a 62–68ch measure, then a single rust button, "Start reading", with an ink hairline text link beside it, "I already have an account".

Right one-third, bleeding slightly off the right edge: a warm flat illustration of an open book with a small ink bird perched on the page, mustard highlights on the text lines, drawn on cream with no frame. No gradient, no centred stack, no floating product screenshot.

The section number 01 sits in the left rail in tabular Literata over a small-caps section label and a hairline ink rule. As the visitor scrolls, the page continues as a sequence of essay openers — full-width illustrated rule, headline, paragraph, illustration plate — each carrying its own chapter number, with one deliberate full-bleed illustration between sections. The whole app reads as a book's table of contents rather than a nav bar.

This concept recomposes only accepted content and controls: the product's identity and reading-assistance purpose, the two entry actions into Sign Up and Login, and the chapter rail. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief.

• Focal subject. The warm flat illustration of an open book with a small ink bird perched on the page, mustard highlights on the text lines, drawn on cream with no frame, bleeding slightly off the right edge.
• Input → transformation → outcome thesis. As the visitor scrolls, each essay-opener section fades up 8px over 320ms with a slow ease-out as it enters the viewport, one at a time, never staggered into a cascade — so the page reads as turning through a book rather than loading a dashboard. The outcome is that the visitor reaches the two entry actions, "Start reading" and "I already have an account", having read the product's purpose in sequence.
• Motion vocabulary. Content fades up 8px over 320ms with a slow ease-out, one section at a time. Hover on links and buttons runs a 1px ink underline from left to right over 180ms. Button press compresses the offset shadow from 2px to 0px. A single illustrated spot — the small ink-drawn bird in the hero — loops a slow 4-second blink/wing-tick. No parallax, no bounce, no marquees.
• Composed first frame. The eyebrow SPARX READER · READING ASSISTANCE in small caps, the full-width 1px ink rule beneath it, the oversized Literata headline wrapping across 2–3 lines, one 62ch paragraph, the rust "Start reading" button with its 2px offset ink shadow, the ink hairline link "I already have an account" beside it, the section number 01 in the left rail, and the open-book-and-bird illustration bleeding off the right edge. Nothing is mid-animation; the frame is complete and readable.
• Reduced-motion state. With prefers-reduced-motion, the fade-up and the bird's 4-second loop are suppressed. All sections render in their final position at full opacity, the hero illustration holds a static frame, and the hover underline and button-press shadow compression are removed in favour of an immediate state change. Every headline, label, and control remains whole and readable at 375px, 768px and 1280px.

9. Non-Functional Requirements

NFR-1 — Reading measure and legibility (explicit, from creative direction) Body copy is set at a 62–68ch measure with 1.7 line-height, and ink #241F1A on cream #F4EEE2 carries all body copy at approximately 13:1 contrast. Rationale: the product's value is text, and the page must respect it.

NFR-2 — Readable text and controls stay whole (explicit, from creative direction) Headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit, with no other element covering any part of them. Imagery, decoration and motion may be cropped, bled, rotated, overlapped or cut as the direction asks, provided they cover no readable text or control. Rationale: legibility is a hard constraint that outranks decorative gesture.

NFR-3 — Reduced-motion usability (explicit, from creative direction) With prefers-reduced-motion, the interface provides a usable static arrangement: the mobile margin strip wraps into rows or remains horizontally scrollable so each item can be brought fully into view, and no motion is required to read or operate anything. Rationale: the product is used in quiet study sessions and must not depend on motion.

NFR-4 — Restrained motion ceiling (explicit, from creative direction) Motion is limited to an 8px fade-up over 320ms on section entry, a 200ms fade with a 4px rise for chat messages, a 180ms left-to-right 1px ink underline on hover, a 2px→0px button shadow compression on press, and one 4-second illustrated loop in the hero only. No parallax, no bounce, no marquees, no tickers, no springy micro-interactions. Rationale: the direction sets a restrained tempo suited to a tool used during study.

NFR-5 — Durable, identity-bound reader state (required_inference) A reader's conversation history and saved highlights persist and remain bound to that reader's identity across sessions, so that returning readers resume their own work and never see another reader's. Rationale: FR-6 and FR-7 require resumable, private, actor-specific state.

NFR-6 — Durable, identity-bound operator configuration (required_inference) The bot's behaviour configuration and reading-assistance content persist and remain bound to the operator identity that saved them, so that an operator resumes their own configuration work. Rationale: FR-5 requires resumable operator configuration.

NFR-7 — Role-restricted protected destinations (explicit, from planning scope) Reader Chat is restricted to the Reader role and Bot Settings is restricted to the Bot Operator role. Landing, Login, and Sign Up are anonymously reachable. Rationale: the accepted access contract assigns each protected destination to one persona.

NFR-8 — No protected state before verification (required_inference) Login and Sign Up reveal no protected state before verification or enrollment succeeds, and a protected destination never owns the interaction that establishes access to itself. Rationale: the access boundary must be truthful for both personas.

NFR-9 — Backend integration (explicit, from planning scope) The application requires backend integration to serve reading assistance, persist conversations and highlights, and persist bot configuration. Rationale: the accepted behaviour cannot be delivered client-side alone.

10. Tech Stack

No technology choices were specified by the user. The following are coherent defaults for the accepted delivery shape — a first-party web application with application-owned identity, custom UI, and backend integration — and are labeled as defaults.

• Frontend: React (web), single-page application. [Default — not specified by user]
• Backend: Python with FastAPI. [Default — not specified by user]
• Storage: A relational database for account identities, conversations, reader turns, bot turns, saved highlights, and bot configuration. [Default — not specified by user]
• Containerization: Docker with docker-compose for local and single-host deployment. [Default — not specified by user]
• Orchestration: Kubernetes is not required by any accepted requirement and is omitted. [Default — not specified by user]

The creative direction's typography and colour tokens are hard requirements, not defaults: Literata for headings, Source Serif 4 for body, JetBrains Mono solely for code-like operator values, and the palette in Section 6.

11. Assumptions and Constraints

Assumptions.

• A-1. The bot's reading assistance is produced by the application's own backend. No third-party reading-assistance provider was named, and none is assumed. (required_inference)
• A-2. A Reader's conversation history and saved highlights are private to that Reader. No sharing, publishing, or peer-visibility capability was accepted. (required_inference)
• A-3. A Bot Operator's configuration applies to the bot as a whole rather than to individual Readers, since no per-Reader configuration was accepted. (required_inference)
• A-4. Bot Operators are provisioned by the application or by an existing operator; the exact provisioning mechanism is not specified by the source and is left to implementation. (required_inference)
• A-5. The three suggested prompts shown in Reader Chat's margin column are supplied by the application. The source does not specify how they are chosen. (required_inference)

Constraints.

• C-1. The active human personas are exactly two: Reader and Bot Operator. No additional persona is introduced. (explicit)
• C-2. The page inventory is exactly five pages — Landing, Login, Sign Up, Reader Chat, Bot Settings — with the access assignments given in Section 2c. No page is added, removed, merged, split, renamed, or reordered. (explicit)
• C-3. Landing, Login, and Sign Up are anonymously reachable. Reader Chat is restricted to the Reader role; Bot Settings is restricted to the Bot Operator role. (explicit)
• C-4. Bot Operators do not self-enroll through Sign Up; they arrive through invitation or provisioning. (explicit)
• C-5. The palette, typography, shape language, layout, imagery, and motion ceiling in Sections 6 and 8 are binding. The generic indigo/blue-on-white SaaS template is forbidden. (explicit)
• C-6. No adjacent education-platform capability is in scope: no grading, assessment scoring, class rosters, teacher dashboards, progress analytics, social or sharing features, or content marketplaces. (explicit exclusion)
• C-7. No future requirements have been accepted; nothing is deferred to a later horizon. (explicit)

12. Glossary

• Sparx Reader — The reading-assistance bot described by this document, delivered as a first-party web application.
• Reader — An active human persona: a student or learner who brings reading material or reading questions to the bot and acts on its assistance.
• Bot Operator — An active human persona: the person who configures and maintains the bot's behaviour and reading-assistance content so that readers can use it.
• Bot — The system actor that produces reading assistance inside Reader Chat. It is not a persona and has no human-facing surface of its own.
• Reader Chat — The protected conversation workspace where a Reader sends reading-related requests or material and receives assistance in the same conversation.
• Bot Settings — The protected operator workspace where a Bot Operator sets up and maintains the bot's behaviour and reading-assistance content.
• Reader turn — A message the Reader sends in Reader Chat; rendered flush-left on cream with a 1px hairline and a small-caps YOU label.
• Bot turn — A message of assistance the bot produces in Reader Chat; rendered on #FFFCF5 with a 3px mustard left border and a small-caps SPARX label.
• Margin column — The right-hand column in Reader Chat holding the current passage, saved highlights, and three suggested prompts, separated from the conversation by a hairline vertical rule; below 1024px it becomes a horizontally scrollable strip beneath the composer.
• Highlight — A saved excerpt from the current passage, held in the margin column and bound to the Reader's identity.
• Suggested prompt — One of three prompts offered in the margin column so a Reader always has a way to begin or continue.
• Chapter rail — The narrow left rail on every page carrying a small-caps section label over a hairline ink rule with a tabular chapter number (01, 02, 03).
• Essay opener — The repeating Landing section pattern: full-width illustrated rule, headline, paragraph, illustration plate.
• Anonymous boundary — The set of pages reachable without an established identity: Landing, Login, and Sign Up.
• Protected boundary — The set of pages requiring an established identity: Reader Chat and Bot Settings.