Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/inception/application-design/application-design.md
T
SluijsensandClaude Opus 5.5 b5b7f3b3db Adds application design for the front-end shell feature
Component boundaries, interfaces, services and dependencies for the
shell: footer, back-to-top, skip link, status pages, page intro,
shared RouterLink, content folder and navigation module. Includes the
answered design questions and the revised site content requirement.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 23:20:41 +02:00

5.5 KiB
Raw Blame History

Application Design — frontend-shell (consolidated)

Detail documents: components.md · component-methods.md · services.md · component-dependency.md

Overview

The shell stays the three-part frame from LAYOUT.md, now with full accessibility plumbing:

  • Header: NavigationBar
  • Page content: main#main
  • Footer: Footer

Around these sit a Chakra skip link and a BackToTop button. Pages are routed through TanStack Router. Unknown URLs and page errors render inside the shell. Site-wide content comes from a new content/ folder and is passed down as props from two provisioning points. Menus are typed route lists in navigation.ts. Styling reuses the existing theme and extends Chakra's own recipes where styles repeat.

graph TD
    Skip["SkipNavLink"] --> Header["NavigationBar (logo link, mainNav)"]
    Header --> Main["main#main: Outlet / NotFound / ErrorPage"]
    Main --> Foot["Footer (SiteContent, footerNav)"]
    Foot --> Top["BackToTop (fixed)"]
    classDef chrome fill:#e76f51,stroke:#ad533d,stroke-width:1px,color:#000;
    classDef content fill:#ffffff,stroke:#333333,stroke-width:1px,color:#000;
    classDef footer fill:#f4a261,stroke:#b77a49,stroke-width:1px,color:#000;
    class Skip,Header chrome;
    class Main content;
    class Foot,Top footer;

Text alternative: top-to-bottom order of the shell: skip link, header, main content (page, 404 or error page), footer, and the fixed back-to-top button.

Design Decisions

# Decision Source
D1 One folder per component (Footer/, BackToTop/, PageIntro/, StatusPage/); AppShell.tsx stays AD Q1 = A
D2 New content/ folder: siteContent, heroContent, content types, socialPlatforms AD Q2 = A
D3 Content enters via props from AppShell and the home route; components never import content AD Q3 = A
D4 Menus are code: navigation.ts with mainNav + footerNav, typed on routes; FR-04 revised AD Q4 = A
D5 PageIntro as reusable top block for content pages (placeholders now, real pages later) AD Q5 = A
D6 StatusPage shared by NotFound and ErrorPage AD Q6 = A
D7 Footer links via Chakra's built-in Link with a new subtle variant; router links via asChild AD Q7 = A
D8 One shared RouterLink = chakra(Link); NavLink, MobileNav, LinkButton refactored onto it AD Q8 = A
D9 Hover-opacity pattern centralised as recipe iconControl; HeroArrows and HeroSocials use it AD Q9 = A
D10 Skip link + main via Chakra SkipNavLink/SkipNavContent, restyled through the theme NFR-02
D11 BackToTop reuses useScrolledPast; pure helpers (backToTopThreshold, visibleSocials, copyrightLine) for PBT NFR-02, NFR-03
D12 Router: scrollRestoration, root notFoundComponent, defaultErrorComponent + root errorComponent FR-08…FR-10

Requirements Traceability

Requirement Realised by
FR-01 Placeholder routes routes/{portfolio,soorten-fotoshoots,contact,privacyverklaring}.tsx + PageIntro
FR-02 Navigation items navigation.ts mainNav → NavigationBar, MobileNav
FR-03 Logo link NavigationBar logo wrapped in RouterLink to="/"
FR-04 Site content content/siteContent.ts, content/types.ts; menus in navigation.ts (D4)
FR-05 Footer Footer, FooterColumn, footerNav, link subtle variant, logo-dark.png
FR-06 Back to top BackToTop, useScrolledPast, backToTopThreshold
FR-07 Skip link + main SkipNavLink/SkipNavContent in AppShell, skipNavLink recipe override
FR-08 Scroll restoration createRouter({ scrollRestoration: true })
FR-09 404 NotFound → StatusPage, root notFoundComponent
FR-10 Error page ErrorPage → StatusPage, defaultErrorComponent + root errorComponent
FR-11 Tech debt theme.ts (250vh), over-mij.tsx, NavigationBar (const), assets, package.json
NFR-01 Accessibility Landmarks, skip link, subtle link contrast (ink.soft/accent.deep), hidden-state of BackToTop
NFR-02 Reuse/Chakra D7–D11
NFR-03 Testing Pure helpers (D11) + component tests; toolchain in NFR Requirements
NFR-04 Security rel="noopener noreferrer" on external links; generic ErrorPage; headers in NFR Requirements

Open Points for Functional Design

  • 404 title and noindex: a global not-found has no route head of its own. Choose between React 19 metadata hoisting (<title>/<meta> rendered inside NotFound) and a root head that reacts to the not-found state. Verify there is no duplicate <title> with HeadContent.
  • BackToTop focus: after "scroll to top", decide whether focus moves to the skip target (main) or stays on the button. The button is hidden at the top, so a focus decision is needed.
  • Behaviour rules and testable properties (PBT-01) for backToTopThreshold, visibleSocials, copyrightLine and the mainNav/footerNav invariants.

Compliance Summary (Application Design)

Security Baseline

  • SECURITY-09/15: compliant by design (generic ErrorPage; root error boundary as global handler).
  • SECURITY-13: compliant (no external resources).
  • SECURITY-04/10: addressed in NFR Requirements.
  • Others: N/A (see requirements.md).

Property-Based Testing

  • PBT-01: candidate pure functions identified (D11). Property identification is completed in Functional Design.
  • Other PBT rules: N/A at this stage.