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

79 lines
5.5 KiB
Markdown
Raw 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.
# Application Design — frontend-shell (consolidated)
Detail documents: [components.md](components.md) · [component-methods.md](component-methods.md) · [services.md](services.md) · [component-dependency.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.
```mermaid
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.