Files
SluijsensandClaude Opus 5.5 069c7cb7eb Adds AI-DLC construction docs for the front-end shell feature
Functional design, NFR requirements, code generation plan and summary,
and build-and-test instructions with results.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 17:05:03 +02:00

247 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 (`"<Page> | 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 `<main id="main">`, 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 `<style>` tags. This exception is documented with that justification.
- **No secrets**: no secrets or credentials in front-end code. The site has no authentication.
### NFR-05 Performance
- The shell adds no network requests beyond its bundled assets. The footer logo reuses the already-bundled `logo-dark.png`.
- Scroll listeners are passive. The to-top button and the header share the existing scroll-hook approach; no layout thrashing.
### NFR-06 Responsive design (added at Functional Design)
- Mobile-first with Chakra's default breakpoints; works from 320px wide up to 32:9 without horizontal scrolling.
- Works at 200% zoom; touch targets at least 44×44px below `lg`.
- Content is limited to one shared content width; fixed elements align with it on ultrawide screens.
- *Source: functional design change request; rules BR-RWD-01…05*
---
## Security Baseline — Applicability at Requirements Level
| Rule | Status | Rationale |
|---|---|---|
| SECURITY-01 Encryption at rest/in transit | N/A | No data stores |
| SECURITY-02 Access logging on intermediaries | N/A | No load balancer/CDN/API gateway defined (hosting not in scope) |
| SECURITY-03 Application-level logging | N/A | No server-side component; static SPA. Client error reporting to be revisited when the API/hosting exists |
| SECURITY-04 HTTP security headers | Compliant (planned) | NFR-04 header set for dev/preview + documented for production |
| SECURITY-05 Input validation | N/A | No API endpoints or user input in the shell |
| SECURITY-06 Least privilege | N/A | No IAM |
| SECURITY-07 Network configuration | N/A | No network infrastructure |
| SECURITY-08 Application access control | N/A | Public site, no authentication or protected resources |
| SECURITY-09 Hardening | Compliant (planned) | FR-10 generic error page; FR-11 removes starter assets |
| SECURITY-10 Supply chain | Compliant (planned) | Lock file, `pnpm audit`, no unused deps (NFR-04, FR-11) |
| SECURITY-11 Secure design | N/A | No security-critical logic or public endpoints in the shell |
| SECURITY-12 Authentication | N/A | No authentication |
| SECURITY-13 Integrity | Compliant (planned) | No CDN-loaded resources |
| SECURITY-14 Alerting and monitoring | N/A | No server-side component; Operations phase undecided |
| SECURITY-15 Exception handling | Compliant (planned) | FR-10 root error boundary as global handler; generic user-facing message |
## Summary of Key Decisions
| # | Decision |
|---|---|
| Q1 | Placeholder routes for Portfolio, Soorten fotoshoots, Contact; full menu now |
| Q2 | Shared API-shaped `siteContent` module (Hero + Footer) |
| Q3 | Footer socials as text links |
| Q4 / C1 | Footer monogram reuses `logo-dark.png` |
| Q5 / C2 | Footer menu = design links + Privacyverklaring (placeholder route) |
| Q6 | To-top with Ant Design `up-outlined` icon |
| Q7 | WCAG 2.1 AA guideline for the shell (incl. contrast deviation from design) |
| Q8 | Scroll restoration on back/forward |
| Q9 | 404 page inside the shell |
| Q10 | All listed tech debt cleaned up |
| Q11 | Vitest + React Testing Library |
| Q12 | Security Baseline enforced |
| Q13 | Property-Based Testing enforced (full) |
| Q14 | Operations phase undecided — ask again after Build and Test |