Adds AI-DLC construction docs for the front-end shell feature
Functional design, NFR requirements, code generation plan and summary, and build-and-test instructions with results. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# Code Summary — frontend-shell
|
||||
|
||||
All application code is in `web/`. Plan: [frontend-shell-code-generation-plan.md](../../plans/frontend-shell-code-generation-plan.md).
|
||||
|
||||
## Structure
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Root["routes/__root.tsx"] --> Shell["AppShell"]
|
||||
Root --> Head["siteHead + JSON-LD"]
|
||||
Shell --> Skip["SkipNavLink"]
|
||||
Shell --> Nav["NavigationBar"]
|
||||
Shell --> Main["main#35;main + Outlet"]
|
||||
Shell --> Foot["Footer"]
|
||||
Shell --> Top["BackToTop"]
|
||||
Main --> Pages["Route pages via PageIntro / Hero"]
|
||||
Main --> Status["NotFound / ErrorPage via StatusPage"]
|
||||
Pages --> Registry["sitePages + pageHead"]
|
||||
Registry --> Sitemap["sitemap.xml at build"]
|
||||
|
||||
classDef layout fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
|
||||
classDef ui fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
|
||||
classDef data fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
|
||||
class Root,Shell,Main layout;
|
||||
class Skip,Nav,Foot,Top,Pages,Status ui;
|
||||
class Head,Registry,Sitemap data;
|
||||
```
|
||||
|
||||
Text alternative: the root route renders the shell and site-wide head data; the shell holds the skip link, navigation, main content, footer and back-to-top button; pages take their head data from the page registry, which also generates the sitemap.
|
||||
|
||||
## Files
|
||||
|
||||
### Created
|
||||
| Area | Files | Covers |
|
||||
|---|---|---|
|
||||
| Config | `vite.config.ts` (replaces `.js`), `config/securityHeaders.ts`, `config/sitemapPlugin.ts`, `eslint.config.js`, `lighthouserc.cjs` + `.d.cts` | TD-03…07, NFR-SEC-01…03, BR-SEO-06 |
|
||||
| Theme | `recipes/container.ts`, `link.ts`, `skipNavLink.ts`, `iconControl.ts` | BR-THEME-02…07 |
|
||||
| Content | `content/siteContent.ts` | FR-04, BR-EMAIL-01 |
|
||||
| Logic | `lib/slidesToLoad.ts`, `lib/backToTopThreshold.ts`, `visibleSocials.ts`, `emailAddress.ts`, `copyrightLine.ts`, `navigation.ts`, `sitePages.ts`, `sitemap.ts` | BR-TOP-01, BR-SOC-*, BR-EMAIL-*, BR-FOOT-02, BR-NAV-*, BR-SEO-* |
|
||||
| Components | `RouterLink`, `PageIntro/`, `StatusPage/` (`StatusPage`, `NotFound`, `ErrorPage`), `Footer/` (`Footer`, `FooterColumn`, `FooterLink`), `BackToTop/` | FR-01, FR-05…FR-10 |
|
||||
| Hooks | `hooks/useRouteFocus.ts` | BR-A11Y-01 |
|
||||
| Routes | `portfolio.tsx`, `soorten-fotoshoots.tsx`, `contact.tsx`, `privacyverklaring.tsx` | FR-01 |
|
||||
| Static | `public/robots.txt`, `public/og-image.jpg` (1200×630 crop of `hero-1.jpg`), `public/logo.png` | BR-SEO-04/05/08 |
|
||||
| Tests | 17 test files, incl. `src/test/` (setup, axe matcher, arbitraries, `renderWithProviders`) and `src/app.test.tsx` (integration) | NFR-M-01, NFR-A-02 |
|
||||
|
||||
### Modified
|
||||
- `theme.ts`: removed `250vh`; added focus ring, `content`/`pageTop`/z-index tokens, `pageTitle`, recipe registration.
|
||||
- `seo.ts`: `pageHead(path)` from the registry, canonical, Open Graph image, `siteHead`, JSON-LD.
|
||||
- `main.tsx`: `next-themes` removed, `scrollRestoration`, `defaultErrorComponent`.
|
||||
- `routes/__root.tsx`, `index.tsx`, `over-mij.tsx`.
|
||||
- `AppShell`, `NavigationBar` (logo link, `mainNav`, 44px menu button, z-index tokens), `MobileNav`, `NavLink`, `LinkButton` (onto `RouterLink`).
|
||||
- `Hero`: socials prop; first only the active photo, after it is painted also the next and previous (BR-HERO-01). `HeroArrows` and `HeroSocials` use `iconControl`.
|
||||
- `index.html`: fallback head with `og:image`, canonical, `twitter:card`.
|
||||
- `package.json`: scripts, dependencies, `postinstall` typegen. `pnpm-workspace.yaml`: `source-map-js` override.
|
||||
- `tsconfig.json`, `.gitignore`, `.prettierignore`.
|
||||
- Formatting only: Prettier over all of `web/`, which also touched existing files such as `useHeroSlider.ts` and line endings.
|
||||
|
||||
### Moved / deleted
|
||||
- Moved: `components/Hero/{heroContent,socialPlatforms,types}.ts` → `content/`.
|
||||
- Deleted: `components/Footer.tsx`, `NavigationBar/navItems.ts`, `assets/hero.png`, `assets/typescript.svg`, `assets/vite.svg`.
|
||||
|
||||
## Deviations From the Plan
|
||||
|
||||
| Planned | Done instead | Why |
|
||||
|---|---|---|
|
||||
| `vitest-axe` | Own `toHaveNoViolations` on `axe-core` (TD-02 fallback) | `vitest-axe` 0.1.0 types target the old Vitest `Vi` namespace |
|
||||
| ESLint 10 | ESLint 9 | `eslint-plugin-jsx-a11y` supports up to ESLint 9 |
|
||||
| — | `inert` on the hidden to-top button | Makes BR-TOP-03 hold without CSS and testable in jsdom |
|
||||
| — | Hero loads the active slide first, then only its neighbours | Stacked slides defeat `loading="lazy"`; mobile LCP 19.7s → 4.3s, home download 2.6 MB → 1.2 MB |
|
||||
| Footer brand column: logo above text, left-aligned | Mobile centred and stacked; tablet/desktop logo 110px beside the text; tagline split into two lines in the content | User choice after reviewing renders at 390/820/1440px |
|
||||
| Home mobile Performance ≥ 0.9 | ≥ 0.8 for now (`lighthouserc.cjs`); desktop stays 0.9 (`lighthouserc.desktop.cjs`) | User choice; responsive images come with the API/CMS |
|
||||
| `audit:deps` on all packages | `audit:deps` on production packages; `audit:dev` reports dev tools without blocking | User choice; dev tools never ship |
|
||||
| — | `.ts` extensions in the config import chain | Vite 8 warns these become required for its native config loader |
|
||||
| — | `postinstall: chakra typegen` | Typegen output lives in `node_modules` and was lost on reinstall |
|
||||
|
||||
## Scripts
|
||||
|
||||
| Command | Does |
|
||||
|---|---|
|
||||
| `pnpm test` / `pnpm test:watch` | Vitest with coverage (100% threshold on pure functions) |
|
||||
| `pnpm lint`, `pnpm format:check` | ESLint, Prettier |
|
||||
| `pnpm build` | Type check + Vite build, including `sitemap.xml` |
|
||||
| `pnpm audit:deps` | `pnpm audit --prod --audit-level high` (blocks) |
|
||||
| `pnpm audit:dev` | `pnpm audit`, report only |
|
||||
| `pnpm lighthouse` | Lighthouse CI, mobile (`lighthouserc.cjs`) then desktop (`lighthouserc.desktop.cjs`); needs local Chrome |
|
||||
| `pnpm check` | All of the above in order |
|
||||
|
||||
## LAYOUT.md
|
||||
No change. The shell blocks (Header / Content / Footer) are unchanged. Skip link and back-to-top are not page sections.
|
||||
+175
@@ -0,0 +1,175 @@
|
||||
# Business Logic Model — frontend-shell
|
||||
|
||||
The shell has four flows: content provisioning, page navigation, not-found/error rendering and the back-to-top interaction. Rules are referenced by ID from [business-rules.md](business-rules.md).
|
||||
|
||||
## 1. Content provisioning
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Site["content/siteContent"] --> Shell["AppShell"]
|
||||
Hero_c["content/heroContent"] --> Home["Home route"]
|
||||
Site --> Home
|
||||
Shell -->|"content prop"| Footer["Footer"]
|
||||
Home -->|"content + socials props"| Hero["Hero"]
|
||||
Footer --> VS1["visibleSocials"]
|
||||
Footer --> EA["emailAddress"]
|
||||
Hero --> VS2["visibleSocials"]
|
||||
|
||||
classDef data fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef provider fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
|
||||
classDef ui fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
|
||||
classDef fn fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000;
|
||||
|
||||
class Site,Hero_c data;
|
||||
class Shell,Home provider;
|
||||
class Footer,Hero ui;
|
||||
class VS1,VS2,EA fn;
|
||||
```
|
||||
|
||||
Text alternative: static content modules are imported only by AppShell and the home route, which pass them as props to Footer and Hero; both use the pure helpers to decide what to show.
|
||||
|
||||
- Components never import content (AD D3). Later the two import points become route loaders or API calls.
|
||||
- The e-mail address is joined in `Footer` at render (BR-EMAIL-01).
|
||||
|
||||
## 2. Page navigation and scroll position
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(246,224,94,0.4) Visitor
|
||||
participant V as Visitor
|
||||
end
|
||||
box rgba(99,179,237,0.4) App
|
||||
participant R as Router
|
||||
participant S as AppShell
|
||||
participant P as Page
|
||||
end
|
||||
V->>R: Click menu link
|
||||
R->>S: Render matched route in main
|
||||
S->>P: Render page with its head
|
||||
R-->>V: Scroll to top of new page
|
||||
V->>R: Browser back
|
||||
R-->>V: Restore previous scroll position
|
||||
```
|
||||
|
||||
Text alternative: a menu click renders the new page inside the shell and starts at the top; browser back restores the earlier scroll position (FR-08, router scroll restoration).
|
||||
|
||||
## 3. Not-found and error rendering
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Url["URL requested"] --> Match{"Route matches?"}
|
||||
Match -->|"no"| NF["NotFound in main, shell stays"]
|
||||
NF --> NFHead["Own title + noindex"]
|
||||
Match -->|"yes"| Render{"Error while rendering?"}
|
||||
Render -->|"no"| Page["Page in main"]
|
||||
Render -->|"in a page"| ErrIn["ErrorPage in main, shell stays"]
|
||||
Render -->|"in the shell"| ErrOut["ErrorPage without shell"]
|
||||
ErrIn --> Log["console.error once"]
|
||||
ErrOut --> Log
|
||||
ErrIn --> Retry{"Opnieuw proberen?"}
|
||||
Retry -->|"yes"| Reset["Reset boundary + invalidate router"]
|
||||
Reset --> Render
|
||||
Retry -->|"Terug naar home"| HomeR["Navigate to /"]
|
||||
|
||||
classDef decision fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef fail fill:#F44336,stroke:#b71c1c,stroke-width:1px,color:#000;
|
||||
classDef action fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
|
||||
class Match,Render,Retry decision;
|
||||
class Page,HomeR ok;
|
||||
class NF,ErrIn,ErrOut fail;
|
||||
class Url,NFHead,Log,Reset action;
|
||||
```
|
||||
|
||||
Text alternative: an unknown URL shows NotFound inside the shell; a page error shows ErrorPage inside the shell and a shell error shows it without the shell; errors are logged once, and the visitor can retry (re-render) or go home.
|
||||
|
||||
## 4. Back-to-top interaction
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(246,224,94,0.4) Visitor
|
||||
participant V as Visitor
|
||||
end
|
||||
box rgba(154,230,180,0.4) Shell
|
||||
participant H as useScrolledPast
|
||||
participant B as BackToTop
|
||||
participant M as main
|
||||
end
|
||||
V->>H: Scroll down
|
||||
H->>B: scrollY above threshold so visible
|
||||
V->>B: Click or Enter
|
||||
B->>V: Scroll to top, smooth or instant
|
||||
B->>M: Move focus with preventScroll
|
||||
H->>B: scrollY below threshold so hidden
|
||||
```
|
||||
|
||||
Text alternative: scrolling past the threshold makes the button visible; activating it scrolls to the top (instant under reduced motion), moves focus to main and the button hides again (BR-TOP-02, -05, -06).
|
||||
|
||||
## 5. Focus on page change (BR-A11Y-01)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(246,224,94,0.4) Visitor
|
||||
participant V as Visitor
|
||||
end
|
||||
box rgba(154,230,180,0.4) App
|
||||
participant R as Router
|
||||
participant F as useRouteFocus
|
||||
participant M as main
|
||||
end
|
||||
V->>R: Follow a link or use back and forward
|
||||
R->>R: Render new page and restore scroll
|
||||
R->>F: Resolved with a new pathname
|
||||
alt First load
|
||||
F->>F: Do nothing
|
||||
else Pathname changed
|
||||
F->>M: Focus with preventScroll
|
||||
end
|
||||
M-->>V: Screen reader reads from start of content
|
||||
```
|
||||
|
||||
Text alternative: after the router has rendered a page with a new pathname (not on first load), focus moves to main without scrolling, so a screen reader starts reading the new content.
|
||||
|
||||
## 6. Build-time SEO files (BR-SEO-06 to -08)
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Pages["sitePages registry"] --> Plugin["Vite sitemap plugin"]
|
||||
Url["siteUrl"] --> Plugin
|
||||
Plugin -->|"indexed pages only"| Xml["dist/sitemap.xml"]
|
||||
Robots["public/robots.txt"] --> Dist["dist/robots.txt"]
|
||||
Pages --> Test{"Test: registry equals route tree?"}
|
||||
Tree["Generated route tree"] --> Test
|
||||
Test -->|"no"| Fail["Test fails"]
|
||||
|
||||
classDef code fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef out fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef check fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef fail fill:#F44336,stroke:#b71c1c,stroke-width:1px,color:#000;
|
||||
|
||||
class Pages,Url,Tree,Robots code;
|
||||
class Plugin build;
|
||||
class Xml,Dist out;
|
||||
class Test check;
|
||||
class Fail fail;
|
||||
```
|
||||
|
||||
Text alternative: during the build a small Vite plugin turns the indexed entries of the page registry into sitemap.xml and robots.txt is copied as a static file; a test fails when the registry and the route tree list different pages.
|
||||
|
||||
**Effort and reliability of the generated sitemap (CH Q5)**:
|
||||
- The plugin is about 30 lines. The XML is built by the pure, property-tested function `sitemapXml`.
|
||||
- It needs no route crawling and no extra dependency. It reads the same `sitePages` module the route heads use, so a page can never be indexed in the sitemap and `noindex` in its head at the same time.
|
||||
- The only manual step is adding a new page to `sitePages`. BR-SEO-07 makes the tests fail when that is forgotten.
|
||||
|
||||
## Recommendations Outside This Feature (CQ4 = A)
|
||||
|
||||
Recorded so they come back with the Contact page and the .NET API:
|
||||
|
||||
1. **Contact form** as the main contact channel (technique 3). The address then appears nowhere on the site. Needs the back-end: server-side sending, a honeypot field and rate limiting, and possibly a CAPTCHA.
|
||||
2. **Dedicated address + spam filter** (technique 4). Already partly in place: `info@andreaslop.nl` is used only for the website. Remaining step: a strict spam filter on that mailbox.
|
||||
3. **CMS content**: the e-mail address keeps the `{ user, domain }` shape in the API (BR-EMAIL-01).
|
||||
4. **Old static site**: as long as it is online, it exposes the address literally in its HTML. Replacing it with this site removes that source.
|
||||
5. **Prerendering** (CH Q1 = A): generate static HTML per route at build time once the real pages exist, so link previews (WhatsApp, Facebook, LinkedIn) show the right title and image per page. BR-SEO-11 keeps this possible without rework. Belongs with hosting/Operations.
|
||||
6. **Responsive images**: serve smaller variants of the hero and portfolio photos per screen width (`srcset`). Comes with the portfolio feature, where most photos are.
|
||||
+182
@@ -0,0 +1,182 @@
|
||||
# Business Rules — frontend-shell
|
||||
|
||||
Rule IDs are referenced by the code generation plan and the tests. "Q" = [frontend-shell-fd-questions.md](../../plans/frontend-shell-fd-questions.md), "CQ" = [frontend-shell-fd-clarification-questions.md](../../plans/frontend-shell-fd-clarification-questions.md).
|
||||
|
||||
## Back-to-top button
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-TOP-01 | Threshold = `backToTopThreshold(viewportHeight)` = `0.6 × max(0, viewportHeight)`. Non-finite input counts as 0. | FR-06 |
|
||||
| BR-TOP-02 | Visible when `scrollY > threshold` (strictly greater), otherwise hidden. Evaluated on mount and on every (passive) scroll event via `useScrolledPast`. | FR-06 |
|
||||
| BR-TOP-03 | Hidden means `visibility: hidden`: not focusable, not in the accessibility tree, not clickable. | FR-06 |
|
||||
| BR-TOP-04 | Show/hide animation: fade + 8px upward slide with the `interaction` duration and `smooth` easing. Under `prefers-reduced-motion: reduce`: instant, no transition. | Q3 = A |
|
||||
| BR-TOP-05 | Click: scroll to the top, `smooth`, or `instant` under reduced motion. | FR-06 |
|
||||
| BR-TOP-06 | After the click, focus moves to `main#main` with `preventScroll`, so the smooth scroll is not interrupted. `main` shows no focus ring for programmatic focus. | Q2 = A |
|
||||
| BR-TOP-07 | Appearance: `ink` background, white `up-outlined` icon, no border, square, 46×46px. Hover/focus-visible: background `accent.deep`. Focus-visible also shows a focus ring. | CQ1 = A, Q4 = A |
|
||||
| BR-TOP-08 | Position: fixed at the bottom right. The right offset is the design offset (`clamp(1rem, 3vw, 2rem)`), but on viewports wider than the `Container` max width it aligns with the container's right edge instead of the screen corner. | CQ2 = A |
|
||||
| BR-TOP-09 | Stacking: below the header and the mobile menu. | FR-06 |
|
||||
|
||||
## Hero slides
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-HERO-01 | Only the active slide loads first. Once it has loaded and been painted, `slidesToLoad(active, count)` decides which slides are mounted: the active one, the next and the previous, wrapping around (from the first slide the previous is the last). Slides further away load when the slider gets near them. | Code change Q3 = A |
|
||||
|
||||
## Social links
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-SOC-01 | `visibleSocials(socials)` keeps a link only when `href` parses as a URL with protocol `https:`. Empty, `http:`, `javascript:`, relative or unparseable values are dropped. | Q5 = A |
|
||||
| BR-SOC-02 | Order is preserved; no entries are added or changed. | — |
|
||||
| BR-SOC-03 | Hero and Footer both use `visibleSocials`; the Hero shows icons, the Footer shows platform names. | FR-04, AD D11 |
|
||||
| BR-SOC-04 | External links open in a new tab with `rel="noopener noreferrer"`. | NFR-04 |
|
||||
|
||||
## E-mail address
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-EMAIL-01 | The address is stored as `{ user, domain }` and joined in the browser by `emailAddress(parts)` at render time. The complete address is never a literal in source, bundle or content data. | CQ3 = A |
|
||||
| BR-EMAIL-02 | `emailAddress` returns `null` when the parts are invalid: either part empty, containing whitespace or `@`, or a domain without a `.`. Otherwise it returns `user@domain`. | CQ3 = A |
|
||||
| BR-EMAIL-03 | The Footer shows the joined address as link text with `href="mailto:<address>"`, as in the design. | CQ3 = A |
|
||||
|
||||
## Footer
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-FOOT-01 | A column with nothing to show is omitted entirely (heading included): Socials when `visibleSocials` is empty, Contact when `emailAddress` is `null`. The grid closes up. | Q6 = A |
|
||||
| BR-FOOT-02 | Copyright: `copyrightLine(year)` = `"© {year} Andrea Slop Fotografie"`, with `year = new Date().getFullYear()` at render. | FR-05 |
|
||||
| BR-FOOT-03 | Footer menu links get `aria-current="page"` when active (router default), with **no** visual difference. | Q7 = B |
|
||||
| BR-FOOT-04 | Link colours: `ink.soft`, hover/focus `accent.deep` (`link` variant `subtle`). Column headings and bottom bar use `ink.soft`. | NFR-01 |
|
||||
|
||||
## Navigation
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-NAV-01 | `mainNav` and `footerNav` each contain no duplicate `to`. | — |
|
||||
| BR-NAV-02 | `mainNav` starts with Home `/` and does not contain `/privacyverklaring`. | FR-02 |
|
||||
| BR-NAV-03 | Every `to` in both menus is a registered route (type-checked). | AD D4 |
|
||||
|
||||
## Not-found page
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-404-01 | Any URL without a matching route renders `NotFound` inside the shell (root `notFoundComponent`). | FR-09 |
|
||||
| BR-404-02 | `NotFound` renders its own `<title>` "Pagina niet gevonden \| Andrea Slop Fotografie" and `<meta name="robots" content="noindex">`. React 19 hoists both into `<head>` and removes them on navigation. Only the root route matches, and it sets no title, so there is no duplicate `<title>`. | Q1 = A |
|
||||
|
||||
## Error page
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-ERR-01 | Render and route errors render `ErrorPage`: inside the shell for page errors, without the shell for errors in the shell itself. | FR-10, AD services |
|
||||
| BR-ERR-02 | `ErrorPage` never renders the error message, stack or any error property. | SECURITY-09/15 |
|
||||
| BR-ERR-03 | `ErrorPage` logs the error once with `console.error(error)`, in every environment. | Q11 = A |
|
||||
| BR-ERR-04 | Actions: "Opnieuw proberen" (resets the error boundary and invalidates the router, so the route loads again) and "Terug naar home". | Q10 = B |
|
||||
| BR-ERR-05 | `ErrorPage` sets `<title>` "Er ging iets mis \| Andrea Slop Fotografie" and `robots: noindex`, the same way as BR-404-02. | Derived from BR-404-02 |
|
||||
|
||||
## SEO (change request)
|
||||
|
||||
"CH" = [frontend-shell-fd-change-questions.md](../../plans/frontend-shell-fd-change-questions.md).
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-SEO-01 | Every route takes its title, description and `indexed` flag from the `sitePages` registry via `pageHead(path)`. Title = `"{title} \| Andrea Slop Fotografie"`. Home keeps its full keyword title. | FR-01, CH |
|
||||
| BR-SEO-02 | Every page sets `<link rel="canonical">` and `og:url` to `canonicalUrl(path)` = `siteUrl` + path. No trailing slash (the root is `siteUrl/`), no query, no hash. | CH Q2 = A |
|
||||
| BR-SEO-03 | Pages with `indexed: false`, the 404 page and the error page set `robots: noindex`. Indexed pages set no robots tag. | CH |
|
||||
| BR-SEO-04 | Every page has `og:image` (absolute URL), `og:image:alt`, `og:image:width`/`height` and `twitter:card = summary_large_image`. The default is `defaultOgImage`; a page may override it. The fallback head in `index.html` has the same tags for the home page. | CH Q3 = A |
|
||||
| BR-SEO-05 | The root head renders one `ProfessionalService` JSON-LD block. It sits where `HeadContent` renders (in the body of this SPA); Google reads JSON-LD anywhere in the page. `jsonLdScript` serialises it with `<`, `>` and `&` escaped as `<`, `>`, `&`, so content can never close the `<script>` element. | CH Q4 = A, security |
|
||||
| BR-SEO-06 | At build time a small Vite plugin generates `sitemap.xml` from `sitePages`: one `<url><loc>` per indexed page, as an absolute, XML-escaped URL. No `lastmod`, because Google ignores unreliable values. | CH Q5 = B |
|
||||
| BR-SEO-07 | A test fails when a route has no `sitePages` entry, or an entry has no route. | CH Q5 (check from A) |
|
||||
| BR-SEO-08 | `public/robots.txt` allows everything and points to `https://andreaslop.nl/sitemap.xml`. | CH Q5 |
|
||||
| BR-SEO-09 | Exactly one `h1` per page, and no skipped heading levels. Footer column headings are `h2` (styled as `eyebrow`), because they are top-level sections of the page. | CH |
|
||||
| BR-SEO-10 | Internal navigation uses real `<a href>` links (router `Link`). Images: <ul><li>a meaningful `alt`, or `alt=""` when decorative</li><li>`width`/`height` against layout shift</li><li>`loading="lazy"` below the fold</li><li>the first hero slide loads eagerly with `fetchpriority="high"`</li></ul> | CH |
|
||||
| BR-SEO-11 | No `window` or `document` access during render, only in effects and handlers. All head data goes through route `head`. This keeps prerendering possible later without rework. | CH Q1 = A |
|
||||
|
||||
## Screen readers and keyboard (change request)
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-A11Y-01 | After every client-side page change, focus moves to `main#main` with `preventScroll`. A page change means the pathname changes; the first load does not count. The router's scroll restoration keeps handling the scroll position. Same mechanism as the skip link and BR-TOP-06. | CH Q6 = A |
|
||||
| BR-A11Y-02 | Landmarks: <ul><li>one `header`</li><li>`nav aria-label="Hoofdmenu"` and `nav aria-label="Mobiel menu"`</li><li>one `main#main`</li><li>one `footer` with `nav aria-label="Footermenu"`</li></ul> | NFR-01 |
|
||||
| BR-A11Y-03 | Links that open a new tab announce it. Text links get the visually hidden text " (opent in nieuw tabblad)". Icon-only links get it in their `aria-label`, e.g. "Instagram (opent in nieuw tabblad)". | CH |
|
||||
| BR-A11Y-04 | Icons are `aria-hidden`; icon-only controls have an `aria-label`. | NFR-01 |
|
||||
| BR-A11Y-05 | The whole site has one focus style, from the theme (BR-THEME-02). Components do not define their own outline; they may only switch the ring colour on photos. | CH |
|
||||
| BR-A11Y-06 | `main` and other programmatic focus targets (`tabIndex=-1`) show no focus ring. | BR-TOP-06 |
|
||||
| BR-A11Y-07 | All animations and smooth scrolling are off under `prefers-reduced-motion: reduce`. | NFR-01 |
|
||||
|
||||
## Responsive (change request)
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-RWD-01 | Mobile-first, with Chakra's default breakpoints: `sm` 480, `md` 768, `lg` 1024, `xl` 1280, `2xl` 1536. Per-component behaviour is in [frontend-components.md](frontend-components.md). | CH |
|
||||
| BR-RWD-02 | No horizontal scrolling from 320px wide up to 32:9 (WCAG 1.4.10 Reflow). | CH |
|
||||
| BR-RWD-03 | Text sizes are in `rem`. At 200% browser zoom no content is clipped or overlaps (WCAG 1.4.4). | CH |
|
||||
| BR-RWD-04 | Below `lg`, touch targets are at least 44×44px: menu items, footer links, to-top, hamburger and hero controls. Footer links reach this with vertical padding, not with bigger text. | CH |
|
||||
| BR-RWD-05 | Page content never exceeds the shared content width (BR-THEME-04). On ultrawide screens it is centred, and fixed elements align with it (BR-TOP-08). | CH, CQ2 |
|
||||
|
||||
## Reuse via Chakra and the theme (change request)
|
||||
|
||||
| ID | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-THEME-01 | A value that exists as a token is never hard-coded. That covers colours, spacing (`gutter`, `header`), durations, easings, letter spacing and z-index. | NFR-02 |
|
||||
| BR-THEME-02 | Focus ring: one global `:focus-visible` style in `globalCss` (2px outline, 2px offset). Its colour comes from the semantic token `focusRing` (`accent.deep`). On photos, the `iconControl` recipe switches it to white. | CH |
|
||||
| BR-THEME-03 | A new text style `pageTitle` is used for every page `h1` (PageIntro, StatusPage). `eyebrow` stays the one label style. | NFR-02 |
|
||||
| BR-THEME-04 | A new size token `content` holds the `Container` max width. `Container` and BackToTop's alignment both use it, so there is only one width. | CQ2, NFR-02 |
|
||||
| BR-THEME-05 | New z-index tokens `header`, `mobileNav`, `menuToggle` and `backToTop` replace the current `docked`, `calc(docked - 1)` and `modal` values. They make the stacking order (BR-TOP-09) explicit in one place. | CH |
|
||||
| BR-THEME-06 | A new spacing token `pageTop` holds the header height plus standard spacing. PageIntro and StatusPage use it instead of each computing their own offset. | NFR-02 |
|
||||
| BR-THEME-07 | Shared component styles are recipes (`linkButton`, `link` variant `subtle`, `iconControl`, `skipNavLink`), not repeated style props. A one-off style stays local; it gets no recipe. | NFR-02 |
|
||||
|
||||
## Decision Logic
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start["Render footer"] --> Soc{"visibleSocials non-empty?"}
|
||||
Soc -->|"yes"| ShowSoc["Show Socials column"]
|
||||
Soc -->|"no"| HideSoc["Omit Socials column"]
|
||||
ShowSoc --> Mail{"emailAddress valid?"}
|
||||
HideSoc --> Mail
|
||||
Mail -->|"yes"| ShowMail["Show Contact column with mailto link"]
|
||||
Mail -->|"no"| HideMail["Omit Contact column"]
|
||||
Scroll["Scroll event"] --> Past{"scrollY greater than 0.6 x viewport?"}
|
||||
Past -->|"yes"| Visible["To-top visible"]
|
||||
Past -->|"no"| Hidden["To-top hidden, not focusable"]
|
||||
|
||||
classDef decision fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef show fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef hide fill:#e9d5ff,stroke:#6b21a8,stroke-width:1px,color:#000;
|
||||
classDef start fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
|
||||
class Soc,Mail,Past decision;
|
||||
class ShowSoc,ShowMail,Visible show;
|
||||
class HideSoc,HideMail,Hidden hide;
|
||||
class Start,Scroll start;
|
||||
```
|
||||
|
||||
Text alternative: the footer shows the Socials column only when at least one valid social link remains and the Contact column only when the e-mail parts are valid; the to-top button is visible only when scrolled past 60% of the viewport height.
|
||||
|
||||
## Testable Properties (PBT-01)
|
||||
|
||||
| Function / component | Property | Category |
|
||||
|---|---|---|
|
||||
| `backToTopThreshold` | For any finite `h ≥ 0`: `0 ≤ t(h) ≤ h` | Invariant |
|
||||
| `backToTopThreshold` | For finite `h1 ≤ h2`: `t(h1) ≤ t(h2)` (monotonic; non-finite input is 0 by BR-TOP-01) | Invariant |
|
||||
| `backToTopThreshold` | Equals the model `0.6 × max(0, h)`; non-finite or negative input gives 0 | Oracle |
|
||||
| `visibleSocials` | `visibleSocials(visibleSocials(x)) = visibleSocials(x)` | Idempotence |
|
||||
| `visibleSocials` | Output is an order-preserving subsequence of the input | Invariant |
|
||||
| `visibleSocials` | Every output `href` has protocol `https:`; every input with an `https:` URL is kept | Easy verification / Oracle |
|
||||
| `emailAddress` | For valid parts: splitting the result at `@` returns the original `{ user, domain }` | Round-trip |
|
||||
| `emailAddress` | Result is `null` or contains exactly one `@` and no whitespace | Invariant |
|
||||
| `copyrightLine` | For any integer year: extracting the number from the line returns the year | Round-trip |
|
||||
| `copyrightLine` | Always starts with `©` and ends with "Andrea Slop Fotografie" | Invariant |
|
||||
| `canonicalUrl` | Idempotent: canonicalising the path of a canonical URL yields the same URL. Always starts with `siteUrl`; never ends with `/` except the root; never contains `?` or `#` | Idempotence / Invariant |
|
||||
| `sitemapXml` | For any page list, the set of `<loc>` values equals the set of canonical URLs of the indexed pages, each exactly once | Oracle / Invariant |
|
||||
| `sitemapXml` | Output is well-formed XML even for paths with `&`, `<`, `'` or `"`; parsing it back yields the original URLs | Round-trip |
|
||||
| `jsonLdScript` | `JSON.parse(jsonLdScript(x))` deep-equals `x` for any JSON value with arbitrary strings | Round-trip |
|
||||
| `jsonLdScript` | Output never contains `<`, so `</script` cannot occur | Invariant |
|
||||
| `slidesToLoad` | Unique valid indexes, `min(count, 3)` of them, the active one first | Invariant |
|
||||
| `slidesToLoad` | Every returned slide is at most one step away from the active one, wrapping around | Oracle |
|
||||
| `sitePages` vs route tree | Same set of paths (BR-SEO-07; static data, example-based) | — |
|
||||
| `mainNav`, `footerNav` | BR-NAV-01/02 (static data; example-based tests, no generator needed) | — |
|
||||
|
||||
**No PBT properties identified** (example-based tests only):
|
||||
- `AppShell`, `NavigationBar`, `PageIntro`, `StatusPage`, `NotFound`, `ErrorPage`, `Footer`, `BackToTop` components: rendering and interaction with fixed inputs. Their logic lives in the pure functions above.
|
||||
- Theme recipes: static style data.
|
||||
+163
@@ -0,0 +1,163 @@
|
||||
# Domain Entities — frontend-shell
|
||||
|
||||
The shell has no back-end data. Its "domain" is the site-wide content that will later come from the CMS API, plus the menus, which are code. Every content type is plain data (strings, objects, arrays), so it can later be replaced 1-on-1 by an API response.
|
||||
|
||||
Decisions: [frontend-shell-fd-questions.md](../../plans/frontend-shell-fd-questions.md), [frontend-shell-fd-clarification-questions.md](../../plans/frontend-shell-fd-clarification-questions.md).
|
||||
|
||||
## Entity Relationships
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
SiteContent["SiteContent"]
|
||||
SocialLink["SocialLink"]
|
||||
EmailAddress["EmailAddress"]
|
||||
SocialPlatform["SocialPlatform registry"]
|
||||
HeroContent["HeroContent"]
|
||||
HeroSlide["HeroSlide"]
|
||||
HeroCta["HeroCta"]
|
||||
NavItem["NavItem"]
|
||||
Routes["Registered routes"]
|
||||
|
||||
SiteContent -->|"has 0..n"| SocialLink
|
||||
SiteContent -->|"has 1"| EmailAddress
|
||||
SocialLink -->|"refers to"| SocialPlatform
|
||||
HeroContent -->|"has 1..n"| HeroSlide
|
||||
HeroContent -->|"has 1"| HeroCta
|
||||
HeroCta -->|"points to"| Routes
|
||||
NavItem -->|"points to"| Routes
|
||||
|
||||
classDef content fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
|
||||
classDef value fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
|
||||
classDef code fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
|
||||
class SiteContent,HeroContent content;
|
||||
class SocialLink,EmailAddress,HeroSlide,HeroCta value;
|
||||
class SocialPlatform,NavItem,Routes code;
|
||||
```
|
||||
|
||||
Text alternative: SiteContent holds social links (each referring to a platform in the registry) and one e-mail address; HeroContent holds slides and a CTA pointing to a route; nav items point to routes (blue = CMS content, orange = value objects, green = code).
|
||||
|
||||
## Content (later from the CMS) — `content/types.ts`
|
||||
|
||||
### SiteContent
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `footerIntro` | `string` | yes | Intro text under the footer logo |
|
||||
| `socials` | `SocialLink[]` | yes (may be empty) | Social profiles; shown in Hero (icons) and Footer (names) |
|
||||
| `email` | `EmailAddress` | yes | Contact address, **stored in parts** (anti-spam, clarification Q3 = A) |
|
||||
|
||||
Static value until the API exists:
|
||||
- `footerIntro`: "Lifestyle fotograaf uit Huizen.
|
||||
Ik leg jouw mooiste momenten vast." (each sentence on its own line; line breaks in the content are kept, so the CMS can use a plain text area)
|
||||
- `socials`: Facebook and Instagram (the current links from `heroContent.ts`)
|
||||
- `email`: `{ user: 'info', domain: 'andreaslop.nl' }`
|
||||
|
||||
### EmailAddress (new value object)
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `user` | `string` | yes | Part before the `@` |
|
||||
| `domain` | `string` | yes | Part after the `@` |
|
||||
|
||||
**Why parts**: the complete address then appears in neither the HTML nor the JavaScript bundle nor (later) the API response. It is joined only in the browser at render time (BR-EMAIL-01). This **refines FR-04 and the Application Design**, where `email` was a `string`.
|
||||
|
||||
### SocialLink (renamed from `HeroSocial`)
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `platform` | `SocialPlatform` | yes | Key into the platform registry |
|
||||
| `href` | `string` | yes | Profile URL; only shown when it is a valid `https://` URL (BR-SOC-01) |
|
||||
|
||||
### HeroContent, HeroSlide, HeroCta (moved from `Hero/types.ts`)
|
||||
Unchanged, except that `HeroContent.socials` is removed. The Hero receives `SiteContent.socials` as a separate prop.
|
||||
|
||||
| Entity | Fields |
|
||||
|---|---|
|
||||
| `HeroContent` | `title`, `tagline`, `cta: HeroCta`, `slides: HeroSlide[]` |
|
||||
| `HeroSlide` | `id`, `src`, `alt` |
|
||||
| `HeroCta` | `label`, `to` |
|
||||
|
||||
## Code (not content)
|
||||
|
||||
### SocialPlatform registry — `content/socialPlatforms.ts`
|
||||
A fixed set of supported platforms: `facebook` and `instagram`, each with a display `name` and bundled `icon`. The CMS supplies only links. A platform outside the registry is a type error.
|
||||
|
||||
### NavItem — `navigation.ts`
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `to` | registered route path | A typo is a type error |
|
||||
| `label` | `string` | Menu text |
|
||||
|
||||
| Menu | Items, in order |
|
||||
|---|---|
|
||||
| `mainNav` | Home `/`, Over mij `/over-mij`, Portfolio `/portfolio`, Soorten fotoshoots `/soorten-fotoshoots`, Contact `/contact` |
|
||||
| `footerNav` | Portfolio, Soorten fotoshoots, Contact, Privacyverklaring `/privacyverklaring` |
|
||||
|
||||
### Page copy (code until the real pages exist)
|
||||
Placeholder, 404 and error page texts are fixed strings in their components. See [frontend-components.md](frontend-components.md).
|
||||
|
||||
## SEO entities (change request)
|
||||
|
||||
Decisions: [frontend-shell-fd-change-questions.md](../../plans/frontend-shell-fd-change-questions.md) ("CH").
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
SiteConfig["siteUrl and site defaults"]
|
||||
SitePage["SitePage registry"]
|
||||
Route["Route file"]
|
||||
Head["Page head"]
|
||||
Sitemap["sitemap.xml"]
|
||||
JsonLd["ProfessionalService JSON-LD"]
|
||||
Socials["SiteContent.socials"]
|
||||
|
||||
Route -->|"looks up its"| SitePage
|
||||
SitePage -->|"feeds"| Head
|
||||
SiteConfig -->|"base URL for"| Head
|
||||
SitePage -->|"indexed pages generate"| Sitemap
|
||||
SiteConfig -->|"base URL for"| Sitemap
|
||||
SiteConfig -->|"name, url, logo"| JsonLd
|
||||
Socials -->|"sameAs"| JsonLd
|
||||
|
||||
classDef code fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef output fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef content fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
|
||||
|
||||
class SiteConfig,SitePage,Route code;
|
||||
class Head,Sitemap,JsonLd output;
|
||||
class Socials content;
|
||||
```
|
||||
|
||||
Text alternative: the page registry is the single source for each route's head and for the generated sitemap; the site configuration supplies the base URL, and the JSON-LD block combines site data with the social links (green = code, blue = generated output, dark blue = content).
|
||||
|
||||
### Site configuration — `seo.ts`
|
||||
| Constant | Value | Use |
|
||||
|---|---|---|
|
||||
| `siteUrl` | `https://andreaslop.nl` (no `www`, no trailing slash) | Canonical URLs, `og:url`, `og:image`, sitemap, JSON-LD (CH Q2 = A) |
|
||||
| `siteName` | `Andrea Slop Fotografie` | `og:site_name`, title suffix, JSON-LD |
|
||||
| `defaultOgImage` | `/og-image.jpg`, 1200×630, a crop of a hero photo, with alt text | Site-wide preview image; a page may override it (CH Q3 = A) |
|
||||
|
||||
### SitePage registry — `sitePages.ts` (new)
|
||||
The single list of pages. Route heads and the sitemap both read it, so they cannot drift apart.
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `path` | registered route path | Type-checked against the route tree |
|
||||
| `title` | `string` | Page title without the site suffix (≤ ~60 chars including suffix) |
|
||||
| `description` | `string` | Meta description (≤ ~155 chars) |
|
||||
| `indexed` | `boolean` | `true`: in the sitemap, no robots tag. `false`: `noindex`, not in the sitemap |
|
||||
| `ogImage?` | `string` | Optional page-specific preview image |
|
||||
|
||||
Initial values:
|
||||
- `/` is indexed.
|
||||
- `/over-mij`, `/portfolio`, `/soorten-fotoshoots`, `/contact` and `/privacyverklaring` are **not** indexed while they are placeholders.
|
||||
- Putting a real page live means flipping `indexed` to `true`.
|
||||
|
||||
The 404 and error pages are not in the registry. They are not routes, and always set `noindex` themselves.
|
||||
|
||||
### Structured data — ProfessionalService (CH Q4 = A)
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
| `@type` | `ProfessionalService` |
|
||||
| `name`, `url`, `logo`, `image` | `siteName`, `siteUrl`, absolute logo URL, `defaultOgImage` |
|
||||
| `address` | `PostalAddress` with `addressLocality` Huizen, `addressCountry` NL |
|
||||
| `areaServed` | `Place` "Huizen" |
|
||||
| `sameAs` | hrefs of `visibleSocials(siteContent.socials)` |
|
||||
| e-mail | **Deliberately absent** (BR-EMAIL-01) |
|
||||
+188
@@ -0,0 +1,188 @@
|
||||
# Frontend Components — frontend-shell
|
||||
|
||||
Paths relative to `web/src/`. Builds on [components.md](../../../inception/application-design/components.md); this file adds behaviour, state and final copy. Rule IDs refer to [business-rules.md](business-rules.md).
|
||||
|
||||
## Component Hierarchy
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
root["__root.tsx RootLayout"]
|
||||
head["HeadContent"]
|
||||
shell["AppShell"]
|
||||
skip["SkipNavLink"]
|
||||
nav["NavigationBar"]
|
||||
navlink["NavLink"]
|
||||
mobile["MobileNav"]
|
||||
main["SkipNavContent as main"]
|
||||
outlet["Outlet"]
|
||||
pages["Route pages"]
|
||||
intro["PageIntro"]
|
||||
hero["Hero"]
|
||||
notfound["NotFound"]
|
||||
errorp["ErrorPage"]
|
||||
status["StatusPage"]
|
||||
footer["Footer"]
|
||||
col["FooterColumn"]
|
||||
top["BackToTop"]
|
||||
rlink["RouterLink"]
|
||||
lbtn["LinkButton"]
|
||||
scrolled["useScrolledPast"]
|
||||
|
||||
root --> head
|
||||
root --> shell
|
||||
shell --> skip
|
||||
shell --> nav
|
||||
shell --> main
|
||||
shell --> footer
|
||||
shell --> top
|
||||
nav --> navlink
|
||||
nav --> mobile
|
||||
main --> outlet
|
||||
outlet --> pages
|
||||
outlet --> notfound
|
||||
outlet --> errorp
|
||||
pages --> intro
|
||||
pages --> hero
|
||||
notfound --> status
|
||||
errorp --> status
|
||||
status --> lbtn
|
||||
footer --> col
|
||||
navlink --> rlink
|
||||
mobile --> rlink
|
||||
lbtn --> rlink
|
||||
footer --> rlink
|
||||
nav --> scrolled
|
||||
top --> scrolled
|
||||
|
||||
classDef layout fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
|
||||
classDef ui fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
|
||||
classDef hook fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000;
|
||||
classDef chakra fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
|
||||
|
||||
class root,shell,main,outlet layout;
|
||||
class nav,navlink,mobile,pages,intro,hero,notfound,errorp,status,footer,col,top,lbtn ui;
|
||||
class rlink,scrolled hook;
|
||||
class head,skip chakra;
|
||||
```
|
||||
|
||||
Text alternative: the root layout renders HeadContent and AppShell; AppShell holds the skip link, NavigationBar, main (with the routed page, NotFound or ErrorPage), Footer and BackToTop; NotFound and ErrorPage share StatusPage; all router links go through RouterLink and both NavigationBar and BackToTop use useScrolledPast (green = layout, blue = UI, purple = shared primitive/hook, orange = built-in).
|
||||
|
||||
## Components
|
||||
|
||||
### AppShell
|
||||
- **Props / state**: none
|
||||
- **Renders**: `SkipNavLink` "Direct naar de inhoud" → `NavigationBar` → `SkipNavContent as="main" id="main"` with `<Outlet />` → `Footer content={siteContent}` → `BackToTop`
|
||||
- **Hook**: `useRouteFocus()` (new, `hooks/`) subscribes to the router's resolved event and moves focus to `main#main` when the pathname changes, skipping the first load (BR-A11Y-01)
|
||||
|
||||
### RootLayout (`__root.tsx`)
|
||||
- Root `head`: `siteHead` (site-wide Open Graph and `twitter:card` tags, default `og:image`) plus the JSON-LD script from `jsonLdScript(professionalService(siteContent))` (BR-SEO-04, -05)
|
||||
|
||||
### Route heads
|
||||
- Each route calls `pageHead('/portfolio')` etc. `pageHead` looks up the `sitePages` entry and returns title, description, canonical link, `og:url`, `og:title`, `og:description`, `og:image` and, for `indexed: false`, `robots: noindex` (BR-SEO-01 to -04)
|
||||
|
||||
### Footer (+ local FooterColumn)
|
||||
- **Props**: `content: SiteContent`. **State**: none.
|
||||
- **Derived**: `socials = visibleSocials(content.socials)`, `email = emailAddress(content.email)`, `year = new Date().getFullYear()`
|
||||
- **Top section** (`SimpleGrid`, 1 / 2 / 3 columns):
|
||||
- Brand: `logo-dark.png` (alt "Andrea Slop Fotografie") + `footerIntro` with its line breaks kept. Mobile: logo 150px and text centred, stacked. Tablet and desktop: logo 110px with the text beside it, vertically centred (footer review)
|
||||
- "Socials": text links with the platform name plus visually hidden " (opent in nieuw tabblad)"; omitted when empty (BR-FOOT-01, BR-A11Y-03)
|
||||
- "Contact": `mailto:` link with the address as text; omitted when `email` is `null`
|
||||
- Column headings are `h2` with `textStyle="eyebrow"` (BR-SEO-09); the logo has `width`/`height` and `loading="lazy"` (BR-SEO-10)
|
||||
- **Bottom bar**: `copyrightLine(year)` + `nav aria-label="Footermenu"` with `footerNav`. Stacked and centred on mobile.
|
||||
- **Links**: `Link variant="subtle"`; internal via `asChild` + `RouterLink` (`aria-current` without visual change, BR-FOOT-03)
|
||||
|
||||
### BackToTop
|
||||
- **Props**: none. **State**: `visible` from `useScrolledPast(threshold)`; `threshold` is a module-level function `() => backToTopThreshold(window.innerHeight)`.
|
||||
- **Renders**: `chakra.button` with `aria-label="Terug naar boven"` and the `up-outlined` icon (`aria-hidden`)
|
||||
- **Behaviour**: BR-TOP-01…09. Click handler:
|
||||
1. `reduced = matchMedia('(prefers-reduced-motion: reduce)').matches`
|
||||
2. `window.scrollTo({ top: 0, behavior: reduced ? 'instant' : 'smooth' })`
|
||||
3. `document.getElementById('main')?.focus({ preventScroll: true })`
|
||||
|
||||
### PageIntro
|
||||
- **Props**: `title`, `eyebrow?`, `children?`
|
||||
- **Renders**: `pt="pageTop"`, `Container`, eyebrow (`textStyle="eyebrow"`), one `h1` (`textStyle="pageTitle"`), children
|
||||
|
||||
### StatusPage
|
||||
- **Props**: `title`, `children` (message), `actions?: ReactNode`. Defaults to one `LinkButton to="/"` "Terug naar home".
|
||||
- **Refinement of the Application Design**: `action?: { label, to }` becomes `actions?: ReactNode`, because the error page needs a `button` next to a link (BR-ERR-04).
|
||||
- **Renders**: `pt="pageTop"`, centred `Container`, one `h1` (`textStyle="pageTitle"`), text, action row
|
||||
|
||||
### NotFound
|
||||
- Renders `<title>` + `<meta name="robots" content="noindex">` (BR-404-02) and `StatusPage`
|
||||
|
||||
### ErrorPage
|
||||
- **Props**: `ErrorComponentProps` (`error`, `reset`). `error` is used only for logging.
|
||||
- `useEffect(() => console.error(error), [error])` (BR-ERR-03)
|
||||
- Renders `<title>` + `noindex` (BR-ERR-05) and `StatusPage` with two actions:
|
||||
- "Opnieuw proberen": `chakra.button` with the `linkButton` recipe, variant `accent`. On click: `reset()` and `router.invalidate()`
|
||||
- "Terug naar home": `LinkButton variant="outline"`
|
||||
|
||||
### NavigationBar, NavLink, MobileNav
|
||||
- Menu from `mainNav`. Logo wrapped in `RouterLink to="/"` with `aria-label="Andrea Slop Fotografie, naar de homepage"`. Otherwise unchanged.
|
||||
|
||||
### Hero, HeroSocials, HeroArrows
|
||||
- `Hero` props `content: HeroContent` and `socials: SocialLink[]`. `HeroSocials` renders `visibleSocials(socials)` with `aria-label` "{name} (opent in nieuw tabblad)". Both icon controls use the `iconControl` recipe, which also turns the focus ring white on photos.
|
||||
- The first slide loads eagerly with `fetchpriority="high"`, the others lazily (BR-SEO-10).
|
||||
|
||||
## Responsive Behaviour (BR-RWD-01 to -05)
|
||||
|
||||
| Component | base (< 768) | md (768–1023) | lg (≥ 1024) | Ultrawide |
|
||||
|---|---|---|---|---|
|
||||
| NavigationBar | 66px, hamburger + mobile menu, always solid | same as base | 92px → 68px after scrolling, inline menu, transparent over the hero | content width centred |
|
||||
| Footer top | 1 column | 2 equal columns; the third wraps to a new row | 3 columns, `1.2fr 1fr 1fr` | content width centred |
|
||||
| Footer bottom bar | stacked, centred | one row: © left, menu right | same as md | content width centred |
|
||||
| PageIntro / StatusPage | `gutter` side margin, title size `pageTitle` base | larger `pageTitle` | largest `pageTitle` | content width centred |
|
||||
| BackToTop | 46px, design offset, 44px+ target | same | same | aligned to the content edge (BR-TOP-08) |
|
||||
| Hero | full-screen photo, controls 44px+ | same | same | photo fills the width, text in the content width |
|
||||
|
||||
Every column: no horizontal scroll from 320px; works at 200% zoom.
|
||||
|
||||
## Theme Usage (BR-THEME-01 to -07)
|
||||
|
||||
| Shared piece | Kind | Status | Used by |
|
||||
|---|---|---|---|
|
||||
| `paper`, `ink`, `ink.soft`, `line`, `accent.deep` | colour tokens | existing | all |
|
||||
| `focusRing` | semantic colour token + global `:focus-visible` | new | every focusable element |
|
||||
| `gutter`, `header` | spacing tokens | existing | NavigationBar, Footer, PageIntro, StatusPage |
|
||||
| `pageTop` | spacing token | new | PageIntro, StatusPage |
|
||||
| `content` | size token | new | `Container` recipe, BackToTop |
|
||||
| `header`, `mobileNav`, `menuToggle`, `backToTop` | z-index tokens | new | NavigationBar, MobileNav, BackToTop |
|
||||
| `interaction`, `smooth` | duration/easing | existing | all transitions |
|
||||
| `eyebrow` | text style | existing | footer headings, PageIntro eyebrow, buttons |
|
||||
| `pageTitle` | text style | new | PageIntro, StatusPage |
|
||||
| `linkButton` | recipe | existing | LinkButton, ErrorPage retry button |
|
||||
| `link` variant `subtle` | recipe variant | new | Footer |
|
||||
| `iconControl` | recipe | new | HeroArrows, HeroSocials |
|
||||
| `skipNavLink` | recipe override | new | SkipNavLink |
|
||||
| `RouterLink` | shared primitive | new | NavLink, MobileNav, LinkButton, logo, Footer |
|
||||
|
||||
## Copy
|
||||
|
||||
### Placeholder pages (Q8 = A)
|
||||
Every placeholder uses `PageIntro` with the line **"Deze pagina is nog in de maak. Kom snel terug!"**
|
||||
|
||||
| Route | Eyebrow | `h1` |
|
||||
|---|---|---|
|
||||
| `/over-mij` | Andrea Slop Fotografie | Over mij |
|
||||
| `/portfolio` | Werk | Portfolio |
|
||||
| `/soorten-fotoshoots` | Mogelijkheden | Soorten fotoshoots |
|
||||
| `/contact` | Neem contact op | Contact |
|
||||
| `/privacyverklaring` | Privacy | Privacyverklaring |
|
||||
|
||||
### Status pages
|
||||
| Page | `h1` | Text | Actions |
|
||||
|---|---|---|---|
|
||||
| 404 (Q9 = A) | Pagina niet gevonden | Deze pagina bestaat niet (meer). Misschien is de link verouderd of zit er een typfout in het adres. | Terug naar home |
|
||||
| Error (Q10 = B) | Er ging iets mis | Door een fout kan deze pagina nu niet worden getoond. Probeer het opnieuw of ga terug naar de homepage. | Opnieuw proberen, Terug naar home |
|
||||
|
||||
## User Interaction Flows
|
||||
- **Keyboard, first Tab**: skip link appears → Enter → focus in `main#main`
|
||||
- **Back to top**: scroll down → button appears → click/Enter → page scrolls up, focus in `main`, button hides
|
||||
- **Page change**: click a menu link → new page at the top, focus in `main`, screen reader reads the new content
|
||||
- **Unknown URL**: shell + 404 → "Terug naar home"
|
||||
- **Page error**: shell + error page → "Opnieuw proberen" re-renders the route, or "Terug naar home"
|
||||
|
||||
## Forms and API Integration
|
||||
- **Forms**: none in the shell. The contact form is a later feature (see business-logic-model.md, Recommendations).
|
||||
- **API**: none yet. `siteContent` and `heroContent` are static modules shaped like the future CMS responses.
|
||||
+107
@@ -0,0 +1,107 @@
|
||||
# NFR Requirements — frontend-shell
|
||||
|
||||
Refines requirements NFR-01…NFR-06 into measurable criteria. Decisions: [frontend-shell-nfr-requirements-plan.md](../../plans/frontend-shell-nfr-requirements-plan.md) ("Q"), [frontend-shell-nfr-clarification-questions.md](../../plans/frontend-shell-nfr-clarification-questions.md) ("CQ"). Business rules (BR-*) are in [business-rules.md](../functional-design/business-rules.md).
|
||||
|
||||
## Quality Gates Overview
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Code["Code change"] --> Lint["pnpm lint"]
|
||||
Lint --> Test["pnpm test incl. PBT, axe, coverage"]
|
||||
Test --> Build["pnpm build incl. type check and sitemap"]
|
||||
Build --> Audit["pnpm audit:deps"]
|
||||
Audit --> LH["pnpm lighthouse on preview"]
|
||||
LH --> Ready["Release ready"]
|
||||
Check["pnpm check runs all steps"] -.-> Lint
|
||||
|
||||
classDef step fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef gate fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef done fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
|
||||
class Code done;
|
||||
class Lint,Test,Build,Audit,LH step;
|
||||
class Check gate;
|
||||
class Ready done;
|
||||
```
|
||||
|
||||
Text alternative: `pnpm check` runs lint, tests (including property-based and accessibility tests), build, dependency audit and Lighthouse in that order; every step must pass before a release.
|
||||
|
||||
## NFR-P Performance
|
||||
|
||||
| ID | Requirement | Measure | Source |
|
||||
|---|---|---|---|
|
||||
| NFR-P-01 | Lighthouse Performance ≥ 90, mobile and desktop, on every route. **Exception (temporary): home page on mobile ≥ 80**, until responsive images come from the API/CMS and prerendering exists (measured 0.81–0.82). | `pnpm lighthouse` against `pnpm preview` | Q3 = B; code change Q1 = B |
|
||||
| NFR-P-02 | No layout shift from shell elements: images have `width`/`height`, fonts are self-hosted | Lighthouse CLS ≤ 0.1 | BR-SEO-10 |
|
||||
| NFR-P-03 | The shell adds no network requests beyond bundled assets | No third-party origins in the network log | NFR-05 |
|
||||
| NFR-P-04 | Router devtools are not in the production bundle | Build output does not contain the devtools chunk | SECURITY-09 |
|
||||
| NFR-P-05 | Scroll handling is passive, and NavigationBar and BackToTop share `useScrolledPast` | Code review | NFR-05 |
|
||||
|
||||
## NFR-A Accessibility
|
||||
|
||||
| ID | Requirement | Measure | Source |
|
||||
|---|---|---|---|
|
||||
| NFR-A-01 | Lighthouse Accessibility = 100, mobile and desktop, on every route | `pnpm lighthouse` | Q3 = B |
|
||||
| NFR-A-02 | No axe-core violations in the component tests of the shell, placeholder, 404 and error pages | `pnpm test` (`vitest-axe`) | Q4 = A |
|
||||
| NFR-A-03 | `jsx-a11y` lint rules pass | `pnpm lint` | Q5 = A |
|
||||
| NFR-A-04 | Keyboard and screen-reader behaviour per BR-A11Y-01…07 and BR-TOP-03/06 | Example-based tests + manual check with NVDA or VoiceOver at Build and Test | NFR-01 |
|
||||
| NFR-A-05 | Colour contrast per NFR-01. axe in `jsdom` cannot measure contrast, so Lighthouse covers it | NFR-A-01 | Q4 note |
|
||||
|
||||
## NFR-S SEO
|
||||
|
||||
| ID | Requirement | Measure | Source |
|
||||
|---|---|---|---|
|
||||
| NFR-S-01 | Lighthouse SEO = 100 on indexed pages (currently `/`) | `pnpm lighthouse` | CQ1 |
|
||||
| NFR-S-02 | Non-indexed pages are `noindex` on purpose. Lighthouse's "blocked from indexing" audit is the only allowed SEO failure there | Lighthouse assertion per URL | CQ1 |
|
||||
| NFR-S-03 | `sitemap.xml` contains exactly the indexed pages; registry and route tree are in sync | `pnpm test` (BR-SEO-07, PBT) + build output | BR-SEO-06/07 |
|
||||
|
||||
## NFR-SEC Security
|
||||
|
||||
| ID | Requirement | Measure | Source |
|
||||
|---|---|---|---|
|
||||
| NFR-SEC-01 | Headers on `preview`: <ul><li>CSP (below)</li><li>HSTS `max-age=31536000; includeSubDomains`</li><li>`nosniff`</li><li>`X-Frame-Options: DENY`</li><li>`Referrer-Policy: strict-origin-when-cross-origin`</li></ul> | Test on the header config + response check at Build and Test | SECURITY-04 |
|
||||
| NFR-SEC-02 | Production CSP: `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`. `style-src 'unsafe-inline'` is justified: Chakra/Emotion inject runtime styles. | Lighthouse Best Practices: no CSP violations in the console | SECURITY-04 |
|
||||
| NFR-SEC-03 | The dev server uses the same headers. Its CSP adds only Vite's needs: `'unsafe-inline'` in `script-src` for the React Refresh preamble, and `ws:` in `connect-src` for HMR. These dev exceptions never reach `preview` or production. | Header config test | Q1 = A |
|
||||
| NFR-SEC-04 | The production CSP has no inline scripts. `next-themes` is removed (Q2 = A); JSON-LD is a non-executed data block. | NFR-SEC-02 | Q2 = A |
|
||||
| NFR-SEC-05 | `pnpm audit:deps` (`--prod --audit-level high`) passes: no high or critical advisories in packages that ship with the site. Advisories in dev-only tools are reported by `pnpm audit:dev` but do not block. | `pnpm check` | Q8 = A, SECURITY-10; code change Q2 = A |
|
||||
| NFR-SEC-06 | Dependencies are pinned by `pnpm-lock.yaml`; no unused dependencies; build tools in `devDependencies` | Code review | SECURITY-10 |
|
||||
| NFR-SEC-07 | No secrets in front-end code; the e-mail address is never a literal (BR-EMAIL-01) | Test: bundle does not contain the joined address | NFR-04, BR-EMAIL-01 |
|
||||
| NFR-SEC-08 | Error and 404 pages expose no internals (BR-ERR-02) | Example-based test | SECURITY-09/15 |
|
||||
|
||||
## NFR-R Reliability
|
||||
|
||||
| ID | Requirement | Measure | Source |
|
||||
|---|---|---|---|
|
||||
| NFR-R-01 | A render error in a page never blanks the site: the shell stays and ErrorPage shows | Test with a throwing route | FR-10 |
|
||||
| NFR-R-02 | Errors are logged with `console.error` in every environment (BR-ERR-03). Central logging is out of scope (SECURITY-03 N/A until there is a back-end). | Test | Q11 (FD) |
|
||||
|
||||
## NFR-M Maintainability and Testing
|
||||
|
||||
| ID | Requirement | Measure | Source |
|
||||
|---|---|---|---|
|
||||
| NFR-M-01 | Every testable property in business-rules.md has a fast-check property test. Failures print the seed and shrink. | `pnpm test` | PBT-02…08 |
|
||||
| NFR-M-02 | 100% statement and branch coverage of the pure functions: `backToTopThreshold`, `visibleSocials`, `emailAddress`, `copyrightLine`, `canonicalUrl`, `sitemapXml`, `jsonLdScript`. No global threshold; coverage is reported. | Vitest coverage with per-file thresholds | Q7 = A |
|
||||
| NFR-M-03 | ESLint (TypeScript, React Hooks, jsx-a11y) and Prettier pass | `pnpm lint`, `pnpm format:check` | Q5 = A |
|
||||
| NFR-M-04 | `pnpm check` runs lint, format check, tests, build, audit and Lighthouse, in that order, and fails on the first failing step. It runs locally at any time. | Script | Q8 = A, CQ1 = A |
|
||||
| NFR-M-05 | No duplicate styling: theme usage per BR-THEME-01…07 | Code review | NFR-02 |
|
||||
|
||||
## NFR-B Browser Support
|
||||
|
||||
| ID | Requirement | Source |
|
||||
|---|---|---|
|
||||
| NFR-B-01 | Supported: the last 2 versions of Chrome, Edge, Firefox and Safari, and Safari on iOS 16+. Older browsers get the site without guarantees. | Q6 = A |
|
||||
| NFR-B-02 | Features used must work in that set: `color-mix()`, `:focus-visible`, `fetchpriority`, `prefers-reduced-motion`, `scrollTo` behaviour `instant`. `fetchpriority` degrades gracefully. | Q6 = A |
|
||||
|
||||
## Not Applicable
|
||||
|
||||
| Category | Rationale |
|
||||
|---|---|
|
||||
| Scalability | Static site without a server; load is the host's concern |
|
||||
| Availability / DR | Depends on the future host (Operations phase) |
|
||||
| Data protection / compliance | No personal data processed by the shell; privacy statement is a placeholder page |
|
||||
|
||||
## Follow-ups Outside This Unit
|
||||
|
||||
1. **CI/CD**: run `pnpm check` (including Lighthouse) automatically as the final step on every push or pull request, so a forgotten local check is caught early (CQ1). Hand-over to Deployment Setup in the Operations phase.
|
||||
2. **Wider browser support** (Q6 note): reconsider support for older mobile browsers (e.g. iOS 14/15) once real visitor statistics exist.
|
||||
3. **Responsive images** (code change Q1): the hero (and later portfolio) images should come in several widths from the API/CMS or an image service, used via `srcset`. Restores NFR-P-01 to 0.9 for the home page together with prerendering.
|
||||
4. **Production headers**: configure the same header set (NFR-SEC-01/02) on the production host (Operations).
|
||||
+104
@@ -0,0 +1,104 @@
|
||||
# Tech Stack Decisions — frontend-shell
|
||||
|
||||
Existing stack (unchanged): React 19, TypeScript, Vite, TanStack Router, Chakra UI v3, pnpm. See [technology-stack.md](../../../../../_shared/reverse-engineering/technology-stack.md).
|
||||
|
||||
All new packages are installed with pnpm at their latest stable version and pinned by `pnpm-lock.yaml` (SECURITY-10).
|
||||
|
||||
## Dependency Changes
|
||||
|
||||
| Package | Change | Kind | Why |
|
||||
|---|---|---|---|
|
||||
| `vitest` | add | dev | Test runner, native to Vite (NFR-03) |
|
||||
| `@vitest/coverage-v8` | add | dev | Coverage with per-file thresholds (NFR-M-02) |
|
||||
| `jsdom` | add | dev | DOM environment for component tests |
|
||||
| `@testing-library/react`, `@testing-library/user-event`, `@testing-library/jest-dom` | add | dev | Component tests from the user's perspective |
|
||||
| `fast-check` | add | dev | Property-based testing (PBT-09) |
|
||||
| `vitest-axe` (on `axe-core`) | add | dev | Accessibility assertions in component tests (Q4 = A) |
|
||||
| `eslint`, `@eslint/js`, `typescript-eslint`, `eslint-plugin-react-hooks`, `eslint-plugin-jsx-a11y`, `globals` | add | dev | Linting (Q5 = A) |
|
||||
| `@lhci/cli` | add | dev | Lighthouse CI with assertions (Q3 = B) |
|
||||
| `next-themes` | **remove** | — | The site is fixed to light; it only added an inline script (Q2 = A) |
|
||||
| `@vitejs/plugin-react` | move to dev | dev | Build tool (FR-11) |
|
||||
| `@tanstack/react-router-devtools` | move to dev | dev | Loaded only in development (NFR-P-04) |
|
||||
|
||||
## Decisions
|
||||
|
||||
### TD-01 Property-based testing: fast-check (PBT-09)
|
||||
- **Generators**: fast-check provides custom arbitraries for the domain types (`SocialLink`, `EmailAddress`, `SitePage`, paths, JSON values).
|
||||
- **Shrinking and replay**: shrinking is on by default. On failure, fast-check reports the seed and path, and `fc.assert(..., { seed, path })` replays the exact case.
|
||||
- **Test runner**: runs as normal Vitest tests, so no separate runner is needed.
|
||||
- **Default runs**: 100 per property. Raise it per property only when needed.
|
||||
- **Considered**: `@fast-check/vitest` (adds `test.prop`). Not needed: plain `fc.assert` inside `it` is enough and is one dependency less.
|
||||
|
||||
### TD-02 Test environment: Vitest + jsdom
|
||||
- The Vitest config lives in `vite.config.ts` (`test` section), so tests use the same aliases and plugins as the app.
|
||||
- Setup file: `@testing-library/jest-dom` matchers + `vitest-axe` matchers.
|
||||
- Router-dependent components are tested inside a memory-history router.
|
||||
- **Fallback**: if `vitest-axe` turns out to be incompatible with the installed Vitest version, a ~10-line custom `toHaveNoViolations` matcher on `axe-core` replaces it. Same assertion, one dependency less.
|
||||
|
||||
### TD-03 Linting: ESLint flat config
|
||||
- Rule sets: `@eslint/js` recommended, `typescript-eslint` recommended, `react-hooks` recommended, `jsx-a11y` recommended.
|
||||
- Prettier remains the formatter. No stylistic ESLint rules, to avoid conflicts.
|
||||
- Excluded: `routeTree.gen.ts` and `dist`.
|
||||
|
||||
### TD-04 Lighthouse CI
|
||||
- **Server**: `@lhci/cli` starts `pnpm preview`, so the real production headers and the SPA fallback apply. It measures every route in `sitePages` plus one unknown URL (the 404), on both mobile and desktop.
|
||||
- **Assertions**:
|
||||
- Performance ≥ 0.9
|
||||
- Accessibility = 1
|
||||
- Best Practices = 1
|
||||
- SEO = 1 on indexed URLs. On `noindex` URLs only the `is-crawlable` audit is allowed to fail (NFR-S-02).
|
||||
- **Requirements**: a local Chrome/Chromium.
|
||||
- **Results**: written to `.lighthouseci/`, which is git-ignored. No upload to a public server.
|
||||
- **Scripts**:
|
||||
- `pnpm lighthouse` runs it on its own.
|
||||
- It is part of `pnpm check` (CQ1 = A).
|
||||
|
||||
### TD-05 Security headers in Vite
|
||||
- **One source**: `securityHeaders(mode)` in a small config module, used by `server.headers` (dev) and `preview.headers`.
|
||||
- Production mode returns the strict set (NFR-SEC-01/02).
|
||||
- Dev mode adds only the Vite exceptions (NFR-SEC-03).
|
||||
- **Testing**: the function is pure, so a test can check that the production CSP never contains `unsafe-eval`, never contains `unsafe-inline` in `script-src`, and never contains `ws:`.
|
||||
- **Production**: the same production set is the required configuration for the future host.
|
||||
|
||||
### TD-06 Vite config in TypeScript
|
||||
- `vite.config.js` becomes `vite.config.ts`. It contains:
|
||||
- the existing plugins
|
||||
- the local `sitemap` plugin (BR-SEO-06), which reads `sitePages`
|
||||
- the security headers (TD-05)
|
||||
- the Vitest `test` section
|
||||
- **Plugin**: about 30 lines, using Rollup's `generateBundle` hook to emit `sitemap.xml`. The XML itself comes from the pure, tested `sitemapXml`.
|
||||
|
||||
### TD-07 Scripts in `package.json`
|
||||
|
||||
| Script | Runs |
|
||||
|---|---|
|
||||
| `test` | `vitest run --coverage` |
|
||||
| `test:watch` | `vitest` |
|
||||
| `lint` | `eslint .` |
|
||||
| `format:check` | `prettier --check .` |
|
||||
| `audit:deps` | `pnpm audit --audit-level high` |
|
||||
| `lighthouse` | `lhci autorun` |
|
||||
| `check` | lint → format:check → test → build → audit:deps → lighthouse, stopping at the first failure |
|
||||
|
||||
### TD-08 Colour mode
|
||||
- **Without `next-themes`**: the light theme is the default. The `_dark` semantic token values stay in the theme, so a dark mode can be added later without rework.
|
||||
- **Considered**: keeping `next-themes` and allowing its script via a CSP hash. Rejected: the hash breaks on every library update, and the script has no use while the site is light-only.
|
||||
|
||||
## Security Baseline Compliance (NFR Requirements)
|
||||
|
||||
| Rule | Status | Rationale |
|
||||
|---|---|---|
|
||||
| SECURITY-04 | Compliant | Header set + CSP defined, `unsafe-inline` only for styles with documented justification (NFR-SEC-01…04) |
|
||||
| SECURITY-09 | Compliant | Devtools dev-only, starter assets removed, generic error pages |
|
||||
| SECURITY-10 | Compliant | Lock file, `audit:deps` in `check`, unused `next-themes` removed, build tools in dev |
|
||||
| SECURITY-13 | Compliant | No CDN resources; Lighthouse CI uploads nothing externally |
|
||||
| SECURITY-15 | Compliant | Root error boundary (NFR-R-01) |
|
||||
| SECURITY-03, -14 | N/A | No server component; revisit with the .NET API |
|
||||
| Others | N/A | As in requirements.md |
|
||||
|
||||
## PBT Compliance (NFR Requirements)
|
||||
|
||||
| Rule | Status | Rationale |
|
||||
|---|---|---|
|
||||
| PBT-09 | Compliant | fast-check: custom arbitraries, shrinking, seed replay, runs in Vitest (TD-01) |
|
||||
| Others | N/A at this stage | Applied in Code Generation |
|
||||
Reference in New Issue
Block a user