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,57 @@
+# Code Generation Plan — react-frontend-app
+
+## Unit Context
+- **Unit**: `react-frontend-app` (single unit, greenfield)
+- **Workspace root**: `K:\Development\SlpSoftware\Projects\SlpSoftware` (from aidlc-state.md)
+- **Project structure pattern**: Greenfield single unit → `src/`, `tests/`, config files at workspace root
+- **Requirements source**: `aidlc-docs/features/react-frontend/inception/requirements/requirements.md`
+- **Design sources**: Functional Design, NFR Requirements, NFR Design artifacts under `aidlc-docs/features/react-frontend/construction/react-frontend-app/`
+- **Stories**: N/A (User Stories stage was skipped for this feature)
+- **Dependencies**: None (first and only unit)
+
+## Steps
+
+### Project Structure Setup
+- [x] Step 1: Scaffold Vite + React + TypeScript project files at workspace root (`package.json`, `vite.config.ts`, `tsconfig.json`, `tsconfig.node.json`, `index.html`, `.gitignore`)
+- [x] Step 2: Configure Tailwind CSS with red/purple theme variants (`tailwind.config.ts`, `postcss.config.js`, `src/index.css`) per NFR Requirements/Design decisions
+- [x] Step 3: Configure ESLint + Prettier (`.eslintrc.cjs` or `eslint.config.js`, `.prettierrc`)
+- [x] Step 4: Configure Vitest + React Testing Library (`vitest.config.ts` or Vite test config, `src/test/setup.ts`)
+
+### Domain Data & Theme Foundation
+- [x] Step 5: Create typed content data module `src/data/content.ts` (NavLink, HeroContent, PackageCard, ProcessStep, AboutContent, ContactInfo) with the reference designs' Dutch copy ported 1-to-1 (FR-1, domain-entities.md)
+- [x] Step 6: Create theme tokens module `src/theme/tokens.ts` (red default + purple alternate, per domain-entities.md `ThemeTokens`)
+- [x] Step 7: Self-host fonts (Sora, Instrument Sans, JetBrains Mono) via `@fontsource` packages, imported in the app entry point (NFR Design font-loading decision)
+
+### Application Shell (Router, Query, Theme, Error Handling)
+- [x] Step 8: Create `ThemeProvider` (`src/theme/ThemeProvider.tsx`) implementing BR-1/BR-2/BR-3 (default red, persistence, fallback on invalid stored value)
+- [x] Step 9: Create `ErrorBoundary` (`src/components/ErrorBoundary.tsx`) with on-brand fallback message (NFR Design resilience pattern)
+- [x] Step 10: Set up TanStack Router with hash history (`src/router.tsx`, `src/routes/__root.tsx`, `src/routes/index.tsx`) composing ErrorBoundary → ThemeProvider → QueryClientProvider → RootLayout → routed content
+- [x] Step 11: Set up TanStack Query (`src/queryClient.ts`) and the placeholder `usePackagesQuery` hook (`src/hooks/usePackagesQuery.ts`) with `staleTime: Infinity`
+- [x] Step 12: Wire the application entry point (`src/main.tsx`) to mount the router
+
+### Frontend Components Generation
+- [x] Step 13: Create `RootLayout` (`src/components/RootLayout.tsx`)
+- [x] Step 14: Create `Nav` + `ThemeToggle` (`src/components/Nav.tsx`, `src/components/ThemeToggle.tsx`) with Dutch `aria-label`/`aria-pressed`
+- [x] Step 15: Create `Hero` (`src/components/Hero.tsx`) including the animated code line respecting `prefers-reduced-motion`
+- [x] Step 16: Create `PackagesSection` + `PackageCard` (`src/components/PackagesSection.tsx`, `src/components/PackageCard.tsx`) consuming `usePackagesQuery`
+- [x] Step 17: Create `ProcessSection` + `ProcessStep` (`src/components/ProcessSection.tsx`, `src/components/ProcessStep.tsx`)
+- [x] Step 18: Create `AboutSection` (`src/components/AboutSection.tsx`)
+- [x] Step 19: Create `ContactSection` (`src/components/ContactSection.tsx`)
+- [x] Step 20: Create `Footer` (`src/components/Footer.tsx`)
+- [x] Step 21: Assemble `src/routes/index.tsx` to render Hero, PackagesSection, ProcessSection, AboutSection, ContactSection in order
+
+### Frontend Components Unit Testing
+- [x] Step 22: Write unit tests for theme logic (`src/theme/__tests__/ThemeProvider.test.tsx`) covering BR-1, BR-2, BR-3
+- [x] Step 23: Write component tests for `Nav`/`ThemeToggle` (`src/components/__tests__/Nav.test.tsx`)
+- [x] Step 24: Write component tests for `PackagesSection`/`PackageCard` (`src/components/__tests__/PackagesSection.test.tsx`)
+
+### Documentation Generation
+- [x] Step 25: Create `README.md` at workspace root with setup/run/build/test instructions
+- [x] Step 26: Create code summary documentation at `aidlc-docs/features/react-frontend/construction/react-frontend-app/code/code-summary.md`
+
+### Deployment Artifacts
+- [x] Step 27: Add `npm audit`-friendly `package-lock.json` (generated automatically on install) and confirm `.gitignore` excludes `node_modules`/`dist` — verified: `package-lock.json` present, `npm audit --omit=dev` reports 0 vulnerabilities
+- [x] Step 28: Verify `vite.config.ts` base path is compatible with hash-based routing on a static/FTP host (no special `base` needed since hash routing carries the route state client-side) — confirmed via successful `npm run build`
+
+## Story Traceability
+No user stories exist for this feature (stage skipped). Traceability is instead to `requirements.md` (FR-1 through FR-5, NFR-1 through NFR-5) and to the approved Functional Design / NFR Requirements / NFR Design artifacts, referenced inline per step above.
@@ -0,0 +1,68 @@
+# Functional Design Clarification Questions — react-frontend-app
+
+Please answer each question by filling in the letter choice after the `[Answer]:` tag.
+
+## Question 1: Theme toggle placement and style
+Where and how should the visible theme switcher (red/purple) be placed in the UI?
+
+A) A small icon/swatch button in the nav bar (next to the "Start project" CTA), showing the current theme and toggling on click
+B) A labeled two-option switch (e.g. "Rood" / "Paars" segmented control) in the nav bar
+C) A floating control (e.g. fixed corner button) separate from the nav bar
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+## Question 2: Theme data shape
+How should the two theme palettes be modeled in code?
+
+A) A single TypeScript object/record per theme (e.g. `{ red: {...tokens}, purple: {...tokens} }`) mapped to CSS custom properties at runtime via a `data-theme` attribute on `<html>`/`<body>`
+B) Two separate static CSS files (one per theme) that get swapped via a `<link>` tag toggle
+C) Tailwind config with two named theme variants selected via a class on the root element (e.g. `theme-red`, `theme-purple`)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: C
+
+## Question 3: Package/content data shape
+How should the static package/pricing/content data (nav links, hero copy, package cards, steps, etc.) be structured in code for this iteration?
+
+A) One central static data module (e.g. `content.ts`) exporting typed constants/arrays consumed directly by components — easiest to later swap for a TanStack Query hook with the same shape
+B) Hardcoded directly inside each component (no separate data module)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+## Question 4: TanStack Router route structure for this iteration
+Given there is effectively one page right now, how should the initial route structure look?
+
+A) A root route (`__root.tsx`) rendering the shared layout (nav, theme provider, footer) with a single index route (`/`) rendering the full page content — ready to add sibling routes later
+B) A single flat route with no nested layout route yet (add the root/layout split only when a second route is introduced)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+## Question 5: TanStack Query placeholder usage
+Since there's no backend yet, how should the "prepared for TanStack Query" requirement (FR-5) be reflected in this functional design?
+
+A) Define one placeholder query hook (e.g. `usePackagesQuery`) that currently resolves the static data through `queryFn` (wrapped in a Promise) so the calling component already consumes it via `useQuery`, making a future real API swap a one-line change
+B) Only add the `QueryClientProvider` at the app root for now, without creating any actual query hook yet — components keep reading static data directly until a real API exists
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+## Question 6: Reduced-motion handling for the theme switch itself
+The reference design already respects `prefers-reduced-motion` for the caret blink. Should the theme-switch transition (background/color change) also respect this preference?
+
+A) Yes — make the theme color transition instant (no fade) when `prefers-reduced-motion: reduce` is set, consistent with the existing caret handling
+B) No special handling needed for the theme transition — only the existing caret animation needs to respect it
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+## Question 7: Accessibility labeling for the theme switcher
+What accessible name/label should the new theme switcher control have?
+
+A) `aria-label="Wissel kleurthema"` (Dutch, matching the rest of the site's language) with `aria-pressed`/`aria-checked` reflecting current state
+B) `aria-label="Toggle color theme"` (English)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
@@ -0,0 +1,18 @@
+# Functional Design Plan — react-frontend-app
+
+## Unit Context
+- **Unit**: `react-frontend-app` (single unit — Units Generation was skipped per the approved execution plan; this is the only unit of work for this feature)
+- **Source**: `aidlc-docs/features/react-frontend/inception/requirements/requirements.md`
+
+## Steps
+
+- [x] Define the theme/color-token domain model (red default palette, purple alternate palette, shared token shape)
+- [x] Define the static content domain model (nav links, hero copy, package/pricing cards, process steps, about/tech-stack content, contact info) sourced 1-to-1 from the reference designs
+- [x] Define business rules for theme selection and persistence (default theme, switching behavior, persistence/fallback rules)
+- [x] Define the frontend component hierarchy (Nav, Hero, PackagesSection/PackageCard, ProcessSection/Step, AboutSection, ContactSection, Footer, ThemeProvider/ThemeToggle)
+- [x] Define props/state for each component and the user interaction flows (theme toggle click, anchor navigation, hover/focus states, mailto CTA)
+- [x] Define the TanStack Router route structure (root layout route + index route housing the whole page for this iteration)
+- [x] Define the TanStack Query integration point (provider placement + a placeholder query hook shape for future package/content data, backed by static data for now)
+- [x] Generate context-appropriate clarification questions and store in a dedicated question file
+- [x] Generate functional design artifacts: business-logic-model.md, business-rules.md, domain-entities.md, frontend-components.md
+- [x] Present completion message and await approval
@@ -0,0 +1,49 @@
+# NFR Design Plan — react-frontend-app
+
+## Steps
+
+- [x] Define resilience pattern (error boundary fallback behavior)
+- [x] Define scalability pattern (justify minimal need given static single-page scope)
+- [x] Define performance pattern (TanStack Query caching config, font-loading strategy)
+- [x] Define security pattern (SRI application, CSP scope given deferred HTTP headers)
+- [x] Define logical components (theme store, content store, query client, router instance)
+- [x] Generate nfr-design-patterns.md and logical-components.md
+
+## Category Applicability Justification
+
+- **Resilience Patterns**: Applicable at a minimal level — a top-level React error boundary is the only meaningful resilience concern for a static, no-backend frontend (per SECURITY-15 from NFR Requirements).
+- **Scalability Patterns**: Not meaningfully applicable — this is a static single-page site with no server-side scaling concerns; the only "scaling" consideration is adding more routes/queries later, already covered by the Functional Design's extensible route/query structure.
+- **Performance Patterns**: Applicable — caching behavior of the placeholder TanStack Query hook and web font loading strategy are worth deciding now.
+- **Security Patterns**: Applicable at the scope already defined in NFR Requirements (SECURITY-10/13/15 addressed now; SECURITY-04/14 deferred) — this stage just needs to decide the concrete implementation pattern.
+- **Logical Components**: Applicable — need to name the concrete provider/store components (ThemeProvider, QueryClientProvider, Router instance) that implement the functional design.
+
+## Clarification Questions
+
+Please answer each question by filling in the letter choice after the `[Answer]:` tag.
+
+### Question 1: Error boundary fallback behavior
+When an unexpected rendering error occurs, what should the top-level error boundary show?
+
+A) A minimal, on-brand fallback message (styled with the current theme) with no technical details, e.g. "Er ging iets mis. Probeer de pagina te vernieuwen."
+B) A plain, unstyled fallback message (not necessarily following the current theme)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+### Question 2: TanStack Query caching for the placeholder hook
+Since `usePackagesQuery` currently wraps static data (no real network call), how should its caching be configured?
+
+A) Use TanStack Query defaults (`staleTime: 0`, refetch on window focus) — harmless for static data since the `queryFn` always returns the same static array anyway
+B) Set a long `staleTime` (e.g. `Infinity`) now, anticipating that once real data-fetching is wired in later, the content won't need to refetch constantly
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+### Question 3: Web font loading strategy
+The reference design loads Google Fonts (Sora, Instrument Sans, JetBrains Mono) via `<link>` tags. How should this be handled in the React app?
+
+A) Keep loading via Google Fonts CDN `<link>` tags in `index.html`, adding SRI hashes where Google Fonts' CSS response allows it (per SECURITY-13 decision)
+B) Self-host the font files as static assets bundled with the app (avoids depending on an external CDN and SRI complications, at the cost of larger initial bundle/setup effort)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: B
@@ -0,0 +1,88 @@
+# NFR Requirements Plan — react-frontend-app
+
+## Steps
+
+- [x] Assess Security Baseline rule applicability for a static, no-backend React frontend
+- [x] Determine performance expectations (Lighthouse-style targets, bundle size sensitivity)
+- [x] Determine testing/tooling expectations (test runner, linting, formatting)
+- [x] Determine routing fallback strategy for the FTP/static hosting target (NFR-4 follow-up) — AI recommendation: hash-based routing (see nfr-requirements.md)
+- [x] Determine accessibility target level
+- [x] Determine CI expectations for this iteration
+- [x] Generate nfr-requirements.md and tech-stack-decisions.md
+
+## Clarification Questions
+
+Please answer each question by filling in the letter choice after the `[Answer]:` tag.
+
+### Question 1: Performance target
+Is there a specific performance target for this static marketing site (e.g. Lighthouse score, load time)?
+
+A) No hard numeric target — just keep the bundle reasonably small and avoid obvious performance mistakes (code-splitting not required yet for a single page)
+B) Target a Lighthouse Performance score of 90+ on the built production bundle
+C) No performance requirements at all for this iteration
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+### Question 2: Testing tooling
+Which testing setup should be used for this iteration (component/unit tests)?
+
+A) Vitest + React Testing Library (natural fit with Vite)
+B) Jest + React Testing Library
+C) No automated tests for this iteration — only manual verification and a successful build
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+### Question 3: Linting / formatting
+Should linting and formatting be configured as part of this setup?
+
+A) Yes — ESLint (with React/TypeScript rules) + Prettier, configured and passing on the initial codebase
+B) Only ESLint, no Prettier
+C) Not needed for this iteration
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A
+
+### Question 4: Routing fallback strategy for FTP hosting (NFR-4 follow-up)
+Since the target deployment is a plain FTP/static web host and TanStack Router is being set up now, which routing mode should be used to avoid future deep-link/404 problems on that kind of host?
+
+A) Use TanStack Router's `hashHistory` (URLs like `/#/pakketten`) — works on any static host without server configuration, at the cost of slightly less clean URLs
+B) Use browser `history` mode now and defer the FTP rewrite-rule (`.htaccess`) problem to Deployment Setup in the Operations phase, since there's only one route today
+C) Not sure — let the AI recommend based on best practice for this hosting target
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: C
+
+### Question 5: Accessibility target
+What accessibility (a11y) target should this frontend meet?
+
+A) WCAG 2.1 AA as a target (semantic HTML, sufficient color contrast for both themes, keyboard-operable theme toggle, aria labels per functional design)
+B) No formal target — best-effort only, matching whatever the reference HTML already provides
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: B
+
+### Question 6: CI for this iteration
+Should a CI pipeline (e.g. GitHub Actions) running build/lint/test be set up as part of this iteration?
+
+A) Yes — set up a basic CI workflow that runs install, lint, test, and build on every push
+B) Not yet — CI can be addressed later, possibly during the Operations phase (Deployment Setup)
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: B
+
+### Question: Security Baseline Rule Applicability
+Given this is a static, no-backend marketing frontend (per requirements.md), most backend-oriented Security Baseline rules (SECURITY-01, 02, 05, 06, 07, 08, 11, 12, 13, 14, 15) will be marked **N/A**. The following rules ARE potentially applicable and need a decision on scope:
+- SECURITY-04 (HTTP security headers) — depends on hosting; may need to be deferred to Deployment Setup if the FTP host doesn't support custom headers easily
+- SECURITY-09 (hardening/misconfiguration) — mainly "no sample/demo pages", generic error handling for a client-side app
+- SECURITY-10 (software supply chain) — dependency lock file + vulnerability scanning, applicable to any npm project
+- SECURITY-13 (integrity) — Subresource Integrity (SRI) for the Google Fonts CDN `<link>` tags
+
+How should these be handled for this iteration?
+
+A) Address SECURITY-10 (lock file + `npm audit`/dependency scanning) and SECURITY-13 (SRI where feasible) now during Code Generation; defer SECURITY-04 (HTTP headers) to Deployment Setup since it depends on the final hosting choice; mark SECURITY-09 items as addressed via a standard production build (no demo pages, generic error boundary)
+B) Defer ALL of these to the Operations phase (Deployment Setup / Production Readiness) — do not address any Security Baseline rule during Code Generation
+X) Other (please describe after [Answer]: tag below)
+
+[Answer]: A