# 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:
"`, 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 `` "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.