Initial commit: React frontend (SLP Software) + AIDLC workflow docs

Co-authored-by: Junie <junie@jetbrains.com>
2026-07-20 00:19:44 +02:00
commit e299f1c745
73 changed files with 7275 additions and 0 deletions
@@ -0,0 +1,47 @@
+# Code Summary — react-frontend-app
+
+## Application Code (Workspace Root)
+
+### Project Configuration
+- `package.json`, `vite.config.ts`, `tsconfig.json`, `tsconfig.node.json`, `index.html`, `.gitignore`
+- `tailwind.config.ts`, `postcss.config.js` — Tailwind theme mapped to CSS custom properties
+- `eslint.config.js` (ESLint 9 flat config), `.prettierrc`
+- `README.md` — setup/run/build/test instructions
+
+### Domain Data & Theme
+- `src/data/content.ts` — typed static content (NavLink, HeroContent, PackageCardData, ProcessStepData, AboutContent, ContactInfo), copied 1-to-1 from the reference designs
+- `src/theme/tokens.ts` — theme value model (`red`/`purple`), storage key, validation/fallback (BR-1/BR-3)
+- `src/theme/ThemeProvider.tsx` — theme context, localStorage persistence (BR-2), applies `theme-red`/`theme-purple` class to `<html>`
+- `src/index.css` — theme token CSS variables (`.theme-red`, `.theme-purple`), global styles, caret animation, reduced-motion handling
+- `src/fonts.ts` — self-hosted font imports (`@fontsource/sora`, `@fontsource/instrument-sans`, `@fontsource/jetbrains-mono`)
+
+### Application Shell
+- `src/queryClient.ts` — shared `QueryClient` (`staleTime: Infinity`)
+- `src/hooks/usePackagesQuery.ts` — placeholder query hook wrapping static package data
+- `src/components/ErrorBoundary.tsx` — top-level on-brand error boundary
+- `src/routes/__root.tsx` — root route composing ErrorBoundary → ThemeProvider → QueryClientProvider → RootLayout
+- `src/routes/index.tsx` — index route assembling the page sections
+- `src/router.tsx` — router instance with hash-based history
+- `src/main.tsx` — application entry point
+
+### Components
+- `src/components/RootLayout.tsx`, `Nav.tsx`, `ThemeToggle.tsx`, `Hero.tsx`, `PackagesSection.tsx`, `PackageCard.tsx`, `ProcessSection.tsx`, `ProcessStep.tsx`, `AboutSection.tsx`, `ContactSection.tsx`, `Footer.tsx`
+
+### Tests
+- `src/theme/__tests__/ThemeProvider.test.tsx` — 4 tests covering BR-1, BR-2, BR-3
+- `src/components/__tests__/Nav.test.tsx` — 3 tests (nav links, accessible toggle label, toggle interaction)
+- `src/components/__tests__/PackagesSection.test.tsx` — 2 tests (package rendering, featured badge)
+- `src/test/setup.ts` — Testing Library / jest-dom setup for Vitest
+
+## Verification (Step 13.5)
+- **Build**: ✅ Success (`npm run build` — `tsc -b && vite build`)
+- **Unit Tests**: ✅ 9 passed, 0 failed (`npm run test` — Vitest)
+- **Lint**: ✅ 0 errors (2 non-blocking `react-refresh/only-export-components` warnings on files that intentionally export a hook alongside a component)
+
+### Post-Review Fix: Deprecated Package Warnings
+After initial review, the user requested that the `npm install` deprecation warnings (`eslint@8.57.1`, `@humanwhocodes/config-array`, `@humanwhocodes/object-schema`, and related transitive packages) be resolved. Resolved by migrating from ESLint 8 (`.eslintrc.cjs`) to **ESLint 9 flat config** (`eslint.config.js`), using `typescript-eslint`, `@eslint/js`, `globals`, and `eslint-plugin-react-hooks` v5. Re-verified: build, tests (9/9), and lint (0 errors) all still pass after the migration, and `npm install` no longer reports deprecation warnings for these packages.
+
+## Traceability
+- Requirements: FR-1 (content parity), FR-2 (componentization), FR-3 (theme switching), FR-4 (preserved micro-interactions), FR-5 (TanStack Router/Query scaffolding), NFR-1 through NFR-5
+- Functional Design business rules BR-1 through BR-6 implemented as described above
+- NFR Design patterns (error boundary, query caching, self-hosted fonts, hash routing) implemented as described above
@@ -0,0 +1,65 @@
+# Business Logic Model — react-frontend-app
+
+## Overview
+This unit's business logic is small and UI-centric: rendering static marketing content and managing the theme (red default / purple alternate) selection and persistence. There is no backend business logic in this iteration.
+
+## Process Flow: Page Load and Theme Resolution
+
+```mermaid
+graph TD
+    start_load["Visitor loads the site"]
+    read_storage["Read stored theme preference from localStorage"]
+    check_stored["Stored preference found?"]
+    use_stored["Use stored theme (red or purple)"]
+    use_default["Use default theme: red"]
+    apply_theme["Apply theme class/attribute to document root"]
+    load_content["Load static content module (nav, hero, packages, steps, about, contact)"]
+    init_query["Initialize QueryClientProvider and packages placeholder query"]
+    render_page["Render page sections via TanStack Router index route"]
+
+    start_load --> read_storage
+    read_storage --> check_stored
+    check_stored -->|"Yes"| use_stored
+    check_stored -->|"No"| use_default
+    use_stored --> apply_theme
+    use_default --> apply_theme
+    apply_theme --> load_content
+    load_content --> init_query
+    init_query --> render_page
+
+    classDef process fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
+    classDef decision fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
+    classDef terminal fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
+
+    class start_load,render_page terminal;
+    class read_storage,use_stored,use_default,apply_theme,load_content,init_query process;
+    class check_stored decision;
+```
+
+Text alternative: On load, the app reads a stored theme preference; if found it is used, otherwise red is used as default; the theme is applied to the document, static content is loaded, the query provider is initialized, then the page renders.
+
+## Process Flow: Theme Switch Interaction
+
+```mermaid
+graph TD
+    click_toggle["Visitor clicks the theme toggle button in the nav"]
+    determine_next["Determine next theme (red to purple, or purple to red)"]
+    update_state["Update in-memory theme state (ThemeProvider context)"]
+    persist_storage["Persist chosen theme to localStorage"]
+    reapply_theme["Re-apply theme class/attribute to document root"]
+    update_toggle["Update toggle button visual state and aria-pressed"]
+
+    click_toggle --> determine_next
+    determine_next --> update_state
+    update_state --> persist_storage
+    persist_storage --> reapply_theme
+    reapply_theme --> update_toggle
+
+    classDef process fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
+    classDef terminal fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
+
+    class click_toggle terminal;
+    class determine_next,update_state,persist_storage,reapply_theme,update_toggle process;
+```
+
+Text alternative: Clicking the toggle determines the other theme, updates in-memory state, persists it to localStorage, reapplies the theme to the document, and updates the toggle button's visual/accessible state.
@@ -0,0 +1,42 @@
+# Business Rules — react-frontend-app
+
+## BR-1: Default Theme Rule
+The site MUST use the **red** theme when no stored theme preference exists (first visit, cleared storage, or unsupported storage).
+
+## BR-2: Theme Persistence Rule
+Whenever the visitor switches themes, the chosen theme MUST be written to `localStorage` immediately, so a page reload or new visit resolves to the same theme (BR-1 only applies when nothing is stored).
+
+## BR-3: Valid Theme Values Rule
+Only two theme values are valid: `red` and `purple`. If a stored value is anything else (corrupted/unexpected), the app MUST fall back to the default theme (`red`) rather than error.
+
+## BR-4: Content Fidelity Rule
+All rendered marketing copy, prices (€300 / €750 / "Op maat"), and the contact e-mail (`info@slpsoftware.nl`) MUST match the reference HTML designs exactly for this iteration (per requirements FR-1); no content may be altered, abbreviated, or replaced with placeholder text.
+
+## BR-5: Reduced Motion Rule
+When the visitor's OS/browser signals `prefers-reduced-motion: reduce`, both the hero caret blink animation AND the theme-switch color transition MUST be instant / non-animated.
+
+## BR-6: Single Route Rule (current iteration)
+For this iteration, all page sections (nav, hero, packages, process, about, contact, footer) are rendered under a single index route (`/`). No section requires its own route yet.
+
+## Decision Flow: Theme Resolution on Load
+
+```mermaid
+graph TD
+    load_pref{"Stored theme value exists?"}
+    valid_check{"Stored value is 'red' or 'purple'?"}
+    use_stored_value["Use stored value as active theme"]
+    fallback_default["Fall back to default theme: red"]
+
+    load_pref -->|"No"| fallback_default
+    load_pref -->|"Yes"| valid_check
+    valid_check -->|"Yes"| use_stored_value
+    valid_check -->|"No (corrupted/unexpected)"| fallback_default
+
+    classDef decision fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
+    classDef outcome fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
+
+    class load_pref,valid_check decision;
+    class use_stored_value,fallback_default outcome;
+```
+
+Text alternative: If no stored theme exists, or the stored value is not "red"/"purple", the app falls back to red; otherwise the valid stored value is used.
@@ -0,0 +1,97 @@
+# Domain Entities — react-frontend-app
+
+## Overview
+This unit has no persisted backend entities. The "domain" here is the static content model and the theme model that drive rendering.
+
+## Entity Relationships
+
+```mermaid
+graph TD
+    theme_pref["ThemePreference"]
+    theme_tokens["ThemeTokens"]
+    site_content["SiteContent"]
+    nav_link["NavLink"]
+    hero_content["HeroContent"]
+    package_card["PackageCard"]
+    process_step["ProcessStep"]
+    about_content["AboutContent"]
+    contact_info["ContactInfo"]
+
+    theme_pref -->|"selects"| theme_tokens
+    site_content -->|"has many"| nav_link
+    site_content -->|"has one"| hero_content
+    site_content -->|"has many"| package_card
+    site_content -->|"has many"| process_step
+    site_content -->|"has one"| about_content
+    site_content -->|"has one"| contact_info
+
+    classDef entity fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
+    classDef value fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
+
+    class theme_pref,site_content entity;
+    class theme_tokens,nav_link,hero_content,package_card,process_step,about_content,contact_info value;
+```
+
+Text alternative: A ThemePreference selects a set of ThemeTokens; SiteContent aggregates NavLinks, one HeroContent, many PackageCards, many ProcessSteps, one AboutContent, and one ContactInfo (blue = stateful entity, orange = static value objects).
+
+## Entity Definitions
+
+### ThemePreference
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `value` | `'red' \| 'purple'` | Yes | Currently active theme; defaults to `'red'` per BR-1 |
+| `source` | `'stored' \| 'default'` | Yes | Whether the value came from `localStorage` or the default fallback |
+
+### ThemeTokens
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `bg`, `surface`, `surfaceAlt`, `line`, `text`, `muted` | `string` (hex) | Yes | Neutral palette tokens, taken 1-to-1 from the reference CSS variables |
+| `accent`, `accentSoft`, `accentLine` | `string` (hex/rgba) | Yes | Accent palette tokens (red or purple variant), taken 1-to-1 from the reference CSS variables |
+
+### NavLink
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | Yes | Link text (e.g. "Pakketten") |
+| `href` | `string` | Yes | Anchor target (e.g. "#pakketten") |
+| `isCta` | `boolean` | No | Marks the "Start project" call-to-action link |
+
+### HeroContent
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `eyebrow` | `string` | Yes | Small label above the heading |
+| `heading` | `string` | Yes | Main H1 text |
+| `lead` | `string` | Yes | Lead paragraph text |
+| `codeLine` | `string` | Yes | The animated code-line snippet text |
+
+### PackageCard
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | Yes | e.g. `pakket_01` |
+| `title` | `string` | Yes | e.g. "Landingspagina" |
+| `description` | `string` | Yes | Short description |
+| `price` | `string` | Yes | e.g. "€ 300" or "Op maat" |
+| `priceNote` | `string` | Yes | e.g. "eenmalig, excl. btw" |
+| `features` | `string[]` | Yes | Bullet list of included features |
+| `ctaLabel` | `string` | Yes | Button text |
+| `featured` | `boolean` | No | Marks the "Meest gekozen" (most chosen) card |
+
+### ProcessStep
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | Yes | e.g. "stap 01 — intake" |
+| `title` | `string` | Yes | e.g. "Kennismaken" |
+| `description` | `string` | Yes | Step description |
+
+### AboutContent
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `paragraphs` | `string[]` | Yes | About-section body paragraphs |
+| `techStack` | `{ label: string; value: string }[]` | Yes | Tech-stack list items (Front-end, Back-end, API's, Focus) |
+
+### ContactInfo
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `heading` | `string` | Yes | Contact section heading |
+| `description` | `string` | Yes | Contact section body text |
+| `email` | `string` | Yes | `info@slpsoftware.nl` |
+| `mailSubject` | `string` | Yes | Prefilled mailto subject |
@@ -0,0 +1,77 @@
+# Frontend Components — react-frontend-app
+
+## Component Hierarchy
+
+```mermaid
+graph TD
+    root_route["__root.tsx\n(Root Route: ThemeProvider + QueryClientProvider)"]
+    layout["RootLayout\n(Nav + Footer wrapper)"]
+    index_route["index.tsx\n(/ Index Route)"]
+    nav["Nav"]
+    theme_toggle["ThemeToggle"]
+    hero["Hero"]
+    packages_section["PackagesSection"]
+    package_card["PackageCard (x3)"]
+    process_section["ProcessSection"]
+    process_step["ProcessStep (x3)"]
+    about_section["AboutSection"]
+    contact_section["ContactSection"]
+    footer["Footer"]
+
+    root_route --> layout
+    layout --> nav
+    nav --> theme_toggle
+    layout --> index_route
+    index_route --> hero
+    index_route --> packages_section
+    packages_section --> package_card
+    index_route --> process_section
+    process_section --> process_step
+    index_route --> about_section
+    index_route --> contact_section
+    layout --> footer
+
+    classDef root_node fill:#4CAF50,stroke:#2e7d32,stroke-width:2px,color:#000;
+    classDef layout_node fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
+    classDef page_node fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
+    classDef guard_node fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
+
+    class root_route root_node;
+    class layout,index_route layout_node;
+    class nav,hero,packages_section,package_card,process_section,process_step,about_section,contact_section,footer page_node;
+    class theme_toggle guard_node;
+```
+
+Text alternative: The root route provides ThemeProvider and QueryClientProvider and renders a RootLayout (Nav with ThemeToggle, plus Footer) wrapping the index route, which renders Hero, PackagesSection (three PackageCard instances), ProcessSection (three ProcessStep instances), AboutSection, and ContactSection.
+
+## Components: Props and State
+
+| Component | Props | State | Notes |
+|---|---|---|---|
+| `RootRoute` (`__root.tsx`) | — | — | Hosts `ThemeProvider` and `QueryClientProvider`; renders `<Outlet />` |
+| `ThemeProvider` | `children: ReactNode` | `theme: 'red' \| 'purple'` (from context) | Reads/writes `localStorage`; exposes `theme` and `toggleTheme()` via context; applies `theme-red`/`theme-purple` class to `<html>` |
+| `RootLayout` | `children: ReactNode` | — | Renders `Nav`, `children` (routed content), `Footer` |
+| `Nav` | `links: NavLink[]` | — | Renders logo, `nav-links`, `ThemeToggle`, CTA link |
+| `ThemeToggle` | — | — | Reads `theme`/`toggleTheme` from `ThemeProvider` context; `aria-label="Wissel kleurthema"`, `aria-pressed` reflects whether purple is active |
+| `Hero` | `content: HeroContent` | — | Renders eyebrow, heading, lead, animated code line (caret respects `prefers-reduced-motion`), two CTA buttons |
+| `PackagesSection` | `packages: PackageCard[]` | — | Renders section head + grid of `PackageCard` |
+| `PackageCard` | `pkg: PackageCard` | — | Renders one pricing card; `featured` prop styling for "Meest gekozen" |
+| `ProcessSection` | `steps: ProcessStep[]` | — | Renders section head + grid of `ProcessStep` |
+| `ProcessStep` | `step: ProcessStep` | — | Renders one process step (label, title, description) |
+| `AboutSection` | `content: AboutContent` | — | Renders paragraphs + tech-stack panel |
+| `ContactSection` | `content: ContactInfo` | — | Renders contact box with mailto CTA |
+| `Footer` | — | — | Renders copyright + mono tagline |
+
+## User Interaction Flows
+
+- **Theme toggle click**: `ThemeToggle` → calls `toggleTheme()` from `ThemeProvider` context → context updates `theme` state → writes new value to `localStorage` (BR-2) → root element's theme class is updated → all themed elements re-render with new token values → transition is instant if `prefers-reduced-motion: reduce` (BR-5), otherwise a short color transition plays.
+- **In-page anchor navigation**: Clicking a `Nav` link or hero CTA scrolls smoothly to the target section (`scroll-behavior: smooth`), respecting `prefers-reduced-motion` (falls back to instant jump).
+- **Hover / focus-visible states**: Preserved 1-to-1 from the reference design on nav links, buttons, and cards (border/color changes on `:hover`/`:focus-visible`).
+- **Mailto CTA**: Clicking the contact CTA or the inline mail link opens the visitor's mail client via a `mailto:` link with a prefilled subject.
+
+## Form Validation Rules
+None — this iteration has no forms; the only interactive control is the theme toggle and standard anchor/mailto links.
+
+## API Integration Points (Forward-Looking)
+- `usePackagesQuery` (TanStack Query hook, placeholder): `queryFn` currently resolves the static `PackageCard[]` data from the content module wrapped in `Promise.resolve(...)`, consumed via `useQuery` in `PackagesSection`. This keeps the component's data-access pattern identical to what it will be once a real backend endpoint exists — only the `queryFn` implementation will need to change in a future iteration (per FR-5).
+- No other components call `useQuery` in this iteration; `Nav`, `Hero`, `ProcessSection`, `AboutSection`, and `ContactSection` read directly from the static content module for now.
@@ -0,0 +1,42 @@
+# Logical Components — react-frontend-app
+
+## Component/Provider Overview
+
+```mermaid
+graph TD
+    router["Router Instance\n(TanStack Router, hash history)"]
+    query_client["QueryClientProvider\n(staleTime: Infinity for placeholder queries)"]
+    theme_provider["ThemeProvider\n(theme state + localStorage persistence)"]
+    error_boundary["ErrorBoundary\n(on-brand fallback UI)"]
+    root_route["Root Route (__root.tsx)"]
+    fonts["Self-hosted Fonts\n(bundled static assets)"]
+
+    router --> root_route
+    root_route --> error_boundary
+    error_boundary --> theme_provider
+    theme_provider --> query_client
+    root_route -.->|"loads"| fonts
+
+    classDef infra fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000;
+    classDef guard fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
+    classDef layout fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
+    classDef asset fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
+
+    class router,query_client infra;
+    class error_boundary guard;
+    class theme_provider,root_route layout;
+    class fonts asset;
+```
+
+Text alternative: The router hosts the root route, which is wrapped by an ErrorBoundary, which wraps ThemeProvider, which wraps QueryClientProvider; the root route also loads self-hosted font assets (purple = infra provider, orange = guard/boundary, blue = layout/route, green = static asset).
+
+## Logical Component Definitions
+
+| Component | Type | Responsibility |
+|---|---|---|
+| **Router Instance** | Infrastructure | Created via TanStack Router with `createHashHistory()`; defines the root route and index route tree. |
+| **QueryClientProvider** | Infrastructure | Wraps the app with a single shared `QueryClient`; configures default `staleTime: Infinity` for this iteration's placeholder queries. |
+| **ThemeProvider** | Layout/Context | Owns `theme` state (`'red' \| 'purple'`), reads/writes `localStorage`, applies the active theme class to the document root; exposes `theme` + `toggleTheme()` via React context (implements BR-1, BR-2, BR-3). |
+| **ErrorBoundary** | Guard | Top-level React error boundary; renders the on-brand fallback UI on unexpected render errors (implements the Resilience Pattern). |
+| **Root Route (`__root.tsx`)** | Layout/Route | Composes `ErrorBoundary` → `ThemeProvider` → `QueryClientProvider` → `RootLayout` (Nav/Footer) → routed content (`<Outlet />`). |
+| **Self-hosted Fonts** | Static Asset | Sora, Instrument Sans, and JetBrains Mono font files bundled with the app and declared via local `@font-face`/`@fontsource` imports — no external CDN dependency. |
@@ -0,0 +1,26 @@
+# NFR Design Patterns — react-frontend-app
+
+## Resilience Pattern: Top-Level Error Boundary
+A single React error boundary wraps the routed content inside the root route. On an unexpected rendering error it shows a minimal, on-brand fallback message styled with the currently active theme (e.g. "Er ging iets mis. Probeer de pagina te vernieuwen."), with no stack traces or technical details exposed (satisfies SECURITY-09 and SECURITY-15 from NFR Requirements).
+
+## Scalability Pattern: Not Applicable (Justified)
+This is a static single-page marketing site with no server-side component to scale. The only forward-looking "scalability" concern — adding more routes and swapping the placeholder query for a real API — is already accommodated structurally by the Functional Design's root/index route split and the `usePackagesQuery` hook shape, so no additional scalability pattern is introduced at this stage.
+
+## Performance Patterns
+
+### Query Caching
+The `usePackagesQuery` placeholder hook is configured with `staleTime: Infinity` (and no automatic refetch-on-window-focus), since its `queryFn` currently always returns the same static array. This is a deliberate choice anticipating the future real-data swap, where refetch behavior can be tuned once real network latency/staleness exists.
+
+### Font Loading
+Fonts (Sora, Instrument Sans, JetBrains Mono) are **self-hosted** as static assets bundled with the app (via `@fontsource/*` packages or locally vendored font files + `@font-face` declarations), rather than loaded from the Google Fonts CDN.
+- **Impact on Security Baseline SECURITY-13 (integrity)**: Self-hosting removes the need for Subresource Integrity (SRI) hashes on font `<link>` tags entirely, since no external CDN resource is loaded for fonts anymore. The NFR Requirements SECURITY-13 note ("SRI where feasible") is superseded by this decision — self-hosting is a stronger mitigation (no external dependency at all) than SRI on a CDN resource.
+- **Trade-off accepted**: Slightly larger initial bundle/setup effort, in exchange for one fewer external dependency and a fully offline-buildable app.
+
+## Security Patterns
+- **Dependency/supply chain (SECURITY-10)**: `package-lock.json` committed; `npm audit` step documented in build instructions (implemented in Build and Test stage).
+- **Integrity (SECURITY-13)**: Satisfied via the font self-hosting decision above (no external CDN assets requiring SRI remain in this iteration).
+- **Hardening (SECURITY-09) & fail-safe defaults (SECURITY-15)**: Satisfied via the Resilience Pattern (error boundary) above and a standard production build with no demo/sample routes.
+- **HTTP security headers (SECURITY-04)**: Remains deferred to Deployment Setup (Operations phase), unchanged from NFR Requirements — no hosting decision has been finalized yet.
+
+## Logical Components
+See `logical-components.md` for the concrete component/provider list implementing these patterns.
@@ -0,0 +1,53 @@
+# NFR Requirements — react-frontend-app
+
+## Performance
+- **Target**: No hard numeric target. Keep the production bundle reasonably small; code-splitting is not required for this single-page iteration but the setup should not preclude it later (Vite handles this automatically as routes/queries grow).
+
+## Testing
+- **Test runner**: Vitest (pairs naturally with Vite)
+- **Component testing**: React Testing Library
+- **Scope for this iteration**: Component rendering tests for key components (`Nav`, `ThemeToggle`, `PackagesSection`, `PackageCard`) and a unit test for the theme resolution/persistence logic (BR-1, BR-2, BR-3).
+
+## Linting & Formatting
+- **ESLint** configured with React + TypeScript rules (e.g. `typescript-eslint`, `eslint-plugin-react-hooks`)
+- **Prettier** for consistent formatting
+- Both must pass cleanly on the initial generated codebase.
+
+## Routing Strategy for Static/FTP Hosting (AI Recommendation)
+The user deferred this decision to the AI (Question 4 = "Not sure — let the AI recommend").
+
+**Decision: Use TanStack Router's hash-based history (`createHashHistory`) for this iteration.**
+
+**Rationale**:
+- The confirmed deployment target (requirements.md NFR-4) is a traditional web host via FTP/manual upload, where server-side rewrite rules (`.htaccess` or equivalent) are not guaranteed to be configurable or reliably supported.
+- Hash-based routing (`/#/route`) works correctly on any static file host with zero server configuration, because the part after `#` is never sent to the server — the server only ever needs to serve `index.html`.
+- The trade-off (slightly less clean URLs, e.g. `example.com/#/pakketten` instead of `example.com/pakketten`) is acceptable for a small marketing site and avoids a class of "404 on refresh/direct link" bugs that browser `history` mode would introduce on this hosting target.
+- If hosting later moves to a platform with reliable rewrite support (e.g. Netlify/Vercel per requirements.md's alternative hosting note), this can be revisited and switched to `createBrowserHistory` — this is a router configuration change only, not a structural one, since TanStack Router's history mode is set in one place at the router's creation.
+
+## Accessibility
+- **Target**: Best-effort only, matching whatever the reference HTML already provides (no formal WCAG level mandated for this iteration). Note: the functional design already includes concrete accessibility details (Dutch `aria-label` and `aria-pressed` on the theme toggle) that will still be implemented, since they were explicit functional design decisions — this NFR decision only means no additional formal accessibility audit/target is required beyond that.
+
+## CI/CD
+- **This iteration**: No CI pipeline is set up yet. Deferred to the Operations phase (Deployment Setup), which will define the concrete build/deploy process for the FTP target.
+
+## Security Baseline — Rule-by-Rule Applicability
+
+| Rule | Applicability | Decision / Rationale |
+|---|---|---|
+| SECURITY-01 (encryption at rest/in transit) | N/A | No data store exists in this static frontend. |
+| SECURITY-02 (access logging on intermediaries) | N/A | No load balancer/API gateway/CDN configured by this unit; would apply at hosting level if applicable, out of scope here. |
+| SECURITY-03 (application-level logging) | N/A | No server-side application component; a client-side app has no backend logs to configure. |
+| SECURITY-04 (HTTP security headers) | Deferred | Depends on the final hosting choice and whether the host supports custom headers — deferred to Deployment Setup (Operations phase). |
+| SECURITY-05 (input validation on API params) | N/A | No API endpoints exist in this unit. |
+| SECURITY-06 (least-privilege access policies) | N/A | No IAM/cloud roles involved. |
+| SECURITY-07 (restrictive network configuration) | N/A | No network/firewall resources involved. |
+| SECURITY-08 (application-level access control) | N/A | No authenticated resources or user accounts exist. |
+| SECURITY-09 (hardening/misconfiguration) | Addressed now | Production build via Vite has no sample/demo pages; a top-level React error boundary will show a generic message instead of exposing stack traces. |
+| SECURITY-10 (software supply chain) | Addressed now | `package-lock.json` committed; `npm audit` documented as part of build instructions; no unused dependencies added. |
+| SECURITY-11 (secure design principles) | N/A | No security-critical logic (auth, payments) exists in this unit. |
+| SECURITY-12 (authentication/credential mgmt) | N/A | No authentication exists in this unit. |
+| SECURITY-13 (software/data integrity) | Addressed now (partial) | Subresource Integrity (SRI) hashes will be added to the Google Fonts `<link>` tags where the CDN provides stable, hashable assets; no other external CDN resources are used. |
+| SECURITY-14 (alerting and monitoring) | Deferred | No backend/log service exists yet; revisit if/when Monitoring Setup (Operations phase) introduces any client-side error/analytics reporting. |
+| SECURITY-15 (exception handling / fail-safe defaults) | Addressed now | A top-level React error boundary is added; the `usePackagesQuery` placeholder hook's promise-based `queryFn` will have explicit error handling wired through TanStack Query's error state. |
+
+**Summary**: 10 of 15 Security Baseline rules are N/A for this static, no-backend frontend. 4 rules (SECURITY-09, SECURITY-10, SECURITY-13, SECURITY-15) are addressed during this iteration's Code Generation. 2 rules (SECURITY-04, SECURITY-14) are explicitly deferred to the Operations phase.
@@ -0,0 +1,15 @@
+# Tech Stack Decisions — react-frontend-app
+
+| Concern | Decision | Rationale |
+|---|---|---|
+| Build tool | Vite | Confirmed in requirements.md NFR-1; fast dev server, first-class TypeScript/React support, pairs naturally with Vitest. |
+| Language | TypeScript | Confirmed in requirements.md NFR-1; type safety for the domain entities defined in functional design. |
+| UI library | React 18+ | Confirmed in requirements.md NFR-1. |
+| Styling | Tailwind CSS | Confirmed in requirements.md NFR-2. Theme variants implemented as Tailwind theme classes (`theme-red` / `theme-purple`) per Functional Design Question 2 answer. |
+| Routing | TanStack Router, hash-based history (`createHashHistory`) | Confirmed in requirements.md FR-5; hash history chosen per this stage's routing-strategy decision (NFR Requirements Question 4) to be safe on a plain FTP static host without server rewrite rules. |
+| Data fetching (forward-looking) | TanStack Query (`@tanstack/react-query`) | Confirmed in requirements.md FR-5; a `QueryClientProvider` is set up now, with one placeholder query hook (`usePackagesQuery`) as defined in Functional Design. |
+| Testing | Vitest + React Testing Library | NFR Requirements Question 2 answer A. |
+| Linting | ESLint (`typescript-eslint`, `eslint-plugin-react-hooks`) + Prettier | NFR Requirements Question 3 answer A. |
+| Package manager | npm (with committed `package-lock.json`) | Default choice for a Vite-scaffolded project; supports SECURITY-10 (lock file requirement). |
+| CI | None for this iteration | NFR Requirements Question 6 answer B — deferred to Operations phase. |
+| Accessibility | Best-effort (no formal WCAG target this iteration) | NFR Requirements Question 5 answer B; explicit a11y attributes from Functional Design are still implemented. |