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>
247 lines
16 KiB
Markdown
247 lines
16 KiB
Markdown
# 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 |
|