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

14 KiB

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

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
  • 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

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
  • 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 classNames (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