Files
SlpSoftware/aidlc-docs/features/redesign-modern-timetravel/inception/requirements/requirements.md
T

10 KiB
Raw Blame History

Requirements — redesign-modern-timetravel

Intent Analysis

  • User request: Build design option B (Modern) as the default site, add a button next to the light/dark switch to switch to option E (Time-travel), and build the contact form along with it. Other sessions that also need a form, and the CMS & API session, are attached when the form build starts.
  • Request type: New Feature (redesign + variant switch + new capability: contact form)
  • Scope estimate: Multiple components / cross-system (frontend theme system, nav, all landing sections, form; CMS/API repo SlpModularCms for the endpoint and shared module)
  • Complexity estimate: Complex
  • Requirements depth: Standard (comprehensive for the form/cross-repo part)
  • Design source: Claude Design canvas https://claude.ai/artifact/UkpzA5YPLheZm3fpmWdPtn — B = Modern.dc.html, E = Tijdreis2.dc.html, PakkettenModern.dc.html, PakkettenTijd.dc.html, plus dark wrappers. Accent B #7A1414, E #AC0000.

Functional Requirements

Variants and theming

  • FR-1 Variant B (Modern) is the default experience: hero, Over (with photo), Pakketten, Werkwijze ("Van idee naar live in drie stappen"), Contact (with form), footer, per the canvas design. Section years are not in the menu.
  • FR-2 Variant E (Time-travel) is built in full (this feature, separate unit after B): eras 2026 modern, 2013 flat, 2006 web 2.0, 1998 Windows-98 style with the redesigned Werkwijze step cards, 1989 terminal; per canvas design E. Years remain as badges per block.
  • FR-3 The theme model becomes variant (B | E) × mode (light | dark). The old red/purple themes are removed (answer Q4-A). B accent #7A1414, E accent #AC0000. The 1989 terminal section looks the same in light and dark.
  • FR-4 Nav contains the existing mode switch and, next to it, an icon-only button to switch to E (and back to B), with tooltip and accessible label (Q2-B).
  • FR-5 Mode starts from the visitor's system preference (prefers-color-scheme); an explicit choice overrides it and is remembered (Q5-B). The variant is not remembered: every visit starts in B; E is an easter egg (Q3-A).
  • FR-6 E is loaded lazily (code-split) so the default B bundle stays small. (Design decision proposed by AI; revisit in Application Design.)

Packages

  • FR-7 The packages block works with any number of packages from /api/v1/offerings (Q6-A). Skeleton count and grid are no longer hard-coded to 3.
  • FR-8 Filter chips (category + count, e.g. Alles/Websites/Onderhoud) appear from 4 packages on. Category is a new field in the API (category, the category name), a CMS/API change handed to the CMS builder. Categories are managed in the CMS (sub-section of the Offerings admin), not in settings; Bryan starts with Websites and Onderhoud (decision 2026-11-09, revised; earlier example values Websites/Software/Beheer were only placeholders). Mock data for 6 packages in tests uses these names.
  • FR-9 A "Past er niets bij? / Maatwerk" banner always stays below the cards.
  • FR-10 On mobile the cards form a horizontal swipe row (CSS scroll-snap) for any number of packages (Q7-A): ~85% card width so the next card peeks, dot indicator, the featured package first in view; grid on tablet/desktop (3 columns, 2 columns at ≤1000px). Must be keyboard and screen-reader usable and not depend on JavaScript for scrolling.
  • FR-11 Content for the four additional packages (Webshop, CMS, Koppelingen & API's, Onderhoud) is out of scope; layout is built generically and tested with mock data of 6 packages (Q8-A).
  • FR-12 Both B and E have their own styling of the packages block (B: square chips and cards; E: 2006 glossy tabs and cards), light and dark.

Contact form

  • FR-13 Fields: name, e-mail, subject/package (select, preselected via the "Kies …" button of a package card) and message (Q9-A). All four fields are required (follow-up decision 2026-11-09). All fields validated on the client and on the server. Limits and messages are aligned with the ASF form: name max 100, e-mail max 254, message max 2000.
  • FR-14 Submit sends the message to the CMS/API, which stores it and e-mails the site owner (Q10-A), e.g. POST /api/v1/contact-messages. Exact contract defined together with the CMS sessions. Store first, mail best-effort with a status; a mail failure never fails the save. Stored messages are kept 12 months (follow-up decision), then removed by a retention job.
  • FR-14a (future, out of scope) The owner may later turn a stored message into an assignment in an administration system to produce quotes and invoices. Not built now; the stored message keeps its own id and a status so this stays possible.
  • FR-15 Form states: idle, validating (inline errors), submitting, success, server error with retry; no loss of input on error.
  • FR-16 Spam protection (Q12-C): honeypot field + time check + server-side rate limit, with an external captcha as a fallback to switch on if abuse occurs (ASF plans Friendly Captcha; provider to be settled in the contract). Suggested hardening from the CMS session: server-signed timestamp token for the time check, idempotency key against double submit, identical response on spam detection so bots learn nothing, site id derived from host/config (never from the request body).
  • FR-17 A one-sentence privacy note under the form (purpose and retention), no consent checkbox (Q13-A). Recipient e-mail, retention period and the privacy-statement link/text are configurable per site (requested by the ASF website session; ASF keeps its sentence "Lees in de privacyverklaring wat ik met je gegevens doe." linking to /privacyverklaring). Captcha provider: Friendly Captcha fits ASF (its code already has a [data-robot-check] slot).
  • FR-18 Reusable module (Q11-B, Q16-A, follow-up decision): two parts. (1) A Contact/Forms API module in SlpModularCms (endpoint, storage, mail, spam checks, retention job). (2) One frontend package cms-client (working name) in SlpModularCms that types and calls the CMS API, with separately importable parts (subpath imports such as /contact, later /offerings) so a site only bundles what it uses. The contact part is headless (state/reducer, validation, preselect with change counter, idPrefix, render slots for honeypot/robot check/status, injectable texts and submit function, a11y wiring); each site, including B and E here and the other sites, supplies its own markup and styling. Types come from the CMS OpenAPI description. Offerings moves into the same package later for consistency (not in this feature unless cheap). Consumption route (workspace/file dependency or tagged copy first, private registry only with a third consumer) is a recommendation awaiting the user's confirmation.
  • FR-19 Form copy and layout per design: B has a red contact block with a white (light) / dark form panel; E has the terminal-style form in 1989 and matching styles per era where applicable.

Non-Functional Requirements

  • NFR-1 Accessibility: WCAG 2.1 AA for B and E (contrast, keyboard, screen reader, visible focus); all animation (marquee, scanlines, dither, caret) disabled under prefers-reduced-motion (Q14-A).

  • NFR-2 Responsive: layouts work from 360px to 1440px+; no horizontal page scroll (swipe row excepted).

  • NFR-3 Performance: E is code-split; fonts are self-hosted via @fontsource (no Google Fonts requests) and limited to the weights used; images keep the existing responsive WebP variants.

  • NFR-4 Security (Security Baseline enabled): server-side validation and output encoding, no secrets in the frontend bundle, rate limiting, no PII in logs or Sentry/Umami events, security headers / CSP compatible with the new fonts and API origin, dependency hygiene. Applicable SECURITY rules are enforced as blocking at each stage.

  • NFR-5 Privacy: stored contact messages contain personal data; retention is 12 months, stated in the privacy note and enforced by the CMS retention job. No e-mail address or message text in logs or Sentry breadcrumbs.

  • NFR-6 Testing: Vitest + Testing Library for components (theme switch, variant switch, packages grid with 3 and 6 items, swipe row semantics, form states). Property-based testing partial (Q-PBT-B): applies to pure functions and serialization round-trips, e.g. form validation functions and request/response serialization.

  • NFR-7 Maintainability: theme tokens as CSS variables per variant × mode; Tailwind semantic color names remain; content stays in content.ts/API.

  • NFR-8 Compatibility: hash routing and static hosting remain; the existing Sentry/Umami integration and the CI/CD pipeline keep working.

  • NFR-9 SEO and performance (U6): static text is prerendered into the HTML at build; dynamic parts (packages, later gallery) are injected by the CMS host from current data, fresh within minutes; canonical, Open Graph/Twitter, favicon set, JSON-LD (organisation and offers), robots.txt and sitemap.xml; test hosts serve Disallow: / and X-Robots-Tag: noindex from the host, not the bundle; Lighthouse in the pipeline on mobile and desktop is a hard gate of at least 0.9 per category (exceptions only with a recorded owner decision); no new third-party scripts.

Assumptions

  • Current copy and texts of the live site (incl. the November text update) are leading unless the design says otherwise.
  • The packages API keeps its current shape plus category; the CMS session implements it.
  • E may use period-appropriate fonts (Archivo for B; Open Sans, Trebuchet/Verdana, Times/Arial, VT323 for E) as self-hosted or system fonts.
  • Delivery: one branch feature/redesign-modern-timetravel, commits per unit, one PR at the end.

Risks and Dependencies

  • Cross-repo: the endpoint, the category API field and the headless form module live in SlpModularCms; the CMS session must be attached. See aidlc-docs/features/redesign-modern-timetravel/aidlc-state.md § Coordination Notes.
  • Form coordination moment: the user wants to be told before the form build starts so other sessions (e.g. Andrea site with its own ContactForm) and the CMS session can join.
  • E is a large build; B-first ordering limits risk.

Operations

  • Include Operations Phase: Undecided — asked again after Construction (Q15-C). Likely topics: nginx route for the form endpoint, monitoring of form errors.

Extension Compliance Summary

  • Security Baseline: enabled (Q-Security-A). Requirements-level compliance: NFR-4/5 added; detailed per-rule checks run in later stages.
  • Property-Based Testing: partial (Q-PBT-B). Requirements-level: NFR-6.