System Requirements Document for gilded-que

1. Introduction

gilded-que is a reusable core CRUD (create, read, update, delete) foundation intended to be the starting point for multiple projects. The product intent is a working, honest data-management base — a scaffold a developer can clone or adopt so that each new project begins from a functioning record lifecycle rather than from an empty repository.

The audience is the Project Starter (Developer): a technical user who values density, tabular numerals, keyboard-first flows, and surfaces whose behavior is legible from the source. The product is not a marketing SaaS dashboard; it is a tool meant to be read, reused, and extended.

The current delivery is a first-party web application with application-owned identity, a public landing entry, self-service enrollment and returning verification, and a protected record lifecycle (browse, create, update, delete) over durable, per-user records.

2. System Overview

gilded-que currently delivers one cohesive capability: a durable, per-user core CRUD over records, wrapped in the minimum identity continuity needed for a developer to return to their own data across sessions.

Actors

• Project Starter (Developer) — the single accepted active human persona. Creates, reads, updates, and deletes records; owns the durable state produced.
• Application backend — non-persona system actor. Persists records, enforces identity continuity, and serves the CRUD API.
• Identity/session service (application-owned) — non-persona system actor. Establishes and verifies the Project Starter's identity so durable records remain bound to the correct participant.

Accepted behavior

• Anonymous public entry that explains the reusable CRUD foundation.
• Self-service first-use enrollment and returning verification.
• Protected browse of existing records, focused creation of a new record, and focused update/delete of an existing record.
• Durable persistence of records per identity, with observable success, empty, loading, and error/recovery states.

Ownership

All current human-facing behavior is owned by first-party custom pages. Identity is application-owned. No provider-owned or external destinations are part of the current scope.

Narrow exclusions

• No adjacent account-management capabilities (no profile editing, no password reset flows, no role administration) beyond first-use enrollment and returning verification.
• No multi-tenant organization model, no sharing, no collaboration, no audit log, no notifications.
• No differentiated permissions or role-based visibility: identity establishes continuity of ownership, not differentiated control over shared state.
• No analytics, billing, or third-party integrations.

2a. Product Interpretation and Delivery Boundary

gilded-que is delivered as a first-party web application. The public Landing page is anonymously reachable and explains what the CRUD foundation is and what it contains. Because the product produces durable, per-user records that a developer must be able to resume across sessions, the application owns identity: a first-time visitor establishes identity through Sign Up, and a returning visitor verifies identity through Login. Both entry surfaces are anonymously reachable; the protected record surfaces are not.

The protected working area consists of three cohesive destinations: Records (the independently revisitable browse owner), New Record (the focused create owner), and Record Details (the focused update/delete owner). These are separated because their working contexts, authoritative state, and completion outcomes differ: browsing a list, committing a new record, and mutating an existing record each have distinct entry points, distinct success states, and distinct failure/recovery paths.

Everything else — persistence, identity verification, record mutation — is backend execution supporting these human-facing surfaces. Nothing in the current scope is provider-owned, external, or headless.

Future ideas are explicitly out of current scope and are recorded in Section 11 rather than implemented here.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains the reusable core CRUD foundation for starting multiple projects. Presents the product's purpose, the shape of the record lifecycle (create, read, update, delete), and the entry points into identity establishment.
• Primary actions: Navigate to Sign Up (primary CTA, tangerine fill). Navigate to Login for returning users.
• Supporting actions: Read the CRUD capability summary; read the data-model schematic; read the code sample panel.
• Domain entities: Record (referenced conceptually), Field, Value.
• Component responsibilities:
  • Split editorial hero: oversized left-aligned headline, subline, primary CTA pinned beneath the subline.
  • Full-height dark ink code panel bleeding to the right viewport edge, showing a monospace CRUD snippet with the active line highlighted in tangerine and a small tangerine tabular numeral in its top-right corner.
  • Full-width ruled strip of four monospace stats (records, fields, endpoints, latency) separated by 1px ink hairlines, each label in 11px uppercase tracked micro-type.
  • Schematic box-and-line diagram of Record → Field → Value in ink hairlines with tangerine connectors.
• States:
  • Loading: not applicable (static content).
  • Empty: not applicable.
  • Success: page renders fully; both identity entry points are reachable.
  • Error: not applicable.
  • Recovery: not applicable.

Sign Up

• Information/state: Anonymous first-use enrollment surface. Collects the minimum identity information required to establish a durable, privately owned record set.
• Primary actions: Submit enrollment to establish identity and proceed to the protected record area.
• Supporting actions: Navigate to Login if identity already exists; return to Landing.
• Domain entities: Identity (the Project Starter's account), Session.
• Component responsibilities:
  • Enrollment form with two-column label/value alignment on desktop, stacked on mobile.
  • Inline field-level validation messaging.
  • Submit control (ink fill) with disabled/pending state.
  • Link to Login.
• States:
  • Loading: submit control shows pending state; form inputs disabled during submission.
  • Empty: initial form with no values entered.
  • Success: identity established; session created; navigation to Records.
  • Error: field-level validation errors shown inline; submission-level failure shown as a single line of ink text with a retry affordance.
  • Recovery: entered values are preserved on failure so the Project Starter can correct and resubmit without re-entering everything.

Login

• Information/state: Anonymous returning-verification surface. Verifies an existing identity so the Project Starter regains access to their durable records.
• Primary actions: Submit credentials to verify identity and proceed to the protected record area.
• Supporting actions: Navigate to Sign Up if no identity exists; return to Landing.
• Domain entities: Identity, Session.
• Component responsibilities:
  • Verification form with two-column label/value alignment on desktop, stacked on mobile.
  • Inline field-level validation messaging.
  • Submit control (ink fill) with disabled/pending state.
  • Link to Sign Up.
• States:
  • Loading: submit control shows pending state; form inputs disabled during submission.
  • Empty: initial form with no values entered.
  • Success: identity verified; session created; navigation to Records.
  • Error: verification failure shown as a single line of ink text; field-level validation errors shown inline.
  • Recovery: entered values are preserved on failure so the Project Starter can correct and resubmit.

Records

• Information/state: Protected browse owner. Displays the list of existing records owned by the verified identity. Independently revisitable; the expected return point after create, update, or delete.
• Primary actions: Open a record (navigate to Record Details). Navigate to New Record.
• Supporting actions: Sort/filter the list; read the record count; use inline row actions revealed on hover/focus.
• Domain entities: Record (id, fields, values, timestamps), Record count.
• Component responsibilities:
  • Ruled data grid with 1px hairline borders, sticky ink header, right-aligned tabular counts, and a 3px tangerine left rule that slides in on the focused row.
  • Records counter block with a tangerine left rule and a monospace tabular numeral.
  • Inline row actions revealed on hover/focus.
  • Empty-state line of ink text with a monospace 0 records numeral and a tangerine text link to New Record.
  • 240px ink-on-paper left rail (collapsing to a 56px icon rail at 768px and a horizontally scrollable top bar at 375px) carrying wordmark, primary nav (Records, New Record), and a keyboard-shortcut cheat sheet.
• States:
  • Loading: table skeleton with hairline rules; count numeral pending.
  • Empty: single line of ink text with monospace 0 records numeral and a tangerine text link to New Record; 1.2s tangerine caret blink in the prompt.
  • Success: table renders with records; count numeral counts up over 200ms when the list resolves.

• Error: single line of ink text describing the failure with a retry affordance.
• Recovery: retry re-requests the list; previously loaded rows remain visible until the retry resolves.

New Record

• Information/state: Protected focused create owner. Collects the field values for a new record and commits it to durable storage.
• Primary actions: Submit the new record.
• Supporting actions: Cancel and return to Records; navigate to Records via the left rail.
• Domain entities: Record, Field, Value.
• Component responsibilities:
  • Create form with two-column label/value alignment on desktop, stacked on mobile.
  • Field-group micro-labels in 11px uppercase with 0.12em tracking.
  • Inline field-level validation messaging.
  • Submit control (ink fill) with disabled/pending state.
  • Cancel control returning to Records.
  • 240px left rail with wordmark, primary nav, and keyboard-shortcut cheat sheet.
• States:
  • Loading: submit control shows pending state; inputs disabled during submission.
  • Empty: initial form with no values entered.
  • Success: record persisted; navigation to Records with the new record visible in the list.
  • Error: field-level validation errors shown inline; submission-level failure shown as a single line of ink text with a retry affordance.
  • Recovery: entered values are preserved on failure so the Project Starter can correct and resubmit.

Record Details

• Information/state: Protected focused owner for updating and deleting an existing record. Displays the record's current field values and its identity (id, timestamps).
• Primary actions: Submit updates to the record. Delete the record.
• Supporting actions: Cancel and return to Records; navigate to Records via the left rail.
• Domain entities: Record (id, fields, values, timestamps), Field, Value.
• Component responsibilities:
  • Update form with two-column label/value alignment on desktop, stacked on mobile.
  • Record id and timestamps rendered in monospace with tabular numerals.
  • Field-group micro-labels in 11px uppercase with 0.12em tracking.
  • Inline field-level validation messaging.
  • Submit control (ink fill) with disabled/pending state.
  • Delete control with destructive hover treatment in tangerine.
  • Cancel control returning to Records.
  • 240px left rail with wordmark, primary nav, and keyboard-shortcut cheat sheet.
• States:
  • Loading: form skeleton with hairline rules; record id and timestamps pending.
  • Empty: not applicable (a record is always loaded).
  • Success: update persisted, or delete completed; navigation to Records with the change reflected.
  • Error: record-not-found shown as a single line of ink text with a link back to Records; field-level validation errors shown inline; submission-level failure shown as a single line of ink text with a retry affordance.

• Recovery: entered values are preserved on update failure so the Project Starter can correct and resubmit; a failed delete leaves the record intact and reports the failure with a retry affordance.

3. Functional Requirements

FR-1 — Public entry to the CRUD foundation (explicit) As a Project Starter (Developer), I should be able to reach an anonymous public entry that explains the reusable core CRUD foundation for starting multiple projects, so that I can understand what the base provides before establishing identity.

• Trigger/input: Anonymous visit to the application root.
• Observable result: The Landing page renders with the product purpose, the CRUD capability summary, the data-model schematic, and the code sample panel.
• Access state: Anonymous; no identity required.
• Failure/recovery: Not applicable (static content).
• Continuation: The Project Starter proceeds to Sign Up (first use) or Login (returning).

FR-2 — Self-service first-use enrollment (required_inference) As a Project Starter (Developer), I should be able to establish my own identity through self-service enrollment, so that the records I create are durably and privately bound to me.

• Trigger/input: Selection of the primary CTA on Landing; submission of the enrollment form on Sign Up.
• Observable result: Identity is established, a session is created, and the Project Starter lands on Records.
• Access state: Anonymous entry; protected state becomes available only after identity is established.
• Failure/recovery: Field-level validation errors are shown inline; submission-level failure is reported as a single line of ink text with a retry affordance; entered values are preserved.
• Continuation: The Project Starter proceeds to browse, create, update, or delete records.

FR-3 — Returning verification (required_inference) As a Project Starter (Developer), I should be able to verify my existing identity, so that I can resume work on my durable records in a later session.

• Trigger/input: Selection of the login entry point on Landing; submission of the verification form on Login.
• Observable result: Identity is verified, a session is created, and the Project Starter lands on Records.
• Access state: Anonymous entry; protected state becomes available only after verification succeeds.
• Failure/recovery: Verification failure is reported as a single line of ink text; field-level validation errors are shown inline; entered values are preserved.
• Continuation: The Project Starter proceeds to browse, create, update, or delete records.

FR-4 — Read: browse existing records (explicit) As a Project Starter (Developer), I should be able to view the list of existing records, so that I can see what data the foundation already holds.

• Trigger/input: Navigation to Records after identity is established, or via the left rail from any protected page.
• Observable result: A ruled data grid renders the records owned by the verified identity, with a right-aligned tabular record count.
• Access state: Protected; requires established identity.
• Failure/recovery: A list-load failure is reported as a single line of ink text with a retry affordance; previously loaded rows remain visible until the retry resolves.
• Continuation: The Project Starter opens a record, or navigates to New Record.

FR-5 — Create: add a new record (explicit) As a Project Starter (Developer), I should be able to add a new record, so that the foundation holds data I can then read, update, and delete.

• Trigger/input: Navigation to New Record from Records or the left rail; submission of the create form.
• Observable result: The record is persisted and appears in the Records list.
• Access state: Protected; requires established identity.
• Failure/recovery: Field-level validation errors are shown inline; submission-level failure is reported as a single line of ink text with a retry affordance; entered values are preserved.
• Continuation: The Project Starter returns to Records with the new record visible.

FR-6 — Update: modify an existing record (explicit) As a Project Starter (Developer), I should be able to update an existing record, so that the foundation's data stays correct as a project evolves.

• Trigger/input: Opening a record from Records to reach Record Details; submission of the update form.
• Observable result: The record's field values are persisted and reflected in the Records list.
• Access state: Protected; requires established identity.
• Failure/recovery: Field-level validation errors are shown inline; submission-level failure is reported as a single line of ink text with a retry affordance; entered values are preserved.
• Continuation: The Project Starter returns to Records with the change reflected.

FR-7 — Delete: remove an existing record (explicit) As a Project Starter (Developer), I should be able to delete an existing record, so that the foundation does not accumulate data a project no longer needs.

• Trigger/input: Selection of the delete control on Record Details.
• Observable result: The record is removed and no longer appears in the Records list.
• Access state: Protected; requires established identity.
• Failure/recovery: A failed delete leaves the record intact and reports the failure as a single line of ink text with a retry affordance.
• Continuation: The Project Starter returns to Records with the record removed.

FR-8 — Durable, identity-bound record ownership (required_inference) As a Project Starter (Developer), I should have my records persist durably and remain bound to my identity, so that the foundation is a reliable starting point across sessions and across the multiple projects I begin from it.

• Trigger/input: Any create, update, or delete action performed while verified.
• Observable result: Records persist across sessions and are only visible to the identity that owns them.
• Access state: Protected; requires established identity.
• Failure/recovery: A persistence failure is surfaced on the originating page with a retry affordance; no partial state is presented as success.
• Continuation: The Project Starter resumes from Records in a later session.

4. User Personas

Project Starter (Developer)

Product context. The Project Starter is a developer who begins multiple projects and wants each one to start from a working data-management foundation rather than an empty repository. They adopt gilded-que as a reusable core CRUD base: a record lifecycle that already creates, reads, updates, and deletes durable data, so that the first hours of a new project go into the project's actual problem instead of into scaffolding a CRUD layer.

Primary goal. To have a core CRUD foundation that is genuinely reusable as the starting point for several projects — one whose behavior is legible enough to read, trust, and extend.

Distinct accepted responsibilities. The Project Starter is the sole active human actor and performs the complete record lifecycle: they establish their own identity on first use, verify it on return, browse the record list, create new records, update existing records, and delete records they no longer need. They also decide when the foundation is complete enough to serve as the base for a new project.

Relevant inputs and decisions. They supply identity information at enrollment and verification, and field values when creating or updating a record. Their decisions are: whether to enroll or verify, which record to open, what values a record should hold, and whether a record should be removed.

Interactions with other accepted participants. The Project Starter interacts only with the application itself. There is no second human participant, no collaborator, and no external counterparty in the current scope. The backend and identity service act on the Project Starter's behalf but are not participants with their own goals.

Observable success. The Project Starter can return in a later session, verify identity, and find their records exactly as they left them; they can complete a full create → read → update → delete cycle without leaving the protected area; and the base is coherent enough that they would begin another project from it.

Constraints carried from source. The audience is technical and values density, tabular numerals, keyboard-first flows, and honest surfaces. The product is explicitly not a marketing SaaS dashboard.

5. Core User Flows

Flow 1 — First use: understand the foundation and establish identity

1. The Project Starter arrives anonymously at the application root and lands on Landing.
2. They read the oversized headline, the subline, and the CRUD capability summary; they read the data-model schematic (Record → Field → Value) and the dark ink code panel showing the create/read/update/delete calls with the active line highlighted in tangerine.
3. They decide the foundation is what they want and select the tangerine primary CTA, which takes them to Sign Up.
4. On Sign Up, they enter the minimum identity information required. The form uses two-column label/value alignment on desktop and stacks on mobile.
5. They submit. The submit control enters a pending state and inputs are disabled.
6. Success: identity is established, a session is created, and they land on Records.
7. Failure: field-level validation errors appear inline, or a submission-level failure appears as a single line of ink text with a retry affordance. Their entered values are preserved, so they correct and resubmit without re-entering everything.
8. Continuation: they proceed to Flow 3 (browse), Flow 4 (create), or Flow 5 (update/delete).

Flow 2 — Returning use: verify identity and resume

1. The Project Starter returns in a later session and lands on Landing.
2. They select the login entry point and arrive at Login.
3. They enter their identity information and submit. The submit control enters a pending state and inputs are disabled.
4. Success: identity is verified, a session is created, and they land on Records with their previously created records intact.
5. Failure: verification failure is reported as a single line of ink text; field-level validation errors appear inline. Their entered values are preserved so they can correct and resubmit.
6. Continuation: they proceed to Flow 3 (browse), Flow 4 (create), or Flow 5 (update/delete).

Flow 3 — Read: browse the record list

1. From any protected page, the Project Starter navigates to Records via the left rail (240px on desktop, 56px icon rail at 768px, horizontally scrollable top bar at 375px).
2. The list loads. While loading, the table shows a skeleton with hairline rules and the count numeral is pending.
3. Success: the ruled data grid renders with a sticky ink header, right-aligned tabular counts, and a 3px tangerine left rule that slides in on the focused row. The records total counts up over 200ms as the list resolves.
4. Empty: instead of a table, a single line of ink text appears with a monospace 0 records numeral and a tangerine text link to New Record; a 1.2s tangerine caret blinks in the prompt. The Project Starter follows the link to Flow 4.
5. Failure: a list-load failure appears as a single line of ink text with a retry affordance; previously loaded rows remain visible until the retry resolves.
6. Continuation: the Project Starter opens a record (Flow 5) or navigates to New Record (Flow 4).

Flow 4 — Create: add a new record

1. From Records (via the primary nav, the empty-state link, or the left rail), the Project Starter arrives at New Record.
2. They fill in the record's field values. Field groups are labeled with 11px uppercase micro-labels at 0.12em tracking; the form uses two-column label/value alignment on desktop and stacks on mobile.
3. They submit. The submit control enters a pending state and inputs are disabled.
4. Success: the record is persisted and they are returned to Records, where the new record is visible in the list and the count reflects it.
5. Failure: field-level validation errors appear inline, or a submission-level failure appears as a single line of ink text with a retry affordance. Their entered values are preserved so they can correct and resubmit.
6. Alternative: they select Cancel and return to Records without creating anything.
7. Continuation: they open the new record (Flow 5) or create another (Flow 4).

Flow 5 — Update or delete an existing record

1. From Records, the Project Starter opens a record and arrives at Record Details.
2. The record loads. While loading, the form shows a skeleton with hairline rules and the record id and timestamps are pending.
3. Success: the record's current field values render, with the record id and timestamps in monospace with tabular numerals.
4. Update: they change field values and submit. The submit control enters a pending state and inputs are disabled. On success, the changes are persisted and they return to Records with the change reflected. On failure, field-level validation errors appear inline or a submission-level failure appears as a single line of ink text with a retry affordance, and their entered values are preserved.
5. Delete: they select the delete control, which carries a destructive hover treatment in tangerine. On success, the record is removed and they return to Records with the record gone. On failure, the record remains intact and the failure is reported as a single line of ink text with a retry affordance.
6. Record not found: if the record cannot be loaded, a single line of ink text reports this with a link back to Records.
7. Alternative: they select Cancel and return to Records without changing anything.
8. Continuation: they return to Flow 3 (browse) or Flow 4 (create).

6. Visuals Colors and Theme

Muse and headline. Rasmus Andersson — Systematic product craft with an opinion: a warm paper ground, ink type, and one hot tangerine signal for the CRUD foundation.

The product is literally a foundation for other projects, so its own visual language is a foundation too: a visible scale, a warm off-white paper ground instead of bootstrap white, ink text, and one hot non-blue accent used as a signal color for state, focus, and primary actions. The register is not "marketing SaaS" but "a tool I will actually read the source of" — precise, opinionated, warm in material, cold in logic.

Palette (light mode)

Proportion: ~70% paper, ~22% white surface, ~6% ink fill, ~2% tangerine. No blues, no indigos, no gradients.

Typography

• Headings: Space Grotesk at 600–700 with tight tracking (−0.02em to −0.04em), sentence case for section headings.
• Body: Inter Tight.
• Micro-labels: uppercase 11px with 0.12em tracking for field groups and table headers.
• Scale: 1.333 modular — 12 / 13 / 15 / 16 / 21 / 28 / 37 / 50 / 66.
• Display clamp: clamp(36px, 8vw, 66px) for the landing headline; page titles clamp(26px, 4vw, 37px); section headings 21px; body 16px with 1.55 line-height for long-form and 1.35 for dense table rows; table and label text 13px; monospace numerals at 13px with tabular-nums.

Shape language

• 4/8-pt spacing scale throughout.
• Compact controls: 8px radius on buttons and inputs, 12px on cards and panels, 2px on tags and status pills.
• Hairline 1px borders (#E4DFD6) on every surface.
• No shadows for elevation except a single 0 1px 0 rgba(20,21,23,0.04) on sticky headers.
• No pill buttons, no soft blobs, no large radii.
• The only decorative shape is a 3px tangerine left rule on active rows and on the records counter block.

Layout

• Fixed 240px left rail on desktop holding wordmark, primary nav (Records, New Record), and a keyboard-shortcut cheat sheet.
• Content area is a 12-column grid with a 640–880px reading measure for forms and a full-width dense table for the Records list.
• At 768px the rail collapses to a 56px icon rail; at 375px it becomes a top bar with a horizontally scrollable nav.
• Forms use two-column label/value alignment on desktop and stack on mobile.
• The Records table is a ruled data grid with tabular numerals, right-aligned counts, a sticky header, and inline row actions revealed on hover/focus.
• Empty states are a single line of ink text with a monospace 0 records numeral and a tangerine text link — no illustration.

Imagery

No photography, no illustration, no 3D. The interface is the imagery: schematic diagrams of the data model (a simple box-and-line diagram of Record → Field → Value rendered in ink hairlines with tangerine connectors), a code sample panel showing the create/read/update/delete calls in a dark ink block with the tangerine accent on the active line, and monospace numerals used as ornament throughout. The landing page uses one dark ink code panel as its only non-UI visual element.

7. Signature Design Concept

The landing first screen is a split editorial composition, not a centered SaaS hero.

• Left column (7 of 12 on desktop, full width on mobile): an oversized Space Grotesk headline set at clamp(36px, 8vw, 66px) reading "A core CRUD foundation you can actually read." stacked over three lines, with a 15px Inter Tight subline beneath it and a single tangerine-filled primary button ("Open the records") pinned directly under the subline, left-aligned.
• Right column (5 of 12): a full-height dark ink (#141517) code panel bleeding to the right viewport edge, showing a monospace CRUD snippet with the active line highlighted in tangerine (#E8562A), and a small tangerine tabular numeral 04 in its top-right corner.
• Below the fold: a full-width ruled strip of four monospace stats (records, fields, endpoints, latency) separated by 1px ink hairlines, each label in 11px uppercase tracked micro-type.

Nothing is centered; nothing floats; the ground is warm paper, not white. The composition recomposes only accepted content — the product purpose, the CRUD capability summary, the data-model schematic, and the two identity entry points — and introduces no new behavior, page, or destination.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the dark ink code panel bleeding off the right viewport edge, with the active CRUD line highlighted in tangerine and the tabular numeral 04 in its top-right corner.
• Input → transformation → outcome thesis: as the page settles, the code panel's active line resolves into its tangerine highlight and the 04 numeral settles into place — the foundation presenting itself as readable, working code. No scroll-linked effect, no parallax, no looping motion beyond the empty-state caret.
• Motion vocabulary: fast, functional 120–200ms transitions with cubic-bezier(0.2, 0, 0, 1). Focus rings animate in 80ms. Row hover shifts background to #F1EDE6 in 120ms. Page transitions are a 160ms opacity fade with no movement. The only looping motion is a 1.2s tangerine caret blink in the empty-state prompt and a 200ms count-up on the records total when the list resolves. No bounce, no particles, no parallax, no scroll-linked effects.
• Composed first frame: warm paper ground; oversized left-aligned headline stacked over three lines; 15px subline; tangerine primary CTA pinned beneath the subline; full-height dark ink code panel bleeding off the right edge with the active line in tangerine and 04 in the corner; below the fold, the ruled strip of four monospace stats.
• Reduced-motion state: all transitions resolve instantly; the empty-state caret renders as a static tangerine block; the records count renders at its final value without counting up. The layout is unchanged and every readable element remains whole and inside its container at 375px, 768px, and 1280px.

9. Non-Functional Requirements

NFR-1 — Durable persistence (required_inference) Records must persist durably and remain bound to the identity that created them, so that the foundation is a reliable starting point across sessions and across the multiple projects begun from it. Rationale: the accepted product intent is a reusable base for multiple projects; a base that loses data between sessions cannot serve that intent.

NFR-2 — Identity continuity without differentiated permissions (required_inference) Identity establishes ownership continuity only. No role-based visibility, permission tiers, or differentiated control over shared state is introduced. Rationale: the source establishes a single active human persona who owns their own records; no shared-state control requirement exists.

NFR-3 — Responsive integrity (explicit, from creative direction) Readable text and controls stay whole at every viewport: headlines, wordmarks, labels, numbers, card text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) 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, or overlapped exactly as the creative direction asks, as long as they cover no readable text or control.

NFR-4 — Reduced motion (explicit, from creative direction) With prefers-reduced-motion, provide a usable static arrangement: transitions resolve instantly, the empty-state caret is static, and the records count renders at its final value. Every item remains fully readable.

NFR-5 — Motion budget (explicit, from creative direction) UI-layer transitions stay within 120–200ms with cubic-bezier(0.2, 0, 0, 1). No bounce, spring, particle, parallax, or scroll-linked motion. The only looping motion is the 1.2s tangerine caret blink in the empty-state prompt.

NFR-6 — Accessible contrast and focus (required_inference) Ink (#141517) on paper (#F6F3EE) and on white (#FFFFFF) meets accessible contrast for body and heading text; muted (#8A857D) is reserved for labels, captions, and metadata. Focus rings use the tangerine accent (#E8562A) and animate in 80ms. Rationale: the direction specifies a focus-ring treatment and a muted role; making them usable requires contrast and visible focus.

NFR-7 — Keyboard-first operation (explicit, from creative direction) The left rail carries a keyboard-shortcut cheat sheet as first-class content, and inline row actions are revealed on hover or focus, so the record lifecycle is operable without a pointer.

10. Tech Stack

• Frontend: React (web), with the Space Grotesk / Inter Tight typographic system and the token set defined in Section 6.
• Backend: Python / FastAPI, extending a single shared backend process that serves the CRUD API and identity endpoints.
• Storage: A relational database appropriate to durable, identity-bound records.
• Packaging: Docker / docker-compose for the application services.
• Deployment: Kubernetes only if deployment requires it; not required by the current scope.

No source-specified technology choices conflict with these; the stack is the minimal set needed to deliver the accepted behavior.

11. Assumptions and Constraints

Assumptions

• A-1 (required_inference): The Project Starter is the sole active human persona; no second human participant, collaborator, or external counterparty exists in the current scope.
• A-2 (required_inference): Identity is application-owned because durable records must remain bound to the correct participant across sessions. Enrollment is self-service; verification is by returning credentials.
• A-3 (required_inference): A "record" is a durable, identity-owned entity with an id, a set of fields and values, and timestamps. The exact field schema is not specified by the source and is left to the implementation of the foundation.
• A-4 (basic_default): The three protected destinations (Records, New Record, Record Details) are separated because their working contexts, authoritative state, and completion outcomes differ. This is an information-architecture decision, not a new capability.

Constraints

• C-1 (explicit): The product is a core CRUD foundation intended as a starting point for multiple projects. It must remain reusable as such.
• C-2 (explicit): The generic indigo/blue-on-white SaaS template is forbidden. No blues, no indigos, no gradients.
• C-3 (explicit): No photography, no illustration, no 3D renders, no particle fields, no gradient meshes. The interface is the imagery.
• C-4 (explicit): No pill buttons, no large 24px+ radii, no drop shadows used for elevation.
• C-5 (explicit): Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, and system-ui are excluded as heading or body fonts.
• C-6 (explicit): No bouncy, springy, or scroll-linked parallax motion; nothing over 200ms in the UI layer.
• C-7 (explicit): Empty states stay as one line of ink text plus a monospace numeral — no illustrated empty states or decorative spot art.
• C-8 (explicit): No centered hero with headline, subtext, blue button, and gradient blob.
• C-9 (explicit): No grid of identical hover-lift cards for the records list; the list is a ruled data table.

Future (explicitly out of current scope)

• Additional projects built from this foundation are future work; the current scope is the foundation itself.
• No adjacent account-management capabilities (profile editing, password reset, role administration), no multi-tenant organization model, no sharing or collaboration, no audit log, no notifications, no analytics, no billing, and no third-party integrations are part of the current delivery.

12. Glossary

• Core CRUD — The create, read, update, and delete lifecycle over durable records that constitutes the reusable foundation.
• Record — A durable, identity-owned entity in the foundation, identified by an id and holding a set of fields and values plus timestamps.
• Field — A named slot within a record that holds a value.
• Value — The data held by a field in a record.
• Project Starter (Developer) — The single accepted active human persona; the developer who adopts the foundation as the starting point for multiple projects.
• Identity — The application-owned account that binds durable records to the correct participant.
• Session — The verified state that grants access to the protected record surfaces.
• Protected surface — A destination that requires established identity: Records, New Record, Record Details.
• Anonymous surface — A destination reachable without identity: Landing, Sign Up, Login.
• Tabular numerals — Monospace digits with tabular-nums used as ornament on record ids, counts, and stat blocks.
• Micro-label — An 11px uppercase label with 0.12em tracking used for field groups and table headers.