From db2fa89b90cc476fe3853d357c8364f5578148ff Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Wed, 14 Oct 2026 13:03:26 +0200 Subject: [PATCH] Adds AI-DLC inception docs for the front-end shell feature Workspace detection, reverse engineering of web/, requirements with answered verification questions, the execution plan and the open application design questions for the frontend-shell feature. Co-Authored-By: Claude Opus 5.5 --- .../reverse-engineering/api-documentation.md | 42 ++++ .../reverse-engineering/architecture.md | 107 ++++++++ .../reverse-engineering/business-overview.md | 47 ++++ .../code-quality-assessment.md | 26 ++ .../reverse-engineering/code-structure.md | 93 +++++++ .../component-inventory.md | 24 ++ .../reverse-engineering/dependencies.md | 54 +++++ .../reverse-engineering-timestamp.md | 17 ++ .../reverse-engineering/technology-stack.md | 28 +++ aidlc-docs/active-features.md | 5 + .../features/frontend-shell/aidlc-state.md | 77 ++++++ aidlc-docs/features/frontend-shell/audit.md | 164 +++++++++++++ .../plans/application-design-plan.md | 110 +++++++++ .../inception/plans/execution-plan.md | 182 ++++++++++++++ .../requirement-clarification-questions.md | 39 +++ .../requirement-verification-questions.md | 148 ++++++++++++ .../inception/requirements/requirements.md | 228 ++++++++++++++++++ aidlc-docs/language-preference.md | 12 + 18 files changed, 1403 insertions(+) create mode 100644 aidlc-docs/_shared/reverse-engineering/api-documentation.md create mode 100644 aidlc-docs/_shared/reverse-engineering/architecture.md create mode 100644 aidlc-docs/_shared/reverse-engineering/business-overview.md create mode 100644 aidlc-docs/_shared/reverse-engineering/code-quality-assessment.md create mode 100644 aidlc-docs/_shared/reverse-engineering/code-structure.md create mode 100644 aidlc-docs/_shared/reverse-engineering/component-inventory.md create mode 100644 aidlc-docs/_shared/reverse-engineering/dependencies.md create mode 100644 aidlc-docs/_shared/reverse-engineering/reverse-engineering-timestamp.md create mode 100644 aidlc-docs/_shared/reverse-engineering/technology-stack.md create mode 100644 aidlc-docs/active-features.md create mode 100644 aidlc-docs/features/frontend-shell/aidlc-state.md create mode 100644 aidlc-docs/features/frontend-shell/audit.md create mode 100644 aidlc-docs/features/frontend-shell/inception/plans/application-design-plan.md create mode 100644 aidlc-docs/features/frontend-shell/inception/plans/execution-plan.md create mode 100644 aidlc-docs/features/frontend-shell/inception/requirements/requirement-clarification-questions.md create mode 100644 aidlc-docs/features/frontend-shell/inception/requirements/requirement-verification-questions.md create mode 100644 aidlc-docs/features/frontend-shell/inception/requirements/requirements.md create mode 100644 aidlc-docs/language-preference.md diff --git a/aidlc-docs/_shared/reverse-engineering/api-documentation.md b/aidlc-docs/_shared/reverse-engineering/api-documentation.md new file mode 100644 index 0000000..266e6be --- /dev/null +++ b/aidlc-docs/_shared/reverse-engineering/api-documentation.md @@ -0,0 +1,42 @@ +# API Documentation + +## REST APIs +None. The project has no back-end yet. The static design README anticipates these future endpoints on a .NET API: +- `POST /api/contact` — contact form, payload `{ naam, email, onderwerp, bericht }` +- `/api/pages`, `/api/portfolio`, `/api/packages` — CMS content + +## Internal APIs + +### Routes (TanStack Router, file-based) +| Path | File | Head | Component | +|------|------|------|-----------| +| (root) | `routes/__root.tsx` | `siteHead` | `AppShell` via `RootLayout` | +| `/` | `routes/index.tsx` | `pageHead(...)` | `Hero` | +| `/over-mij` | `routes/over-mij.tsx` | `pageHead(...)` | placeholder | + +### seo.ts +- **Methods**: `pageHead({ title: string, description: string })` → `{ meta: [...] }`; `siteHead` constant +- **Return Types**: TanStack Router `head` option object (title, description, og:title, og:description) + +### Components (props) +- `AppShell()` — no props +- `NavigationBar()` — no props; reads route via `useRouterState`, scroll via `useScrolledPast` +- `NavLink(props: ComponentProps)` +- `MobileNav({ id: string, open: boolean, onClose: () => void })` +- `Footer()` — no props +- `LinkButton(props: ChakraLink props & { variant?: 'outline' | 'accent' | 'light' })` +- `Hero({ content: HeroContent })`, `HeroArrows({ onPrev, onNext })`, `HeroSocials({ socials: HeroSocial[] })` + +### Hooks +- `useScrolledPast(getThreshold: () => number): boolean` — `getThreshold` must be referentially stable (it is an effect dependency) +- `useHeroSlider(count: number)` → `{ active, reducedMotion, autoplay, paused, next, prev, handlers }` + +## Data Models +### NavItem (`navItems.ts`) +- **Fields**: `to` (route path), `label` (Dutch menu label) +- **Validation**: `as const` — `to` must be a registered route for type-safe `Link` + +### HeroContent (`Hero/types.ts`) +- **Fields**: `title`, `tagline`, `cta: { label, to }`, `slides: { id, src, alt }[]`, `socials: { platform, href }[]` +- **Relationships**: `HeroSocial.platform` is a `SocialPlatform` key from `socialPlatforms.ts` +- **Validation**: empty `href` → social not shown diff --git a/aidlc-docs/_shared/reverse-engineering/architecture.md b/aidlc-docs/_shared/reverse-engineering/architecture.md new file mode 100644 index 0000000..f074cc4 --- /dev/null +++ b/aidlc-docs/_shared/reverse-engineering/architecture.md @@ -0,0 +1,107 @@ +# System Architecture + +## System Overview +A single client-side React SPA (`web/`) built with Vite. Routing is file-based via TanStack Router; styling uses Chakra UI v3 with a custom theme system (tokens taken from the static design). There is no back-end, API, database or deployment pipeline yet; the README states a .NET API is planned. Content is currently hard-coded in TypeScript modules shaped so they can later come from that API. + +## Architecture Diagram + +```mermaid +graph TD + Main["main.tsx: ChakraProvider + ThemeProvider + RouterProvider"] --> Root["routes/__root.tsx: HeadContent + AppShell + Devtools"] + Root --> Shell["components/AppShell.tsx"] + Shell --> Nav["NavigationBar (+ NavLink, MobileNav, navItems)"] + Shell --> Outlet["Outlet (active page route)"] + Shell --> Footer["Footer (placeholder)"] + Outlet --> Home["routes/index.tsx: Hero"] + Outlet --> About["routes/over-mij.tsx: placeholder"] + Home --> Hero["Hero (+ HeroArrows, HeroSocials, useHeroSlider)"] + Hero --> Content["heroContent.ts (static content)"] + Nav --> Scroll["hooks/useScrolledPast"] + Theme["theme.ts + recipes/linkButton.ts"] -.-> Main + Seo["seo.ts: pageHead / siteHead"] -.-> Root + Seo -.-> Home + classDef entry fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef shell fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef page fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef support fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000; + class Main,Root entry; + class Shell,Nav,Footer,Outlet shell; + class Home,About,Hero page; + class Content,Scroll,Theme,Seo support; +``` + +Text alternative: main.tsx mounts providers and the router; the root route renders AppShell (NavigationBar, the active page via Outlet, Footer); the home route renders the Hero; theme and SEO helpers support all of it. + +## Component Descriptions +### main.tsx +- **Purpose**: Application bootstrap +- **Responsibilities**: Creates the router, registers types, mounts ChakraProvider (custom system), next-themes ThemeProvider (light only), loads self-hosted fonts, removes static fallback head tags +- **Dependencies**: routeTree.gen.ts, theme.ts +- **Type**: Application + +### routes/__root.tsx +- **Purpose**: Root route / layout +- **Responsibilities**: Site-wide head tags (`siteHead`), renders `HeadContent`, `AppShell` and router devtools +- **Dependencies**: AppShell, seo.ts +- **Type**: Application + +### components/AppShell.tsx +- **Purpose**: Application shell +- **Responsibilities**: Renders NavigationBar, ``, Footer. No `
` landmark, skip link or to-top button yet +- **Type**: Application + +### components/NavigationBar/ +- **Purpose**: Site header and navigation +- **Responsibilities**: Fixed header; transparent over the hero on desktop on `/` until scrolled 150px; shrinks after scroll (desktop); swaps dark/light logo; desktop link list with animated underline (`NavLink`); hamburger button and full-screen `MobileNav` below `lg` (Escape to close, body scroll lock, clip-path reveal). `navItems.ts` is the single menu source (currently Home, Over mij) +- **Type**: Application + +### components/Footer.tsx +- **Purpose**: Site footer +- **Responsibilities**: Placeholder copyright line only; uses Tailwind-style `className`s that have no effect (Tailwind is not installed) +- **Type**: Application + +### components/Hero/ +- **Purpose**: Homepage hero slider +- **Responsibilities**: Crossfade slides with zoom, progress bar driven autoplay, arrows, swipe, pause on hover/focus/hidden tab, reduced-motion support, social icons. Content typed in `types.ts` for future API use; `socialPlatforms.ts` maps platform keys to offline Iconify icons +- **Type**: Application + +### theme.ts / recipes/linkButton.ts +- **Purpose**: Design system +- **Responsibilities**: Colour, font, spacing, easing, duration tokens; semantic `bg`/`fg`, `header` size tokens; `eyebrow`/`display` text styles; `linkButton` recipe (outline / accent / light) +- **Type**: Application (shared UI foundation) + +### seo.ts +- **Purpose**: Head tag helpers +- **Responsibilities**: `pageHead({title, description})` for route `head` options; `siteHead` for site-wide Open Graph tags +- **Type**: Application (utility) + +## Data Flow + +```mermaid +sequenceDiagram + box rgba(246,224,94,0.4) Browser + participant V as Visitor + end + box rgba(99,179,237,0.4) SPA + participant R as Router + participant S as AppShell + participant P as Page route + end + V->>R: Open URL or click nav link + R->>S: Render root layout + S->>P: Render matched route via Outlet + P-->>R: head() title and meta + R-->>V: Updated page and head tags +``` + +Text alternative: a visitor navigates, the router renders the root layout (AppShell), which renders the matched page through the Outlet; the page's head() supplies title/meta tags. + +## Integration Points +- **External APIs**: None yet (planned .NET API for content and contact form) +- **Databases**: None +- **Third-party Services**: Outbound links only — Facebook, Instagram profiles + +## Infrastructure Components +- **CDK Stacks**: None +- **Deployment Model**: Not defined yet; output is a static Vite build (`dist/`) +- **Networking**: N/A diff --git a/aidlc-docs/_shared/reverse-engineering/business-overview.md b/aidlc-docs/_shared/reverse-engineering/business-overview.md new file mode 100644 index 0000000..aa97249 --- /dev/null +++ b/aidlc-docs/_shared/reverse-engineering/business-overview.md @@ -0,0 +1,47 @@ +# Business Overview + +## Business Context Diagram + +```mermaid +graph LR + Visitor["Website visitor (prospective client)"] --> Site["Andrea Slop Fotografie website (React SPA)"] + Crawler["Search engines and link previews"] --> Site + Site --> Social["Facebook and Instagram profiles"] + Site --> Mail["E-mail (info@andreaslop.nl)"] + Owner["Andrea (photographer, content owner)"] -.-> CMS["Planned .NET API / CMS"] + CMS -.-> Site + classDef person fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef system fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef external fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef planned fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,stroke-dasharray:5 5,color:#000; + class Visitor,Owner,Crawler person; + class Site system; + class Social,Mail external; + class CMS planned; +``` + +Text alternative: visitors and crawlers use the website, which links out to social profiles and e-mail; a planned .NET API/CMS (dashed) will later supply content managed by Andrea. + +## Business Description +- **Business Description**: Portfolio and marketing website for Andrea Slop Fotografie, a lifestyle photographer in Huizen (NL). It presents her work (loveshoots, family, pregnancy and newborn shoots), tells who she is, lists shoot types and prices, and gets prospective clients to make contact. It replaces an existing WordPress (Solene theme) site at andreaslop.nl. +- **Business Transactions** (current state — front-end only, no back-end yet): + - **Browse the homepage** — hero slider with featured photos, call-to-action to "Over mij" + - **Navigate between pages** — header navigation (desktop) and hamburger menu (mobile) + - **Visit social profiles** — Facebook / Instagram links in the hero + - **Share / discover pages** — per-page title, meta description and Open Graph tags for search engines and link previews + - *Planned (static design only)*: portfolio browsing with lightbox, shoot types and pricing, contact form, Instagram feed +- **Business Dictionary**: + - **Shell** — the Header / page content / Footer frame shared by every page (see LAYOUT.md) + - **Hero** — full-screen photo slider at the top of the homepage + - **Info menu / side area** — slide-in panel from the design with socials and e-mail (out of scope for this site, by owner decision) + - **Shoot** — a photo session type (newborn, pregnancy, loveshoot, portraits) + - **CMS** — the planned .NET API that will provide page content; content is hard-coded until then + +## Component Level Business Descriptions +### web (React front-end) +- **Purpose**: The public website visitors see +- **Responsibilities**: Page routing, layout shell, homepage hero, SEO head tags, design system (colours, fonts, buttons) + +### design/andreaslop-static (reference only) +- **Purpose**: Static HTML/CSS/JS rebuild of the live site, used as the visual and structural source of truth +- **Responsibilities**: Defines page sections, header/footer markup, design tokens and interactions to port to React diff --git a/aidlc-docs/_shared/reverse-engineering/code-quality-assessment.md b/aidlc-docs/_shared/reverse-engineering/code-quality-assessment.md new file mode 100644 index 0000000..84b1359 --- /dev/null +++ b/aidlc-docs/_shared/reverse-engineering/code-quality-assessment.md @@ -0,0 +1,26 @@ +# Code Quality Assessment + +## Test Coverage +- **Overall**: None +- **Unit Tests**: None (no test runner installed) +- **Integration Tests**: None +- Verification so far is `tsc` type-checking during `pnpm build` and manual browser checks + +## Code Quality Indicators +- **Linting**: Not configured (TypeScript `noUnused*` flags only) +- **Code Style**: Mostly consistent (Prettier: 4 spaces, single quotes). Exception: `routes/over-mij.tsx` uses double quotes and 2-space indent +- **Documentation**: Good inline comments in Dutch explaining intent; README is a stub + +## Technical Debt +- `theme.ts` `globalCss.body.height: '250vh'` — temporary scroll-testing hack; forces every page to be 2.5 screens tall +- `components/Footer.tsx` and `routes/over-mij.tsx` use Tailwind-style `className`s (`p-2`, `text-sm`, …) that do nothing — Tailwind is not installed +- `AppShell` has no `
` landmark; static design has a skip link targeting `#main` +- Header logo is not a link to the homepage (design: link with aria-label) +- Social links are defined inside `Hero/heroContent.ts`; the footer in the design needs the same links → candidate for shared site-level content +- `NavigationBar.tsx` uses `let [open, setOpen]` (should be `const`) +- Unused Vite starter assets: `assets/hero.png`, `assets/typescript.svg`, `assets/vite.svg` +- Design asset `footer-mark.png` (footer logo) not yet present in `web/src/assets` + +## Patterns and Anti-patterns +- **Good Patterns**: design tokens as single source of truth; API-shaped static content; accessible interactions (aria labels, Escape to close, reduced motion, focus-visible handling); shared `navItems` for desktop and mobile +- **Anti-patterns**: no-op `className` usage (see above); global body height hack diff --git a/aidlc-docs/_shared/reverse-engineering/code-structure.md b/aidlc-docs/_shared/reverse-engineering/code-structure.md new file mode 100644 index 0000000..5b4edd6 --- /dev/null +++ b/aidlc-docs/_shared/reverse-engineering/code-structure.md @@ -0,0 +1,93 @@ +# Code Structure + +## Build System +- **Type**: npm-compatible via **pnpm** (lockfile `web/pnpm-lock.yaml`) +- **Configuration**: + - `web/package.json` — scripts `dev` (vite), `build` (`tsc && vite build`), `preview`, `typegen` (Chakra typegen for theme) + - `web/vite.config.js` — TanStack Router plugin (`autoCodeSplitting`) before `@vitejs/plugin-react`; `resolve.tsconfigPaths` + - `web/tsconfig.json` — strict-ish bundler mode, `@/*` → `src/*` alias, `noUnusedLocals/Parameters`, `erasableSyntaxOnly` + - `web/.prettierrc` — 4 spaces, single quotes, semicolons + +## Key Classes/Modules + +```mermaid +graph TD + Root["routes/__root.tsx"] --> AppShell["components/AppShell.tsx"] + AppShell --> NavigationBar["NavigationBar/NavigationBar.tsx"] + AppShell --> Footer["components/Footer.tsx"] + NavigationBar --> NavLink["NavigationBar/NavLink.tsx"] + NavigationBar --> MobileNav["NavigationBar/MobileNav.tsx"] + NavigationBar --> navItems["NavigationBar/navItems.ts"] + MobileNav --> navItems + NavigationBar --> useScrolledPast["hooks/useScrolledPast.tsx"] + Index["routes/index.tsx"] --> Hero["Hero/Hero.tsx"] + Hero --> HeroArrows["Hero/HeroArrows.tsx"] + Hero --> HeroSocials["Hero/HeroSocials.tsx"] + Hero --> useHeroSlider["Hero/useHeroSlider.ts"] + Hero --> LinkButton["components/LinkButton.tsx"] + HeroSocials --> socialPlatforms["Hero/socialPlatforms.ts"] + classDef shell fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef page fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef util fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000; + class Root,AppShell,NavigationBar,Footer,NavLink,MobileNav shell; + class Index,Hero,HeroArrows,HeroSocials page; + class navItems,useScrolledPast,useHeroSlider,LinkButton,socialPlatforms util; +``` + +Text alternative: the root route renders AppShell (NavigationBar with NavLink/MobileNav/navItems, plus Footer); the index route renders Hero with its arrows, socials, slider hook and the shared LinkButton. + +### Existing Files Inventory +- `web/index.html` — HTML entry; static fallback title/meta for non-JS crawlers (`data-fallback`) +- `web/src/main.tsx` — bootstrap: providers, router, fonts, removes fallback head tags +- `web/src/routeTree.gen.ts` — generated by TanStack Router plugin (do not edit) +- `web/src/routes/__root.tsx` — root layout route, site-wide head +- `web/src/routes/index.tsx` — home page (`/`), renders Hero +- `web/src/routes/over-mij.tsx` — about page (`/over-mij`), placeholder content +- `web/src/components/AppShell.tsx` — shell: NavigationBar + Outlet + Footer +- `web/src/components/Footer.tsx` — placeholder footer +- `web/src/components/LinkButton.tsx` — router `Link` styled with `linkButton` recipe +- `web/src/components/NavigationBar/NavigationBar.tsx` — header, logo, desktop nav, hamburger +- `web/src/components/NavigationBar/NavLink.tsx` — desktop nav link with underline animation +- `web/src/components/NavigationBar/MobileNav.tsx` — full-screen mobile menu +- `web/src/components/NavigationBar/navItems.ts` — menu items (Home, Over mij) +- `web/src/components/Hero/*` — hero slider (component, arrows, socials, hook, content, types, platforms) +- `web/src/hooks/useScrolledPast.tsx` — boolean "scrolled past threshold" hook +- `web/src/recipes/linkButton.ts` — Chakra recipe for the square design button +- `web/src/theme.ts` — Chakra system config (tokens, semantic tokens, text styles, recipes) +- `web/src/seo.ts` — `pageHead` / `siteHead` helpers +- `web/src/assets/*` — hero photos, light/dark logos, unused Vite starter assets (`hero.png`, `typescript.svg`, `vite.svg`) +- `web/public/favicon.png`, `web/public/icons.svg` — static public assets + +## Design Patterns +### Chakra `chakra()` factory around router `Link` +- **Location**: NavLink, MobileNav, LinkButton +- **Purpose**: Router-aware links with Chakra style props and `_currentPage` / `aria-current` styling +- **Implementation**: `const ChakraLink = chakra(Link)` + +### Design tokens + recipes +- **Location**: theme.ts, recipes/ +- **Purpose**: Single source for colours, fonts, spacing, motion; reusable component variants +- **Implementation**: `defineConfig` tokens/semanticTokens/textStyles, `defineRecipe` + `useRecipe` + +### API-shaped static content +- **Location**: Hero/heroContent.ts + types.ts, navItems.ts +- **Purpose**: Hard-coded content today, swappable for CMS API responses later +- **Implementation**: Plain data objects typed with interfaces; components receive them as props + +### Route-level head management +- **Location**: seo.ts, each route's `head` option, `HeadContent` in root +- **Purpose**: Per-page SEO without SSR + +## Critical Dependencies +### @chakra-ui/react +- **Version**: ^3.37.0 +- **Usage**: All layout and styling +- **Purpose**: Component library and styling system +### @tanstack/react-router (+ router-plugin) +- **Version**: ^1.170.39 / ^1.168.40 +- **Usage**: File-based routes, `Link`, `Outlet`, `HeadContent`, `useRouterState` +- **Purpose**: Routing and head management +### @iconify/react + @iconify-icons/ant-design +- **Version**: ^6.0.2 / 2.0.1 +- **Usage**: Offline icons in Hero +- **Purpose**: Icons bundled at build time (no API calls) diff --git a/aidlc-docs/_shared/reverse-engineering/component-inventory.md b/aidlc-docs/_shared/reverse-engineering/component-inventory.md new file mode 100644 index 0000000..e1ae827 --- /dev/null +++ b/aidlc-docs/_shared/reverse-engineering/component-inventory.md @@ -0,0 +1,24 @@ +# Component Inventory + +## Application Packages +- `web` — React 19 SPA (Vite, Chakra UI v3, TanStack Router): the public website + +## Infrastructure Packages +- None (no IaC, Docker, or CI/CD configuration present) + +## Shared Packages +- None as separate packages. Inside `web`, shared modules are `theme.ts`, `recipes/`, `seo.ts`, `hooks/`, `components/LinkButton.tsx` + +## Test Packages +- None + +## Reference (non-code) +- `design/andreaslop-static` — static HTML/CSS/JS design reference (not built or deployed) +- `design/AndreaSlopFotografie_React.zip` — archive of design files + +## Total Count +- **Total Packages**: 1 +- **Application**: 1 +- **Infrastructure**: 0 +- **Shared**: 0 +- **Test**: 0 diff --git a/aidlc-docs/_shared/reverse-engineering/dependencies.md b/aidlc-docs/_shared/reverse-engineering/dependencies.md new file mode 100644 index 0000000..be326f4 --- /dev/null +++ b/aidlc-docs/_shared/reverse-engineering/dependencies.md @@ -0,0 +1,54 @@ +# Dependencies + +## Internal Dependencies + +```mermaid +graph LR + routes["routes/*"] --> components["components/*"] + routes --> seo["seo.ts"] + components --> hooks["hooks/*"] + components --> theme["theme.ts tokens (via Chakra props)"] + components --> assets["assets/*"] + main["main.tsx"] --> theme + main --> routes + classDef app fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef support fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000; + class main,routes,components app; + class seo,hooks,theme,assets support; +``` + +Text alternative: main depends on theme and routes; routes depend on components and seo; components depend on hooks, theme tokens and assets. + +### routes depend on components +- **Type**: Compile +- **Reason**: Routes render AppShell (root) and page components + +### components depend on theme tokens +- **Type**: Runtime (string token references such as `bg="paper"`, `h="header"`) +- **Reason**: All visual values come from the Chakra system + +## External Dependencies +### @chakra-ui/react +- **Version**: ^3.37.0 +- **Purpose**: Styling system and UI primitives +- **License**: MIT +### @tanstack/react-router +- **Version**: ^1.170.39 +- **Purpose**: Routing +- **License**: MIT +### react / react-dom +- **Version**: ^19.3.0 +- **Purpose**: UI runtime +- **License**: MIT +### next-themes +- **Version**: ^0.4.6 +- **Purpose**: Colour mode +- **License**: MIT +### @iconify/react, @iconify-icons/ant-design +- **Version**: ^6.0.2, 2.0.1 +- **Purpose**: Icons +- **License**: MIT (icons: Ant Design, MIT) +### @fontsource/jost, @fontsource/marcellus +- **Version**: ^5.3.0 +- **Purpose**: Self-hosted web fonts +- **License**: OFL-1.1 diff --git a/aidlc-docs/_shared/reverse-engineering/reverse-engineering-timestamp.md b/aidlc-docs/_shared/reverse-engineering/reverse-engineering-timestamp.md new file mode 100644 index 0000000..322cecb --- /dev/null +++ b/aidlc-docs/_shared/reverse-engineering/reverse-engineering-timestamp.md @@ -0,0 +1,17 @@ +# Reverse Engineering Metadata + +**Analysis Date**: 2026-10-14T09:58:04Z +**Analyzer**: AI-DLC +**Workspace**: C:\Users\bdslo\Documents\Development\AndreaSlopFotografie +**Codebase Commit**: 8f5841c (branch feature/hero-slider-and-navigation) +**Total Files Analyzed**: 30 (web/src, web config files, design/andreaslop-static shell markup and README) + +## Artifacts Generated +- [x] business-overview.md +- [x] architecture.md +- [x] code-structure.md +- [x] api-documentation.md +- [x] component-inventory.md +- [x] technology-stack.md +- [x] dependencies.md +- [x] code-quality-assessment.md diff --git a/aidlc-docs/_shared/reverse-engineering/technology-stack.md b/aidlc-docs/_shared/reverse-engineering/technology-stack.md new file mode 100644 index 0000000..0ca9cee --- /dev/null +++ b/aidlc-docs/_shared/reverse-engineering/technology-stack.md @@ -0,0 +1,28 @@ +# Technology Stack + +## Programming Languages +- TypeScript — ~6.0.2 — all application code (TSX) +- HTML/CSS/JS — design reference only (`design/andreaslop-static`) +- C# / .NET — planned back-end (not present) + +## Frameworks +- React — ^19.3.0 — UI +- Chakra UI — ^3.37.0 (+ @emotion/react ^11.14.0) — styling system and components +- TanStack Router — ^1.170.39 — file-based routing, head management (devtools ^1.167.2) +- next-themes — ^0.4.6 — colour mode provider (fixed to light) +- @fontsource/jost, @fontsource/marcellus — ^5.3.0 — self-hosted fonts +- @iconify/react ^6.0.2 + @iconify-icons/ant-design 2.0.1 — offline icons + +## Infrastructure +- None yet; static build output suitable for any static host + +## Build Tools +- Vite — ^8.3.0 — dev server and bundler +- @vitejs/plugin-react — ^6.1.1 +- @tanstack/router-plugin — ^1.168.40 — route tree generation, code splitting +- @chakra-ui/cli — ^3.37.0 — theme typegen +- pnpm — package manager +- Prettier — ^3.9.9 — formatting + +## Testing Tools +- None configured (no test runner, no linter such as ESLint) diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md new file mode 100644 index 0000000..50476ee --- /dev/null +++ b/aidlc-docs/active-features.md @@ -0,0 +1,5 @@ +# Active Features + +| Type | Name | Status | Branch | Affected Components | Session Start | +|------|------|--------|--------|---------------------|---------------| +| Feature | frontend-shell | 🔵 Inception | feature/frontend-shell | web/src (AppShell, NavigationBar, Footer, Hero socials, new BackToTop/SkipLink/404/error pages, routes, theme.ts, main.tsx), web/vite.config.js, web/package.json | 2026-10-14 | diff --git a/aidlc-docs/features/frontend-shell/aidlc-state.md b/aidlc-docs/features/frontend-shell/aidlc-state.md new file mode 100644 index 0000000..183b417 --- /dev/null +++ b/aidlc-docs/features/frontend-shell/aidlc-state.md @@ -0,0 +1,77 @@ +# AI-DLC State Tracking + +## Project Information +- **Feature Name**: Front-end application shell (header/navigation, footer, shell chrome) +- **Feature Slug**: frontend-shell +- **Project Type**: Brownfield +- **Start Date**: 2026-10-14T09:46:02Z +- **Current Stage**: INCEPTION - Application Design +- **Branch**: feature/frontend-shell + +## Workspace State +- **Existing Code**: Yes +- **Programming Languages**: TypeScript (React/TSX) +- **Build System**: pnpm + Vite (`tsc && vite build`) +- **Project Structure**: Single front-end SPA in `web/`; static HTML design reference in `design/andreaslop-static/`; .NET back-end planned but not present +- **Reverse Engineering Needed**: Yes +- **Workspace Root**: C:\Users\bdslo\Documents\Development\AndreaSlopFotografie + +## Code Location Rules +- **Application Code**: Workspace root (NEVER in aidlc-docs/) — front-end lives in `web/` +- **Feature Documentation**: aidlc-docs/features/frontend-shell/ only +- **Shared Artifacts**: aidlc-docs/_shared/ +- **Structure patterns**: See code-generation.md Critical Rules + +## Language Configuration +- **Documentation Language**: English +- **Conversation Language**: User Language (Dutch) + +## Extension Configuration +| Extension | Enabled | Decided At | +|---|---|---| +| Security Baseline | Yes | Requirements Analysis | +| Property-Based Testing | Yes (full enforcement) | Requirements Analysis | + +## Operations Configuration +- **Include Operations Phase**: Undecided +- **Decided At**: Pending — asked at Requirements Analysis + +## Scope Notes (from user) +- Side area / "Info menu" from the static design is OUT of scope (deliberately left out) +- E-mail address in the mobile menu is OUT of scope (deliberately left out) + +## Execution Plan Summary +- **Total Stages**: 13 (excluding Operations) +- **Stages to Execute**: Application Design, Functional Design, NFR Requirements, Code Generation, Build and Test +- **Stages to Skip**: User Stories (single persona, concrete FRs), Units Generation (single unit), NFR Design (small patterns, folded into NFR Requirements + code plan), Infrastructure Design (no infrastructure) + +## Stage Progress + +### 🔵 INCEPTION PHASE +- [x] Workspace Detection +- [x] Reverse Engineering +- [x] Requirements Analysis +- [x] User Stories - SKIP +- [x] Workflow Planning +- [ ] Application Design - EXECUTE +- [ ] Units Generation - SKIP + +### 🟢 CONSTRUCTION PHASE +- [ ] Functional Design - EXECUTE +- [ ] NFR Requirements - EXECUTE +- [ ] NFR Design - SKIP +- [ ] Infrastructure Design - SKIP +- [ ] Code Generation - EXECUTE +- [ ] Build and Test - EXECUTE + +### 🟡 OPERATIONS PHASE +- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - UNDECIDED + +## Current Status +- **Lifecycle Phase**: INCEPTION +- **Current Stage**: Application Design +- **Next Stage**: Functional Design + +## Reverse Engineering Status +- [x] Reverse Engineering - Artifacts generated on 2026-10-14T09:58:04Z (approved 2026-10-14T10:05:21Z) +- **Artifacts Location**: aidlc-docs/_shared/reverse-engineering/ diff --git a/aidlc-docs/features/frontend-shell/audit.md b/aidlc-docs/features/frontend-shell/audit.md new file mode 100644 index 0000000..2ad19fc --- /dev/null +++ b/aidlc-docs/features/frontend-shell/audit.md @@ -0,0 +1,164 @@ +# AI-DLC Audit Log — frontend-shell + +## Initial User Request + +**Timestamp**: 2026-10-14T09:46:02Z + +**User Input**: "ik wil met aidlc de shell voor de front-end afmaken" + +**AI Response**: "Started AI-DLC workflow. Displayed welcome message and began Workspace Detection." + +**Context**: INCEPTION - Workspace Detection (start) + +--- + +## Workspace Detection + +**Timestamp**: 2026-10-14T09:46:02Z + +**User Input**: "(none — automatic stage)" + +**AI Response**: "No existing aidlc-docs/active-features.md or legacy aidlc-state.md found — new AI-DLC workspace. Existing code found in web/ (React 19 + Vite 8 + TypeScript 6, Chakra UI v3, TanStack Router file-based routing, pnpm). Brownfield. No shared reverse engineering artifacts. Request classified as Feature (completing the application shell: header/navigation, side area, footer, to-top, skip link — new user-facing behaviour, no defect reported). Feature slug: frontend-shell. Language preference question written to aidlc-docs/language-preference.md." + +**Context**: INCEPTION - Workspace Detection; classification = Feature; next = language preference answer, then Reverse Engineering + +**Findings**: +- Shell defined in LAYOUT.md as Header / Page content / Footer +- Current shell: web/src/components/AppShell.tsx renders NavigationBar + Outlet + Footer +- NavigationBar: fixed header, transparent overlay over hero on desktop, sticky shrink after scroll, mobile hamburger menu (MobileNav) — implemented +- Footer: placeholder only (copyright line with Tailwind-style classNames that do nothing) +- Missing vs. static design (design/andreaslop-static): side area / "Info menu" panel, to-top button, skip link + main landmark, mobile-nav e-mail meta, logo link to home, full footer, nav items for Portfolio / Soorten fotoshoots / Contact (routes not yet present) + +--- + +## Workspace Detection - Language Preference and Scope Input + +**Timestamp**: 2026-10-14T09:58:04Z + +**User Input**: "Ik heb de vragen beantwoord. Het info-menu mag wegblijven. Ook het e-mailadresmag uit het mobiele menu blijven. Die heb ik bewust weggelaten" + +**AI Response**: "Read aidlc-docs/language-preference.md: answer A (English documentation, Dutch conversation). Recorded scope decisions: side area / Info menu out of scope; e-mail address in mobile menu out of scope (deliberately omitted). Workspace Detection complete; proceeding to Reverse Engineering." + +**Context**: INCEPTION - Workspace Detection complete; Language Configuration stored in aidlc-state.md + +--- + +## Reverse Engineering + +**Timestamp**: 2026-10-14T09:58:04Z + +**User Input**: "(none — automatic stage start)" + +**AI Response**: "Analyzed web/ (30 files incl. config) and design/andreaslop-static shell markup. Generated business-overview.md, architecture.md, code-structure.md, api-documentation.md, component-inventory.md, technology-stack.md, dependencies.md, code-quality-assessment.md and reverse-engineering-timestamp.md in aidlc-docs/_shared/reverse-engineering/. Presented completion message and asked for approval." + +**Context**: INCEPTION - Reverse Engineering; awaiting user approval + +--- + +## Reverse Engineering - Approval + +**Timestamp**: 2026-10-14T10:05:21Z + +**User Input**: "ga verder" + +**AI Response**: "Reverse Engineering approved. Proceeding to Requirements Analysis (standard depth)." + +**Context**: INCEPTION - Reverse Engineering complete + +--- + +## Requirements Analysis - Clarifying Questions + +**Timestamp**: 2026-10-14T10:05:21Z + +**User Input**: "(none — stage start)" + +**AI Response**: "Intent analysis: Enhancement/New Feature, multiple components within web/, moderate complexity, standard depth. Created inception/requirements/requirement-verification-questions.md with 14 questions (nav items for missing pages, footer content source, footer socials, footer logo, footer menu, to-top button, accessibility, scroll restoration, 404 page, tech debt, testing, security extension opt-in, PBT extension opt-in, Operations phase)." + +**Context**: INCEPTION - Requirements Analysis; awaiting answers + +--- + +## Requirements Analysis - Answers Received + +**Timestamp**: 2026-10-14T10:17:16Z + +**User Input**: "ik heb de vragen beantwoord" + +**AI Response**: "Read requirement-verification-questions.md. Answers: Q1 A (placeholder routes), Q2 A (shared siteContent module), Q3 A (text links), Q4 X ('het huidige bestand heeft een witte achtergrond. Als je die wat kan aanpassen zodat de achtergrodnd doorichtig is dan kan hij in de footer erbij. Als dat niet lukt dan zou dat dele uit de footer kunnen. Het lijkt mij sowieso onnodige vulling?'), Q5 C (design links + privacy statement link), Q6 B (to-top with icon), Q7 A (WCAG 2.1 AA shell baseline), Q8 A (scroll restoration), Q9 A (404 page in shell), Q10 A (all tech debt), Q11 A (Vitest + RTL), Q12 A (security extension enabled), Q13 A (PBT extension enabled, full), Q14 C (Operations undecided). Loaded security-baseline.md and property-based-testing.md. Investigated Q4: converted design/andreaslop-static/assets/img/footer-mark.png to transparent in scratchpad (works); found web/src/assets/logo-dark.png is the same monogram and already transparent. Ambiguities detected in Q4 (conditional answer + question about value) and Q5/Q1 (privacy link target does not exist). Created requirement-clarification-questions.md with 2 questions." + +**Context**: INCEPTION - Requirements Analysis; awaiting clarification answers + +--- + +## Requirements Analysis - Clarification Answers and Requirements Document + +**Timestamp**: 2026-10-14T10:35:01Z + +**User Input**: "Ik heb de vragen beantwoord" + +**AI Response**: "Read requirement-clarification-questions.md: Clarification 1 = A (reuse logo-dark.png as footer monogram), Clarification 2 = A (placeholder route /privacyverklaring). No remaining contradictions. Measured contrast of design colours: ink.muted 3.19:1 and accent 3.03:1 on paper.alt fail WCAG AA for small text → requirement to use ink.soft / accent.deep instead (deliberate design deviation, NFR-01). Generated inception/requirements/requirements.md with 11 functional and 5 non-functional requirements, security applicability table. User Stories assessed as skip (single visitor persona, requirements already concrete per element). Presented completion message with Request Changes / Add User Stories / Continue options." + +**Context**: INCEPTION - Requirements Analysis; awaiting approval + +--- + +## Requirements Analysis - Change Request + +**Timestamp**: 2026-10-14T10:41:44Z + +**User Input**: "Misschien is het impliciet, maar ik zie het nergens staan. Voor styling moet zovele mogelijk hergebruikt worden en moet Chakra benut worden. Forceer het niet, maar waar handig wel gebruiken." + +**AI Response**: "Added NFR-02 'Styling: reuse first, use Chakra where it helps' to requirements.md: reuse existing tokens/textStyles/recipes/components, use Chakra components and layout primitives where they fit, centralise styling that repeats in 2+ places (theme or small shared component), do not force Chakra or add one-off recipes/tokens. Former NFR-02 renamed NFR-02a. Re-presented completion message." + +**Context**: INCEPTION - Requirements Analysis; change applied, awaiting approval + +--- + +## Requirements Analysis - Approval + +**Timestamp**: 2026-10-14T10:44:41Z + +**User Input**: "continue to next stage" + +**AI Response**: "Requirements approved. User Stories skipped. Proceeding to Workflow Planning." + +**Context**: INCEPTION - Requirements Analysis complete + +--- + +## Workflow Planning + +**Timestamp**: 2026-10-14T10:44:41Z + +**User Input**: "(none — stage start)" + +**AI Response**: "Created inception/plans/execution-plan.md. EXECUTE: Application Design (minimal), Functional Design (minimal, PBT-01), NFR Requirements (minimal, PBT-09/SECURITY-04/10), Code Generation, Build and Test. SKIP: User Stories, Units Generation (single unit), NFR Design (patterns small, folded into NFR Requirements + code plan), Infrastructure Design (no infra). Operations: Undecided. Risk: Low. Presented plan for approval." + +**Context**: INCEPTION - Workflow Planning; awaiting approval + +--- + +## Workflow Planning - Approval and Branch Handling + +**Timestamp**: 2026-10-14T10:51:43Z + +**User Input**: "De huidige branch moet inderdaad nog worden afgesloten zodat we op een nieuwe branch kunnen werken. Kan jij dat doen of moet ik dta zelf doen? Verder ziet het er goed uit en mag je verder naar de volgende stage" + +**AI Response**: "Execution plan approved. Asked how to close the branch (AskUserQuestion). User chose: 'PR op Gitea, ik merge' and 'Lokaal + remote verwijderen'. Created Gitea PR #2 (feature/hero-slider-and-navigation -> master; first attempt rejected by Gitea DB because of a 4-byte emoji in the body, retried without emoji), merged fast-forward-only (master = 8f5841c) with remote branch deletion. Local SSH to origin not available from agent shells, so master was fast-forwarded locally to the same commit, origin/master ref aligned to the API-confirmed sha, stale remote-tracking ref and local branch deleted. Created local branch feature/frontend-shell from master (not pushed). Updated branch in aidlc-state.md and active-features.md." + +**Context**: INCEPTION - Workflow Planning complete; branch feature/frontend-shell + +--- + +## Application Design - Plan and Questions + +**Timestamp**: 2026-10-14T10:51:43Z + +**User Input**: "(none — stage start)" + +**AI Response**: "Created inception/plans/application-design-plan.md (minimal depth) with 9 questions: folder structure, content module location, content provisioning (props/import/context), footer menu location, placeholder page component, status page component, footer link styling (Chakra link recipe variant), shared RouterLink refactor, hover-opacity pattern. Pre-decided per NFR-02: Chakra SkipNavLink/SkipNavContent for skip link + main, reuse useScrolledPast, LinkButton, eyebrow text style." + +**Context**: INCEPTION - Application Design; awaiting answers + +--- diff --git a/aidlc-docs/features/frontend-shell/inception/plans/application-design-plan.md b/aidlc-docs/features/frontend-shell/inception/plans/application-design-plan.md new file mode 100644 index 0000000..6305d4e --- /dev/null +++ b/aidlc-docs/features/frontend-shell/inception/plans/application-design-plan.md @@ -0,0 +1,110 @@ +# Application Design Plan — frontend-shell + +Depth: **minimal**. Single front-end package; the design pins down component boundaries, props, shared pieces and what moves into the theme (NFR-02 reuse principle). Detailed behaviour rules follow in Functional Design. + +## Plan + +- [ ] 1. Answer the design questions below +- [ ] 2. Analyze answers for ambiguities (follow-up questions if needed) +- [ ] 3. Generate `components.md` — component definitions and responsibilities +- [ ] 4. Generate `component-methods.md` — props/signatures of components, hooks and helpers +- [ ] 5. Generate `services.md` — router configuration, head management, content provisioning +- [ ] 6. Generate `component-dependency.md` — dependency matrix, data flow +- [ ] 7. Generate `application-design.md` — consolidated design +- [ ] 8. Validate completeness and consistency (requirements FR-01…FR-11, NFR-01…NFR-05, Security/PBT applicability) + +## Already decided (no question needed) + +These follow directly from the requirements and the reuse principle (NFR-02): + +- **Skip link**: use Chakra's built-in `SkipNavLink` + `SkipNavContent` (`id="main"`, rendered `as="main"`). Restyle via the theme's `skipNavLink` recipe so it matches the design (ink background, white text). +- **Back-to-top visibility**: reuse the existing `useScrolledPast` hook, with a module-level threshold function (60% of the viewport height). +- **Icons**: `@iconify/react/offline` with the bundled `up-outlined` from `@iconify-icons/ant-design`. +- **404 / error buttons**: the existing `LinkButton` (`linkButton` recipe). +- **Footer column headings**: the existing `eyebrow` text style. + +--- + +## Questions + +Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe. Waar ik een voorkeur heb staat **(aanbevolen)**. + +### Vraag 1: Mappenstructuur van de shell-componenten +Nu staat `AppShell.tsx` los in `components/`, met `NavigationBar/` en `Hero/` als eigen mappen. + +A) Per component een eigen map, zoals nu: `components/Footer/`, `components/BackToTop/`, `components/StatusPage/`… `AppShell.tsx` blijft waar het is. **(aanbevolen)** Dit sluit aan bij het bestaande patroon. +B) Eén map `components/Shell/` met `AppShell`, `Footer/`, `BackToTop`, `NavigationBar/` erin (NavigationBar verhuist) +C) Een aparte map `layout/` naast `components/` voor alles wat shell is +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: + +### Vraag 2: Waar komt de content-module te staan, en verhuist `heroContent` mee? +A) Nieuwe map `src/content/` met `siteContent.ts` en de types. `heroContent.ts` en de types in `Hero/types.ts` verhuizen mee, zodat alle "straks-uit-de-API"-data op één plek staat. **(aanbevolen)** +B) Nieuwe map `src/content/` alleen voor `siteContent`. `heroContent` blijft bij de Hero. +C) `src/siteContent.ts` los naast `seo.ts` +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: + +### Vraag 3: Hoe krijgen Footer en Hero de site-content binnen? +A) Via props: `AppShell` geeft `siteContent` door aan `Footer`, en de home-route geeft de socials door aan `Hero`. Dat is hetzelfde patroon als de Hero nu met `content` werkt, en makkelijk te testen. Als de API er is, wordt alleen de bron vervangen (bv. een route-loader). **(aanbevolen)** +B) Componenten importeren `siteContent` direct. Dat is het simpelst, maar later moet elk component aangepast worden. +C) Een React-context (`SiteContentProvider` + `useSiteContent()`) rond de app, klaar om later met data uit de API gevuld te worden +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: + +### Vraag 4: Waar staan de menu-items voor het footermenu? +De items van het hoofdmenu (`navItems`) zijn routes, en routes zijn code: het CMS kan geen pagina's toevoegen. In de requirements (FR-04) stond het footermenu in `siteContent`. + +A) Het footermenu staat naast `navItems` in de navigatiecode (bijvoorbeeld `navigation.ts` met `mainNav` en `footerNav`), getypeerd op bestaande routes. `siteContent` bevat alleen echte content (tekst, socials, e-mail). Ik pas FR-04 hierop aan. **(aanbevolen)** +B) Het footermenu staat in `siteContent`, zoals in FR-04. De `to`-waarden zijn gewone strings, dus de router controleert de types minder streng. +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: + +### Vraag 5: Opbouw van de placeholder-pagina's +Vijf routes krijgen voorlopig placeholder-inhoud: portfolio, soorten-fotoshoots, contact, privacyverklaring en over-mij. + +A) Een herbruikbaar `PageIntro`-component: ruimte onder de header, `Container`, eyebrow en `h1`. De placeholders gebruiken het nu, en de echte pagina's straks als bovenste blok (het "Intro"-blok uit LAYOUT.md). **(aanbevolen)** +B) Een apart `PagePlaceholder`-component, alleen voor de placeholders, dat later weer verdwijnt +C) Per route inline, zonder gedeeld component +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: + +### Vraag 6: 404- en foutpagina +A) Eén gedeeld `StatusPage`-component (titel, tekst, knop naar home). `NotFound` en `ErrorPage` zijn er dunne wrappers omheen. **(aanbevolen)** +B) Twee losse componenten +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: + +### Vraag 7: Stijl van de footerlinks +Footerlinks (socials, e-mail, footermenu) delen één stijl: zachte kleur, accent bij hover, en een zichtbare focusring. Die stijl komt op meer dan twee plekken voor, dus centraliseren is zinvol. + +A) Chakra's ingebouwde `Link`-recipe uitbreiden met een variant `subtle` in het thema. Footerlinks worden ``, en voor router-links gebruiken we ``. Zo benutten we Chakra zelf. **(aanbevolen)** +B) Een eigen nieuwe recipe `subtleLink`, naast `linkButton` +C) Een klein `FooterLink`-component met style props, zonder thema-uitbreiding +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: + +### Vraag 8: Gedeelde router-link en bestaande code +`chakra(Link)` wordt nu in drie bestanden apart gedefinieerd: `NavLink`, `MobileNav` en `LinkButton`. + +A) Eén gedeelde `RouterLink` (in `components/RouterLink.tsx`) en de drie bestaande bestanden daarop omzetten. Dat is een kleine, veilige refactor. **(aanbevolen)** +B) Alleen de nieuwe code gebruikt de gedeelde `RouterLink`. Bestaande bestanden blijven zoals ze zijn. +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: + +### Vraag 9: Het "volledig zichtbaar bij hover"-patroon +`HeroArrows` en `HeroSocials` herhalen allebei hetzelfde patroon: opacity 0.6, bij hover of focus naar 1, met de transitie-tokens. De terug-naar-boven-knop gebruikt dat patroon niet (die heeft een rand en kleur zoals in het design). + +A) Centraliseren in het thema, als recipe of als gedeelde style-set, en de twee Hero-componenten erop omzetten. Dat is een kleine, veilige refactor. +B) Laten zoals het is. Het komt maar op twee plekken voor, beide in de Hero, en de shell gebruikt het niet. **(aanbevolen)** Hier doen we "niet forceren". +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: diff --git a/aidlc-docs/features/frontend-shell/inception/plans/execution-plan.md b/aidlc-docs/features/frontend-shell/inception/plans/execution-plan.md new file mode 100644 index 0000000..b6126b6 --- /dev/null +++ b/aidlc-docs/features/frontend-shell/inception/plans/execution-plan.md @@ -0,0 +1,182 @@ +# Execution Plan — frontend-shell + +## Detailed Analysis Summary + +### Transformation Scope (Brownfield) +- **Transformation Type**: Single package (`web/`), application-level changes only — no architectural or infrastructure transformation +- **Primary Changes**: Complete the application shell: footer, back-to-top, skip link + main landmark, 404 and error pages, logo link, full navigation with placeholder routes, scroll restoration, shared site content module, theme additions for reused styling, test toolchain, security headers on dev/preview server, tech-debt clean-up +- **Related Components**: `AppShell`, `NavigationBar` (+ `navItems`), `Footer`, `Hero` (socials source), `theme.ts`, `main.tsx` (router options), `routes/*`, `vite.config.js`, `package.json` + +### Change Impact Assessment +- **User-facing changes**: Yes — new footer, to-top button, skip link, 404/error pages, extra menu items and placeholder pages, footer contrast deviates from design (AA) +- **Structural changes**: Yes (minor) — new shell components, shared `siteContent` module, shared router-link primitive; shell stays Header / main / Footer +- **Data model changes**: Yes (minor) — new typed `SiteContent` shape; `HeroContent.socials` moves to it +- **API changes**: No external API. Internal: Hero's content props change (socials no longer in `heroContent`) +- **NFR impact**: Yes — accessibility (WCAG 2.1 AA), new test toolchain incl. PBT, security headers / CSP, supply-chain hygiene + +### Component Relationships + +```mermaid +graph TD + Root["routes/__root.tsx"] --> AppShell["AppShell"] + Root --> NotFound["NotFound page (new)"] + Root --> ErrorPage["Error page (new)"] + AppShell --> SkipLink["SkipLink (new)"] + AppShell --> Nav["NavigationBar (changed)"] + AppShell --> Main["main#main + Outlet (new)"] + AppShell --> Footer["Footer (rebuilt)"] + AppShell --> ToTop["BackToTop (new)"] + Nav --> NavItems["navItems (changed)"] + Footer --> SiteContent["siteContent (new)"] + Hero["Hero (changed)"] --> SiteContent + Footer --> Theme["theme.ts (changed)"] + ToTop --> Theme + Main --> Pages["placeholder routes (new)"] + classDef existing fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef changed fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef added fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + class Root,AppShell existing; + class Nav,NavItems,Hero,Theme,Footer changed; + class NotFound,ErrorPage,SkipLink,Main,ToTop,SiteContent,Pages added; +``` + +Text alternative: the root route renders AppShell plus new NotFound/Error pages; AppShell gains SkipLink, a main landmark, a rebuilt Footer and a new BackToTop; Footer and Hero both read the new siteContent module; theme.ts is extended (blue = unchanged, yellow = changed, green = new). + +- **Primary Component**: `web/` (React SPA) — Change Type: Minor (additive), Priority: Critical +- **Infrastructure Components**: none (only `vite.config.js` dev/preview headers — Configuration-only) +- **Shared Components**: `theme.ts`, `siteContent`, shared router-link primitive — Minor +- **Dependent Components**: `Hero` (socials source) — Minor +- **Supporting Components**: new test setup (Vitest config, test utils, generators) — Minor + +### Risk Assessment +- **Risk Level**: Low — isolated front-end, not deployed yet, every change reversible via git +- **Rollback Complexity**: Easy +- **Testing Complexity**: Moderate — new toolchain (Vitest + RTL + fast-check) and jsdom limits around scrolling/media queries + +## Workflow Visualization + +```mermaid +flowchart TD + Start(["User Request"]) + + subgraph INCEPTION["🔵 INCEPTION PHASE"] + WD["Workspace Detection
COMPLETED"] + RE["Reverse Engineering
COMPLETED"] + RA["Requirements Analysis
COMPLETED"] + US["User Stories
SKIP"] + WP["Workflow Planning
IN PROGRESS"] + AD["Application Design
EXECUTE"] + UG["Units Generation
SKIP"] + end + + subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"] + FD["Functional Design
EXECUTE"] + NFRA["NFR Requirements
EXECUTE"] + NFRD["NFR Design
SKIP"] + ID["Infrastructure Design
SKIP"] + CG["Code Generation
(Planning + Generation)
EXECUTE"] + BT["Build and Test
EXECUTE"] + end + + Start --> WD + WD --> RE + RE --> RA + RA -.-> US + RA --> WP + WP --> AD + AD -.-> UG + AD --> FD + FD --> NFRA + NFRA -.-> NFRD + NFRA -.-> ID + NFRA --> CG + CG --> BT + BT --> End(["Complete
(Operations: ask again)"]) + + style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style RE fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style UG fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000 + style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000 + + linkStyle default stroke:#333,stroke-width:2px +``` + +Text alternative: completed Inception stages (green) lead to Application Design, Functional Design and NFR Requirements (orange, execute), then Code Generation and Build and Test (green); User Stories, Units Generation, NFR Design and Infrastructure Design are skipped (grey). The Operations phase is undecided and will be asked again after Build and Test. + +## Phases to Execute + +### 🔵 INCEPTION PHASE +- [x] Workspace Detection (COMPLETED) +- [x] Reverse Engineering (COMPLETED) +- [x] Requirements Analysis (COMPLETED) +- [x] User Stories (SKIPPED) + - **Rationale**: One persona (site visitor), requirements already concrete per shell element with clear acceptance; stories would restate FR-01…FR-11 +- [x] Execution Plan (IN PROGRESS) +- [ ] Application Design - EXECUTE (minimal depth) + - **Rationale**: Several new components (Footer, BackToTop, SkipLink, NotFound, ErrorPage, placeholder page layout) and new shared pieces (`siteContent`, shared router-link primitive, theme additions such as a subtle-link style). Their boundaries, props and what gets centralised in the theme (NFR-02 reuse principle) should be decided once, before code +- [ ] Units Generation - SKIP + - **Rationale**: One package, one cohesive unit ("frontend-shell"); no parallel streams or deployment boundaries to split on + +### 🟢 CONSTRUCTION PHASE +- [ ] Functional Design - EXECUTE (minimal depth) + - **Rationale**: Required by PBT-01 — identify testable properties of the shell's logic (to-top visibility threshold, footer/nav item derivation, current-year copyright, content shape). Also pins down the `SiteContent` data model and to-top / skip-link behaviour rules +- [ ] NFR Requirements - EXECUTE (minimal depth) + - **Rationale**: Tech stack decisions for the new test toolchain (Vitest, RTL, jsdom, fast-check — PBT-09), accessibility acceptance criteria, exact security header set and CSP (SECURITY-04), supply-chain checks (SECURITY-10) +- [ ] NFR Design - SKIP + - **Rationale**: The NFR patterns are small and concrete (one header config in `vite.config.js`, one Vitest setup, one generators file); they are specified directly in NFR Requirements and the code generation plan without a separate design document +- [ ] Infrastructure Design - SKIP + - **Rationale**: No infrastructure; hosting is out of scope (Operations undecided). Production header requirements are documented, not provisioned +- [ ] Code Generation - EXECUTE (ALWAYS) + - **Rationale**: Implementation planning and code generation needed +- [ ] Build and Test - EXECUTE (ALWAYS) + - **Rationale**: Build, test (incl. PBT with seed logging) and verification needed + +### 🟡 OPERATIONS PHASE +- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - UNDECIDED + - **Rationale**: Operations Configuration = Undecided (Q14 = C); asked again at Build and Test + +## Package Change Sequence +Single package (`web/`). Suggested order inside the unit (detailed in the code generation plan): +1. Test toolchain + tech-debt clean-up (safe base, `pnpm build` green) +2. Theme additions + shared primitives (`siteContent`, shared router link) +3. Routes + `navItems` (placeholder pages, privacy page) +4. Shell components (SkipLink + main, Footer, BackToTop, logo link) +5. 404 + error pages, scroll restoration +6. Security headers on dev/preview server +7. Tests (example-based + property-based) per step, final full run + +## Estimated Timeline +- **Total Stages Remaining**: 5 (Application Design, Functional Design, NFR Requirements, Code Generation, Build and Test) +- **Estimated Duration**: a few working sessions; each design stage is short (minimal depth), Code Generation is the bulk + +## Success Criteria +- **Primary Goal**: Every page renders inside a complete shell matching LAYOUT.md and the static design (minus the side area and mobile e-mail), with the agreed accessibility and contrast adjustments +- **Key Deliverables**: + - Footer, BackToTop, SkipLink + main landmark, logo link, full navigation + - Placeholder routes `/portfolio`, `/soorten-fotoshoots`, `/contact`, `/privacyverklaring` + - 404 and generic error pages inside the shell; scroll restoration + - `siteContent` module used by Hero and Footer; reused/centralised styling per NFR-02 + - Vitest + RTL + fast-check setup with example-based and property-based tests + - Security headers on dev/preview server + documented production header set + - Tech-debt items from FR-11 resolved +- **Quality Gates**: + - `pnpm build` succeeds (type-check + bundle) + - `pnpm test` passes, PBT seed logged on failure + - `pnpm audit` reviewed, no unaddressed high/critical issues + - Security Baseline and PBT compliance summaries have no blocking findings + - Manual keyboard/screen check of the shell (skip link, focus styles, to-top, menus) +- **Integration Testing**: Shell + routes together (navigation, 404, error boundary, scroll restoration) +- **Operational Readiness**: Out of scope unless Operations is chosen at Build and Test diff --git a/aidlc-docs/features/frontend-shell/inception/requirements/requirement-clarification-questions.md b/aidlc-docs/features/frontend-shell/inception/requirements/requirement-clarification-questions.md new file mode 100644 index 0000000..e3b6b8b --- /dev/null +++ b/aidlc-docs/features/frontend-shell/inception/requirements/requirement-clarification-questions.md @@ -0,0 +1,39 @@ +# Verduidelijkingsvragen — Front-end shell + +Twee antwoorden zijn nog niet eenduidig genoeg om de requirements op vast te leggen. + +--- + +## Ambiguïteit 1: Logo in de footer (Vraag 4) + +Je antwoord: "Als je de achtergrond doorzichtig kan maken, dan kan hij erbij. Als dat niet lukt, dan kan dat deel uit de footer. Het lijkt mij sowieso onnodige vulling?" + +Wat ik heb uitgezocht: +- **Het lukt.** Het beeldmerk is zwart lijnwerk op wit. Ik heb de witte achtergrond omgezet naar transparantie en het lijnwerk in de ink-kleur van het thema gezet, met zachte randen. Proefversie op de footerachtergrond: `scratchpad/footer-mark-preview.png` (ik kan hem tonen). +- **Het is hetzelfde beeldmerk als het logo in de header.** `web/src/assets/logo-dark.png` is al transparant en toont dezelfde cirkel met "AS" en "Andrea Slop Fotografie". Het verschil: de footerversie heeft dunnere lijnen en veel lege ruimte eromheen. +- **Mijn mening over "onnodige vulling":** de eerste footerkolom bestaat in het design uit het beeldmerk met één zin eronder ("Lifestyle fotograaf uit Huizen…"). Zonder beeldmerk wordt die kolom een losse zin naast twee kolommen met een kopje, en dat oogt wat kaal. Een merkteken onderaan is gangbaar en sluit de pagina rustig af. Het is wel een herhaling van de header, dus weglaten is verdedigbaar. Mijn advies is A. + +### Verduidelijkingsvraag 1 +Wat doen we met het beeldmerk in de footer? + +A) Het bestaande `logo-dark.png` hergebruiken. Er komt geen extra bestand bij en het is al transparant. +B) De omgezette footerversie gebruiken (dunnere lijnen, zoals op de live site), bijgesneden zonder lege rand, als `web/src/assets/footer-mark.png` +C) Geen beeldmerk in de footer. De eerste kolom krijgt alleen de korte tekst. +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +--- + +## Ambiguïteit 2: Link naar de privacyverklaring (Vraag 5 en Vraag 1) + +Je koos bij Vraag 5 voor het footermenu mét een link naar een privacyverklaring "die later komt". Bij Vraag 1 koos je voor placeholder-routes voor pagina's die nog niet af zijn. Het is nog niet duidelijk wat de privacylink nu moet doen. + +### Verduidelijkingsvraag 2 +Wat doet de privacylink zolang de privacyverklaring er nog niet is? + +A) Nu ook een placeholder-route `/privacyverklaring` aanmaken (net als bij Vraag 1). De link werkt meteen en de tekst komt later. +B) De link pas tonen als de pagina bestaat. Tot die tijd is het footermenu zoals in het design (Portfolio, Soorten fotoshoots, Contact). +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A diff --git a/aidlc-docs/features/frontend-shell/inception/requirements/requirement-verification-questions.md b/aidlc-docs/features/frontend-shell/inception/requirements/requirement-verification-questions.md new file mode 100644 index 0000000..a50c5cb --- /dev/null +++ b/aidlc-docs/features/frontend-shell/inception/requirements/requirement-verification-questions.md @@ -0,0 +1,148 @@ +# Verificatievragen — Front-end shell + +Al vastgelegd (geen vraag nodig): +- Het **info-menu (side area)** en het **e-mailadres in het mobiele menu** blijven weg (jouw keuze). +- Het **logo in de header** wordt een link naar de homepage, zoals in het design. +- Het **jaartal** in de footer is altijd het huidige jaar. + +Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe. + +--- + +## Vraag 1: Menu-items voor pagina's die nog niet bestaan +Het design heeft vijf menu-items (Home, Over mij, Portfolio, Soorten fotoshoots, Contact). Alleen voor Home en Over mij bestaat al een route. Wat doen we met de andere drie? + +A) Nu lege placeholder-routes aanmaken (`/portfolio`, `/soorten-fotoshoots`, `/contact`) met eigen titel en beschrijving, en ze in het menu en de footer zetten. De shell is dan compleet en de pagina's worden later gevuld. +B) Alleen menu-items tonen voor pagina's die af zijn. De andere komen erbij als die pagina's gebouwd worden. +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 2: Waar komt de footer-content vandaan? +De footer bevat een korte tekst, sociale links, een e-mailadres en een footermenu. De sociale links staan nu ook al in `heroContent.ts`. + +A) Eén gedeeld, API-vormig contentbestand voor sitebrede gegevens (bv. `siteContent.ts`: socials, e-mail, footertekst). Hero en footer lezen daaruit, en later komt het uit de CMS-API. +B) Direct in de Footer-component zetten. De hero houdt zijn eigen socials. +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 3: Sociale links in de footer +Hoe tonen we Facebook en Instagram in de footer? + +A) Als tekstlinks ("Facebook", "Instagram"), precies zoals in het design +B) Als iconen, net als in de hero +C) Icoon met tekst ernaast +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 4: Logo in de footer +Het design gebruikt een apart beeldmerk (`footer-mark.png`, op de live site `wp-content/uploads/2025/08/4.png`). Dat staat nog niet in `web/src/assets`. + +A) Ik download het van de live site naar `web/src/assets/footer-mark.png` +B) Het bestaande donkere logo (`logo-dark.png`) gebruiken +C) Ik lever het bestand zelf aan +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: X, het huidige bestand heeft een witte achtergrond. Als je die wat kan aanpassen zodat de achtergrodnd doorichtig is dan kan hij in de footer erbij. Als dat niet lukt dan zou dat dele uit de footer kunnen. Het lijkt mij sowieso onnodige vulling? + +## Vraag 5: Footermenu (onderste balk) +In het design staan in de onderste balk naast "© jaar Andrea Slop Fotografie" de links Portfolio, Soorten fotoshoots en Contact. + +A) Zoals in het design: Portfolio, Soorten fotoshoots, Contact +B) Het volledige hoofdmenu (alle items uit `navItems`) +C) Zoals in het design, plus een link naar een privacyverklaring (die pagina komt later) +D) Geen footermenu, alleen de copyright-regel +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: C + +## Vraag 6: Terug-naar-boven-knop +Het design heeft een vierkante knop rechtsonder (↑). Die verschijnt na 60% van een schermhoogte scrollen en scrollt soepel terug, of direct als iemand minder beweging wil (reduced motion). + +A) Bouwen zoals in het design +B) Bouwen, maar met een icoon (bijv. Ant Design `up-outlined`) in plaats van de ↑-pijl +C) Niet bouwen +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: B + +## Vraag 7: Toegankelijkheid van de shell +A) Skip-link "Direct naar de inhoud", een `
`-landmark, zichtbare focusstijlen op alle shell-links en -knoppen, en de shell volledig met het toetsenbord te bedienen (WCAG 2.1 AA als richtlijn) +B) Alleen skip-link en `
`-landmark, zoals in het design +C) Niets extra's +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 8: Scrollpositie bij navigeren +Wat gebeurt er met de scrollpositie als je van pagina wisselt? + +A) Nieuwe pagina begint bovenaan. Met de terug-/vooruitknop van de browser kom je terug op de plek waar je was (scroll restoration). +B) Altijd bovenaan beginnen, ook bij terug/vooruit (het huidige standaardgedrag) +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 9: Pagina niet gevonden (404) +Een onbekende URL toont nu de standaardmelding van TanStack Router. + +A) Een eenvoudige 404-pagina binnen de shell (header en footer blijven staan), met een knop terug naar home +B) Nu niet, later apart oppakken +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 10: Technische schuld rond de shell opruimen +Uit de analyse kwamen een paar punten naar voren: +- `body { height: 250vh }` in `theme.ts` (tijdelijke scroll-test) +- Tailwind-classes die niets doen in `Footer.tsx` en `over-mij.tsx` +- `let` in plaats van `const` in `NavigationBar.tsx` +- Ongebruikte Vite-startbestanden (`hero.png`, `typescript.svg`, `vite.svg`) + +A) Alles meenemen in deze feature +B) Alleen wat de shell direct raakt (de 250vh-hack en de Footer-classes) +C) Niets, dat doe ik apart +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 11: Testen +Het project heeft nog geen testframework. + +A) Vitest + React Testing Library toevoegen en de shell-componenten unit-testen (footer-inhoud, to-top-zichtbaarheid, skip-link, 404) +B) Geen testframework. Verificatie via `pnpm build` (type-check) en een handmatige checklist in de browser. +C) Playwright toevoegen voor end-to-end tests van de shell +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 12: Beveiligingsextensies +Moeten de beveiligingsregels als harde vereisten worden afgedwongen voor dit project? + +A) Ja — dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten (aanbevolen voor productietoepassingen) +B) Nee — sla alle BEVEILIGINGSREGELS over (geschikt voor PoC's, prototypes en experimentele projecten) +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 13: Property-Based Testing Extensie +Moeten de property-based testing (PBT) regels worden afgedwongen voor dit project? + +A) Ja — dwing alle PBT-regels af als blokkerende vereisten (aanbevolen voor projecten met bedrijfslogica, datatransformaties, serialisatie of stateful componenten) +B) Gedeeltelijk — dwing PBT-regels alleen af voor pure functies en serialisatie round-trips (geschikt voor projecten met beperkte algoritmische complexiteit) +C) Nee — sla alle PBT-regels over (geschikt voor eenvoudige CRUD-applicaties, UI-only projecten of dunne integratielagen zonder significante bedrijfslogica) +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 14: Operations-fase +Moet deze feature na de Construction-fase door de Operations-fase (deployment en monitoring inrichten)? + +A) Ja — de Operations-fase doorlopen na Construction (deployment + monitoring) +B) Nee — stoppen na Build and Test (deployment/monitoring vallen buiten deze feature) +C) Weet ik nog niet — vraag het opnieuw na de Construction-fase +X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: C diff --git a/aidlc-docs/features/frontend-shell/inception/requirements/requirements.md b/aidlc-docs/features/frontend-shell/inception/requirements/requirements.md new file mode 100644 index 0000000..dc97a0c --- /dev/null +++ b/aidlc-docs/features/frontend-shell/inception/requirements/requirements.md @@ -0,0 +1,228 @@ +# Requirements — Front-end Application Shell + +## Intent Analysis +- **User Request**: "ik wil met aidlc de shell voor de front-end afmaken" (finish the front-end shell with AI-DLC) +- **Request Type**: Enhancement (completing an existing, partially built feature) with some new capability (routes, footer, to-top, 404, error page) +- **Scope Estimate**: Multiple components within one package (`web/`): shell components, routes, theme, content module, test setup +- **Complexity Estimate**: Moderate — mostly UI work against an existing design, plus a new test toolchain and security/PBT constraints +- **Requirements Depth**: Standard + +## Source of Truth +- Shell structure: [LAYOUT.md](../../../../../LAYOUT.md) — Header / Page content / Footer +- Visual and markup reference: `design/andreaslop-static/` (header, footer, to-top, skip link in `index.html`; styles in `assets/css/style.css`) +- Decisions: [requirement-verification-questions.md](requirement-verification-questions.md), [requirement-clarification-questions.md](requirement-clarification-questions.md) + +## Out of Scope +- **Side area / "Info menu"** panel from the design (owner decision) +- **E-mail address in the mobile menu** (owner decision) +- Real content for Portfolio, Soorten fotoshoots, Contact, Privacyverklaring and Over mij (placeholders only) +- Contact form, Instagram feed, CMS/.NET API +- Hosting/deployment (Operations phase undecided) + +--- + +## Functional Requirements + +### FR-01 Placeholder routes +- Create routes `/portfolio`, `/soorten-fotoshoots`, `/contact` and `/privacyverklaring`. +- Each has its own `head` via `pageHead()` with a title (≤ ~60 chars) and description (≤ ~155 chars), in the existing style (`" | Andrea Slop Fotografie"`). +- Each renders a simple placeholder (page heading plus a short line) that sits below the fixed header, so no content is hidden behind it. +- *Source: Q1 = A, Clarification 2 = A* + +### FR-02 Main navigation items +- `navItems` contains, in this order: Home, Over mij, Portfolio, Soorten fotoshoots, Contact. +- Used by both the desktop navigation and the mobile menu (existing behaviour retained). +- Privacyverklaring is **not** in the main navigation. +- *Source: Q1 = A, design* + +### FR-03 Header logo links home +- The header logo is a link to `/` with accessible name "Andrea Slop Fotografie, naar de homepage" (as in the design). +- The existing dark/light logo swap and shrink behaviour are unchanged. +- *Source: design* + +### FR-04 Shared site content module +- Introduce one API-shaped, typed content module for site-wide data (working name `siteContent`). It holds: + - the footer intro text + - social links (`platform` + `href`, reusing `SocialPlatform`) + - the contact e-mail address + - the footer menu items +- The Hero's social links come from this module instead of `heroContent.ts`, so both Hero and Footer read one source. +- Plain data (strings and arrays), so it can later be replaced 1-on-1 by a CMS API response. +- *Source: Q2 = A* + +### FR-05 Footer +The top section has three columns: +1. **Brand**: the monogram, reusing `web/src/assets/logo-dark.png` (~150px wide), with the intro text "Lifestyle fotograaf uit Huizen. Ik leg jouw mooiste momenten vast met mijn camera." below it. +2. **Socials**: an eyebrow heading "Socials", then **text links** "Facebook" and "Instagram". They open in a new tab with `rel="noopener noreferrer"`. +3. **Contact**: an eyebrow heading "Contact", then a `mailto:` link to the e-mail address. + +The bottom bar holds: +- "© {current year} Andrea Slop Fotografie" +- a footer navigation (`aria-label="Footermenu"`) with Portfolio, Soorten fotoshoots, Contact and Privacyverklaring + +Layout and styling: +- **Responsive**: three columns on desktop, two on tablet and one on mobile, as in the design breakpoints. +- On mobile the bottom bar stacks and is centred. +- **Styling** uses the theme tokens: `paper.alt` background, a `line` top border, link hover in the accent colour, with the contrast exceptions in NFR-01. +- The year is always the current year. +- *Source: Q3 = A, Q5 = C, Clarification 1 = A, Clarification 2 = A, design* + +### FR-06 Back-to-top button +- A fixed square button at the bottom right, styled like the design (`.to-top`), with an Ant Design `up-outlined` icon instead of the ↑ character. +- It becomes visible when the page is scrolled more than 60% of the viewport height, and is hidden again otherwise. +- **Click**: scrolls to the top, smoothly, or instantly when `prefers-reduced-motion: reduce` is set. +- **Accessibility**: + - accessible name "Terug naar boven" + - while hidden it is not focusable, not announced and not clickable +- It sits below the header and mobile menu in stacking order. +- *Source: Q6 = B* + +### FR-07 Skip link and main landmark +- The first focusable element on every page is a skip link "Direct naar de inhoud", visually hidden until it receives focus. +- It targets `
`, which wraps the routed page content (`Outlet`). `main` can receive focus programmatically, so keyboard and screen-reader users land in the content. +- *Source: Q7 = A* + +### FR-08 Scroll position on navigation +- Navigating to a new page starts at the top. +- Browser back/forward restores the previous scroll position (router scroll restoration). +- *Source: Q8 = A* + +### FR-09 Not-found (404) page +- An unknown URL renders a "Pagina niet gevonden" page **inside the shell**: header and footer stay. +- The page shows a heading, a short explanation and a `LinkButton` back to home. +- Head: title "Pagina niet gevonden | Andrea Slop Fotografie" plus `robots: noindex`. +- *Source: Q9 = A* + +### FR-10 Generic error page +- Unexpected render or route errors show a generic error page inside the shell: a short Dutch message and a link home. +- It shows no error message, stack trace or internal details to the visitor. +- *Source: SECURITY-09, SECURITY-15* + +### FR-11 Technical debt clean-up +- Remove `globalCss.body.height: '250vh'` from `theme.ts`. +- Remove the non-functional Tailwind-style `className`s (`Footer.tsx` is replaced; `over-mij.tsx` gets a placeholder in the same style as FR-01). +- Make `over-mij.tsx` follow the project Prettier style. +- `let [open, setOpen]` → `const` in `NavigationBar.tsx`. +- Delete unused starter assets `assets/hero.png`, `assets/typescript.svg`, `assets/vite.svg`, after verifying they are unreferenced. +- Move `@vitejs/plugin-react` from `dependencies` to `devDependencies`. It is a build tool (SECURITY-10 hygiene). +- *Source: Q10 = A* + +--- + +## Non-Functional Requirements + +### NFR-01 Accessibility (WCAG 2.1 AA as guideline for the shell) +- All shell links and buttons are keyboard operable and have a visible focus style. +- Landmarks: + - `header` contains `nav aria-label="Hoofdmenu"` + - `main#main` + - `footer` contains `nav aria-label="Footermenu"` + - Placeholder, 404 and error pages each have exactly one `h1`. +- **Text contrast ≥ 4.5:1** for small text. The design's colours do not all meet this. Measured on `paper.alt`: + + | Token | Contrast on `paper.alt` | AA for small text | + |---|---|---| + | `ink.muted` (#8a827a) | 3.19:1 | fails | + | `accent` (#7f8b76) | 3.03:1 | fails | + | `ink.soft` | 6.72:1 | passes | + | `accent.deep` | 4.80:1 | passes | + + The shell therefore uses `ink.soft` instead of `ink.muted` for the footer headings and the bottom bar, and `accent.deep` instead of `accent` for link hover on light backgrounds. **This is a deliberate deviation from the design.** +- `prefers-reduced-motion` is respected by every new animation or transition (to-top reveal, smooth scrolling). +- *Source: Q7 = A* + +### NFR-02 Styling: reuse first, use Chakra where it helps +Principle: **reuse as much as possible and make good use of Chakra UI v3, where it is a natural fit — do not force it.** *Source: user feedback at Requirements review* + +- **Reuse before adding.** Prefer what already exists over new styling: + - **Theme tokens**: colours, spacing (`gutter`), `header` sizes, durations, easings + - **Text styles**: `eyebrow` for the footer column headings and footer labels + - **Recipes**: `linkButton` for the 404 and error page buttons + - **Components**: `LinkButton`, `NavLink` and `navItems` +- **Use Chakra's built-in components and layout primitives** where they fit, for example: + - `Container`, `SimpleGrid`/`Grid`, `Stack`/`HStack`, `Heading`, `Text`, `Link`, `Image`, `VisuallyHidden` + - responsive style props instead of custom media queries + - `_hover`, `_focusVisible` and `_currentPage` pseudo props +- **Centralise repeated styling.** When the same styling appears in two or more places, lift it into the theme rather than copy it: + - Examples: the subtle-link style shared by footer links, or the "hover to full opacity" icon pattern already in `HeroArrows` and `HeroSocials`. + - Lift it into a token, text style or recipe, or into a small shared component (e.g. one shared `chakra(Link)` instead of one per file). + - Existing code is refactored to use it only where that is a small, safe change. +- **Do not force it.** Use the `chakra.*` factory or plain style props when no built-in component fits. Do not add a recipe or token for a one-off style. Do not bend a Chakra component into something it is not meant for. +- **No other styling approaches**: no hard-coded colours, no CSS files, no Tailwind. + +### NFR-02a Consistency with the existing codebase +- **Files and naming**: + - Components follow the existing folder pattern, e.g. `components/Footer/`. + - Code comments are in Dutch, matching the existing code. + - Prettier style: 4 spaces, single quotes. +- Icons use `@iconify/react/offline` with bundled `@iconify-icons/ant-design` data, so there are no runtime icon requests. + +### NFR-03 Testing +- Add **Vitest**, **React Testing Library** (with `jsdom` and `@testing-library/user-event`) and **fast-check** as dev dependencies. Add a `test` script to `package.json`. +- **Example-based unit tests** cover: + - footer content, links and current year + - to-top visibility, click behaviour and reduced motion + - skip link target + - 404 and error pages rendering inside the shell + - nav items order + - external link attributes +- **Property-based tests** (fast-check) cover the pure logic identified in Functional Design, e.g. the to-top visibility threshold and the derivation of footer and nav items. They log the seed on failure and keep shrinking enabled. +- **`pnpm build`** (type-check and bundle) still succeeds. +- *Source: Q11 = A, Q13 = A (PBT-01…PBT-10)* + +### NFR-04 Security (Security Baseline extension enabled) +- **External links**: every external link uses `target="_blank"` with `rel="noopener noreferrer"`. +- **No visitor-facing internals**: 404 and error pages show no internal details (SECURITY-09, SECURITY-15). +- **No remote scripts or fonts**: no scripts, fonts or styles from external CDNs. Fonts and icons stay self-hosted or bundled (SECURITY-13). +- **Dependencies (SECURITY-10)**: + - New dependencies are added via pnpm, so they are pinned by the committed `pnpm-lock.yaml`. + - No unused dependencies remain. + - `pnpm audit` is documented as the vulnerability scan in the build-and-test instructions. +- **HTTP security headers (SECURITY-04)**: + - A header set is defined and applied to the Vite dev and preview servers: `Content-Security-Policy`, `Strict-Transport-Security`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`. + - The same set is documented as the required configuration for the future production host. + - The CSP needs `style-src 'unsafe-inline'`, because Chakra/Emotion inject runtime `