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>
15 KiB
15 KiB
Business Rules — frontend-shell
Rule IDs are referenced by the code generation plan and the tests. "Q" = frontend-shell-fd-questions.md, "CQ" = 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.
| 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:
|
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:
|
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. |
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
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,BackToTopcomponents: rendering and interaction with fixed inputs. Their logic lives in the pure functions above.- Theme recipes: static style data.