Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/inception/requirements/requirements.md
T
SluijsensandClaude Opus 5.5 db2fa89b90 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 <noreply@anthropic.com>
2026-10-14 13:03:26 +02:00

229 lines
14 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
- 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 `<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*
---
## 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.
---
## 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 |