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>
79 lines
5.5 KiB
Markdown
79 lines
5.5 KiB
Markdown
# 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.
|