# 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, stored as separate `user` and `domain` parts and joined only in the browser (anti-spam; revised in Functional Design, BR-EMAIL-01) - 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. - **Menu items are not content.** The main menu and footer menu items are routes, which are code (the CMS cannot add pages). They live together in a typed navigation module (`mainNav`, `footerNav`), not in `siteContent`. - *Source: Q2 = A; revised by Application Design Q4 = 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." 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, with an Ant Design `up-outlined` icon instead of the ↑ character. It deviates from the design (`.to-top`): dark `ink` background with a white icon so it stands out, and on very wide screens it aligns with the content edge (revised in Functional Design, BR-TOP-07/08). - 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* ### FR-12 SEO foundation (added at Functional Design) - One page registry (`sitePages`) is the single source for per-page title, description, `indexed` flag and preview image. - Every page has a canonical URL and `og:url` on `https://andreaslop.nl`, plus `og:image` and `twitter:card`. Placeholder, 404 and error pages are `noindex`. - Site-wide `ProfessionalService` JSON-LD, without the e-mail address. - `sitemap.xml` is generated at build time from the registry; `robots.txt` is static. A test keeps the registry and the routes in sync. - The code stays prerender-ready (no browser APIs during render); prerendering itself is a follow-up. - *Source: functional design change request, [frontend-shell-fd-change-questions.md](../../construction/plans/frontend-shell-fd-change-questions.md); rules BR-SEO-01…11* ### FR-13 Page change for screen readers (added at Functional Design) - After every client-side page change, focus moves to `main#main`, so screen readers announce the new content. - *Source: change request Q6 = A; rule BR-A11Y-01* --- ## 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 `